v3.0.0

Engram 3.0.0 is a major release. It requires an explicit `expected_project` for every observation update and delete, moves the Go module path to `/v3`, adds OpenCode 2.x support, and confirms host-session registration before agent integrations bind memory writes. This tag publishes the **core binary**; the Pi package `gentle-engram` has a separate npm release channel (details below).

## What changed since v2.2.1

### Agent integrations and session attribution

- Add OpenCode 2.x support through a dual-major plugin entrypoint: the same handlers serve the V1 `server` entry and the V2 `setup` entry, and CI now runs the OpenCode plugin tests ([#1526](https://github.com/Gentleman-Programming/engram/pull/1526)).
- Claude Code, Codex, and OpenCode confirm the host session's registration before binding classified Engram writes and prompt capture, and deny failed, ended, or mismatched registrations instead of persisting to a stale session ([#1478](https://github.com/Gentleman-Programming/engram/pull/1478), [#1513](https://github.com/Gentleman-Programming/engram/pull/1513), [#1479](https://github.com/Gentleman-Programming/engram/pull/1479), [#1521](https://github.com/Gentleman-Programming/engram/pull/1521), [#1488](https://github.com/Gentleman-Programming/engram/pull/1488)). The Claude Code plugin is released under new versions so existing installations receive the session-binding hook ([#1518](https://github.com/Gentleman-Programming/engram/pull/1518), [#1571](https://github.com/Gentleman-Programming/engram/pull/1571)).
- `POST /sessions` accepts `resume: true`: when the requested session has ended, the core reuses a live `<id>:resume:N` continuation or creates the next one atomically, and never reopens ended sessions. OpenCode uses it to keep capturing after restarts and reloads ([#1564](https://github.com/Gentleman-Programming/engram/pull/1564)).
- OpenCode validates session acknowledgements, surfaces deduplicated degraded-operation warnings in tool results, forwards V2 `session.updated` events, and lets explicit writes from an ambiguous multi-repo directory reach MCP recovery ([#1572](https://github.com/Gentleman-Programming/engram/pull/1572), [#1573](https://github.com/Gentleman-Programming/engram/pull/1573), [#1576](https://github.com/Gentleman-Programming/engram/pull/1576)).
- `engram setup codex` no longer writes `model_instructions_file` or `experimental_compact_prompt_file`, which replaced Codex's built-in instructions, and removes them when a previous version wrote them ([#1550](https://github.com/Gentleman-Programming/engram/pull/1550)). On Windows, the Codex session-start hook starts a missing local server detached from the hook pipes ([#1538](https://github.com/Gentleman-Programming/engram/pull/1538)).
- `engram setup pi` no longer registers an Engram MCP server or installs `pi-mcp-adapter`; existing entries are preserved and reported ([#1475](https://github.com/Gentleman-Programming/engram/pull/1475), [#1578](https://github.com/Gentleman-Programming/engram/pull/1578)).
- The server advertises `capabilities.isolated_session_registration` and rejects isolated registrations that conflict with an existing session's directory without changing that session ([#1592](https://github.com/Gentleman-Programming/engram/pull/1592)).

### Memory, projects, and MCP

- `mem_get_observation` accepts an optional `project` for response context and falls back to the observation's stored project when the working directory is ambiguous; retrieval stays ID-based ([#1444](https://github.com/Gentleman-Programming/engram/pull/1444), [#1490](https://github.com/Gentleman-Programming/engram/pull/1490)).
- Add `engram projects merge` with `--dry-run` and `--apply` for one explicitly named separator-variant merge; merges into the reserved `inbox` project are rejected ([#1457](https://github.com/Gentleman-Programming/engram/pull/1457)).
- Preserve prompt inbox identity through sync, backup export, and import, so deleted prompt identities cannot reappear ([#1464](https://github.com/Gentleman-Programming/engram/pull/1464)).
- Ambiguous-project errors list available projects in alphabetical order ([#1565](https://github.com/Gentleman-Programming/engram/pull/1565)).
- Project names detected from Git remotes decode one layer of URL encoding (for example, Azure DevOps `My%20Project`), matching `engram cloud enroll`; `--literal-project` preserves percent-encoded names. Existing stored repository bindings are reused as-is ([#1590](https://github.com/Gentleman-Programming/engram/pull/1590)).

### Sync, Cloud, and doctor repairs

- Apply a superseded session delete at its original chunk position, so chunks that delete and recreate a session no longer stall on a foreign-key failure ([#1520](https://github.com/Gentleman-Programming/engram/pull/1520)).
- Include legacy blank-project session mutations in Cloud upgrade diagnosis and repair; Cloud export stops until they are repaired ([#1528](https://github.com/Gentleman-Programming/engram/pull/1528)).
- Report session-index failures instead of acknowledging an identical Cloud chunk replay as successful ([#1474](https://github.com/Gentleman-Programming/engram/pull/1474)).
- Preserve paused autosync status when an in-progress cycle completes or fails ([#1592](https://github.com/Gentleman-Programming/engram/pull/1592)).
- Add the `orphaned_pending_relations` doctor check and a backup-first `engram doctor repair --check orphaned_pending_relations` route; `engram conflicts stats` reports orphaned relations ([#1472](https://github.com/Gentleman-Programming/engram/pull/1472)).
- Add `engram doctor discard-empty-prompt` to preview or discard an irrecoverable legacy empty prompt mutation; applying requires a backup path ([#1579](https://github.com/Gentleman-Programming/engram/pull/1579)).

### Obsidian, build, and CI

- The Obsidian plugin consumes `GET /export` observations as full snapshots instead of silently accepting an incompatible payload, and its build and typecheck are reproducible in CI ([#1487](https://github.com/Gentleman-Programming/engram/pull/1487), [#1486](https://github.com/Gentleman-Programming/engram/pull/1486)).
- CI runs the existing policy and Obsidian regression suites; the dead-code analyzer uses the module's Go toolchain; manual Pi publication validates the full tag ref ([#1517](https://github.com/Gentleman-Programming/engram/pull/1517), [#1570](https://github.com/Gentleman-Programming/engram/pull/1570), [#1473](https://github.com/Gentleman-Programming/engram/pull/1473)).

## Breaking and compatibility changes

### Go module path

Source consumers must use the v3 module path ([#1598](https://github.com/Gentleman-Programming/engram/pull/1598)):

```bash
go install github.com/Gentleman-Programming/engram/v3/cmd/engram@v3.0.0
```

Code importing `github.com/Gentleman-Programming/engram/v2/...` packages must update its import paths to `/v3`.

### Observation updates and deletes require `expected_project`

Every caller must assert the observation's owner before mutating it ([#1575](https://github.com/Gentleman-Programming/engram/pull/1575)):

- **HTTP:** `PATCH /observations/{id}` and `DELETE /observations/{id}` require `?expected_project=<project>`. A missing, blank, or invalid value returns `400`; an owner mismatch returns `409`; a missing observation returns `404`. A rejected request changes no observation, revision, or sync queue entry.
- **MCP:** `mem_update` and `mem_delete` require an explicit `expected_project` argument. `mem_update` no longer falls back to the stored owner when the working directory is ambiguous; `mem_get_observation` keeps that fallback for reads.
- **Pi:** the Pi-native `mem_update` and `mem_delete` tools require the same argument; see the Pi section below.

`expected_project` is a caller assertion, not authentication or tenant isolation. CLI and internal maintenance paths are unchanged.

### Agent setup behavior

- `engram setup pi` no longer creates an Engram MCP entry or installs `npm:pi-mcp-adapter`. Pi 0.99.0 and later include built-in MCP for other servers; an installed `/mcp` extension replaces it. Remove a retained `mcpServers.engram` entry manually for native-only writes ([#1475](https://github.com/Gentleman-Programming/engram/pull/1475), [#1578](https://github.com/Gentleman-Programming/engram/pull/1578)).
- Claude Code SessionStart no longer runs MCP registration. Register or repair it with `engram setup claude-code` ([#1571](https://github.com/Gentleman-Programming/engram/pull/1571)).
- `engram setup codex` removes legacy instruction-file override keys from the Codex config ([#1550](https://github.com/Gentleman-Programming/engram/pull/1550)).

## Pi 0.2.0 on npm

`engram setup pi` on this tag installs [`gentle-engram` 0.2.0](https://www.npmjs.com/package/gentle-engram/v/0.2.0), published from tag [`pi-v0.2.0`](https://github.com/Gentleman-Programming/engram/releases/tag/pi-v0.2.0), and upgrades existing `gentle-engram` 0.1.16 declarations ([#1604](https://github.com/Gentleman-Programming/engram/pull/1604)). Pi 0.2.0 sends `expected_project`; Pi 0.1.16 does not, so a v3.0.0 server rejects its `mem_update` and `mem_delete` calls with `400`. Rerun `engram setup pi`, or update an existing Pi installation directly:

```bash
pi install npm:gentle-engram@0.2.0
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`. Source installs use the `/v3` module path shown above.
3. Update every HTTP and MCP client that updates or deletes observations to send `expected_project`.
4. Run `engram doctor` and follow only the guidance applicable to your store.
5. Rerun `engram setup codex` to remove legacy instruction overrides, and `engram setup claude-code` if Claude Code's MCP registration is missing.
6. Restart long-running MCP and agent sessions to pick up the new binary. If you use Pi, rerun `engram setup pi` or install `gentle-engram` 0.2.0 as shown above.

## Known limitations accepted for this release

- **Hook-based session attribution:** registration confirmation runs inside agent hooks. Skipped, bypassed, or timed-out hooks are not protected, and direct or manual MCP saves are outside this guard.
- **OpenCode 2.x late parent attribution:** delayed parent attribution through V2 `session.updated` is covered by regression tests but has not been verified in a live runtime.
- **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.1...v3.0.0`](https://github.com/Gentleman-Programming/engram/compare/v2.2.1...v3.0.0).

## 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 (one representative issue per person):

@alfonsitoOoo ([#1549](https://github.com/Gentleman-Programming/engram/issues/1549)) · @carolitascl ([#1510](https://github.com/Gentleman-Programming/engram/issues/1510)) · @danielgap ([#1502](https://github.com/Gentleman-Programming/engram/issues/1502)) · @dkalasic ([#1506](https://github.com/Gentleman-Programming/engram/issues/1506))

@duquejmz ([#1422](https://github.com/Gentleman-Programming/engram/issues/1422)) · @Ealanisln ([#1512](https://github.com/Gentleman-Programming/engram/issues/1512)) · @EmilZapata ([#1509](https://github.com/Gentleman-Programming/engram/issues/1509)) · @JlMoreno00 ([#1507](https://github.com/Gentleman-Programming/engram/issues/1507))

@jorgehn98 ([#1561](https://github.com/Gentleman-Programming/engram/issues/1561)) · @juanda1434 ([#1562](https://github.com/Gentleman-Programming/engram/issues/1562)) · @JuanjoPas ([#1455](https://github.com/Gentleman-Programming/engram/issues/1455)) · @Julpach65 ([#1543](https://github.com/Gentleman-Programming/engram/issues/1543))

@lucasmiachon-blip ([#1471](https://github.com/Gentleman-Programming/engram/issues/1471)) · @luis63e ([#1445](https://github.com/Gentleman-Programming/engram/issues/1445)) · @mauroziux ([#1569](https://github.com/Gentleman-Programming/engram/issues/1569)) · @nicoarias81 ([#1557](https://github.com/Gentleman-Programming/engram/issues/1557))

@northems ([#1470](https://github.com/Gentleman-Programming/engram/issues/1470)) · @orebarranco ([#1551](https://github.com/Gentleman-Programming/engram/issues/1551)) · @pepa22 ([#1508](https://github.com/Gentleman-Programming/engram/issues/1508)) · @quirozino ([#1494](https://github.com/Gentleman-Programming/engram/issues/1494))

@RubenValdez ([#1583](https://github.com/Gentleman-Programming/engram/issues/1583)) · @San73r00z ([#1296](https://github.com/Gentleman-Programming/engram/issues/1296)) · @ScorpionConMate ([#1220](https://github.com/Gentleman-Programming/engram/issues/1220))

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

- @alfonsitoOoo ([#1550](https://github.com/Gentleman-Programming/engram/pull/1550))
- @danielgap ([#1520](https://github.com/Gentleman-Programming/engram/pull/1520))
- @dnlrsls ([#1575](https://github.com/Gentleman-Programming/engram/pull/1575))
- @josegarvinvictoria ([#1490](https://github.com/Gentleman-Programming/engram/pull/1490))
- @Reaan06 ([#1444](https://github.com/Gentleman-Programming/engram/pull/1444))

## Changelog
* 15a2f78885d7ad8ced23b2d1d88383e9bb472c17 fix(setup): pin engram setup pi to gentle-engram 0.2.0 (#1604)
* ce51810bd351f397e49728d6a5be81679cf18554 chore(pi): bump gentle-engram to 0.2.0 (#1602)
* b08308adfbce15584a71f161295b6870aef65ce3 chore(module)!: move Go module path to /v3 for the v3.0.0 release (#1598)
* a43183c22445486eff35bf519b6122b3769e9f02 fix(cloud): preserve literal project identities (#1583) (#1590)
* 9e17c0d84dcaec858f407dc771e43eb2903cc71a test(claude): verify live-host persistence and ended-session refusal (#1594)
* 204156e83a1849d95e263d3cf5b4d8d87a8177a1 fix(pi): isolate explicit cross-project memory saves (#1592)
* 4cb56ac085f53088c7058ea17e4c398f739f1a5b fix(pi): deliver memory protocol via appendSystemPrompt (#1589)
* 2f1e5451fcd1884ebdaeec5bfe0d98d378a6073c fix(pi): enable cloud autosync for the plugin-launched server (#1587)
* 76feaee84a1e33f48ae49c798635ee753e410843 fix(doctor): safely discard legacy empty prompt mutations (#1579)
* a65917f3072ab4f26780bcf52427eba3963bef46 fix(opencode): preserve ambiguous write recovery (#1576)
* 6af3a4b6a408388e2782c4f3c94b3a4ed3cd80c4 refactor(pi): use core resume registration for resumed sessions (#1581)
* e8c0ce3221d1ca20ea4362f9d7322b0a88b3df38 fix(server)!: require expected project for observation mutations (#1575)
* ea890413bd3c8c2409f9092e64882ff6b542960f fix(pi): stop installing pi-mcp-adapter in Pi setup (#1578)
* 099e80d051c8151c29861690835bf08533502c38 fix(conflicts): surface and reconcile orphaned pending relations (#1472)
* 4a31d91df55c3e0f77edefbd9553e07a163c08ec fix(pi): route background warnings through the owning UI (#1574)
* ca3e4478ff3da1f3ea915cab452ffb77c436aa38 fix(opencode): forward V2 session updates (#1573)
* 96e009abcd9a19b3d016470d711dc8b65ec1237c fix(opencode): validate acknowledgements and surface degraded operations (#1572)
* 58d7029d1b1a50716c397ed49a377444c1f68add fix(mcp): anchor get/update by id on stored project when cwd is ambiguous (#1490)
* ccd3520934f1c6fa2b7d316713f2a0f985a156fd fix(scripts): align deadcode analyzer with module Go toolchain (#1570)
* 9786dae575147254c200d8bc0ae0c009365ff823 fix(claude): avoid repeated MCP setup during session start (#1571)
* cd5e1380f768e203d12c329af48cec614e2fedb1 fix(codex): stop replacing Codex's built-in instructions (#1550)
* 5455dc245044589445e7d7a83fdff8c84dfb9689 fix(pi): use host-provided typebox peer (#1567)
* 725932f5b5b948c83959d1967df55343b9a6cfff fix(opencode): resume sessions whose Engram session already ended (#1564)
* f0e56f8228e5b28d69d51400c00ebdc62705d69a fix(store): check relation sync session setup error (#1566)
* c0774674f167833d62da23ce0b582fabe569f17a fix(project): stabilize available project ordering (#1565)
* 85eca9892745e4c74c3464aa20845af7a39d7d08 fix(pi): redact private blocks before truncating prompts (#1559)
* 5a95191eda801ac41d3751e6d5d4cbdefd2add20 feat(opencode): support OpenCode 2.x with a dual-major plugin entrypoint (#1526)
* dd1261149f4074d95d78193e013cc86b8819d25e chore(review): track prompt inbox identity foundation chain (#1464)
* 3284dcc2f20278ea8d37277350be9d96155697a3 docs(pi): clarify native-only setup across package release (#1546)
* bb3ec5cab17371510289df7126e9070c08af7fab fix(codex): detach Windows server from hook pipes (#1538)
* 3ba7df6235f5a58ca0898dc312421881c1fb0acf fix(sync): repair legacy blank-project session mutations (#1528)
* cfa7b7716164467a63444c9605b2ca4c3cc3d0c6 test(codex): cover session-start attribution through persistence (#1529)
* 9a0dd66b0074bd848df72dd8b772a553dffbc01e test(opencode): verify host bindings in isolated store (#1485)
* 78c85e0fc21c1f29bca5b71f8d1c27226f020489 test(pi): verify host-attributed saves reach isolated store (#1484)
* 2e28f195b24d90c1b6622639d8199b205b45eee3 fix(sync): apply superseded session deletes at their chunk position (#1520)
* 3db907f8983eb672328a4d4faea61931e06998e2 test(claude): verify interleaved host writes persist separately (#1483)
* 22dc220a4d5f19345c3ca1730d217250a98a14c9 test(mcp): preserve manual fallback with foreign runtime session (#1481)
* a12562caf47383faa1ed944df67d342ac2788f0d test(codex): verify interleaved host writes persist separately (#1482)
* b6219f7fcadf9cb341d3abe3e69b4430967bf5bb fix(codex): confirm host registration before prompt capture (#1521)
* 923a26c5356915c426e9a6e8f3ea1c8df6e97b4b ci(tests): run existing policy and Obsidian regression suites (#1517)
* 6d1e8b5a1e25e0ff97d01bc27dbb3edff5ad19b1 fix(plugin): release Claude session hook under a new plugin version (#1518)
* 094c07fc0ee77df8299ebc839d989b48f2a5ebb0 fix(codex): withhold hook memory protocol without registration (#1488)
* 70b4a0cff6a3ef48832dc72098ebf42ba2f3aba2 fix(opencode): confirm registered host identity before binding writes (#1479)
* 3d47bae62a84fe6d84e6ddccd4f8eb359e7c40c9 fix(codex): confirm host registration before bound writes (#1513)
* c556cca9d3b7225f1078123c2d80dc0a6273cd33 fix(claude): confirm host session before bound writes (#1478)
* 9454bf56a36a317e6cbed73708eb7c15608b3b07 fix(pi): prevent ending a foreign runtime session (#1477)
* 9dad41baf01c6b9dacfd13808d614987c787ebc7 fix(pi): keep agent writes on native tools during init (#1476)
* a349bc86351621b22759a03864287900ba71d7be fix(pi): stop registering engram mcp during go setup (#1475)
* be0af959c52a3969bf49e005c498caeb6c31e7ee fix(obsidian): consume export observations as full snapshots (#1487)
* 72a4b7b8930b0d24dd773402fc940f883758699f fix(obsidian): make plugin build and typecheck reproducible (#1486)
* 618e30f68f0f2e3b736df91fcfbaaad279ccd3d2 fix(cloud): propagate replay session index failures (#1474)
* 26db54f36ff76312881b3dc4d50d434b14a4c384 fix(release): validate manual Pi publish event ref (#1473)
* c61f601ee9cc3a9cba6abbedd6bef2382318eada feat(cli): merge explicitly named project variants (#1457)
* 3eb2832a8e21ae2d97f1a7e2ace0cc86de7d958a fix(pi): require explicit import of cloned memories (#1456)
* f0274a6191c07fd0730cb999f443e3b0daaf6823 feat(pi): expose bounded compact mem_context options (#1447)
* 3692e1aff0f70a1ef41f0ce3ca7b9f54aad2dc68 docs(agents): link issue-first contribution workflow (#1450)
* 5ddb13045d7a55d66b87703c3d97f7f5b399638e feat(mcp): add project override to mem_get_observation (#1444)