engram

Support the project

Features

---

One binary — Memory without a stack

Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
    ↓ MCP stdio
Engram (single Go binary)
    ↓
SQLite + FTS5 (~/.engram/engram.db)

Codex mutating Engram tools require the running core’s /health response to advertise capabilities.runtime_session_resolution: true before resolving the host session. root_session_resume alone is not sufficient. If the core is incompatible, upgrade it to match the CLI, manually restart the running Engram server, and start a new Codex session. Hooks never restart the server automatically. Unregistered sessions and connection or invalid-response failures remain safely blocked with distinct diagnostics; read-only and non-Engram calls are unaffected.

A Go binary with SQLite + FTS5 full-text search, exposed through CLI, HTTP API, MCP, and an interactive TUI. It works with any MCP-compatible agent, including Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, and Windsurf. No Node.js, Python, or Docker is required: one binary, one SQLite file.

The data directory defaults to ~/.engram; a nonblank ENGRAM_DATA_DIR overrides it and must be an absolute path. On Windows, local-SQLite commands (including serve, mcp, and doctor) create and check <data-directory>/tmp/sqlite before opening SQLite, then set TEMP and TMP for that process only. Startup fails with an operation-specific diagnostic if the directory cannot be used. User/system environment settings and the working directory are unchanged. The directory is shared between processes and is not cleaned by Engram; SQLite manages its own uniquely named temporary files. This preparation also covers cloud status, enroll, unenroll, attest-prompt-source, and the local-store cloud upgrade operations (doctor, repair, bootstrap, remirror, status, rollback). It does not run for protocol-mode, setup, cloud serve, cloud config, top-level cloud repair or cloud bootstrap (distinct from the included cloud upgrade repair and cloud upgrade bootstrap), other cloud upgrade subcommands, or unknown commands. Existing orphan-database migration behavior is unchanged, including for commands excluded from this preparation. Linux/macOS, config-free commands, isolated self-tests, compatibility, and migrate-copy retain their existing behavior.

Docs →

---

Project-aware — The right memory for the right repo

Project-aware reads use the canonical current project when no selector is supplied: an explicit project, then ENGRAM_PROJECT, then cwd detection. Use --all in the CLI or all_projects=true in HTTP for an intentional global read; do not combine either with an explicit project. engram context retains its positional project as an alias for --project. GET /sync/status supports one resolved project and rejects all_projects=true because its provider cannot aggregate status.

Docs →

---

Local first — Portable when needed

Engram keeps memory local by default. The local SQLite database is authoritative; Git Sync exports portable compressed chunks for sharing across machines, and Engram Cloud is optional, project-scoped replication/shared access with browser visibility.

Need	Start here
Local memory and the runtime model	Architecture
Share memory with Git	Git Sync reference
Use optional Cloud replication	Engram Cloud
Diagnose or recover Cloud operations	Cloud troubleshooting

For an existing local database, use the guided upgrade sequence. If the dry run reports changes, apply them before bootstrap; otherwise continue directly to bootstrap.

engram cloud upgrade doctor --project <project>
engram cloud upgrade repair --project <project> --dry-run
engram cloud upgrade repair --project <project> --apply # only when the dry run reports changes
engram cloud upgrade bootstrap --project <project>
engram cloud upgrade status --project <project>

Docs →

---

Terminal UI — Browse what your agent remembers

engram tui

Navigate with j/k, use Enter to drill in, c to copy content to the clipboard, / to search, and Esc to go back. The TUI uses the Catppuccin Mocha theme.

Docs →

---

Also in the box

Component	What it does
MCP tools	Save, search, timeline, session, review, and diagnosis tools for your agent
HTTP API	The same memory over local HTTP endpoints; compound agent workflows
Doctor	engram doctor — read-only operational diagnostics
Conflict surfacing	Flags related or conflicting memories so the agent can judge them
Plugins	OpenCode and Claude Code plugin details
gentle-engram	The Engram package for Pi
Team usage	Shared-memory conventions
Binary self-testing	Isolated reliability and performance checks for released binaries
Obsidian Brain	Export memories as an Obsidian knowledge graph (beta)

Every command, environment variable, and endpoint: Full reference →

Get started

Install

For production use and security support, install the latest stable release from GitHub Releases. Release candidates are prerelease validation and feedback builds; choose one only when you accept prerelease risk. See the Release Policy before upgrading.

Homebrew installs the latest stable release:

brew install gentleman-programming/tap/engram

For Windows, Linux, source builds, and all installation methods, see Installation.

Set up your agent

Run the setup command for the agent you use, then restart that agent. engram setup writes the applicable MCP and integration configuration; it does not require you to start a server for the usual stdio-only setup.

Agent	Setup
Claude Code	engram setup claude-code
Pi	engram setup pi
OpenCode	engram setup opencode
Gemini CLI	engram setup gemini-cli
Codex	engram setup codex
Antigravity CLI	engram setup antigravity-cli
Windsurf	engram setup windsurf
Qwen Code	engram setup qwen
Kiro	engram setup kiro
Cursor	engram setup cursor
VS Code (Copilot)	engram setup vscode-copilot
Kilo Code	engram setup kilocode
Kimi Code	engram setup kimi
CommandCode	engram setup commandcode
Another MCP-compatible agent	Manual MCP setup

For Claude Code, rerunning setup updates the marketplace and the user-scope engram@engram plugin when it is already installed; existing project- or local-scope copies are not updated. An update failure fails setup; restart Claude Code after a successful update to load the new hooks.

Per-agent configuration, plugin behavior, manual MCP setup, compaction resilience, and troubleshooting: Agent Setup → · Pi users can also find the package at gentle-engram.

Read-only compatibility observations

Before considering an existing store, run the explicit-path probe:

engram compatibility --data-dir /absolute/path/to/fixture --json

This command dispatches before updates, configuration, orphan migration or Store.New. It reads directory metadata, the SQLite header and .instance-id only; it does not load SQLite, read memories, create directories/locks or repair identity. Exactly one --data-dir and one --json are accepted; any other argument, including --help, prints the usage line to stderr. Invalid arguments or unsafe metadata produce exit 2, no stdout and a diagnostic on stderr. engram help lists the command. Successful observations produce exit 0 and one JSON object with revision: 1, source: "offline", both authorization flags false and, for an existing store, its instance_id. Status is fresh for an empty directory, legacy_schema/future_schema for non-current headers, or unknown_shape for a current header. Missing directories, malformed headers, missing/invalid identity, nonregular database/identity entries, database-name ambiguity, WAL/SHM/journal sidecars and observed metadata changes are rejected. Directory aliases are resolved; no filesystem path is returned in the JSON.

Offline success never authorizes opening an existing store. A current header cannot prove schema shape, and normal schema-1 startup still executes DDL and repairs. These observations are not atomic snapshots or leases; an undetected race cannot grant permission because offline authorization is always false.

GET /compatibility provides the actual running store’s startup facts, under the same optional bearer authentication as other protected API routes. A successful current-schema startup returns source: "active", status: "ready", active_reuse_authorized: true, its actual instance_id, a per-store-opening random runtime_id, and capability: "startup-verified-store-v1". The response is not derived from /health, release version or externally supplied metadata. Nil, closed, generation-invalidated and future-schema-skipped handles return status: "unknown" and deny reuse. Reads do not open SQLite connections or resolve configuration. Startup facts do not certify arbitrary external in-place schema edits or future changes; clients must not treat this response as a lease, an authentication token or offline migration permission. Compare explicit store identity when reusing a selected runtime; never silently substitute another endpoint. Unknown evidence should leave memory disabled, with guidance to back up, update and restart the existing server, then recheck.

For agents

Treat Engram as a curated project memory, not a transcript sink. Use this operating contract throughout the session.

1. Orient before writing. Start with mem_current_project to confirm the resolved project and its source. At the start of related work, use mem_context and mem_search to recover the relevant history.
2. Search before repeating. Before revisiting a decision, bug, convention, or request that may already be known, search with focused terms. Search results are previews, not the complete record.
3. Retrieve progressively. Use mem_search for candidates, mem_timeline when surrounding session context matters, and mem_get_observation before relying on a full observation.
4. Save significant knowledge deliberately. Save completed bug fixes, decisions, discoveries, configuration changes, patterns, and durable user constraints with mem_save. Do not capture raw tool output or every conversational turn.
5. Keep evolving knowledge stable. Give an evolving topic a stable topic_key such as architecture/auth-model; reuse it to update that topic rather than creating competing memories. Use mem_suggest_topic_key when the key is unclear.
6. Leave a handoff. Before ending a session, save a mem_session_summary with the goal, instructions, discoveries, accomplished work, next steps, and relevant files.
7. Recover after compaction. Persist the compacted handoff with mem_session_summary first. Then call mem_context to recover recent session history before continuing.

When Git initialization changes the detected project

Before creating a repository’s first private Git identity, Engram checks local session history for the exact working directory. If Git suggests remote-app but that directory has history under local-app, implicit project selection stops with project_transition_conflict instead of silently changing scope. History is only a precaution: explicit or imported sessions can also trigger it.

Choose the intended scope deliberately. For a persistent choice, run engram init local-app in the project directory; existing explicit project filters and valid registered-session writes remain available. Do not overwrite an existing configuration without reviewing it. This choice changes future resolution; it does not merge or move previously split memories.

Historical directories are matched as absolute, lexically normalized paths; Engram does not access their filesystems. Relative history without a recorded base is ignored. Only the selected working directory is filesystem-canonicalized, so legacy history stored under a symlink alias may require an explicit project choice (engram init local-app) rather than automatic recognition.

Existing Git bindings stay stable. This check cannot reconstruct history without a usable absolute directory, across relocated paths, or in another local store.

A useful memory is structured

**What**: Added retry-safe upload handling.
**Why**: Retries could create duplicate records.
**Where**: internal/upload/handler.go
**Learned**: Reuse the request id as the idempotency key.

Use a short, searchable title and a fitting type with that content. The full Memory Protocol defines the durable-save rules and session-summary shape.

Choose MCP tools by intent

Tool availability can vary by MCP profile. Start with the intent, then use your client’s tool discovery mechanism (such as ToolSearch) only when a deferred tool is needed.

Intent	Start with
Confirm the project and recover recent work	mem_current_project, mem_context
Find prior knowledge without repeating work	mem_search
Inspect a result in enough detail	mem_timeline, mem_get_observation
Save or refine durable knowledge	mem_save, mem_update, mem_suggest_topic_key
Consolidate observations after preview and explicit confirmation	mem_consolidate (Go MCP server; contract)
Preserve the user’s request	mem_save_prompt
Hand off or close a session	mem_session_summary, mem_session_start, mem_session_end; MCP atomic close: mem_session_finalize
Review stale knowledge or memory relationships	mem_review, mem_judge, mem_compare; MCP batch: mem_judge_many
Diagnose project or store state	mem_doctor

For parameters and the complete, current tool reference, see the full documentation.

Documentation

Where to go	What you’ll find
Intended Usage	The human mental model for using Engram
Installation · Release Policy	Platform support, all installation methods, and stable, RC, security-support, upgrade, and rollback guidance
Agent Setup · Plugins	Per-agent configuration, compaction resilience, and OpenCode and Claude Code plugin details
Architecture · Codebase Guide	Memory model, tool behavior, project structure, flows, and implementation landmarks
Engram Cloud · Team Usage	Cloud quickstart, deployment, technical links, and shared-memory conventions
Doctor · Binary self-testing	Operational diagnosis and repair workflows, and isolated reliability and performance checks for released binaries
Beta Testing · Obsidian Brain	Isolated beta testing flows and cleanup guidance, and exporting memories as an Obsidian knowledge graph (beta)
Comparison	Engram compared with claude-mem
Full Docs · Contributing	Complete CLI, environment, API, and operational reference, and the contributor workflow

Dashboard contributors: if you modify .templ files in internal/cloud/dashboard/, run make templ to regenerate before committing. See Dashboard templ regeneration.

Community

Every change starts with an approved issue. See Contributing for the issue-first workflow, labels, review requirements, and contributor standards.

About the author

Built by Alan Buscaglia (Gentleman Programming). Engram is also the memory layer of Gentle-AI, and it stays a standalone tool you can use with any MCP-compatible agent.

---

Trademark notice: The Engram™ names and logos are trademarks of Alan Buscaglia. The symbol appears on the first prominent mention, and this notice covers the rest. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See TRADEMARKS.md.