v1.19.0

Highlights

engram setup --protocol=<slim|full> — opt-in slim SessionStart hooks

Claude Code sessions receive the Engram memory protocol twice: once from the SessionStart hook's static prose and once from the MCP server instructions (served since v1.4.0). This release lets tooling opt a slug into a slim hook that drops the duplicated static prose (~3.6KB / ~900 tokens per session) while keeping everything dynamic and load-bearing:

• The session CONTEXT block (recent sessions, prompts, pinned and recent observations).
• The post-compaction recovery header and numbered steps — always emitted, in every mode.

How it works

• engram setup <slug> --protocol=<slim|full> persists a per-slug mode atomically in protocol-mode.json under the data dir (ENGRAM_DATA_DIR honored end to end). Corrupted files are never overwritten and other slugs are never dropped.
• A new engram protocol-mode <slug> subcommand is the runtime read path for the version-pinned plugin hooks: it prints slim only when the persisted mode is slim and the binary meets the v1.4.0 instructions-channel floor — every failure path prints full. It is excluded from the startup update check, so hooks never pay a network call.
• engram setup --help now lists flags (including --protocol) and never reads stdin — external tools can probe capability safely with stdin detached and a timeout.
• cmdSetup argument handling is now a two-pass, order-independent classifier: --protocol is honored wherever it appears, unknown flags still fall back to the interactive menu, and setup never fails because of the flag.

Compatibility

Fully backward compatible. No flag → today's behavior everywhere. Old hooks + new binary and new hooks + old binary both degrade safely to the full protocol text. Downstream consumers (gentle-ai) detect the flag automatically via setup --help and start forwarding it — no coordination needed beyond upgrading.

Changelog

• feat(setup): add --protocol flag and protocol-mode runtime read path (#582, closes #581)

Verification: 25+ new Go tests (strict TDD), race-detector clean, live-binary probe validated, and a 16-entry adversarial review ledger archived with the change (openspec/changes/archive/2026-07-08-setup-protocol-flag/).

gentle-engram v0.1.10

What's Changed

• Exposes Pi-native mem_search controls for match_mode and all_projects.
• Forwards match_mode through the Engram HTTP /search endpoint.
• Makes all_projects=true ignore the project filter for cross-project recall.
• Returns HTTP 400 for invalid match_mode values instead of surfacing a server error.

Verification

• cd plugin/pi && npm test
• go test ./internal/server
• npm publish --dry-run --no-git-checks from plugin/pi

Published to npm via GitHub Actions with provenance.

v1.18.0

Highlights

Engram Cloud now supports principal-based user and token management end to end.

This release replaces the old single-token cloud model with managed human users, per-user managed tokens, project grants, first-admin bootstrap, dashboard administration, and runtime managed-token authentication while preserving the legacy ENGRAM_CLOUD_TOKEN path during migration.

Cloud user and token management

• Added managed principals, human users, per-user hashed tokens, and project grants backed by cloud storage.
• Enforced deny-by-default project access for managed principals on sync routes.
• Added managed-admin JSON API handlers for users, tokens, grants, enable/disable, and revoke flows.
• Added dashboard sessions for managed admins, first-admin bootstrap, and managed-user UI for tokens and grants.
• Added CLI bootstrap support for creating the first managed admin and optionally issuing the first managed token.
• Wired engram cloud serve so managed tokens authenticate against real runtime storage when ENGRAM_CLOUD_TOKEN_PEPPER is configured.

Security and audit hardening

• Managed tokens are shown only once and stored as hashes using a dedicated token pepper.
• Disabled managed users cannot receive newly issued managed tokens.
• Revoked tokens and disabled users are rejected consistently by the runtime auth path.
• Token issuance and success audit insertion are atomic for admin API, dashboard, and bootstrap token issuance, so failed audit writes do not leave live unaudited credentials.
• Dashboard login, bootstrap, legacy recovery, deny, and admin mutation paths now record stronger audit events.

Dashboard and operator UX

• Added managed-user dashboard pages for listing users, inspecting details, issuing tokens, granting projects, revoking tokens/grants, and enabling/disabling users.
• Disabled users no longer show an active token creation affordance.
• Disabled-user token creation attempts render a dashboard-styled 409 page instead of raw plain text.
• Docker compose examples now document ENGRAM_CLOUD_TOKEN_PEPPER for managed-token auth testing.

Documentation

• Updated cloud quickstart and troubleshooting docs for managed-token bootstrap and token pepper configuration.
• Archived the OpenSpec change artifacts and promoted the cloud user token management spec.

Validation

• Local validation before release: go test ./...
• Tracker PR CI: Unit Tests and E2E Tests passed.
• Local Docker QA verified authenticated mode, managed-token sync, invalid-token rejection, user/token/grant flows, revocation, disabled-user rejection, and dashboard persistence.

Changelog

• 76cb9fe Merge cloud user token management
• 064c20a fix(cloud): make managed token issuance audit atomic
• 4b4a85a562cf291c6dc86e5b59f39f010e12c74d fix(cloud): polish disabled token dashboard UX
• 3c6c7ce fix(cloud): reject token issuance for disabled users
• 8babe577a28e3b91b2b6223282d30a83e3ae33e3 feat(cloud): wire managed-token auth into cloud runtime
• ee2ac819c807f9cba26bd7d5d57c94fde2a65b31 feat(cloud): add CLI admin bootstrap and sync contract tests
• 7587be0e4711e20de986e494fa8a98a24e9d4cc9 feat(cloud): add managed-user dashboard UX
• 4035ab5df370d5a96767324689f973dd89ffd523 feat(cloud): audit dashboard login and legacy recovery
• 4bd03db532567a27b95f53a3c8927e5c64c26aa5 feat(cloud): add dashboard principal sessions and bootstrap
• 7172b953b7231e7371ade07d00e2a0d25ec18c19 feat(cloud): add managed admin API handlers
• 2669f3bf7b7c0d2031acb74323850bf329f13168 feat(cloud): enforce principal sync grants
• 9defadf8177eae2780aa8a73f399c00ab143354a feat(cloud): add identity storage foundation
• d4c3b386c11389997468f9af13f4e674d1412637 feat(cloud): add auth principal foundation
• a6c473dc8b577598f628122d256a1d93d6d51143 docs(cloud): plan user token management
• 18890d0 docs: refresh codebase setup guide
• 6fc70fb26a08d9fb9b66dac29dd3a63173136133 fix(pi): clarify native Engram provider failures
• 44faeee5731a093fa4577bd81aec0f3f7dc3e52d fix(setup): update cursor post-install test after #522 (#524)

gentle-engram v0.1.9

Highlights

• Declares gentle-engram as the Pi-native memory provider in injected memory instructions.
• Replaces the generic unavailable error with a native-provider transport failure message.
• Adds retry coverage for transient HTTP startup failures and a registered-tool contract test for mem_search.

Validation

• npm test: 24 tests passed.
• npm pack --dry-run: passed for gentle-engram@0.1.9.
• Fresh reliability and resilience reviews: no findings.

v1.17.0

Changelog

• d3258c5 Merge branch 'main' into fix/cloud-relation-backfill
• b851cb9 Merge pull request #494 from forNerzul/fix/local-sync-relations-backfill
• 36c0819 Merge pull request #497 from Gentleman-Programming/fix/cloud-relation-backfill
• 2c93b4c docs(readme): clarify setup flow, serve vs mcp, and ENGRAM_URL (#513)
• ed5b212 feat(opencode): add 15-minute save-nudge for memory parity (#516)
• 7ad6d19 feat(setup): data-driven agent registry + native setup for 7 more agents (#493)
• 13fc976 feat(setup): install the Codex plugin during 'engram setup codex' (#518)
• 237521a feat(store,mcp): add match_mode option to Search and mem_search (#475)
• b0e23a6 fix(codex): add dedicated Codex plugin so hooks load correctly (#514)
• 03b2534 fix(plugin): persist user prompt in UserPromptSubmit hook (#512)
• 980ebd8 fix(setup): anchor marker end-search and reject relative config-home (#520)
• 75cdfcb fix(setup): avoid baking versioned Homebrew Cellar path into MCP configs (#499)
• 9ee6b7f fix(setup): stop writing unread Cursor global rule, write informational copy (#522)
• e1ed602 fix(store): apply session-fallback in cross-project guard and fix REQ-011 log placement
• 3514f03 fix(store): backfill relation sync mutations so relations reach cloud
• e83d2d0 fix(store): restrict relation backfill to judged rows and resolve project via session
• 9225c57 fix(store): use session-fallback project in JudgeRelation enqueue
• af7baf4 fix(sync): export pre-existing relations missing from local chunks
• 37108d8 fix(sync): read prior chunks via Transport, cover updated-relation export

v1.16.3

Changelog

• 59d4b64 Merge branch 'main' into fix/local-sync-relations
• d38bbab Merge pull request #489 from Gentleman-Programming/fix/local-sync-relations
• 68a19f8 fix(plugin): debounce save-nudge to stop per-message repeats
• f4cc070 fix(sync): include memory_relations in local chunk sync

v1.16.2

Highlights

• Adds observation lifecycle state derived from review_after.
• Adds mem_review for listing memories that need review and marking one reviewed.
• Adds Pi-native review support through the Engram HTTP server for gentle-engram.
• Pins critical observations in context so important memory is harder to bury.

Changes

Memory lifecycle

• Surface computed observation state as active or needs_review.
• Add store-level review queries and local-only review reset behavior.
• Expose lifecycle metadata through MCP save/search responses.

MCP, HTTP, and Pi

• Add MCP mem_review for direct agent integrations.
• Add HTTP review routes used by gentle-engram Pi-native tools.
• Add compact Pi chrome for review list and mark-reviewed flows.

TUI and docs

• Show lifecycle state in the TUI list/detail views.
• Document mem_review, lifecycle metadata, HTTP routes, and Pi setup behavior.

Install

brew upgrade engram

Compatibility notes

• mark_reviewed resets the local review cycle only; lifecycle review timestamps are not synced yet.
• Pi users should pair this with gentle-engram@0.1.8 for native mem_review support.

gentle-engram v0.1.8

Highlights

• Adds Pi-native mem_review support for gentle-engram.
• Adds compact Pi tool chrome for listing memories that need review and marking one reviewed.
• Publishes the package as gentle-engram@0.1.8.

Install

pi install npm:gentle-engram@0.1.8

Notes

• Requires an Engram binary/server with the new review HTTP routes from v1.16.2.
• mark_reviewed resets the local review cycle only; lifecycle review timestamps are not synced yet.

v1.16.1

Engram v1.16.1 is a quality and reliability release: seven bug fixes across the MCP session model, cloud sync, project migration, the macOS and Windows builds, and the plugin cache — plus expanded documentation for MCP project overrides, team usage, and topic keys. Every fix was validated by adversarial review before merge.

Highlights

• Active session resolution for mem_save (#386): saves without an explicit session now attach to the active session resolved from the shared store, instead of falling back to manual-save-{project}. This fixes UUID sessions that stayed empty at observation_count: 0.
• Edited memories re-export on sync (#447): mem_update edits are no longer skipped by engram sync. The export now checks UpdatedAt, not just CreatedAt.
• No more case-only duplicate projects (#438): project migration normalizes names before comparing, so a repo whose remote is Repo_Name no longer ping-pongs against a local repo_name.
• macOS 26.4 binaries run again (#402): darwin builds are adhoc re-signed during release, fixing the AMFI SIGKILL (exit 137) on Apple Silicon.
• Cloud upgrade repair applies partial fixes (#446): repairable mutations are now applied even when a blocker is queued, and the message names the real blocker (seq + entity_key) instead of the wrong entry.
• Plugin cache no longer recurses (#217): the plugin version is synced with the marketplace manifest so installs stop creating nested empty cache directories.
• Clearer Windows background sync (#421): autosync token logging now names both ENGRAM_CLOUD_TOKEN and the cloud.json fallback, and the prompt hook emits UTF-8 under PowerShell 5.1.

Contribution highlights

Thanks to the contributors and issue reporters who shaped this release:

• @carlosmoradev authored the new Team Usage guide (#409, closing #305) — scope conventions, language strategy for shared memory, and how scope interacts with sync today.
• Issue reports #386, #438, #446, #447, #217, #421, #401, #402 drove the fixes.
• Adversarial review caught two fixes that looked correct but were not — a session registry that could not cross the HTTP/MCP process boundary, and a plugin source change that breaks Claude Code clients older than v2.1.69 — before either shipped.

Pi companion notes

No new gentle-engram npm package was published in this release. The Pi companion remains gentle-engram@0.1.7; this release updates the main Engram binary and documentation.

Fixes included

• mem_save / prompt / summary / passive saves resolve the most-recent active session from the store before falling back to manual-save-{project}.
• engram sync re-exports observations edited via mem_update (now checks UpdatedAt).
• Project migration normalizes names, preventing case-only duplicate projects (regression of #136).
• darwin release binaries are adhoc re-signed to satisfy AMFI on macOS 26.4.
• cloud upgrade repair --apply applies the repairable subset alongside a blocker and reports the correct blocker.
• Plugin plugin.json version synced with the marketplace manifest to stop recursive cache directories.
• Windows autosync token logging clarified; prompt hook output set to UTF-8.
• New documentation: MCP --project / ENGRAM_PROJECT override, VS Code/WSL setup, Linux EXDEV troubleshooting, a topic_key guide, a Windows Task Scheduler template, and the Team Usage guide.

Changelog

• #449 fix(mcp): resolve active session from store for mem_save instead of manual-save fallback (#386)
• #450 fix(sync): re-export edited observations by checking UpdatedAt in filterNewData (#447)
• #451 fix(server): normalize project names before migrate to prevent case-only duplicates (#438)
• #452 fix(store): apply repairable cloud-upgrade mutations even when a blocker is queued (#446)
• #453 fix(release): adhoc re-sign darwin binaries to prevent AMFI SIGKILL on macOS 26.4 (#402)
• #454 fix(cloud): clarify autosync token error log and add UTF-8 PS1 output encoding (#421)
• #455 fix(plugin): sync plugin.json version to 0.1.1 to stop recursive cache dirs (#217)
• #456 docs: mcp project override, VS Code/WSL, EXDEV, topic_key guide, Task Scheduler
• #409 docs: add team usage guide (#305, by @carlosmoradev)

v1.16.0

Engram v1.16.0 lands a broad, high-impact wave of fixes and features: opt-in HTTP auth and constant-time token comparisons, new CLI delete sub-commands, a TUI clipboard shortcut, cross-project personal search, case-insensitive legacy project matching, a cloud allowlist wildcard, Pi setup hardening, and a wholesale docs refresh. Multiple external contributors and issue reporters drove this release.

Highlights

Security

• Optional local auth for destructive HTTP endpoints (ENGRAM_HTTP_TOKEN): when set, DELETE /sessions/{id}, DELETE /observations/{id}, DELETE /prompts/{id}, GET /export, POST /import, and POST /projects/migrate require Authorization: Bearer <token>. Unset = open (zero-config preserved). Constant-time compare via hmac.Equal.
• Constant-time token comparisons: bearer and admin token checks in internal/cloud/auth and cloudserver use hmac.Equal instead of ==/!=, eliminating the timing-oracle.
• Obsidian exporter path traversal: internal/obsidian/exporter.go sanitizes project and type components before filepath.Join and adds a post-join containment check, rejecting any path that escapes the export root.

CLI

• engram delete now supports sub-commands: delete observation <id>, delete session <id>, delete prompt <id>, and delete project <name>. All accept --hard. The legacy engram delete <obs_id> form still works.
• store.DeleteProject atomic cascade: orphans memory_relations, removes observations (soft or hard), prompts, and sessions (hard only — the FK constraint blocks session removal while soft-deleted observations still reference them).

TUI

• c keybinding copies the highlighted observation to the clipboard via OSC 52 on Recent Observations, Search Results, Observation Detail, and Session Detail. Works over SSH, no system deps.

Search and scopes

• mem_search accepts all_projects: true to search every project at once instead of the resolved one.
• scope=personal without an explicit project now searches personal observations across all projects (mem_search, mem_context).
• global is a valid scope alongside project and personal (was silently coerced to project).
• Legacy mixed-case project data is now searchable: store queries use LOWER(project) = ? so observations stored as Ebook2Audio are found when queried as ebook2audio — the MCP path normalizes; the CLI was the only path that happened to work before.
• Configurable timestamp display: ENGRAM_TIMEZONE sets the display timezone for the TUI and the cloud dashboard. Falls back to system local; UTC is preserved in storage.

Cloud

• ENGRAM_CLOUD_ALLOWED_PROJECTS accepts * to allow every project (per-project enforcement bypassed). Useful for dev and internal deploys.
• sync --cloud sends the Authorization header when only cloud.json carries the token: resolveCloudRuntimeConfig no longer zeroes the file token before reading the env var.
• cloud status detects a dead local daemon with a 1-second probe and prints actionable guidance; the launchd unit template is documented.

MCP

• handleSessionSummary hardened: it now respects the process-level project override (ENGRAM_PROJECT / engram mcp --project) consistent with every other write tool, and rejects empty or whitespace-only content before AddObservation. This fixes stuck sync_mutation rows that blocked cloud upgrade.

Windows

• CLAUDE_PLUGIN_ROOT is escape-quoted in every hooks.json command entry, so all Claude Code hooks fire on profile paths containing spaces (e.g. C:\Users\John Doe\...).

Pi

• engram setup pi pins npmCommand to a mise-stable form (["mise","exec","node@X.Y.Z","--","npm"]) when mise is detected and no command is configured, preventing duplicate installs when Node drifts. Existing values are preserved.
• Pi status bar maps ambiguous_project to an actionable label instead of the generic error.

Docs

• Wholesale sync: the DOCS.md environment-variables table went from 3 to 17 rows; printUsage() env block synced with code; CLI reference tables in README.md and docs/ARCHITECTURE.md now include doctor, conflicts, delete, and projects prune; Codex troubleshooting for "MCP Transport closed" was added; the new ENGRAM_HTTP_TOKEN, ENGRAM_TIMEZONE, scope=personal cross-project behavior, global scope, * cloud wildcard, and Pi npmCommand pinning are all documented.

Contribution highlights

Thanks to the external contributors and issue reporters who shaped this release:

• @carlosmoradev shipped #408 (all_projects flag for mem_search), #346 (configurable timezone), and #410 (install-from-source version-stamp docs).
• @jlsevillano shipped #337 (dead-daemon detection in cloud status and launchd documentation).
• Issue reports that drove targeted fixes: #180 (Obsidian path traversal), #200 (HTTP auth), #350 (constant-time compare), #260 (cloud wildcard), #146 (MCP search empty for legacy data), #391 (personal-scope filter), #403, #413, #393 (handleSessionSummary gaps), #122 (global scope), #343 (sync --cloud auth header), #209, #218, #219 (CLI delete), #141 (TUI copy), #420 (Windows hooks quoting), #385 (Pi npmCommand), #384 (Pi status bar), #167 (Codex docs).

Pi companion notes

No new gentle-engram npm package was published in this release. The current Pi companion remains gentle-engram@0.1.7; this release updates the main Engram binary, the Pi setup logic in engram setup pi, and the Pi documentation.

Changelog

• #443 docs(codex): add troubleshooting for MCP Transport closed error (closes #167)
• #442 fix(plugin): quote CLAUDE_PLUGIN_ROOT in hooks for paths with spaces (closes #420)
• #441 feat(store,cli): cascade DeleteProject + engram delete session|prompt|project (closes #218, #219)
• #439 fix(pi): show actionable status for ambiguous project errors (closes #384)
• #436 docs: bring docs up to date with recently merged features (closes #435)
• #434 feat(cli): add engram delete command to remove observations (closes #209)
• #433 feat(tui): add clipboard copy keybinding via OSC 52 (closes #141)
• #432 fix(pi): pin npmCommand to stable mise node spec (closes #385)
• #431 feat(cloud): wildcard support for ENGRAM_CLOUD_ALLOWED_PROJECTS (closes #260)
• #430 fix(cloud): fall back to cloud.json token when ENGRAM_CLOUD_TOKEN is unset (closes #343)
• #429 security(server): add optional local auth for destructive HTTP endpoints (closes #200)
• #428 fix(store): handle global scope in normalizeScope (closes #122)
• #427 fix(store): use case-insensitive project filter for legacy mixed-case data (closes #146)
• #426 fix(security): replace timing-unsafe token comparisons with hmac.Equal (closes #350)
• #425 fix(mcp): skip project filter for scope=personal with no explicit project (closes #391)
• #424 fix(mcp): harden handleSessionSummary process override and empty-content guard (closes #403, #413, #393)
• #423 fix(obsidian): prevent path traversal in exporter file path construction (closes #180)
• #410 docs: clarify version stamp PATH gotcha and Claude Code schema error (closes #67)
• #408 feat(mcp): add all_projects flag to mem_search (closes #303)
• #346 feat(timeutil): support configurable timezone for timestamp display (closes #169)
• #337 feat(cloud): detect dead local daemon in cloud status and document launchd unit (closes #279)