engram

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