v1.20.0

Changelog

• ea8473c feat(mcp): support project override in mem_session_summary (#504)
• 0accd50 feat(store): replace FTS5 default ranking with weighted BM25 (refers #241) (#526)
• ba9e46c feat(tui): add cloud settings screen and docs (#607)
• 26eb699 feat(tui): add session delete confirmation (#444)
• f200fad fix(cloud): materialize relation mutations on chunk-ingest (WriteChunk) (#600)
• 22fcd43 fix(pi): recover Engram statusline after transient wake-time failures (#640)
• c71d08b fix(store): escape interior double-quotes in sanitizeFTS to prevent FTS5 crash (#586)
• 3da5125 fix(store): prevent duplicate observations on import (#616)

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)