v2.1.0

Engram 2.1.0 builds on the v2 foundation with atomic observation replacements, more reliable local storage and Cloud synchronization, and safer agent integrations. This tag publishes the core binary. The Pi package gentle-engram 0.1.15 was published separately after this core tag; see Pi 0.1.15 below.

What changed since v2.0.0

Memory and local data integrity

• Added atomic literal find-and-replace for existing observations through the validated MCP and HTTP contracts (#1342).
• Acquired SQLite write locks at transaction start to avoid SQLITE_BUSY_SNAPSHOT failures in read-then-write transactions, and upgraded the SQLite runtime with the upstream WAL-reset integrity fix (#1243, #1308). These fixes do not make network filesystems safe for the database; see #1292.
• Added a confirmed, local-only doctor repair path for observations whose parent session is missing; diagnostics now distinguish repairable findings from informational checks (#1268, #1265).

Cloud and sync convergence

• Materialized mutation-only session, observation, and prompt uploads; preserved local hard-delete tombstones during export (#1312, #1313).
• Continued pulling remote changes when enrollment blocks a push, and deferred pulled records only when their parent session is verifiably absent (#1309, #1274).

Agent integrations

• Added a native Codex user-prompt hook command and tightened executable selection. Windows adapter activation and end-to-end timeout verification are not included; #1271 remains open for v2.2.0 (#1356, #1354).
• Bound supported Claude Code writes to their runtime session and added a declarative engram setup kimi adapter for Kimi Code CLI (#1352, #793).
• Improved Pi detection of legacy pre-v2 servers and bounded retry timing in the package bundled with this core tag (#1279).

Pi 0.1.15 is a separate release

gentle-engram 0.1.15 on npm (pi-v0.1.15 source tag) improves transport timeout handling for #1272: bounded read retries, a write timeout budget that accommodates slower writes, and explicit unknown outcomes when a write may already have been applied. It does not silently retry uncertain writes.

pi install npm:gentle-engram@0.1.15

The v2.1.0 core tag still pins Pi 0.1.14 in its bundled setup command. Install Pi 0.1.15 explicitly if you need this patch; it is not part of the v2.1.0 core archives.

Upgrade checklist

1. Back up your local database and configuration. Keep the SQLite database on a local filesystem, not NFS/network storage.
2. Upgrade the core binary with the release archive or Homebrew; verify the archive against checksums.txt when downloading manually.
3. Run engram doctor and follow only the repair guidance applicable to your store. Restart long-running agent and MCP sessions to load the new binary.
4. If you use Pi, install gentle-engram 0.1.15 separately with the command above and restart Pi.

Known limitations accepted for this release

• Network filesystem data safety: #1292 — placing the local SQLite database on NFS/network storage can cause WAL corruption. Use a local filesystem and retain backups.
• Export/import: #1287 — exports with blank session directories can fail to import.
• Windows sync: #1175 — a large multi-project database can make local sync hang.
• Contributor code generation: #1260 — documented go tool templ generate fails without a tool directive; use make templ instead.
• Windows Codex hook: #1271 — its existing shell adapter can still exceed the two-second timeout. The native command added in #1356 is not yet wired on Windows; adapter activation and end-to-end timeout verification are deferred to v2.2.0.

Installation and full comparison

Release archives cover Linux, macOS, and Windows on amd64 and arm64, with checksums.txt; the stable Homebrew formula is also at 2.1.0. See the full core diff in v2.0.0...v2.1.0. The Pi patch has its own tag and npm provenance.

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 filed after v2.0.0 and before this tag, plus earlier reports directly linked to the release (one representative issue per person):

@aaronmasm (#1288) · @Agustin-Prieto (#1287) · @ajavanma (#1261) · @Albe841114 (#1247)

@alesierraalta (#1330) · @Alexso9410 (#1166) · @BenjaMolina (#1271) · @blak0p (#602)

@carolitascl (#1307) · @cristiandavidcaminos (#1135) · @danielgap (#1297) · @despinosaqualit (#1269)

@diego-de-sousa (#1255) · @dnlrsls (#1359) · @edwinvalenc (#1346) · @efirvida (#1292)

@ElCaaarnal (#1340) · @garcialopezco (#1273) · @GhandyP (#1182) · @gtrafael (#1332)

@Haiagari (#1272) · @hjagar (#1175) · @IbatoLionDev (#1278) · @inmoautos (#1353)

@JAAvila-Of (#650) · @jefer94 (#1306) · @jemanuelp (#1351) · @jesusjbriceno (#1344)

@juliobas (#1335) · @lbatmad (#1242) · @LCubero (#1275) · @leoscricca (#1357)

@LucasOliveira-dev2026 (#1256) · @marcoandres (#1345) · @matraket (#1323) · @MiguezPablo (#1294)

@rjoleinik (#1305) · @San73r00z (#1296) · @santiagopm (#1301) · @smachi (#1300)

@TobiasVeiga00 (#1262) · @x4barin (#1355) · @yeerliin (#1302)

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

• @ajavanma (#1280)
• @danielgap (#1164)
• @dnlrsls (#1267)
• @ElCaaarnal (#1341)
• @JAAvila-Of (#793)
• @josegarvinvictoria (#1265)
• @Rafaeldelinares (#1243)

Changelog

• 3090703 chore(lint): format remaining Go tests (#1317)
• ad2e9be chore(mcp): dedupe session id schema guidance (#1319)
• f74102f ci(workflows): add merge queue support (#1290)
• 01bbdf6 docs(cloud): pin production container image (#1318)
• 25c9b7c docs(readme): animate the banner (#1341)
• 08bcdfa feat(memory): add atomic observation replacements (#1342)
• ceb28a0 feat(setup): add kimi agent adapter for Kimi Code CLI (#793)
• 9e34bf3 fix(claude): bind writes to hook session (#1315)
• 48d5fd9 fix(claude): wire authoritative session binding (#1352)
• 3a1a04b fix(cli): reject conflicting conflict scan modes (#1280)
• fa3acd6 fix(cloud): materialize mutation-only uploads (#1312)
• cf7f82e fix(codex): add native prompt hook on main (#1356)
• 9ac5cef fix(doctor): clarify diagnostic-only checks (#1265)
• 9ac3750 fix(doctor): repair orphaned observation sessions (#1268)
• f3f09e5 fix(doctor): require authoritative project evidence (#1310)
• 9f9d637 fix(import): preserve orphaned relation audits (#1311)
• a58ebdc fix(mcp): keep project names out of shell guidance (#1314)
• bbd352c fix(pi): classify legacy pre-v2 servers and retry deterministic failures on a fixed 5s window (#1279)
• 6ad49f1 fix(session): enforce runtime owner liveness (#1267)
• 9997a85 fix(setup): pin Codex executable authority on main (#1354)
• 3dd1f66 fix(store): acquire write lock on begin to eliminate SQLITE_BUSY_SNAPSHOT (#1243)
• c1536ad fix(store): defer pulled records with missing sessions (#1274)
• 4d8f996 fix(store): upgrade SQLite WAL integrity (#1308)
• 33f0fed fix(sync): export local hard-delete tombstones (#1313)
• 998fc8a fix(sync): pull while enrollment blocks push (#1309)
• 1ec0fe9 fix(test): isolate Windows temp Git discovery (#1328)
• 6c4bab2 fix(test): select Git for Windows root Bash (#1339)
• 3199156 fix(workflows): resolve pull requests for merge groups (#1329)
• 7087098 fix: treat blank Engram environment values as unset (#1299)