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, #1365).
• Preserve blank-directory sessions and their dependent records during local import, and apply same-project relation guards across endpoint scopes (#1298, #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, #1400).
• Index project-scoped exports to avoid broad scans of sessions, observations, and prompts (#1379).

Agent setup and CLI

• Add engram setup commandcode for CommandCode's user-scope MCP configuration and Memory Protocol (#1123).
• Restore Codex Windows prompt/startup hook routing, bind Codex MCP writes to their runtime session, and preserve UTF-8 session IDs (#1377, #1367, #1366, #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, #1369).
• Accept implicit stdio MCP registration in Claude Code and select the OpenCode V1 plugin entrypoint explicitly (#1385, #1389).

Dashboard and build reliability

• Render dashboard timestamps in the configured ENGRAM_TIMEZONE, falling back to local time without changing stored UTC values (#1384).
• Pin and scope templ generation to dashboard sources so generated output stays aligned with its templates (#1386, #1397).

Pi 0.1.15 is a separate release

The core's engram setup pi path pins gentle-engram 0.1.15 on npm. Pi source changes on this core tag do not publish a newer npm package. To update an existing Pi installation to the published package:

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. The separate fix for writes after resuming a quit Pi session remains open in #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 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 remains open. The narrow ownership claim above is not the requested operator-facing canonical-ID repair flow.
• Pi quit/resume writes: #1376 remains open; the Pi fix is not in the published npm 0.1.15 package.
• Occupied server port: #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. 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) · @BenjaMolina (#1271) · @efirvida (#1292) · @hectormr206 (#1376)

@hjagar (#1371) · @IsraelitoMX (#1370) · @MiguezPablo (#1391)

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

• @danielgap (#1298)
• @dnlrsls (#1377)
• @eSagraAI (#1123)

Changelog

• ed44edd ci(release): flag unpublished stable artifact changes (#1398)
• 2b1a730 docs(cloud): document existing bearer header grammar (#1390)
• 79c16f8 docs(pi): document minimum server for project listing (#1399)
• d0ba4a9 feat(setup): add CommandCode CLI as supported agent (#1123)
• faeebba fix(build): scope templ generation to dashboard sources (#1397)
• 5fd5ca0 fix(build): unify pinned templ generation commands (#1386)
• 707c942 fix(claude-code): accept implicit stdio MCP registration (#1385)
• 6c8f398 fix(cli): make export and import help side-effect free (#1369)
• e50d697 fix(codex): bind MCP writes to runtime session identity (#1366)
• f2efd5f fix(codex): preserve UTF-8 session registration payload (#1363)
• 0f78c74 fix(codex): restore Windows prompt and startup hooks (#1271) (#1377)
• 3be93e9 fix(codex): route Windows prompt hook through native pin (#1367)
• 37935d7 fix(dashboard): honor configured timezone across admin and Activity (#1384)
• eddd557 fix(opencode): select V1 plugin entrypoint explicitly (#1389)
• 06b61eb fix(pi): preserve live session across reload (#1375)
• c57a1d2 fix(project): resolve promoted child identity canonically (#1395)
• f482177 fix(setup): diagnose stale MCP executable paths (#1394)
• e12e775 fix(store): apply same-project relations across endpoint scopes (#1374)
• 76f938b fix(store): claim terminal legacy session ownership atomically (#1400)
• 3333771 fix(store): preserve blank session directories through local import (#1287) (#1298)
• 615a7b2 fix(store): reject unsafe network filesystem WAL (#1364)
• 111d1fd perf(store): index project-scoped exports on main (#1379)
• 6404679 test(store): cover network filesystem safety and recovery (#1365)