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).
• 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, #1513, #1479, #1521, #1488). The Claude Code plugin is released under new versions so existing installations receive the session-binding hook (#1518, #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).
• 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, #1573, #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). On Windows, the Codex session-start hook starts a missing local server detached from the hook pipes (#1538).
• engram setup pi no longer registers an Engram MCP server or installs pi-mcp-adapter; existing entries are preserved and reported (#1475, #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).

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, #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).
• Preserve prompt inbox identity through sync, backup export, and import, so deleted prompt identities cannot reappear (#1464).
• Ambiguous-project errors list available projects in alphabetical order (#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).

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).
• Include legacy blank-project session mutations in Cloud upgrade diagnosis and repair; Cloud export stops until they are repaired (#1528).
• Report session-index failures instead of acknowledging an identical Cloud chunk replay as successful (#1474).
• Preserve paused autosync status when an in-progress cycle completes or fails (#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).
• Add engram doctor discard-empty-prompt to preview or discard an irrecoverable legacy empty prompt mutation; applying requires a backup path (#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, #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, #1570, #1473).

Breaking and compatibility changes

Go module path

Source consumers must use the v3 module path (#1598):

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):

• 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, #1578).
• Claude Code SessionStart no longer runs MCP registration. Register or repair it with engram setup claude-code (#1571).
• engram setup codex removes legacy instruction-file override keys from the Codex config (#1550).

Pi 0.2.0 on npm

engram setup pi on this tag installs gentle-engram 0.2.0, published from tag pi-v0.2.0, and upgrades existing gentle-engram 0.1.16 declarations (#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:

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.

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) · @carolitascl (#1510) · @danielgap (#1502) · @dkalasic (#1506)

@duquejmz (#1422) · @Ealanisln (#1512) · @EmilZapata (#1509) · @JlMoreno00 (#1507)

@jorgehn98 (#1561) · @juanda1434 (#1562) · @JuanjoPas (#1455) · @Julpach65 (#1543)

@lucasmiachon-blip (#1471) · @luis63e (#1445) · @mauroziux (#1569) · @nicoarias81 (#1557)

@northems (#1470) · @orebarranco (#1551) · @pepa22 (#1508) · @quirozino (#1494)

@RubenValdez (#1583) · @San73r00z (#1296) · @ScorpionConMate (#1220)

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

• @alfonsitoOoo (#1550)
• @danielgap (#1520)
• @dnlrsls (#1575)
• @josegarvinvictoria (#1490)
• @Reaan06 (#1444)

Changelog

• 15a2f78 fix(setup): pin engram setup pi to gentle-engram 0.2.0 (#1604)
• ce51810 chore(pi): bump gentle-engram to 0.2.0 (#1602)
• b08308a chore(module)!: move Go module path to /v3 for the v3.0.0 release (#1598)
• a43183c fix(cloud): preserve literal project identities (#1583) (#1590)
• 9e17c0d test(claude): verify live-host persistence and ended-session refusal (#1594)
• 204156e fix(pi): isolate explicit cross-project memory saves (#1592)
• 4cb56ac fix(pi): deliver memory protocol via appendSystemPrompt (#1589)
• 2f1e545 fix(pi): enable cloud autosync for the plugin-launched server (#1587)
• 76feaee fix(doctor): safely discard legacy empty prompt mutations (#1579)
• a65917f fix(opencode): preserve ambiguous write recovery (#1576)
• 6af3a4b refactor(pi): use core resume registration for resumed sessions (#1581)
• e8c0ce3 fix(server)!: require expected project for observation mutations (#1575)
• ea89041 fix(pi): stop installing pi-mcp-adapter in Pi setup (#1578)
• 099e80d fix(conflicts): surface and reconcile orphaned pending relations (#1472)
• 4a31d91 fix(pi): route background warnings through the owning UI (#1574)
• ca3e447 fix(opencode): forward V2 session updates (#1573)
• 96e009a fix(opencode): validate acknowledgements and surface degraded operations (#1572)
• 58d7029 fix(mcp): anchor get/update by id on stored project when cwd is ambiguous (#1490)
• ccd3520 fix(scripts): align deadcode analyzer with module Go toolchain (#1570)
• 9786dae fix(claude): avoid repeated MCP setup during session start (#1571)
• cd5e138 fix(codex): stop replacing Codex's built-in instructions (#1550)
• 5455dc2 fix(pi): use host-provided typebox peer (#1567)
• 725932f fix(opencode): resume sessions whose Engram session already ended (#1564)
• f0e56f8 fix(store): check relation sync session setup error (#1566)
• c077467 fix(project): stabilize available project ordering (#1565)
• 85eca98 fix(pi): redact private blocks before truncating prompts (#1559)
• 5a95191 feat(opencode): support OpenCode 2.x with a dual-major plugin entrypoint (#1526)
• dd12611 chore(review): track prompt inbox identity foundation chain (#1464)
• 3284dcc docs(pi): clarify native-only setup across package release (#1546)
• bb3ec5c fix(codex): detach Windows server from hook pipes (#1538)
• 3ba7df6 fix(sync): repair legacy blank-project session mutations (#1528)
• cfa7b77 test(codex): cover session-start attribution through persistence (#1529)
• 9a0dd66 test(opencode): verify host bindings in isolated store (#1485)
• 78c85e0 test(pi): verify host-attributed saves reach isolated store (#1484)
• 2e28f19 fix(sync): apply superseded session deletes at their chunk position (#1520)
• 3db907f test(claude): verify interleaved host writes persist separately (#1483)
• 22dc220 test(mcp): preserve manual fallback with foreign runtime session (#1481)
• a12562c test(codex): verify interleaved host writes persist separately (#1482)
• b6219f7 fix(codex): confirm host registration before prompt capture (#1521)
• 923a26c ci(tests): run existing policy and Obsidian regression suites (#1517)
• 6d1e8b5 fix(plugin): release Claude session hook under a new plugin version (#1518)
• 094c07f fix(codex): withhold hook memory protocol without registration (#1488)
• 70b4a0c fix(opencode): confirm registered host identity before binding writes (#1479)
• 3d47bae fix(codex): confirm host registration before bound writes (#1513)
• c556cca fix(claude): confirm host session before bound writes (#1478)
• 9454bf5 fix(pi): prevent ending a foreign runtime session (#1477)
• 9dad41b fix(pi): keep agent writes on native tools during init (#1476)
• a349bc8 fix(pi): stop registering engram mcp during go setup (#1475)
• be0af95 fix(obsidian): consume export observations as full snapshots (#1487)
• 72a4b7b fix(obsidian): make plugin build and typecheck reproducible (#1486)
• 618e30f fix(cloud): propagate replay session index failures (#1474)
• 26db54f fix(release): validate manual Pi publish event ref (#1473)
• c61f601 feat(cli): merge explicitly named project variants (#1457)
• 3eb2832 fix(pi): require explicit import of cloned memories (#1456)
• f0274a6 feat(pi): expose bounded compact mem_context options (#1447)
• 3692e1a docs(agents): link issue-first contribution workflow (#1450)
• 5ddb130 feat(mcp): add project override to mem_get_observation (#1444)