README
¶
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 (15)
| Category | Tools |
|---|---|
| Save & Update | mem_save, mem_update, mem_delete, mem_suggest_topic_key |
| Search & Retrieve | mem_search, mem_context, mem_timeline, mem_get_observation |
| Session Lifecycle | mem_session_start, mem_session_end, mem_session_summary |
| Utilities | mem_save_prompt, mem_stats, mem_capture_passive, mem_merge_projects |
Full tool reference with parameters → DOCS.md#mcp-tools-15-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
| Command | Description |
|---|---|
engram setup [agent] |
Install agent integration |
engram serve [port] |
Start HTTP API (default: 7437) |
engram mcp |
Start MCP server (stdio) |
engram tui |
Launch terminal UI |
engram search <query> |
Search memories |
engram save <title> <msg> |
Save a memory |
engram timeline <obs_id> |
Chronological context |
engram context [project] |
Recent session context |
engram stats |
Memory statistics |
engram export [file] |
Export to JSON |
engram import <file> |
Import from JSON |
engram sync |
Git sync export/import |
engram projects list|consolidate|prune |
Manage project names |
engram obsidian-export |
Export to Obsidian vault (beta) |
engram version |
Show version |
Full CLI with all flags → docs/ARCHITECTURE.md#cli-reference
Documentation
| Doc | Description |
|---|---|
| Installation | All install methods + platform support |
| Agent Setup | Per-agent configuration + Memory Protocol |
| Architecture | How it works + MCP tools + project structure |
| Plugins | OpenCode & Claude Code plugin details |
| Comparison | Why Engram vs claude-mem |
| Intended Usage | Mental model — how Engram is meant to be used |
| Obsidian Brain | Export memories as Obsidian knowledge graph (beta) |
| Contributing | Contribution workflow + standards |
| Full Docs | Complete technical reference |
License
MIT
Inspired by claude-mem — but agent-agnostic, simpler, and built different.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
engram
command
Engram — Persistent memory for AI coding agents.
|
Engram — Persistent memory for AI coding agents. |
|
internal
|
|
|
mcp
Package mcp implements the Model Context Protocol server for Engram.
|
Package mcp implements the Model Context Protocol server for Engram. |
|
obsidian
Package obsidian implements the Engram → Obsidian vault export engine.
|
Package obsidian implements the Engram → Obsidian vault export engine. |
|
project
Package project provides utilities for detecting and normalizing project names.
|
Package project provides utilities for detecting and normalizing project names. |
|
server
Package server provides the HTTP API for Engram.
|
Package server provides the HTTP API for Engram. |
|
setup
Package setup handles agent plugin installation.
|
Package setup handles agent plugin installation. |
|
store
Package store implements the persistent memory engine for Engram.
|
Package store implements the persistent memory engine for Engram. |
|
sync
Package sync implements git-friendly memory synchronization for Engram.
|
Package sync implements git-friendly memory synchronization for Engram. |
|
tui
Package tui implements the Bubbletea terminal UI for Engram.
|
Package tui implements the Bubbletea terminal UI for Engram. |
|
version
Package version checks for newer engram releases on GitHub.
|
Package version checks for newer engram releases on GitHub. |