v2.2.1

Engram 2.2.1 is a patch release focused on session-identity repair, engram doctor, setup path stability, and hook capture reliability. This tag publishes the core binary; the Pi package gentle-engram 0.1.16 was published separately on npm (details below).

What changed since v2.2.0

Session identity and doctor repairs

• Add an explicit, backup-backed repair for legacy blank session IDs: engram doctor repair --check invalid_session_identity --replacement-id <canonical-id> migrates the session with its observations and prompts atomically. Plan and dry-run stay nonmutating, and publication counts report only corrected current-state mutations (#1401, #1406, #1409, #1416).
• Reject historical journal mutations with duplicate source identifiers before identity repair deletes the source session (#1436).
• Backfill missing directory fields in eligible pending session mutations on local-only installs, so they enter the repair plan instead of staying pending (#1443).
• Allow mem_merge_projects to merge explicitly named -/_ separator variants without loosening automatic consolidation (#1415).

Server health

• Local /health now checks the live backing store, and stats propagate SQL errors instead of returning misleading zero counts; failures return a generic HTTP 500 (#1418).
• A same-instance engram serve that cannot bind its port now logs one diagnostic instead of exiting silently; systemd guidance recommends Restart=on-failure (#1405).

Agent setup and hooks

• engram setup records mise's stable shim (<mise-data-dir>/shims/engram) instead of a versioned install path, so MCP registrations survive mise up and mise prune. engram setup pi can repair an mcpServers.engram entry whose absolute command no longer exists (#1425).
• Codex setup and the native Windows hook use the absolute CODEX_HOME when set, otherwise ~/.codex (#1410).
• Claude Code SubagentStop capture preserves multiline content on Windows and Unix, and Claude Code/Codex hooks fall back to stdout when the subagent message is explicitly empty (#1402, #1433).
• engram setup pi now installs npm:gentle-engram@0.1.16 and migrates older pins, including 0.1.14 and 0.1.15 (#1448).

Pi 0.1.16 on npm

gentle-engram 0.1.16 is published with npm provenance from tag pi-v0.1.16. It includes the fix for memory writes after resuming a quit Pi session (pi --continue) (#1387), and pi-engram init now migrates 0.1.14 and 0.1.15 pins. To update an existing Pi installation:

pi install npm:gentle-engram@0.1.16
pi-engram init

Restart Pi afterward.

Upgrade checklist

1. Back up your local database and configuration. Keep the SQLite database on a local filesystem.
2. Upgrade the core binary with a release archive or Homebrew; verify manual downloads against checksums.txt.
3. Run engram doctor. If it reports invalid_session_identity, follow the documented repair with an explicit canonical --replacement-id; run plan/dry-run first.
4. If you installed Engram through mise, rerun engram setup <agent> once so MCP registrations point at the stable shim.
5. Restart long-running MCP and agent sessions to pick up the new binary. If you use Pi, update its npm package as shown above.

Known limitations accepted for this release

• Cloned repositories and Pi: #1445 reports that a cloned repository can silently import tracked memories into the global store. It is open and not addressed here.
• Network filesystems: remote filesystems identified at startup are still rejected, and unknown mounts are not proof of safety. Use local storage and retain backups.

Installation and full comparison

Release archives cover Linux, macOS, and Windows on amd64 and arm64, alongside checksums.txt. See the complete core diff in v2.2.0...v2.2.1.

Thanks to contributors

Thank you to everyone who reported an issue or contributed a merged PR. Open reports are credited as feedback, not described as fixed.

Issue reporters — issues fixed in this release, and reports filed since v2.2.0 (one representative issue per person):

@danielgap (#1424) · @efirvida (#1292) · @gtrafael (#1332) · @hectormr206 (#1376)

@jesusjbriceno (#1344) · @lioneljg (#1408) · @MiguezPablo (#1391) · @WilberC (#1423)

Open feedback: @luis63e (#1445) · @duquejmz (#1422) · @oguarni (#1407)

Merged PR authors — v2.2.0...v2.2.1 (one representative PR per person; the full comparison lists every change):

• @dnlrsls (#1401)
• @lioneljg (#1410)
• @WilberC (#1425)

Changelog

• 63dcc03 docs(architecture): link canonical MCP and CLI references (#1435)
• facaba8 docs(architecture): link canonical cloud route reference (#1430)
• 57275c5 docs(architecture): qualify session context injection (#1442)
• a8e3160 docs(cloud): document dashboard bootstrap recovery routes (#1432)
• 7b8ddf0 docs(cloud): document dashboard managed-user routes (#1414)
• a4f5f03 docs(cloud): document managed admin API routes (#1412)
• 1b2335e docs(pi): align manual install with setup package pin (#1440)
• 298b8fa docs(testing): clarify local verification and CI ownership (#1420)
• 9301e63 fix(codex): resolve active home for windows hooks (#1410)
• a97b98b fix(doctor): backfill pending session directories locally (#1443)
• 289134f fix(doctor): repair legacy blank session IDs explicitly (#1406)
• c72dd99 fix(doctor): report corrected mutation publication counts (#1416)
• 818be84 fix(pi): align gentle-engram 0.1.16 package and installer pins (#1448)
• 99e936c fix(pi): restore memory writes after resuming a quit session (#1387)
• 8bea39c fix(plugin): fall back to stdout for empty subagent messages (#1433)
• 07b282b fix(plugin): preserve Claude SubagentStop message newlines (#1402)
• 55de8f2 fix(server): explain same-instance port conflict to supervisors (#1405)
• 4d9b07e fix(server): report backing-store failures in health and stats (#1418)
• 087c6a5 fix(setup): persist a stable mise shim instead of a versioned install path (#1425)
• 38c45a5 fix(store): merge explicit separator project variants (#1415)
• e13dfe6 fix(store): preserve legacy session history during identity repair (#1401)
• f2802d7 fix(store): reject shadowed session IDs in repair journal (#1436)
• 653e37b test(doctor): cover local-only legacy journal migration (#1409)
• 846f95c test(plugin): resolve Windows hook test paths (#1404)