Memory Lean

io.github.zamansheikhPublished by GitHub account zamansheikhv1.5.0Updated Oct 24, 2026

Token-lean memory for AI agents: a knowledge graph searched cheaply. Drop-in for server-memory.

The publisher's own server: Memory.fit

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local knowledge-graph memory server for AI coding agents, giving cheap, token-lean search and recall of projects, facts and relations across sessions.

What you can do
  • Search and read memory: ranked name-and-snippet search, open full entities with their relations, and get a name index grouped by type.
  • Create and change the graph: add entities, relations and observations, rename entities, and delete entities, relations or observations.
  • Manage archived facts: list what overflowed per entity and restore chosen facts.
  • Run a local web UI to explore, edit and watch the graph, plus CLI helpers for linting, compacting and printing agent instructions.
When to use it
Useful when an agent should remember projects, dependencies, shipped versions, pending work and learned rules between sessions, and you want that recall to cost few tokens. Also a fit if you already use the reference memory server and want the same file and tool names with smaller answers.
Requirements
Runs as a local stdio process, typically via npx, so Node.js is needed. Optional environment variables: MEMORY_FILE_PATH (default ~/.claude/memory-graph/memory.jsonl), MEMORY_OBS_MAX_CHARS, MEMORY_OBS_MAX, MEMORY_SEARCH_LIMIT, MEMORY_BACKUPS_KEPT. No account, API key or network access required.
Before you install
The graph is plain local files that agents can write to, so anything stored there persists and is readable on disk; the README advises keeping it out of git and never storing passwords, keys or tokens, only where a secret lives. Deletes and renames change stored data, though writes are locked, atomic and backed up daily. The web UI is local-only and needs the printed one-time key.

Installation

In SourceWeft

  1. Open Memory Lean in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[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

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):

CallReference servermemory-lean
read_graph~77,800 tokens~2,000 tokens40× smaller
search_nodes, average of 5 common words~31,000 tokens~770 tokens40× smaller

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.

text
/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.

json
{  "mcpServers": {    "memory": { "command": "npx", "args": ["-y", "memory-lean"] }  }}
bash
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:

bash
npx -y memory-lean --ui --demo
Setup for each agent
AgentServer configInstructions
Claude Codepluginincluded in the plugin
Xiaomi MiMo Codemimocode.jsoncskill or AGENTS.md
opencodeopencode.jsonAGENTS.md
OpenAI Codex CLIcodex mcp addAGENTS.md
Cursor.cursor/mcp.jsonAGENTS.md or a rule
VS Code (Copilot).vscode/mcp.jsoncopilot-instructions.md
Gemini CLIsettings.jsonGEMINI.md
Windsurfmcp_config.jsona rule
Clinecline_mcp_settings.json.clinerules/
Zedsettings.jsonAGENTS.md or .rules
JetBrains IDEsAI Assistant settingsa rule or guidelines
Claude Desktopclaude_desktop_config.jsonproject instructions

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

bash
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.
[An entity selected: its relations highlighted on the graph and listed in the side panel][Searching for payments: matching entities stay bright, the rest fade]
Follow the connections. Select an entity to see its facts and relations.Find anything. Search names, types and facts at once.
[Editing a fact in place, with a character counter][The web UI in the light theme]
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:

text
> 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:

text
> 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

LimitWhat it means
Small answerssearch_nodes returns at most 10 names with snippets, read_graph returns an index of names, and only open_nodes returns full entities.
Short factsAn observation longer than 300 characters is rejected, with a message telling the agent to split it or put the detail in the repo.
A cap per entityAn entity keeps 15 observations. Past that, the oldest dated ones move to archive/<entity>.md. Nothing is deleted: they can be listed and restored, and undated facts (the identity facts) always stay.
Search that narrowsEvery word must match somewhere in the entity, so adding a word narrows the result. The reference server looks for the query as one exact phrase.

How it keeps your data safe

SafeguardWhat it means
Safe to shareWriters take a lock file, so several agent sessions can use one graph without overwriting each other. Every write replaces the file atomically.
Daily backupsA copy goes to backups/ once a day; the last 7 are kept.
Damaged lines are keptA line that cannot be read is moved to memory.jsonl.unreadable on the next write and reported, never silently dropped.
Plain filesThe graph is JSON lines, archives are Markdown, backups are copies. You can read, grep and edit all of it by hand.

Tools

ToolWhat it returns
search_nodesRanked list of entity names with counts and up to two matching snippets each. Every word must match the name, type, an observation, or the type of a relation touching the entity.
open_nodesThe full entities you name, as compact text, with every relation touching them and their archive count. Unknown names come back with "did you mean" suggestions.
read_graphAn index: entity names grouped by type, with observation counts. Never the observations.
create_entitiesCreates entities; existing names are skipped.
create_relationsCreates relations between existing entities; duplicates are skipped.
add_observationsAdds facts to an entity, enforcing the length limit and the per-entity cap.
delete_observationsRemoves observations by exact text.
delete_relationsRemoves specific relations.
delete_entitiesRemoves entities and every relation touching them.
rename_entityRenames an entity, keeping its observations, relations and archive. Not in the reference server.
archived_observationsLists what was archived for an entity, optionally filtered, and restores chosen facts. Not in the reference server.

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

Command line

CommandWhat it does
memory-leanRuns the MCP server over stdio. This is what agents start.
memory-lean --ui [port]Opens the web UI. --no-open only prints the link; --demo uses a throwaway copy of a made-up graph.
memory-lean --protocolPrints the agent instructions, ready to append to AGENTS.md, CLAUDE.md or GEMINI.md.
memory-lean --skill <dir>Writes the same instructions as an Agent Skill into <dir>/memory-graph.
memory-lean --lintReports what in the graph is over budget. Read-only.
memory-lean --compactBacks up the graph, then moves overflow observations to the archive.
memory-lean --versionPrints the version.

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:

bash
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:

bash
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:

VariableDefaultMeaning
MEMORY_FILE_PATH~/.claude/memory-graph/memory.jsonlWhere the graph lives
MEMORY_OBS_MAX_CHARS300Longest observation accepted
MEMORY_OBS_MAX15Observations per entity before the oldest dated ones are archived
MEMORY_SEARCH_LIMIT10Default number of search results
MEMORY_BACKUPS_KEPT7Daily backups kept

FAQ

Is my memory sent anywhere?


No. The server reads and writes local files and makes no network requests. The web UI listens on 127.0.0.1 only. Keep the graph out of git, and never store passwords, keys or tokens in it: record where a secret lives, not its value.

Can several agents or sessions share one graph?


Yes. Every write takes a lock, re-reads the file and replaces it atomically, so parallel sessions (and the web UI) do not overwrite each other.

Why plain text search instead of embeddings?


It needs no model, no index and no dependencies, and an agent's queries are mostly names it already knows. Good entity names matter more than clever queries.

What happens to old facts?


When an entity passes 15 facts, the oldest dated ones move to archive/<entity>.md next to the graph. archived_observations, or the Archive section in the web UI, lists and restores them.

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.

Source: README.md at commit f2767b0

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v1.5.0LatestOct 16, 2026
  2. v1.4.1Oct 9, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Memory integrations

Memory.fit

fit.memoryOfficial publisher

Hosted Memory.fit server that lets an AI read your training, sleep, recovery and nutrition data and write back weekly plans, targets and meal plans.

Streamable HTTPWeb executableAuth
Location & LifestyleCredential requiredOct 29, 2026

pg.ddx.io: the PostgreSQL community's memory

io.ddx.pgOfficial publisher

pg.ddx.io: the PostgreSQL community's memory's hosted MCP server, published by pg.ddx.io; no sign-in required; Streamable HTTP; 29 tools.

Streamable HTTPWeb executable
Databases29 toolsOct 24, 2026

var.gg Naming Memory

gg.varOfficial publisher

Remote MCP server that suggests and searches code identifier names from domain concepts in Korean, Japanese, Chinese, Vietnamese and English, and exposes ERD…

Streamable HTTPWeb executable
Databases7 toolsOct 27, 2026

Counterparts

ai.counterparts

Local-first long-term memory for Claude Code and Claude Desktop: the assistant writes notes about you and your projects and recalls them in later sessions.

STDIODesktop only
AI & MLNot validated yetNov 7, 2026

LAHZE - Persian AI Memory Platform

Published by GitHub account pedramgholizadeh

LAHZE - Persian AI Memory Platform's hosted MCP server; no sign-in required; Streamable HTTP; 13 tools.

Streamable HTTPWeb executable
Location & Lifestyle13 toolsNov 3, 2026