Memory Lean

[memory-lean icon]

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.

[npm version] [npm downloads] [tests] [listed in the MCP registry] [zero dependencies] [MIT license]

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

[A tour of the memory-lean web UI: hovering an entity, selecting one to highlight its relations, searching, editing a fact, and switching between the free layout and the layout grouped by type]

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.

Highlights

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, then give it the instructions.

{  "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

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, and anything over budget, which is also marked on the graph.

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    › 2026-03-02: deployed 2.4.0 to production    › deploy with scripts/release.sh, never by hand- 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"] }
## shop-backend [service] (3 archived)- NestJS API behind api.example.com- 2026-03-02: deployed 2.4.0 to production
## relationsshop-app -talks_to-> shop-backendPENDING shop-backend 2.4.0 -blocks-> shop-app

Why it stays lean

How it keeps your data safe

Tools

The three read tools are marked read-only, so clients that support it can run them without asking.

Command line

With npx, put npx -y in front: npx -y memory-lean --ui.

Teach your agent to use it

A memory server only helps if the agent reads it before working and writes to it when something changes. docs/AGENT-PROTOCOL.md is a ready-made set of instructions: what to look up at the start of a task, what to record, how to name things, and what never to store. The Claude Code plugin includes it. For every other agent, one command installs it:

npx -y memory-lean --protocol >> AGENTS.md     # into a rules file: always onnpx -y memory-lean --skill .agents/skills      # as an Agent Skill: loaded when relevant

Adjust the entity types and names in it to your own work.

Coming from the reference memory server

Point MEMORY_FILE_PATH at your existing memory.jsonl and swap the command. The file format is identical, so you can switch back at any time. Existing observations longer than 300 characters are kept as they are; only new writes are checked. To see what is over budget, and optionally fix it:

npx -y memory-lean --lint      # report onlynpx -y memory-lean --compact   # back up, then move overflow to archive/

Settings

All optional, set as environment variables on the server:

FAQ

Roadmap

• Claude Code plugin with the server, a skill and /memory-ui
• Setup guides for 12 agents
• rename_entity and archive restore
• A web UI to explore and edit the graph
• Listed in the official MCP registry
• Listed in the Claude Code plugin directory
• Search across the archived facts of every entity
• Undo in the web UI

Contributing

Ideas, bug reports and pull requests are welcome. The server is one file with no dependencies, the web UI is one HTML file, and npm test runs in a few seconds, so a first change is quick to make. CONTRIBUTING.md has the layout, the ground rules and a list of good first contributions.

If memory-lean saves you tokens, a ⭐ helps other people find it.

Support

memory-lean is free and MIT licensed. If it is useful to you, you can support the work:

[Buy Me a Coffee] [Ko-fi]

Author

Created and maintained by Zaman Sheikh at Silifton.

[GitHub] [X] [LinkedIn] [Website]

Built on the file format and tool names of the Model Context Protocol reference memory server.

License

MIT © 2026 Zaman Sheikh. Free to use, change and share, including commercially; keep the copyright notice.