Engram

Persistent memory for AI coding agents
One brain. Local or cloud. Agent-agnostic, single binary, zero dependencies.

Website • Gentle-AI • Gentle-AI Wiki

Installation • Release Policy • Engram Cloud • Agent Setup • Codebase Guide • Architecture • Plugins • Team Usage • 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 through CLI, HTTP API, MCP, and an interactive TUI. It works with any MCP-compatible agent, including Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, and Windsurf.

No Node.js, Python, or Docker is required: one binary, one SQLite file.

Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
    ↓ MCP stdio
Engram (single Go binary)
    ↓
SQLite + FTS5 (~/.engram/engram.db)

#For agents

Treat Engram as a curated project memory, not a transcript sink. Use this operating contract throughout the session.

1. Orient before writing. Start with mem_current_project to confirm the resolved project and its source. At the start of related work, use mem_context and mem_search to recover the relevant history.
2. Search before repeating. Before revisiting a decision, bug, convention, or request that may already be known, search with focused terms. Search results are previews, not the complete record.
3. Retrieve progressively. Use mem_search for candidates, mem_timeline when surrounding session context matters, and mem_get_observation before relying on a full observation.
4. Save significant knowledge deliberately. Save completed bug fixes, decisions, discoveries, configuration changes, patterns, and durable user constraints with mem_save. Do not capture raw tool output or every conversational turn.
5. Keep evolving knowledge stable. Give an evolving topic a stable topic_key such as architecture/auth-model; reuse it to update that topic rather than creating competing memories. Use mem_suggest_topic_key when the key is unclear.
6. Leave a handoff. Before ending a session, save a mem_session_summary with the goal, instructions, discoveries, accomplished work, next steps, and relevant files.
7. Recover after compaction. Persist the compacted handoff with mem_session_summary first. Then call mem_context to recover recent session history before continuing.

#A useful memory is structured

**What**: Added retry-safe upload handling.
**Why**: Retries could create duplicate records.
**Where**: internal/upload/handler.go
**Learned**: Reuse the request id as the idempotency key.

Use a short, searchable title and a fitting type with that content. The full Memory Protocol defines the durable-save rules and session-summary shape.

#Choose MCP tools by intent

Tool availability can vary by MCP profile. Start with the intent, then use your client's tool discovery mechanism (such as ToolSearch) only when a deferred tool is needed.

For parameters and the complete, current tool reference, see the full documentation.

#Quick start

#Install

For production use and security support, install the latest stable release from GitHub Releases. Release candidates are prerelease validation and feedback builds; choose one only when you accept prerelease risk. See the Release Policy before upgrading.

Homebrew remains on the stable v1.20.0 line:

brew install gentleman-programming/tap/engram

For Windows, Linux, source builds, and all installation methods, see Installation.

#Set up your agent

Run the setup command for the agent you use, then restart that agent. engram setup writes the applicable MCP and integration configuration; it does not require you to start a server for the usual stdio-only setup.

See Agent Setup for per-agent configuration, plugin behavior, manual MCP setup, compaction resilience, and troubleshooting. Pi users can also find the package at gentle-engram.

#Local first, portable when needed

Engram keeps memory local by default. The local SQLite database is authoritative; Git Sync exports portable compressed chunks for sharing across machines, and Engram Cloud is optional, project-scoped replication/shared access with browser visibility.

For an existing local database, use the guided upgrade sequence. If the dry run reports changes, apply them before bootstrap; otherwise continue directly to bootstrap.

engram cloud upgrade doctor --project <project>
engram cloud upgrade repair --project <project> --dry-run
engram cloud upgrade repair --project <project> --apply # only when the dry run reports changes
engram cloud upgrade bootstrap --project <project>
engram cloud upgrade status --project <project>

See the Cloud upgrade reference for apply, rollback, and recovery details.

#Project-aware reads

Project-aware reads use the canonical current project when no selector is supplied: an explicit project, then ENGRAM_PROJECT, then cwd detection. Use --all in the CLI or all_projects=true in HTTP for an intentional global read; do not combine either with an explicit project. engram context retains its positional project as an alias for --project. GET /sync/status supports one resolved project and rejects all_projects=true because its provider cannot aggregate status.

#Terminal UI

engram tui

Navigate with j/k, use Enter to drill in, c to copy content to the clipboard, / to search, and Esc to go back. The TUI uses the Catppuccin Mocha theme.

#Documentation

Dashboard contributors: if you modify .templ files in internal/cloud/dashboard/, run make templ to regenerate before committing. See Dashboard templ regeneration.

#Contributing

Every change starts with an approved issue. See Contributing for the issue-first workflow, labels, review requirements, and contributor standards.

Trademark notice: The Engram names and logos are trademarks of Alan Buscaglia. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See TRADEMARKS.md.

#License

MIT

---

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

#Contributors