engramLong-term memory for coding agents

Decisions, pitfalls, principles and session notes, stored in your repo and served to Claude Code, Cursor or any MCP client.

Get started

What is engram?

GitHub

It remembers the reasons

A decision is stored with its reasoning, and so are the options you rejected. When someone asks why you don't use Redis, the answer comes from the record.

Memories are linked

Typed edges such as supersedes, rejected_because and caused_by let the agent follow a decision back to the problem that caused it.

It checks plans against old mistakes

engram_check compares what the agent is about to do with recorded pitfalls and rejected approaches, before any code is written.

Briefings fit a token budget

Important memories come in full, the next tier is cut to one line, and the rest is a recall away.

Any MCP client

It's a standard MCP server. init sets up Claude Code, Cursor and AGENTS.md; other clients take the same server entry.

Local, and shared through git

SQLite with full-text search on your machine, no native dependencies. A sorted memories.jsonl goes into git next to the code.

See it in action

One minute of real output. The narration is synthetic.

From install to an answer

Below is the example project in examples/adr-demo, which has three ADRs about where to keep sessions.

$ npx @vefimov/engram init
✔ Created .engram/ in ~/code/shop
✔ Claude Code: .mcp.json, CLAUDE.md, 6 skills
✔ Indexed in 66 ms — 3 ADRs, 1 commits, 0 hotspots, 0 possible pitfalls

$ engram why sessions
↩️ ADR-0001: Cache sessions in Redis (superseded)
  Context: Login latency is dominated by the session lookup in Postgres.
  Decision: Store sessions in Redis with a 30-day TTL.
❌ ADR-0002: Store sessions in MongoDB (rejected)
  Rejected: no transactions spanning sessions and the orders table.
✅ ADR-0003: Keep sessions in Postgres (active)
  Sessions live in Postgres with an hourly cleanup job.
  dec_edkgurku —supersedes→ dec_40bmzazh

Then restart your agent and tell it "use engram". It gets a briefing at the start of each task, checks plans against old mistakes, records decisions as they happen, and leaves a note for the next session.