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](https://github.com/Gentleman-Programming/engram/pull/1401), [#1406](https://github.com/Gentleman-Programming/engram/pull/1406), [#1409](https://github.com/Gentleman-Programming/engram/pull/1409), [#1416](https://github.com/Gentleman-Programming/engram/pull/1416)).
- Reject historical journal mutations with duplicate source identifiers before identity repair deletes the source session ([#1436](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/pull/1443)).
- Allow `mem_merge_projects` to merge explicitly named `-`/`_` separator variants without loosening automatic consolidation ([#1415](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/pull/1425)).
- Codex setup and the native Windows hook use the absolute `CODEX_HOME` when set, otherwise `~/.codex` ([#1410](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/pull/1402), [#1433](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/pull/1448)).

## Pi 0.1.16 on npm

[`gentle-engram` 0.1.16](https://www.npmjs.com/package/gentle-engram/v/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](https://github.com/Gentleman-Programming/engram/pull/1387)), and `pi-engram init` now migrates 0.1.14 and 0.1.15 pins. To update an existing Pi installation:

```bash
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](https://github.com/Gentleman-Programming/engram/issues/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`](https://github.com/Gentleman-Programming/engram/compare/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](https://github.com/Gentleman-Programming/engram/issues/1424)) · @efirvida ([#1292](https://github.com/Gentleman-Programming/engram/issues/1292)) · @gtrafael ([#1332](https://github.com/Gentleman-Programming/engram/issues/1332)) · @hectormr206 ([#1376](https://github.com/Gentleman-Programming/engram/issues/1376))

@jesusjbriceno ([#1344](https://github.com/Gentleman-Programming/engram/issues/1344)) · @lioneljg ([#1408](https://github.com/Gentleman-Programming/engram/issues/1408)) · @MiguezPablo ([#1391](https://github.com/Gentleman-Programming/engram/issues/1391)) · @WilberC ([#1423](https://github.com/Gentleman-Programming/engram/issues/1423))

Open feedback: @luis63e ([#1445](https://github.com/Gentleman-Programming/engram/issues/1445)) · @duquejmz ([#1422](https://github.com/Gentleman-Programming/engram/issues/1422)) · @oguarni ([#1407](https://github.com/Gentleman-Programming/engram/issues/1407))

**Merged PR authors** — v2.2.0...v2.2.1 (one representative PR per person; the [full comparison](https://github.com/Gentleman-Programming/engram/compare/v2.2.0...v2.2.1) lists every change):

- @dnlrsls ([#1401](https://github.com/Gentleman-Programming/engram/pull/1401))
- @lioneljg ([#1410](https://github.com/Gentleman-Programming/engram/pull/1410))
- @WilberC ([#1425](https://github.com/Gentleman-Programming/engram/pull/1425))

## Changelog
* 63dcc03927fae13204c29d1d90ad8158501a1c48 docs(architecture): link canonical MCP and CLI references (#1435)
* facaba842db32b55d3a13a6ea16ea31968ae6ce6 docs(architecture): link canonical cloud route reference (#1430)
* 57275c5c1ced7b1523b11fa2fdee5062618411b2 docs(architecture): qualify session context injection (#1442)
* a8e316052e9551f7dbba207c82d576e5a7b4f2eb docs(cloud): document dashboard bootstrap recovery routes (#1432)
* 7b8ddf01110faaa7e336ac940bf1f70acbee146a docs(cloud): document dashboard managed-user routes (#1414)
* a4f5f03c849b101ee8b8d3684747918bb452c4c3 docs(cloud): document managed admin API routes (#1412)
* 1b2335e2842b77310d88db5c80913d2e34a1d5dd docs(pi): align manual install with setup package pin (#1440)
* 298b8fa3f007c2be95df9d4d275c3a0cc1fe7f5d docs(testing): clarify local verification and CI ownership (#1420)
* 9301e633c6b1db4f38e5665500d3f8f676eeef5a fix(codex): resolve active home for windows hooks (#1410)
* a97b98b200e936728ef9fb0ff2d6acfd8baade41 fix(doctor): backfill pending session directories locally (#1443)
* 289134fe7e91e3a2ad8aafde70bc22d0521fe751 fix(doctor): repair legacy blank session IDs explicitly (#1406)
* c72dd99db901945d9bfece6b5cc675037eecf83e fix(doctor): report corrected mutation publication counts (#1416)
* 818be842f57a95063f62f1b745297a96c407c143 fix(pi): align gentle-engram 0.1.16 package and installer pins (#1448)
* 99e936c5d4a7cf0f7b7d842ca6ce9a698ffd61b4 fix(pi): restore memory writes after resuming a quit session (#1387)
* 8bea39cb1c28c1ecfa7a6c8d71acdc602ba73d89 fix(plugin): fall back to stdout for empty subagent messages (#1433)
* 07b282bd7a4529b5d62eef9982a088ab2002266f fix(plugin): preserve Claude SubagentStop message newlines (#1402)
* 55de8f2d779159537589202120f473836353f61f fix(server): explain same-instance port conflict to supervisors (#1405)
* 4d9b07e3b1a7089ddb3718fa081653e906dde3f8 fix(server): report backing-store failures in health and stats (#1418)
* 087c6a5a2c35b61bf8f2be5780034e1037694edb fix(setup): persist a stable mise shim instead of a versioned install path (#1425)
* 38c45a5343d3183a015e1ffbb0e5a034bc3d0d88 fix(store): merge explicit separator project variants (#1415)
* e13dfe6c97f71b76d960f79cf4fa2cbb48ce7110 fix(store): preserve legacy session history during identity repair (#1401)
* f2802d754d1cfc46a4e5b2bf70ca5bea9fead24e fix(store): reject shadowed session IDs in repair journal (#1436)
* 653e37bf8c38bb06754b8a47dfef6294e2bfe077 test(doctor): cover local-only legacy journal migration (#1409)
* 846f95c76d3e2e8335e32ebab7f42ab33f06c777 test(plugin): resolve Windows hook test paths (#1404)