Skip to content

v2.0.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 18 Sep 05:02
· 14 commits to main since this release
v2.0.0
f912af9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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:

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: 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: the dedicated OpenCode 2.x adapter is not included; engram setup opencode targets OpenCode 1.x.
  • #1182: concurrent processes can still encounter SQLite write contention and transient MCP connectivity loss.
  • #1135: a permanently unsatisfiable relation dependency can stall Cloud import convergence.
  • #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.

Assets 9
Loading