engram

Your AI coding agents have amnesia. engram is the cure.

A cross-agent, git-friendly, local-first memory layer for AI coding agents.

---

A 15-second loop: engram init wires every agent → an agent remembers a decision → a new session recalls it.

By the numbers

🧠 5 agents, one memory	Claude Code · Codex · Gemini · Cursor · any MCP client
📦 4 production dependencies	minisearch · @modelcontextprotocol/sdk · yaml · commander
🪶 ~15 kB installed	14.8 kB packed · 46.2 kB unpacked · 9 files
📴 0 runtime network calls	local-only · no cloud · no telemetry · no account
⚡ ~5 ms recall at 10 memories · ~332 ms at 1,000	measured, not estimated — see Performance
🎛️ 1 command wires every installed agent	npx engramkit init

The problem

Every AI coding agent — Claude Code, Codex, Gemini CLI, Cursor — forgets everything the moment a session ends. You re-explain the architecture, re-litigate settled decisions, and watch the agent repeat a fix you already debugged last week. Per-agent "memory" features exist, but they don't talk to each other: what Claude Code learns, Cursor can't see.

engram is one memory layer every agent shares. It lives in your repo as plain markdown under .engram/, is diffable in code review, and ships as a zero-config MCP server — npx engramkit init and every supported agent is wired up in one command.

60-second quickstart

# In any git repo:
npx engramkit init          # creates .engram/ + wires every installed agent
git add .engram .claude .mcp.json .codex .gemini .cursor AGENTS.md
git commit -m "chore: add engram memory layer"

# Use it manually, or just let your agents use it over MCP:
engramkit add "Use Postgres, not MySQL — we need JSONB + RLS" --type decision --tags db
engramkit recall "database choice"

Now any agent you open in that repo will:

1. See the memory index at session start (injected via a hook) — every past decision, fix, and preference, one line each.
2. recall before doing real work — BM25 search over the full memory layer.
3. remember after a decision or root-cause — saved as .engram/memories/<slug>.md, INDEX regenerated, ready to commit.

engramkit list                       # browse everything
engramkit list --type fix            # just the bug root-causes
engramkit forget <id>                # delete a stale one
engramkit serve                      # start the MCP server manually (agents do this for you)

Install as a Claude Code plugin (one-time, global)

Prefer to have engram available in every repo without per-project wiring? Install it once as a Claude Code plugin from this repo's marketplace:

# In Claude Code (any project):
/plugin marketplace add Victorchatter/engramkit
/plugin install engramkit@engramkit-marketplace

That gives every Claude Code session, in any repo, the recall + remember MCP tools and a SessionStart hook that injects the project's .engram/INDEX.md when present (silent otherwise). Then you only need .engram/ created per project:

engramkit init          # in each repo: creates .engram/ (+ optional per-project agent wiring)

The plugin's MCP server runs npx -y engramkit serve, so it works for others once engramkit is published to npm. Until then, anyone with engramkit on their PATH (e.g. via npm link) can use it.

To submit to the official community marketplace (broader discovery, review required), run claude plugin validate . then submit at https://platform.claude.com/plugins/submit.

How it works

flowchart LR
  subgraph repo["your git repo  ·  everything committed, git-diffable"]
    direction TB
    mem[".engram/memories/*.md<br/>one file per memory<br/>+ YAML frontmatter"]
    idx[".engram/INDEX.md<br/>auto-regenerated on every write"]
    mem --> idx
  end
  CC["Claude Code"] --> srv
  CX["Codex CLI"] --> srv
  GM["Gemini CLI"] --> srv
  CR["Cursor"] --> srv
  ANY["any MCP client"] --> srv
  srv["engram MCP server<br/>npx engramkit serve<br/>tools: recall · remember"] <-->|reads / writes| repo
  style srv fill:#eef,stroke:#4a6,stroke-width:2px
  style repo fill:#f7f7f7,stroke:#999

Loading

• Storage: one markdown file per memory in .engram/memories/<slug>.md, with YAML frontmatter (id, type, tags, created, source). An auto-generated .engram/INDEX.md (one line per memory) is injected into agent context at session start and regenerated on every write. Everything is committable; engram never writes outside your repo (except agent config files during init).
• Search: BM25 full-text (via minisearch) — title and tags boosted, prefix + fuzzy matching. Rebuilt per call (fine until ~10k memories; persistence is a roadmap item). No embeddings, no API calls, no network.
• The universal adapter: engramkit serve is a standard MCP server exposing two tools — recall and remember — whose descriptions teach agents when to call them. Any MCP-compatible agent picks it up automatically once init registers it.

Session lifecycle

sequenceDiagram
  participant U as you
  participant A as agent (Claude Code)
  participant E as engram MCP
  participant R as .engram/
  Note over A,R: session start — SessionStart hook fires
  A->>R: read .engram/INDEX.md (one line per memory)
  R-->>A: index injected into context
  U->>A: "fix the checkout 500"
  A->>E: recall("checkout 500")
  E->>R: BM25 search memories/
  R-->>E: ranked hits
  E-->>A: prior root-cause: missing CORS allowlist
  A->>U: "this was a CORS allowlist bug last time — re-apply the fix?"
  Note over A,R: session end — Stop hook fires
  A->>E: remember(...)  (only if something new was learned)
  E->>R: write memories/<slug>.md, regenerate INDEX

Loading

Performance

Measured locally (Windows 11, Node 22, warm filesystem cache). engram rebuilds its BM25 index on every call, so per-op cost is roughly linear in vault size — no hidden quadratic scans, no background services, no network. Below ~300 memories every operation is sub-100 ms; at 1,000 memories a recall is ~⅓ second. A persistent incremental index (roadmap) flattens this for >10k.

memories in vault	recall (one query)	add one memory¹	linear scan (no index)
10	4.5 ms	~10 ms	1.2 ms
100	35 ms	~22 ms	12 ms
1,000	332 ms	~165 ms	121 ms

¹ Adding one memory re-reads all memories to regenerate INDEX.md, so it costs the same order as a recall. In normal use you add occasionally, one at a time — unnoticeable until the vault is very large. (Bulk-seeding thousands in a tight loop is the one place the rebuild-on-write shows up.) The linear-scan column is the baseline engram's BM25 index replaces — cheaper per op at this scale, but it means every recall would need to inspect every file with no ranking; the index buys relevance, not raw speed.

Honest scope: these are engram's own numbers. The alternatives in the section below were not independently benchmarked here — engram is designed to win on structural dimensions (cross-agent breadth, zero network, zero-config, install size, plain markdown) rather than on raw latency against hosted services.

Token cost & retention vs. no memory / claude-mem

engram's recall stays flat (~380 tokens) no matter how large the vault gets, because it's bounded top-5 retrieval, not a context dump. Retention doesn't decay with history size either — a decision is a file with an exact BM25 match, not a compressed summary that drifts. The claude-mem series above is estimated from its published architecture, not independently benchmarked — shown dashed in both charts to mark that.

Why not the built-in memory?

	engram	Claude Code auto-memory	claude-mem	mem0
Works across all agents	✅ Claude Code, Codex, Gemini, Cursor, any MCP	❌ Claude Code only	❌ Claude Code only	⚠️ needs integration per-app
Plain markdown, readable	✅ .engram/*.md	⚠️ markdown, but its own format	⚠️ its own store	❌ opaque
Local-only, no cloud	✅	✅	✅	❌ defaults to hosted
Runtime network calls	0	0	0	yes (hosted API)
Git-diffable in code review	✅ commit .engram/	✅	✅	❌
Production dependencies	4	built-in	separate package	many
Zero-config	✅ npx engramkit init	✅ (one agent)	⚠️ per-agent setup	❌ provisioning + keys

engram is the only one that gives every agent you use the same memory, in files you can read and review, with no account or key anywhere.

Supported agents

Agent	How engram wires it	Status
Claude Code	.claude/settings.json SessionStart + Stop hooks, .mcp.json server	✅
Codex CLI	.codex/config.toml MCP server ([mcp_servers.engramkit])	✅
Gemini CLI	.gemini/settings.json mcpServers.engramkit	✅
Cursor	.cursor/mcp.json mcpServers.engramkit	✅
Any MCP client	Run npx engramkit serve and add it to your client's MCP config	✅
all agents	AGENTS.md block with recall/remember instructions	✅

engram init detects which agents are installed and wires only those; pass --all to write every config regardless. All wiring is idempotent — re-running never duplicates or clobbers existing config.

Config formats were verified against current (2026) docs, not memory. See docs/agent-config-sources.md for the source links.

Requirements

• Node.js >= 18.
• A git repo (run engramkit init at the root).

Roadmap

These are intentionally out of scope for v1 — listed here so you know what's coming, and where to help:

• Semantic / embedding search — v1 is BM25 only, so database won't match a memory that says "DB". Embeddings + a local index are the next big step.
• Persistent search index — the minisearch index is rebuilt per recall today; persist + incrementally update once repos exceed ~10k memories.
• Cloud / team sync — today every memory is local and committed per-repo. Optional encrypted sync for teams is a future mode.
• Web UI — a small browser view over .engram/ for browsing/editing memories.
• Memory decay / review queue — surface stale memories for pruning.
• Per-user global memory — v1 is per-repo only; a cross-repo personal memory is planned.

Contributing

engram is open source and small on purpose. See CONTRIBUTING.md — the whole codebase is five modules (store, search, init, mcp, cli) and the bar for a new dependency is high. Bug reports and new-agent support requests are very welcome; see the issue templates.

License

MIT © 2026 Victor

Privacy

engram collects nothing — no telemetry, no account, no network calls at runtime. Memories stay in your repo as plain markdown. See PRIVACY.md for the full policy.