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](#pi-0115-is-a-separate-release) 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](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/pull/1243), [#1308](https://github.com/Gentleman-Programming/engram/pull/1308)). These fixes do **not** make network filesystems safe for the database; see [#1292](https://github.com/Gentleman-Programming/engram/issues/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](https://github.com/Gentleman-Programming/engram/pull/1268), [#1265](https://github.com/Gentleman-Programming/engram/pull/1265)).

### Cloud and sync convergence

- Materialized mutation-only session, observation, and prompt uploads; preserved local hard-delete tombstones during export ([#1312](https://github.com/Gentleman-Programming/engram/pull/1312), [#1313](https://github.com/Gentleman-Programming/engram/pull/1313)).
- Continued pulling remote changes when enrollment blocks a push, and deferred pulled records only when their parent session is verifiably absent ([#1309](https://github.com/Gentleman-Programming/engram/pull/1309), [#1274](https://github.com/Gentleman-Programming/engram/pull/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](https://github.com/Gentleman-Programming/engram/issues/1271) remains open for v2.2.0 ([#1356](https://github.com/Gentleman-Programming/engram/pull/1356), [#1354](https://github.com/Gentleman-Programming/engram/pull/1354)).
- Bound supported Claude Code writes to their runtime session and added a declarative `engram setup kimi` adapter for Kimi Code CLI ([#1352](https://github.com/Gentleman-Programming/engram/pull/1352), [#793](https://github.com/Gentleman-Programming/engram/pull/793)).
- Improved Pi detection of legacy pre-v2 servers and bounded retry timing in the package bundled with this core tag ([#1279](https://github.com/Gentleman-Programming/engram/pull/1279)).

## Pi 0.1.15 is a separate release

[`gentle-engram` 0.1.15 on npm](https://www.npmjs.com/package/gentle-engram/v/0.1.15) ([`pi-v0.1.15` source tag](https://github.com/Gentleman-Programming/engram/tree/pi-v0.1.15)) improves transport timeout handling for [#1272](https://github.com/Gentleman-Programming/engram/issues/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.

```bash
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](https://github.com/Gentleman-Programming/engram/issues/1292) — placing the local SQLite database on NFS/network storage can cause WAL corruption. Use a local filesystem and retain backups.
- **Export/import:** [#1287](https://github.com/Gentleman-Programming/engram/issues/1287) — exports with blank session directories can fail to import.
- **Windows sync:** [#1175](https://github.com/Gentleman-Programming/engram/issues/1175) — a large multi-project database can make local sync hang.
- **Contributor code generation:** [#1260](https://github.com/Gentleman-Programming/engram/issues/1260) — documented `go tool templ generate` fails without a tool directive; use `make templ` instead.
- **Windows Codex hook:** [#1271](https://github.com/Gentleman-Programming/engram/issues/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`](https://github.com/Gentleman-Programming/engram/compare/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](https://github.com/Gentleman-Programming/engram/issues/1288)) · @Agustin-Prieto ([#1287](https://github.com/Gentleman-Programming/engram/issues/1287)) · @ajavanma ([#1261](https://github.com/Gentleman-Programming/engram/issues/1261)) · @Albe841114 ([#1247](https://github.com/Gentleman-Programming/engram/issues/1247))

@alesierraalta ([#1330](https://github.com/Gentleman-Programming/engram/issues/1330)) · @Alexso9410 ([#1166](https://github.com/Gentleman-Programming/engram/issues/1166)) · @BenjaMolina ([#1271](https://github.com/Gentleman-Programming/engram/issues/1271)) · @blak0p ([#602](https://github.com/Gentleman-Programming/engram/issues/602))

@carolitascl ([#1307](https://github.com/Gentleman-Programming/engram/issues/1307)) · @cristiandavidcaminos ([#1135](https://github.com/Gentleman-Programming/engram/issues/1135)) · @danielgap ([#1297](https://github.com/Gentleman-Programming/engram/issues/1297)) · @despinosaqualit ([#1269](https://github.com/Gentleman-Programming/engram/issues/1269))

@diego-de-sousa ([#1255](https://github.com/Gentleman-Programming/engram/issues/1255)) · @dnlrsls ([#1359](https://github.com/Gentleman-Programming/engram/issues/1359)) · @edwinvalenc ([#1346](https://github.com/Gentleman-Programming/engram/issues/1346)) · @efirvida ([#1292](https://github.com/Gentleman-Programming/engram/issues/1292))

@ElCaaarnal ([#1340](https://github.com/Gentleman-Programming/engram/issues/1340)) · @garcialopezco ([#1273](https://github.com/Gentleman-Programming/engram/issues/1273)) · @GhandyP ([#1182](https://github.com/Gentleman-Programming/engram/issues/1182)) · @gtrafael ([#1332](https://github.com/Gentleman-Programming/engram/issues/1332))

@Haiagari ([#1272](https://github.com/Gentleman-Programming/engram/issues/1272)) · @hjagar ([#1175](https://github.com/Gentleman-Programming/engram/issues/1175)) · @IbatoLionDev ([#1278](https://github.com/Gentleman-Programming/engram/issues/1278)) · @inmoautos ([#1353](https://github.com/Gentleman-Programming/engram/issues/1353))

@JAAvila-Of ([#650](https://github.com/Gentleman-Programming/engram/issues/650)) · @jefer94 ([#1306](https://github.com/Gentleman-Programming/engram/issues/1306)) · @jemanuelp ([#1351](https://github.com/Gentleman-Programming/engram/issues/1351)) · @jesusjbriceno ([#1344](https://github.com/Gentleman-Programming/engram/issues/1344))

@juliobas ([#1335](https://github.com/Gentleman-Programming/engram/issues/1335)) · @lbatmad ([#1242](https://github.com/Gentleman-Programming/engram/issues/1242)) · @LCubero ([#1275](https://github.com/Gentleman-Programming/engram/issues/1275)) · @leoscricca ([#1357](https://github.com/Gentleman-Programming/engram/issues/1357))

@LucasOliveira-dev2026 ([#1256](https://github.com/Gentleman-Programming/engram/issues/1256)) · @marcoandres ([#1345](https://github.com/Gentleman-Programming/engram/issues/1345)) · @matraket ([#1323](https://github.com/Gentleman-Programming/engram/issues/1323)) · @MiguezPablo ([#1294](https://github.com/Gentleman-Programming/engram/issues/1294))

@rjoleinik ([#1305](https://github.com/Gentleman-Programming/engram/issues/1305)) · @San73r00z ([#1296](https://github.com/Gentleman-Programming/engram/issues/1296)) · @santiagopm ([#1301](https://github.com/Gentleman-Programming/engram/issues/1301)) · @smachi ([#1300](https://github.com/Gentleman-Programming/engram/issues/1300))

@TobiasVeiga00 ([#1262](https://github.com/Gentleman-Programming/engram/issues/1262)) · @x4barin ([#1355](https://github.com/Gentleman-Programming/engram/issues/1355)) · @yeerliin ([#1302](https://github.com/Gentleman-Programming/engram/issues/1302))

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

- @ajavanma ([#1280](https://github.com/Gentleman-Programming/engram/pull/1280))
- @danielgap ([#1164](https://github.com/Gentleman-Programming/engram/pull/1164))
- @dnlrsls ([#1267](https://github.com/Gentleman-Programming/engram/pull/1267))
- @ElCaaarnal ([#1341](https://github.com/Gentleman-Programming/engram/pull/1341))
- @JAAvila-Of ([#793](https://github.com/Gentleman-Programming/engram/pull/793))
- @josegarvinvictoria ([#1265](https://github.com/Gentleman-Programming/engram/pull/1265))
- @Rafaeldelinares ([#1243](https://github.com/Gentleman-Programming/engram/pull/1243))

## Changelog

* 3090703a8a8fb15066738d22c27aa649687066f3 chore(lint): format remaining Go tests (#1317)
* ad2e9beaa1b52f223f925bb7d0a56ed577481851 chore(mcp): dedupe session id schema guidance (#1319)
* f74102fa34219fb9740d451dd007ee9648ce81d2 ci(workflows): add merge queue support (#1290)
* 01bbdf65606e28de6dab3d4d6739bd76eb479487 docs(cloud): pin production container image (#1318)
* 25c9b7cbe3c211e79a2e89a407a4923cab5ef622 docs(readme): animate the banner (#1341)
* 08bcdfa3422d32c3794a65901a3eb3b59ce9ffe6 feat(memory): add atomic observation replacements (#1342)
* ceb28a096b4df7c3f89e5b24d18c90c353965819 feat(setup): add kimi agent adapter for Kimi Code CLI (#793)
* 9e34bf3bcbf12c5c306654adcc3e7dcc88921661 fix(claude): bind writes to hook session (#1315)
* 48d5fd93a1371b15bfcdf9e4f05bf4b5bfed1bba fix(claude): wire authoritative session binding (#1352)
* 3a1a04b33de07afb16f769bcb5fde78a39b665d6 fix(cli): reject conflicting conflict scan modes (#1280)
* fa3acd6f4621ea2cfafe2c30c3508abcced1aabc fix(cloud): materialize mutation-only uploads (#1312)
* cf7f82e20415f81a61b43abc3a0e002c1fa48f54 fix(codex): add native prompt hook on main (#1356)
* 9ac5cef4c32c187ba9de895f1d4855e591afb6a8 fix(doctor): clarify diagnostic-only checks (#1265)
* 9ac3750ed239f6a96890a5eabe7a0aee5d827622 fix(doctor): repair orphaned observation sessions (#1268)
* f3f09e52c2223b285e429b742e516ea89c9d9218 fix(doctor): require authoritative project evidence (#1310)
* 9f9d6379ea5e3b1f748de446b248a2f3d11dc852 fix(import): preserve orphaned relation audits (#1311)
* a58ebdc13433e768b35cc086f7c6c18bf1b68e57 fix(mcp): keep project names out of shell guidance (#1314)
* bbd352ca352d9d329b0139c4a042ee95b9700231 fix(pi): classify legacy pre-v2 servers and retry deterministic failures on a fixed 5s window (#1279)
* 6ad49f17b558004b0fa1f70d161cb9f2fba62aae fix(session): enforce runtime owner liveness (#1267)
* 9997a8531df69e25adda25b93aa5f13b29b38cdf fix(setup): pin Codex executable authority on main (#1354)
* 3dd1f66ccec2bae42f5085ff984b1fbbcc421f0a fix(store): acquire write lock on begin to eliminate SQLITE_BUSY_SNAPSHOT (#1243)
* c1536ad96d4581abff08092b4906c81fe0b0f056 fix(store): defer pulled records with missing sessions (#1274)
* 4d8f99641aa60fe6bc6789cc7c5847ec43700e42 fix(store): upgrade SQLite WAL integrity (#1308)
* 33f0fed36cc8f4b3cfb8f50bba98d101487c3152 fix(sync): export local hard-delete tombstones (#1313)
* 998fc8a9a6737afb34f3008082c5e387ed136d47 fix(sync): pull while enrollment blocks push (#1309)
* 1ec0fe9099cc99184db03a7edef7dd87312797a6 fix(test): isolate Windows temp Git discovery (#1328)
* 6c4bab2401bfa89331c1a237cfbc3b8adf6a35d6 fix(test): select Git for Windows root Bash (#1339)
* 3199156fdb265eefc4a90842fab8046dde6c747e fix(workflows): resolve pull requests for merge groups (#1329)
* 70870987f56ae662acf3cfa36fa7e9a99efa9fb3 fix: treat blank Engram environment values as unset (#1299)