Engram

What It Does

Engram is a persistent memory system for AI coding agents. It ships as a single Go binary backed by SQLite with FTS5 full-text search, and exposes its functionality through four interfaces: an MCP server (stdio transport), an HTTP API, a CLI, and an interactive TUI. When an agent finishes a session and forgets everything, Engram stores decisions, bugfix notes, architecture choices, and preferences so the next session can pick up where the last one left off.

It works with any agent that supports MCP: Claude Code, OpenCode, Gemini CLI, Codex, VS Code Copilot, Cursor, Windsurf, and others. The engram setup command writes the correct config for each one.

The Good

19 MCP tools covering the full memory lifecycle. Save, update, delete, search, context retrieval, timeline, session start/end, conflict detection (judge and compare), stats, passive capture, project management, and a doctor tool for diagnostics. The tool surface is well-designed: mem_save accepts structured What/Why/Where/Learned fields, mem_search hits FTS5, mem_context returns session-relevant memory, and mem_judge surfaces contradictions between stored memories.

Single binary, zero runtime dependencies. No Node.js, no Python, no Docker required for local use. The binary is 17 MB on macOS arm64. One brew install or go install and you have the CLI, MCP server, HTTP server, and TUI. This is the lowest-friction install story of any agent memory tool tested.

80,808 lines of Go implementation, 55,308 lines of tests. 399 test functions across the MCP layer (179), store layer (167), and server layer (53). The store alone is 6,499 lines with a dedicated 7,717-line test file and migration tests. This is not a weekend project. The test-to-code ratio is approximately 0.68, which is strong for a Go project.

CLI verified end-to-end. Every CLI subcommand tested on the pre-built binary worked on first run with a clean data directory: save, search, stats, export, context, timeline. No init step, no config file needed, no migration step. The binary creates the SQLite database and schema on first use.

Cloud sync with git-based chunk transport. Memories export as compressed chunks to .engram/ inside your repo. Push to git, pull on another machine, run engram sync --import. No merge conflicts because chunks are append-only. Cloud replication is opt-in via Docker or a hosted server, with project-scoped sync.

Agent-specific setup commands. engram setup claude-code uses the Claude plugin marketplace. engram setup opencode writes the TypeScript plugin. engram setup gemini-cli, engram setup codex, and VS Code MCP registration all work with one command each. The setup command detected four agents on this machine and listed install paths for each.

Built-in TUI with bubbletea. engram tui launches a full terminal UI with vim-style navigation, search, and observation detail views. Catppuccin Mocha themed. This is unusual for an MCP server and makes manual memory inspection pleasant.

21 internal skills for contributors. The repo ships a full skill framework (architecture guardrails, commit hygiene, testing coverage, PR review, etc.) at 1,714 total lines across 21 SKILL.md files. This is the most mature contributor-skill setup seen in any reviewed project.

The Bad

Cloud sync and HTTP API could not be fully verified without Docker. The cloud features require either Docker Compose or a remote server. In a hands-on review without Docker running, the cloud enrollment, sync, and dashboard features are unverified. This is a scope limitation, not a defect.

MCP server requires an agent client to exercise. The MCP server runs on stdio transport (engram mcp). Testing it properly means piping JSON-RPC messages or running it through a real agent. The CLI surface covers the same operations, so the gap is verifiable through code inspection (the 2,681-line mcp.go and 179 test functions cover tool registration, request handling, and edge cases).

No ARM Linux binary in the GoReleaser config. The build matrix covers linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, and windows/amd64. However, the pre-built binary in the repo is macOS arm64 only. Linux users need to build from source or use the GoReleaser GitHub Release artifacts, which were not tested here.

Version reporting shows "dev". The binary from main reports engram dev rather than a tagged version. The GoReleaser config should stamp the version during release builds, but anyone building from source or using the repo binary gets an unhelpful version string.

Smoke Test Results

Hands-on testing on macOS arm64 with the pre-built binary from the repo. All commands use a clean ENGRAM_DATA_DIR=/tmp/engram-test-data to avoid touching the reviewer's real memory store.

Install

$ git clone --depth 1 https://github.com/Gentleman-Programming/engram /tmp/engram-r3
Cloning into '/tmp/engram-r3'...

$ ./cmd/engram/main version
engram dev

PASS. Binary is 17 MB Mach-O arm64, runs immediately.

CLI save and search

$ ENGRAM_DATA_DIR=/tmp/engram-test-data ./cmd/engram/main save "Test memory" "This is a test observation from GearScope review." --type decision --project test-project
Memory saved: #1 "Test memory" (decision)

$ ENGRAM_DATA_DIR=/tmp/engram-test-data ./cmd/engram/main search "test"
Found 1 memories:

[1] #1 (decision) - Test memory
 This is a test observation from GearScope review.
 2026-05-21 23:33:10 | project: test-project | scope: project

PASS. Save and search work on first run with no init step.

Stats and context

$ ENGRAM_DATA_DIR=/tmp/engram-test-data ./cmd/engram/main stats
Engram Memory Stats
 Sessions: 1
 Observations: 1
 Prompts: 0
 Projects: test-project
 Database: /tmp/engram-test-data/engram.db

$ ENGRAM_DATA_DIR=/tmp/engram-test-data ./cmd/engram/main context test-project
## Memory from Previous Sessions

### Recent Sessions
- **test-project** (2026-05-21 23:33:10) [1 observations]

### Recent Observations
- [decision] **Test memory**: This is a test observation from GearScope review.

PASS. Stats and context render structured Markdown output.

Export and timeline

$ ENGRAM_DATA_DIR=/tmp/engram-test-data ./cmd/engram/main export /tmp/engram-export-test.json
Exported to /tmp/engram-export-test.json
 Sessions: 1
 Observations: 1
 Prompts: 0

$ ENGRAM_DATA_DIR=/tmp/engram-test-data ./cmd/engram/main timeline 1
Session: test-project (2026-05-21 23:33:10)
Total observations in session: 1

>>> #1 [decision] Test memory <<<
 This is a test observation from GearScope review.
 2026-05-21 23:33:10

PASS. JSON export is well-structured. Timeline shows chronological context.

Setup command

$ ./cmd/engram/main setup --help
engram setup. Install agent plugin

Which agent do you want to set up?

 [1] OpenCode
 [2] Claude Code
 [3] Gemini CLI
 [4] Codex

PASS. Detects available agents and offers correct install paths.

Codebase metrics

$ find . -name "*.go" | wc -l
133

$ find . -name "*_test.go" | wc -l
66

$ grep -c "func Test" internal/mcp/mcp_test.go internal/server/server_test.go internal/store/store_test.go
internal/mcp/mcp_test.go:179
internal/server/server_test.go:53
internal/store/store_test.go:167

$ wc -l internal/mcp/mcp.go
2681 internal/mcp/mcp.go

$ find . -name "*.go" -path "*/internal/*" | xargs wc -l | tail -1
80812 total

PASS. 399 test functions across the three core packages. MCP server implementation is 2,681 lines with thorough handler coverage.

What the runs tell you

The CLI surface works perfectly on first run with zero configuration. Save, search, stats, context, timeline, and export all produce correct output. The MCP server and HTTP API layers are well-covered by unit tests (232 test functions between them) but could not be exercised in their normal runtime mode (stdio agent transport, long-running HTTP server). Cloud features require Docker. The codebase depth and test coverage provide strong confidence in the untested surfaces.

Setup Walkthrough

1. Install via Homebrew: brew install gentleman-programming/tap/engram
2. Verify: engram version (should print the current version)
3. Set up your agent: engram setup claude-code (or opencode, gemini-cli, codex)
4. The agent config is written automatically. Restart your agent.
5. Done. The agent now has persistent memory across sessions.

No init step, no database migration, no config file editing. The binary creates ~/.engram/engram.db on first use.

Alternatives

1. claude-mem -- the project that inspired Engram. Simpler, Claude-specific, lighter feature set. Good if you only use Claude and want minimal setup.
2. mem0 -- a more general-purpose memory layer with embeddings and a hosted API. Heavier dependency story (Python, vector DB). Better for non-coding agent use cases.
3. Agent memory files in .cursorrules or CLAUDE.md -- the DIY approach. Zero tooling, but limited to static text, no search, no session lifecycle, no conflict detection.