AI coding agents have amnesia. Every session starts from zero: the agent re-reads the same files, re-proposes the approach you rejected last month and re-introduces the bug you already fixed twice.

engram gives your agent a memory. It remembers what a good teammate would — why things are the way they are — and serves it to the agent over MCP exactly when it is needed.

npx @vefimov/engram init

Then tell your agent: "use engram." From that moment it:

• 🧠 opens every task with a short briefing — principles, relevant decisions, known pitfalls, where the last session stopped;
• 💬 says "three weeks ago we decided not to use Redis because of X — want to see that discussion?";
• 🪤 checks its plan against old mistakes before writing code;
• ✍️ records decisions, rejected options and scars as they happen — no one has to remember to write ADRs;
• 🔎 answers "where did we discuss auth?" even if that was forty conversations ago.

Features

| | | | --- | --- | | Knowledge graph | Memories linked with typed edges: supersedes, rejected_because, caused_by, depends_on, implements, part_of | | History, not overwrite | Changing your mind supersedes a decision instead of erasing it. Rejected options are kept — that's what makes "why not X?" answerable | | why timelines | engram why sessions → what we picked, what it replaced, what we rejected, and why | | Pitfall check | engram_check compares a plan against recorded pitfalls and rejected approaches | | Context compressor | Token-budgeted packs: important memories in full, the next tier in one line, the rest one recall away | | Session continuity | Handoff notes — done / decided / open / next — that the next session starts from | | Repo indexer | Imports existing ADRs (Nygard, MADR) as decisions; learns hotspots and reverts from git history | | Fast multilingual search | SQLite FTS5 + BM25, stemming, Unicode — English, Russian, Ukrainian and more | | Team memory | A sorted memories.jsonl you commit; merges on git pull, last-writer-wins, tombstones for deletes | | Six skills | remember-decision, recall, why-we-did-this, avoid-past-mistakes, project-summary, session-handoff | | Any agent | Claude Code, Cursor, Windsurf, Zed, Codex CLI — one memory for all of them | | Zero native deps | Built on Node's built-in node:sqlite. npx just works |

Screenshots

Quick start

# in your repository
npx @vefimov/engram init            # or: npm i -g @vefimov/engram && engram init

init creates .engram/, registers the MCP server (.mcp.json, .cursor/mcp.json), installs skills into .claude/skills/, adds a memory section to CLAUDE.md / AGENTS.md, and indexes your ADRs and git history.

Restart your agent and say "use engram". Then commit the memory:

git add .engram/memories.jsonl .engram/config.json .mcp.json CLAUDE.md .claude/skills

Manual MCP setup for any client:

{
  "mcpServers": {
    "engram": { "command": "npx", "args": ["-y", "@vefimov/engram", "serve"] }
  }
}

MCP tools

| Tool | | | --- | --- | | engram_session_start / engram_session_end | Open a session with a context pack · close it with a handoff summary | | engram_remember / engram_update / engram_forget | Write memory (with supersedes and links) | | engram_recall / engram_get | Search with filters · one memory with links | | engram_why | Timeline of a topic | | engram_check | Check a plan against pitfalls and rejected approaches | | engram_context / engram_summary | Token-budgeted briefing · project overview | | engram_link / engram_related | Build and walk the knowledge graph | | engram_index | Re-index ADRs and git history |

Plus resources (engram://summary, engram://memory/{id}) and every skill as an MCP prompt. Full reference →

CLI

engram status                                   # what engram knows
engram recall payments --kind pitfall           # search
engram why sessions                             # history of a topic
engram check "move sessions to MongoDB"         # past mistakes that apply
engram context "speed up login" -b 1500         # what the agent sees
engram remember "No ORMs in the hot path" -k principle -i 5 -c "…"
engram link dec_a1 rejected_because pit_b2
engram export --format md -o docs/MEMORY.md     # human-readable dump

All commands →

How it works

Agent ──MCP──▶ engram server ──▶ memory store (SQLite + FTS5)  ──▶ .engram/engram.db       (local index)
                    │            graph engine · context compressor
                    │            indexer (ADRs, git)            ──▶ .engram/memories.jsonl (commit this)
                    └── tools · resources · prompts (skills)

Read more: Concepts · How it works · Team memory

Roadmap

• v1.0 — MCP server, memory + graph, context compressor, sessions, ADR/git indexer, skills, CLI, JSONL sync ✅
• v1.1 — code-aware indexer (tree-sitter), optional local embeddings, stale-memory detection
• v1.2 — multiple projects, sync beyond git, web UI for the graph
• v2.0 — embeddings out of the box, one-command integrations, plugins

Contributing

Issues and PRs are welcome — see CONTRIBUTING.md.

License

MIT © Valentyn Yefimov