Engram

<p align="center"> <img width="1024" height="340" alt="image" src="https://github.com/user-attachments/assets/32ed8985-841d-49c3-81f7-2aabc7c7c564" /> </p> <p align="center"> <strong>Persistent memory for AI coding agents</strong><br> <em>Agent-agnostic. Single binary. Zero dependencies.</em> </p> <p align="center"> <a href="docs/INSTALLATION.md">Installation</a> &bull; <a href="docs/AGENT-SETUP.md">Agent Setup</a> &bull; <a href="docs/ARCHITECTURE.md">Architecture</a> &bull; <a href="docs/PLUGINS.md">Plugins</a> &bull; <a href="CONTRIBUTING.md">Contributing</a> &bull; <a href="DOCS.md">Full Docs</a> </p>

---

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

<p align="center"> <img src="assets/tui-dashboard.png" alt="TUI Dashboard" width="400" /> <img width="400" alt="image" src="https://github.com/user-attachments/assets/0308991a-58bb-4ad8-9aa2-201c059f8b64" /> <img src="assets/tui-detail.png" alt="TUI Observation Detail" width="400" /> <img src="assets/tui-search.png" alt="TUI Search Results" width="400" /> </p>

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). Accepts --project or ENGRAM_PROJECT | | 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 | | engram projects list | Show all projects with observation/session/prompt counts | | engram projects consolidate | Interactive merge of similar project names (--all, --dry-run) | | engram projects prune | Remove projects with 0 observations (--dry-run) | | engram version | Show version |

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 | | Contributing | Contribution workflow + standards | | Full Docs | Complete technical reference |

License

MIT

---

Inspired by claude-mem — but agent-agnostic, simpler, and built different.