v2.2.0

Engram 2.2.0 adds CommandCode setup and strengthens local-data safety, project identity, Windows agent hooks, and diagnostics. This tag publishes the **core binary**; the Pi package `gentle-engram` has a separate npm release channel.

## What changed since v2.1.0

### Memory and local data integrity

- Refuse SQLite WAL startup on filesystems identified as remote, with platform-specific detection and regression coverage. Keep the database on a **local filesystem**: unclassified mounts are not certified safe ([#1364](https://github.com/Gentleman-Programming/engram/pull/1364), [#1365](https://github.com/Gentleman-Programming/engram/pull/1365)).
- Preserve blank-directory sessions and their dependent records during local import, and apply same-project relation guards across endpoint scopes ([#1298](https://github.com/Gentleman-Programming/engram/pull/1298), [#1374](https://github.com/Gentleman-Programming/engram/pull/1374)).
- Resolve the canonical identity of an unambiguous promoted child Git repository; atomically claim ownership only for the narrow ended, unowned legacy-session registration case. Neither change is a general automatic session repair ([#1395](https://github.com/Gentleman-Programming/engram/pull/1395), [#1400](https://github.com/Gentleman-Programming/engram/pull/1400)).
- Index project-scoped exports to avoid broad scans of sessions, observations, and prompts ([#1379](https://github.com/Gentleman-Programming/engram/pull/1379)).

### Agent setup and CLI

- Add `engram setup commandcode` for CommandCode's user-scope MCP configuration and Memory Protocol ([#1123](https://github.com/Gentleman-Programming/engram/pull/1123)).
- Restore Codex Windows prompt/startup hook routing, bind Codex MCP writes to their runtime session, and preserve UTF-8 session IDs ([#1377](https://github.com/Gentleman-Programming/engram/pull/1377), [#1367](https://github.com/Gentleman-Programming/engram/pull/1367), [#1366](https://github.com/Gentleman-Programming/engram/pull/1366), [#1363](https://github.com/Gentleman-Programming/engram/pull/1363)).
- Diagnose stale absolute Engram executable paths in supported MCP registrations without changing them automatically; `engram doctor` names the affected client and its explicit `engram setup <agent>` recovery step. Export/import help no longer triggers setup side effects ([#1394](https://github.com/Gentleman-Programming/engram/pull/1394), [#1369](https://github.com/Gentleman-Programming/engram/pull/1369)).
- Accept implicit stdio MCP registration in Claude Code and select the OpenCode V1 plugin entrypoint explicitly ([#1385](https://github.com/Gentleman-Programming/engram/pull/1385), [#1389](https://github.com/Gentleman-Programming/engram/pull/1389)).

### Dashboard and build reliability

- Render dashboard timestamps in the configured `ENGRAM_TIMEZONE`, falling back to local time without changing stored UTC values ([#1384](https://github.com/Gentleman-Programming/engram/pull/1384)).
- Pin and scope templ generation to dashboard sources so generated output stays aligned with its templates ([#1386](https://github.com/Gentleman-Programming/engram/pull/1386), [#1397](https://github.com/Gentleman-Programming/engram/pull/1397)).

## Pi 0.1.15 is a separate release

The core's `engram setup pi` path pins [`gentle-engram` 0.1.15 on npm](https://www.npmjs.com/package/gentle-engram/v/0.1.15). Pi source changes on this core tag do **not** publish a newer npm package. To update an existing Pi installation to the published package:

```bash
pi install npm:gentle-engram@0.1.15
```

Restart Pi afterward. Pi project listing needs an Engram server at least v2.1.0; see the [compatibility guidance](https://github.com/Gentleman-Programming/engram/pull/1399). The separate fix for writes after resuming a quit Pi session remains open in [#1376](https://github.com/Gentleman-Programming/engram/issues/1376); do not treat it as part of this core release.

## Upgrade checklist

1. Back up your local database and configuration. Keep the SQLite database on a **local filesystem**, not NFS or another network mount.
2. Upgrade the core binary with a release archive or Homebrew; verify manual downloads against `checksums.txt`.
3. Run `engram doctor` and follow only the guidance applicable to your store. Restart long-running MCP and agent sessions to pick up the new binary.
4. If you use Pi, update its npm package separately as needed and restart Pi.

## Known limitations accepted for this release

- **Network filesystem data safety:** [#1292](https://github.com/Gentleman-Programming/engram/issues/1292) remains open. Positively identified remote filesystems are rejected at startup; unknown filesystems are not proof of safety. Use local storage and retain backups.
- **Legacy session identity repair:** [#1332](https://github.com/Gentleman-Programming/engram/issues/1332) remains open. The narrow ownership claim above is not the requested operator-facing canonical-ID repair flow.
- **Pi quit/resume writes:** [#1376](https://github.com/Gentleman-Programming/engram/issues/1376) remains open; the Pi fix is not in the published npm 0.1.15 package.
- **Occupied server port:** [#1391](https://github.com/Gentleman-Programming/engram/issues/1391) reports silent `engram serve` exit when another Engram process using the same instance already owns the port; this report is not described as fixed here.

## Installation and full comparison

Release archives cover Linux, macOS, and Windows on amd64 and arm64, alongside `checksums.txt`; the stable Homebrew formula is at 2.2.0. See the complete core diff in [`v2.1.0...v2.2.0`](https://github.com/Gentleman-Programming/engram/compare/v2.1.0...v2.2.0). The Pi package has its own npm version and source tag.

## 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** — reports filed since v2.1.0 and earlier reports directly relevant to these changes (one representative issue per person):

@Agustin-Prieto ([#1287](https://github.com/Gentleman-Programming/engram/issues/1287)) · @BenjaMolina ([#1271](https://github.com/Gentleman-Programming/engram/issues/1271)) · @efirvida ([#1292](https://github.com/Gentleman-Programming/engram/issues/1292)) · @hectormr206 ([#1376](https://github.com/Gentleman-Programming/engram/issues/1376))

@hjagar ([#1371](https://github.com/Gentleman-Programming/engram/issues/1371)) · @IsraelitoMX ([#1370](https://github.com/Gentleman-Programming/engram/issues/1370)) · @MiguezPablo ([#1391](https://github.com/Gentleman-Programming/engram/issues/1391))

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

- @danielgap ([#1298](https://github.com/Gentleman-Programming/engram/pull/1298))
- @dnlrsls ([#1377](https://github.com/Gentleman-Programming/engram/pull/1377))
- @eSagraAI ([#1123](https://github.com/Gentleman-Programming/engram/pull/1123))

## Changelog
* ed44eddc4b0e6c1c5149bcb19ce76c5d32182ddb ci(release): flag unpublished stable artifact changes (#1398)
* 2b1a7303161296962c0b706402ad5b409e8ff588 docs(cloud): document existing bearer header grammar (#1390)
* 79c16f8aa87506f665813e712ccdfbc2698345cf docs(pi): document minimum server for project listing (#1399)
* d0ba4a93fe6e9ccdbaa296fdb1a28e63824d5ad3 feat(setup): add CommandCode CLI as supported agent (#1123)
* faeebba3d20bbc5dfad650b393a8e2928935bb37 fix(build): scope templ generation to dashboard sources (#1397)
* 5fd5ca0038899824eae92354e0f10825eccdcdd9 fix(build): unify pinned templ generation commands (#1386)
* 707c942cd9216720c2a8af4788e350a8781d0970 fix(claude-code): accept implicit stdio MCP registration (#1385)
* 6c8f39819b777584457e7e53072b967ec202793e fix(cli): make export and import help side-effect free (#1369)
* e50d697fe7df31ba26bdb167cf40d287482946af fix(codex): bind MCP writes to runtime session identity (#1366)
* f2efd5fb2b510989106a244cd76ad09cd2ac5545 fix(codex): preserve UTF-8 session registration payload (#1363)
* 0f78c745f719c432fe64e406359641067382d1b6 fix(codex): restore Windows prompt and startup hooks (#1271) (#1377)
* 3be93e9ed74791808ec47d752d7e53a4a0ec390e fix(codex): route Windows prompt hook through native pin (#1367)
* 37935d7fe1b1b2bde0d9c987eefa8de9fa7aa940 fix(dashboard): honor configured timezone across admin and Activity (#1384)
* eddd557d3507bf5d20395bef10ed6919a715d46e fix(opencode): select V1 plugin entrypoint explicitly (#1389)
* 06b61eb1f50a80bc3c2a093f888c28419ff4d244 fix(pi): preserve live session across reload (#1375)
* c57a1d2314a3e5b1cc8be2f0e0e69f19bfec2a18 fix(project): resolve promoted child identity canonically (#1395)
* f482177f45d712fb51e37cfa25956134308efac8 fix(setup): diagnose stale MCP executable paths (#1394)
* e12e7750e377af1350f08b8f2c29a4f01a75f7be fix(store): apply same-project relations across endpoint scopes (#1374)
* 76f938b1942c3967492773ee967be9cbd5b644ea fix(store): claim terminal legacy session ownership atomically (#1400)
* 33337716a842db167a2b66a7fb5d0f7ed2e6461f fix(store): preserve blank session directories through local import (#1287) (#1298)
* 615a7b2dca548a266c5761e2d590f3da701a959c fix(store): reject unsafe network filesystem WAL (#1364)
* 111d1fd5a6eeb6dd274899a3a7ed30f9da594b2e perf(store): index project-scoped exports on main (#1379)
* 64046793c0bf87f9b75b5a316e82bc11bb981c79 test(store): cover network filesystem safety and recovery (#1365)