Memory Lean

memory-lean

Long-term memory for AI coding agents that doesn't burn the context window.

A knowledge graph your agent searches cheaply, and a web UI where you can see and edit all of it.

Install · Quick start · Web UI · How it works · Tools · Setup for 12 agents · Contributing

memory-lean is an MCP server that gives Claude Code, Codex, Cursor, MiMo Code and any other MCP client a memory that lasts between sessions: which projects exist, what depends on what, which version shipped, what is still pending, and which rules were learned the hard way. It is a drop-in replacement for the reference memory server (@modelcontextprotocol/server-memory), with the same file and tool names, but its answers are about 40 times smaller.

Install and update

memory-lean needs Node.js 18 or newer and nothing else.

npm install -g memory-lean          # install

npm install -g memory-lean@latest # update to the newest release memory-lean --version # the version you have

Installed this way, the command in your agent's MCP config is memory-lean. The other two ways to run it need no npm command:

| Claude Code plugin | In Claude Code: /plugin marketplace add zamansheikh/memory-lean /plugin install memory-lean@memory-lean | In a terminal: claude plugin marketplace update memory-lean claude plugin update memory-lean@memory-lean |

• Restart after an update. A session that is already open keeps the server it started with. Start a new session, or reconnect the memory server in your agent (/mcp in Claude Code).
• Your memory is not touched. An update replaces the server only. The graph file stays as it is (~/.claude/memory-graph/memory.jsonl unless you moved it), and every version reads the same file.
• npx still runs an old version? Older npm versions reuse the copy they downloaded first. Write memory-lean@latest in the config instead of memory-lean.

What changed in each release is in the changelog.

Highlights

About 40× smaller answers. Search returns a ranked list of names and the lines that matched, not every entity in full, so the agent can afford to check its memory before every task.

A web UI for people. See the whole graph grouped by type, follow relations, and add, edit or delete anything. Agent writes show up live.

Drop-in replacement. Same memory.jsonl file and the same nine tools as the reference server. Switch in, and switch back whenever you like.

Works with every agent. Copy-paste setup for Claude Code, MiMo Code, Codex, Cursor, Copilot, Gemini CLI, Zed, JetBrains and more, plus the instructions that teach the agent to use it.

Stays small by itself. Short facts, a cap per entity, and an archive for the overflow, so the graph never grows into a wall of text.

Private and safe. Plain local files, daily backups, a write lock for parallel sessions, and no network access. One server file, zero dependencies.

The numbers

Measured on a real graph of 237 entities, 355 relations and 1,160 facts (tokens ≈ characters ÷ 4):

A narrow search that matches one or two entities saves less, because there is little to trim. To measure your own graph, run node tools/bench.mjs from a clone; it is read-only and prints sizes, never content.

Quick start

Claude Code: install the plugin. It adds the server, the instructions as a skill, a short reminder at the start of each session, and /memory-ui.

/plugin marketplace add zamansheikh/memory-lean

/plugin install memory-lean@memory-lean

Any other agent: add the server to its MCP config. It tells the agent the basics when it starts; the full instructions go into the rules file your agent reads.

{

"mcpServers": { "memory": { "command": "npx", "args": ["-y", "memory-lean"] } } }

npx -y memory-lean --protocol >> AGENTS.md   # into the rules file your agent reads

Just looking? Open the web UI on a made-up example graph:

npx -y memory-lean --ui --demo

Setup for each agent

The graph is created on the first write at ~/.claude/memory-graph/memory.jsonl, whichever agent writes it, so all your agents share one memory. Set MEMORY_FILE_PATH to keep it somewhere else.

Web UI

npx -y memory-lean --ui

This opens your memory in the browser. Everything an agent can do, you can do here:

• Explore. Each type gets its own bubble. Click an entity to highlight everything it connects to, drag nodes to arrange them, and scroll to zoom. Search matches names, types and facts.
• Edit. Add, edit and delete facts, rename an entity or change its type, add and remove relations, create and delete entities, and restore archived facts. Every change passes the same checks as the agents' tools.
• Watch. Changes your agents make appear within two seconds.
• Spot problems. The overview lists pending work, the most connected entities, anything over budget (also marked on the graph), and signs the graph needs tidying: finished pending work, near-duplicate names, entities nothing links to.

Follow the connections. Select an entity to see its facts and relations. Find anything. Search names, types and facts at once.

Edit in place. With the same 300-character limit the agents have. Light or dark. It follows your system, or pick one.

The page runs on your machine only (127.0.0.1) and needs the one-time key in the link it prints, so other websites cannot read or change your memory. Nothing is uploaded anywhere.

How it works

Search, then open

The reference server answers a search with every matching entity in full, as pretty-printed JSON. memory-lean answers with a ranked list of names and the lines that matched:

> search_nodes { "query": "deploy" }

57 match "deploy", top 10 shown (narrow the query or raise limit). open_nodes for full entities.

• shop-backend [service] 12 obs, 6 rel › deploy with scripts/release.sh, never by hand › 2026-03-02: deployed 2.4.0 to production
• PENDING shop-backend 2.4.0 [pending] 2 obs, 3 rel › …mobile apps still call the old endpoint until the deploy of 2.4.0 reaches them

The agent then opens only what it needs:

> open_nodes { "names": ["shop-backend"], "related": true }

shop-backend [service] (3 archived)

• NestJS API behind api.example.com
• 2026-03-02: deployed 2.4.0 to production

relations

RULE no Friday deploys -applies_to-> shop-backend › Deploys after Thursday 18:00 need the on-call's approval PENDING shop-backend 2.4.0 -blocks-> shop-backend › 2026-03-02: 2.4.0 published, the apps still call the old endpoint (+1 more) shop-app -talks_to-> shop-backend

With related: true, the rules and pending work that touch the entity come first, each introduced by its first fact. A rule is often a single fact, so one call is enough to start a task, and (+1 more) says when opening one would add something.

A search that is too narrow does not just fail. It names the term that is nowhere and the entities that come closest, so the agent drops the right word instead of guessing:

> search_nodes { "query": "shop release pipeline" }

No entities match "shop release pipeline". In no entity: pipeline. Closest (2 of 3 terms): shop-backend, shop-app.

Facts that were moved to the archive still answer a search. An entity whose onl