Persistent memory for AI coding agents
Agent-agnostic. Single binary. Zero dependencies.
Installation •
Agent Setup •
Architecture •
Plugins •
Contributing •
Full Docs
engram /ˈen.ɡræm/ — neuroscience: the physical trace of a memory in the brain.
Your AI coding agent forgets everything when the session ends. Engram gives it a brain.
A Go binary with SQLite + FTS5 full-text search, exposed via CLI, HTTP API, MCP server, and an interactive TUI. Works with any agent that supports MCP — Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, Windsurf, or anything else.
Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
↓ MCP stdio
Engram (single Go binary)
↓
SQLite + FTS5 (~/.engram/engram.db)
Quick Start
Install
brew install gentleman-programming/tap/engram
Windows, Linux, and other install methods → docs/INSTALLATION.md
Setup Your Agent
| Agent | One-liner |
|---|
| Claude Code | claude plugin marketplace add Gentleman-Programming/engram && claude plugin install engram |
| OpenCode | engram setup opencode |
| Gemini CLI | engram setup gemini-cli |
| Codex | engram setup codex |
| VS Code | code --add-mcp '{"name":"engram","command":"engram","args":["mcp"]}' |
| Cursor / Windsurf / Any MCP | See docs/AGENT-SETUP.md |
Full per-agent config, Memory Protocol, and compaction survival → docs/AGENT-SETUP.md
That's it. No Node.js, no Python, no Docker. One binary, one SQLite file.
How It Works
1. Agent completes significant work (bugfix, architecture decision, etc.)
2. Agent calls mem_save → title, type, What/Why/Where/Learned
3. Engram persists to SQLite with FTS5 indexing
4. Next session: agent searches memory, gets relevant context
Full details on session lifecycle, topic keys, and memory hygiene → docs/ARCHITECTURE.md
MCP Tools
| Tool | Purpose |
|---|
mem_save | Save observation |
mem_update | Update by ID |
mem_delete | Soft or hard delete |
mem_suggest_topic_key | Stable key for evolving topics |
mem_search | Full-text search |
mem_session_summary | End-of-session save |
mem_context | Recent session context |
mem_timeline | Chronological drill-in |
mem_get_observation | Full content by ID |
mem_save_prompt | Save user prompt |
mem_stats | Memory statistics |
mem_session_start | Register session start |
mem_session_end | Mark session complete |
mem_capture_passive | Extract learnings from text output |
mem_merge_projects | Merge project name variants (admin) |
Full tool reference → docs/ARCHITECTURE.md#mcp-tools
Terminal UI
engram tui
Navigation: j/k vim keys, Enter to drill in, / to search, Esc back. Catppuccin Mocha theme.
Git Sync
Share memories across machines. Uses compressed chunks — no merge conflicts, no huge files.
engram sync # Export new memories as compressed chunk
git add .engram/ && git commit -m "sync engram memories"
engram sync --import # On another machine: import new chunks
engram sync --status # Check sync status
Full sync documentation → DOCS.md
CLI Reference
