v2.0.0

Engram 2.0.0 is the first stable release of the v2 line. It contains 462 commits since v1.20.0 across project-aware memory, agent integrations, relation-aware retrieval, optional Cloud replication, managed access, diagnostics, and data-integrity hardening.

## What changed since v1.20.0

### Project-aware memory and ownership

- Project identity is resolved consistently from explicit configuration, `ENGRAM_PROJECT`, Git metadata, and the current directory.
- Added `mem_current_project`, project listing/consolidation/pruning, project merging, explicit global reads, and legacy ownership rescue tooling.
- Runtime-bound session attribution prevents writes from being assigned to the wrong session, project, worktree, or agent process.
- Project-scoped reads now behave consistently across CLI, MCP, HTTP, export, review, Obsidian export, and sync status.

### Richer local memory and retrieval

- Added curated prompt capture, topic-key upserts, duplicate/revision tracking, review cycles, local pinning, context-size limits, UTF-8-safe truncation, and compact context output.
- Expanded FTS5 search with project and scope filters, match modes, topic-key results, and CJK/trigram support.
- Added `engram doctor`, expanded project-management commands, improved the Bubble Tea TUI, and introduced beta Obsidian knowledge-graph export.
- Backup export/import now preserves pinned observations and memory relations.

### Conflict detection and memory relations

- `mem_save` can surface likely conflicting memories for review.
- Added `mem_judge` and `mem_compare` for persisted verdicts including `supersedes`, `conflicts_with`, `compatible`, and `not_conflict`.
- Search results expose stable relation annotations.
- CLI and local HTTP surfaces support conflict listing, scanning, statistics, inspection, and deferred-relation replay.
- Relation judgments participate in local, Git, and Cloud synchronization with dependency-aware deferral.

### Agent integrations and session safety

- Expanded setup and integration coverage for Claude Code, OpenCode, Codex, Pi, Gemini CLI, Cursor, VS Code Copilot, Kiro, Kilo Code, Qwen Code, Windsurf, and other MCP clients.
- Added thin plugin and hook integrations for session lifecycle, compaction recovery, passive capture, prompt capture, and Memory Protocol injection.
- Hardened Pi cross-project write protection, shutdown handling, package compatibility, error reporting, and installer/package-version parity.
- Published `gentle-engram@0.1.13`, matching the version installed by `engram setup pi`.
- The OpenCode 1.x adapter now works in Node-hosted plugin environments without relying on Bun globals.

### Optional Cloud replication and autosync

- Added the optional `engram cloud serve` runtime with Postgres-backed storage, project enrollment, compressed chunk transport, mutation push/pull, and deterministic reason codes.
- Added opt-in autosync for `engram serve` and `engram mcp`, with lease protection, bounded retries, exponential backoff, degraded-state reporting, and graceful shutdown.
- Added project-scoped Cloud upgrade commands: `doctor`, `repair`, `bootstrap`, `status`, and pre-verification rollback.
- Added per-target tombstone floors and offline reconciliation for unenrolled legacy journal entries.
- Local SQLite remains authoritative; Cloud remains optional replication and browser visibility.

### Cloud dashboard and managed access

- Added server-rendered project, session, observation, prompt, contributor, health, sync-control, audit, and managed-user dashboard surfaces.
- Added managed principals, human users, project grants, token issuance/revocation, first-admin bootstrap, and audit logging.
- Added dedicated managed-token hashing through `ENGRAM_CLOUD_TOKEN_PEPPER`.
- Dashboard reads now enforce the authenticated principal’s project grants instead of relying only on the deployment allowlist.
- Existing `ENGRAM_CLOUD_TOKEN` and `ENGRAM_CLOUD_ADMIN` credentials remain available as a legacy fallback.

### Reliability and data-integrity hardening

- Added safe planning and explicit partial outcomes for legacy ownership repair.
- Hardened nullable legacy-session handling across store reads, export, deletion, lifecycle operations, and diagnostics.
- Added doctor findings for unowned sessions and orphaned observation/session references.
- Rejected titleless observations before side effects, preventing poisoned mutation queues.
- Hardened sync ordering, mutation payload validation, CJK migrations, UTF-8 truncation, autosync shutdown, and SQLite generation boundaries.
- Added Obsidian export path-containment protection.
- Made Cloud push limits configurable while preserving the 8 MiB default.
- `doctor repair` now distinguishes repairable checks from diagnostic-only checks and prints executable continuations.

## Breaking and compatibility changes

### Go module path

Source consumers must use the v2 module path:

```bash
go install github.com/Gentleman-Programming/engram/v2/cmd/engram@latest
```

### Read scoping

Omitted project selectors now resolve the canonical current project instead of implicitly reading every project. Use `--all` or `all_projects=true` only when a global read is intentional.

### Project resolution

Ambiguous current-directory detection now fails with available-project information. Configure `.engram/config.json`, set `ENGRAM_PROJECT`, move into the intended repository, or pass an explicit project.

### Cloud scope and authentication

- Cloud sync remains explicitly project-scoped; `engram sync --cloud --all` is rejected.
- Cloud servers require `ENGRAM_CLOUD_ALLOWED_PROJECTS`.
- Authenticated deployments require a non-default `ENGRAM_JWT_SECRET`.
- `ENGRAM_CLOUD_TOKEN_PEPPER` enables managed-token authentication and must be distinct from `ENGRAM_JWT_SECRET`. Without it, legacy Cloud credentials continue to work.

## Upgrade checklist

1. Back up `~/.engram/engram.db`.
2. Upgrade Engram through Homebrew or a release archive.
3. Run `engram doctor` and follow any reported repair path.
4. Restart long-running MCP servers and agent sessions so they load the v2 binary and contracts.
5. Pi users should rerun `engram setup pi` if their installation still resolves an older `gentle-engram` package.
6. For enrolled Cloud projects, follow the Cloud `doctor` → `repair` → `bootstrap` upgrade sequence instead of assuming an implicit remote migration.

## Known limitations

- [#1242](https://github.com/Gentleman-Programming/engram/issues/1242): a stale OpenCode root session can still make omitted-session `mem_save` fail closed. End the stale session or provide the intended `session_id`.
- [#1220](https://github.com/Gentleman-Programming/engram/issues/1220): the dedicated OpenCode 2.x adapter is not included; `engram setup opencode` targets OpenCode 1.x.
- [#1182](https://github.com/Gentleman-Programming/engram/issues/1182): concurrent processes can still encounter SQLite write contention and transient MCP connectivity loss.
- [#1135](https://github.com/Gentleman-Programming/engram/issues/1135): a permanently unsatisfiable relation dependency can stall Cloud import convergence.
- [#1175](https://github.com/Gentleman-Programming/engram/issues/1175): local sync can become pathologically slow on very large stores containing extensive duplicate history.

## Installation

Release archives include Linux, macOS, and Windows builds for amd64 and arm64 plus `checksums.txt`. The stable tag also updates the Homebrew formula.

## Full comparison

See every commit in [`v1.20.0...v2.0.0`](https://github.com/Gentleman-Programming/engram/compare/v1.20.0...v2.0.0).