{"_id":"memory-lean","_rev":"7-f67d559de256dacc6bb258706e60c2f9","name":"memory-lean","dist-tags":{"latest":"1.6.1"},"versions":{"0.0.0-stage":{"name":"memory-lean","version":"0.0.0-stage","_id":"memory-lean@0.0.0-stage","stub":true,"maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"dist":{"shasum":"8e0ee4c4d24104b091a6f44c090f4db343be298f","tarball":"https://registry.npmjs.org/memory-lean/-/memory-lean-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-7XfeRKjNwVZOiTEOq6KiP5cds2d9QSc4YfgaWA/kHViQR7P+sXem5tSLBkKMDepKhpgBEQcKYQqtWjzsoDhs5w==","signatures":[{"sig":"MEYCIQDHFX3VUuQn4xXr3z62pAxRrXoA1aUzojIt36E77KDqiAIhANVwCftp1zee0BCPPQawawF4gARDWHK6oV7fcutbP3Cb","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":333},"_npmUser":{"name":"zamansheikh","email":"zaman6545@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.1.0":{"name":"memory-lean","version":"1.1.0","keywords":["mcp","model-context-protocol","memory","knowledge-graph","claude","ai-agent","tokens"],"license":"MIT","_id":"memory-lean@1.1.0","maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"homepage":"https://github.com/zamansheikh/memory-lean#readme","bugs":{"url":"https://github.com/zamansheikh/memory-lean/issues"},"bin":{"memory-lean":"server/memory-lean.mjs"},"dist":{"shasum":"0e4d1bce875805ff81e30a4a5f9431e6f1ac534b","tarball":"https://registry.npmjs.org/memory-lean/-/memory-lean-1.1.0.tgz","fileCount":5,"integrity":"sha512-BVLWgQXT3ilOGD2hCpRGVqGga7NWUBYjY+etB189ubIOAD2KSlqwwycAKjCTXCsv5mDhaanieUXV2r4guDFfKg==","signatures":[{"sig":"MEQCIBJNym+qYE3UxaDH3ssagSd2QjBhIUQTurDcfYqZBOslAiAsXBkghGB7s0aCGwA9WkwN0TgVbQZ8cfWP9V2bxMnzxw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIFwnhOOHDrxtbwGxH906YSzDer5AaFCkvL+pA38kD8pCAiBG2kH3voo4uJoHY5+ZCEg588a6jp2b0G5ZrAqmjbAW8w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38507},"type":"module","engines":{"node":">=18"},"gitHead":"e84b08056b42a0a810bd1be71735538ceffdd988","scripts":{"test":"node --test","lint-graph":"node server/memory-lean.mjs --lint"},"_npmUser":{"name":"zamansheikh","email":"zaman6545@gmail.com"},"repository":{"url":"git+https://github.com/zamansheikh/memory-lean.git","type":"git"},"_npmVersion":"11.16.0","description":"A token-lean MCP memory server: a knowledge graph your AI agent can search without reading the whole thing. Drop-in replacement for @modelcontextprotocol/server-memory.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/memory-lean_1.1.0_1791548716619_0.0856956983609165","host":"s3://npm-registry-packages-npm-production"}},"1.4.0":{"name":"memory-lean","version":"1.4.0","keywords":["mcp","mcp-server","model-context-protocol","memory","knowledge-graph","claude","claude-code","cursor","ai-agent","tokens"],"author":{"url":"https://zamansheikh.com","name":"Zaman Sheikh"},"license":"MIT","_id":"memory-lean@1.4.0","maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"homepage":"https://github.com/zamansheikh/memory-lean#readme","bugs":{"url":"https://github.com/zamansheikh/memory-lean/issues"},"bin":{"memory-lean":"server/memory-lean.mjs"},"dist":{"shasum":"fbd00ebc261a982aaa89478048fe9f1a5143f255","tarball":"https://registry.npmjs.org/memory-lean/-/memory-lean-1.4.0.tgz","fileCount":8,"integrity":"sha512-MgLnajosY86pAFs5hjtwv0dEThXGOenbGNF2qempd26qgnpeZ7DtmGOhwpoVOW+5jqeuJsiopn51oY/29zsydA==","signatures":[{"sig":"MEYCIQDF2C7zTBFxajQcxn7+VIwlaheFjPQkrdxhCzszYVtmcAIhAOfFSAXmNhwRXLhqoxK89EWkRj4dG/DM18wC4H5cIK9y","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQCcXRcGjEfQcesgir3k/5UsEaGCOaqBD1v5eCJiHv6VRwIgdgIPKZ5WWoDs5L9QoS3hDEUfIk3EgoeTtWqutPaxq04=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64478},"type":"module","engines":{"node":">=18"},"funding":[{"url":"https://www.buymeacoffee.com/zamansheikh","type":"buymeacoffee"},{"url":"https://ko-fi.com/zamansheikh","type":"ko-fi"}],"gitHead":"2f5b66614afbf4c8b091b24bd354d674a1b18a16","mcpName":"io.github.zamansheikh/memory-lean","scripts":{"test":"node --test","lint-graph":"node server/memory-lean.mjs --lint"},"_npmUser":{"name":"zamansheikh","email":"zaman6545@gmail.com"},"repository":{"url":"git+https://github.com/zamansheikh/memory-lean.git","type":"git"},"_npmVersion":"11.16.0","description":"A token-lean MCP memory server: a knowledge graph your AI agent can search without reading the whole thing. Drop-in replacement for @modelcontextprotocol/server-memory.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/memory-lean_1.4.0_1791550139076_0.06944204381642094","host":"s3://npm-registry-packages-npm-production"}},"1.4.1":{"name":"memory-lean","version":"1.4.1","keywords":["mcp","mcp-server","model-context-protocol","memory","knowledge-graph","claude","claude-code","cursor","ai-agent","tokens"],"author":{"url":"https://zamansheikh.com","name":"Zaman Sheikh"},"license":"MIT","_id":"memory-lean@1.4.1","maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"homepage":"https://github.com/zamansheikh/memory-lean#readme","bugs":{"url":"https://github.com/zamansheikh/memory-lean/issues"},"bin":{"memory-lean":"server/memory-lean.mjs"},"dist":{"shasum":"6a066d89188a8202f918142ab68be38b32357258","tarball":"https://registry.npmjs.org/memory-lean/-/memory-lean-1.4.1.tgz","fileCount":8,"integrity":"sha512-8cnqezK5pLZwImoWXJNcIjXDr2lIlvcYwNNe0MOVLIIewlDIwRnG1GXysGR1UUGR+olJDoWp95EP8uSCTdWWvw==","signatures":[{"sig":"MEUCIQChABHJYCVwbKLQXQbarrzc/nDgKp7QXEjUkENhVwruMQIgcUq2v05rg5fLwZux3Ai4LGJ4S4kNMOlE86CUpBGtWlg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQDmYzD+GI/GmGdNxTmlZSJjclPyEstUWqMKuoKr4/pnOwIhALt3keXcsTCP/pGsbFGklZcB0Q6bBsIdWI88M+dE5V8m","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/memory-lean@1.4.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":64613},"type":"module","engines":{"node":">=18"},"funding":[{"url":"https://www.buymeacoffee.com/zamansheikh","type":"buymeacoffee"},{"url":"https://ko-fi.com/zamansheikh","type":"ko-fi"}],"gitHead":"55615453cf1c456228dc375892afe7b5db38c984","mcpName":"io.github.zamansheikh/memory-lean","scripts":{"test":"node --test","lint-graph":"node server/memory-lean.mjs --lint"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"4a724619-6cd8-4867-947f-5c4e4a0ec825"}},"repository":{"url":"git+https://github.com/zamansheikh/memory-lean.git","type":"git"},"_npmVersion":"12.2.0","description":"A token-lean MCP memory server: a knowledge graph your AI agent can search without reading the whole thing. Drop-in replacement for @modelcontextprotocol/server-memory.","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/memory-lean_1.4.1_1791550662597_0.7619666010741999","host":"s3://npm-registry-packages-npm-production"}},"1.5.0":{"name":"memory-lean","version":"1.5.0","keywords":["mcp","mcp-server","model-context-protocol","memory","knowledge-graph","claude","claude-code","cursor","ai-agent","tokens"],"author":{"url":"https://zamansheikh.com","name":"Zaman Sheikh"},"license":"MIT","_id":"memory-lean@1.5.0","maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"homepage":"https://github.com/zamansheikh/memory-lean#readme","bugs":{"url":"https://github.com/zamansheikh/memory-lean/issues"},"bin":{"memory-lean":"server/memory-lean.mjs"},"dist":{"shasum":"bdf8487ffe61973b8a84bad0d4b276936a3459dd","tarball":"https://registry.npmjs.org/memory-lean/-/memory-lean-1.5.0.tgz","fileCount":10,"integrity":"sha512-NF/sDZ0m0jIwRzmlRryVVGEQD8H8egXwRqYzUHgYdKhZ6dVxc6xvNUMArOb2dWux1BX0UJ8GqPCgvXWkvJrbMA==","signatures":[{"sig":"MEUCIGc/aW9R18Fnq0MKXg5O1waFWEpIPwbyiCpT4ETEicBeAiEAgITzAP4zLq7ZfaHG9qucz+mWtDhBwghtEKFa9eQYZ1E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIE/qlOLyzsllpWEB/apx0BSnW358BjrIoEQGTNveq/zTAiAfsMuzdDYFesxz96/fVFNh8jSLdcMrg0OJngqoXgS/Jg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/memory-lean@1.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":161799},"type":"module","engines":{"node":">=18"},"funding":[{"url":"https://www.buymeacoffee.com/zamansheikh","type":"buymeacoffee"},{"url":"https://ko-fi.com/zamansheikh","type":"ko-fi"}],"gitHead":"0e3bd36be78f3d255ed163b36a2d794297f6683c","mcpName":"io.github.zamansheikh/memory-lean","scripts":{"test":"node --test","lint-graph":"node server/memory-lean.mjs --lint"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"4a724619-6cd8-4867-947f-5c4e4a0ec825"}},"repository":{"url":"git+https://github.com/zamansheikh/memory-lean.git","type":"git"},"_npmVersion":"12.2.0","description":"A token-lean MCP memory server: a knowledge graph your AI agent can search without reading the whole thing. Drop-in replacement for @modelcontextprotocol/server-memory.","directories":{},"_nodeVersion":"24.21.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/memory-lean_1.5.0_1792154251907_0.610980834948978","host":"s3://npm-registry-packages-npm-production"}},"1.6.0":{"name":"memory-lean","version":"1.6.0","keywords":["mcp","mcp-server","model-context-protocol","memory","knowledge-graph","claude","claude-code","cursor","ai-agent","tokens"],"author":{"url":"https://zamansheikh.com","name":"Zaman Sheikh"},"license":"MIT","_id":"memory-lean@1.6.0","maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"homepage":"https://github.com/zamansheikh/memory-lean#readme","bugs":{"url":"https://github.com/zamansheikh/memory-lean/issues"},"bin":{"memory-lean":"server/memory-lean.mjs"},"dist":{"shasum":"b74160c1de941f3417d450b371ac333bebafb20b","tarball":"https://registry.npmjs.org/memory-lean/-/memory-lean-1.6.0.tgz","fileCount":10,"integrity":"sha512-xmFfDAboXWhjJLwjXyhvE6ZHR/zcls/IuBwUg18eA3yeHlYLozfApF8MhZ6tICXkDqf8JCl5i+ACa0sJrW9prg==","signatures":[{"sig":"MEQCIFj6F0LNKTxl4WTwUFZ8YkD7ccSjyJ7aWlpAwWJxqGupAiBTqf7uQtjBXD5hE00UgRbSZFeI6Myoo0umdUhuokvD1A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDuRvo2ISluNJW4Ore0reUMB0Bl4aQSpUm8iv1j08o6kQIgUDP1AsWkkSdkEUPQ1KsSLbG5rQKT6OQTEiJGV2rT8EM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/memory-lean@1.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":195102},"type":"module","engines":{"node":">=18"},"funding":[{"url":"https://www.buymeacoffee.com/zamansheikh","type":"buymeacoffee"},{"url":"https://ko-fi.com/zamansheikh","type":"ko-fi"}],"gitHead":"7f5e5da00308a9e00cd6af55a9684b76db493e75","mcpName":"io.github.zamansheikh/memory-lean","scripts":{"test":"node --test","version":"node tools/sync-version.mjs && git add server/memory-lean.mjs plugin/.claude-plugin/plugin.json server.json plugin/.mcp.json plugin/commands/memory-ui.md","lint-graph":"node server/memory-lean.mjs --lint"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"4a724619-6cd8-4867-947f-5c4e4a0ec825"}},"repository":{"url":"git+https://github.com/zamansheikh/memory-lean.git","type":"git"},"_npmVersion":"12.2.2","description":"A token-lean MCP memory server: a knowledge graph your AI agent can search without reading the whole thing. Drop-in replacement for @modelcontextprotocol/server-memory.","directories":{},"_nodeVersion":"24.22.2","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/memory-lean_1.6.0_1794404785372_0.9502089318860422","host":"s3://npm-registry-packages-npm-production"}},"1.6.1":{"_id":"memory-lean@1.6.1","bin":{"memory-lean":"server/memory-lean.mjs"},"bugs":{"url":"https://github.com/zamansheikh/memory-lean/issues"},"dist":{"shasum":"3d72df7d91cd398401cbd8733f744c39b2c32027","tarball":"https://registry.npmjs.org/memory-lean/-/memory-lean-1.6.1.tgz","fileCount":10,"integrity":"sha512-+okiRA02OPWZstNnR8ZTZe7ovbdJde3/RBhCIFdfN1JJxaNY+EPZG+9L0f2nOJAX/de5wi1/GFG+pozTlp7DGw==","signatures":[{"sig":"MEYCIQCa5IHrsLf4f5WBRxceFHdbDf+FZzsF2NK/zGKVSfBIzQIhAJl5crDxxOj1ucGfxk4pxwyk3LWRz3jmUkaJxHiMCeVF","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCo2QSnaht/iFdCmWwuQI0KMdcuijU/nxWCzKnyXrO+FQIhANZa+vcXszEIO2mxAp2IqBdJT5PsuAwSnd3/1I6FEVMP"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/memory-lean@1.6.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":196847},"name":"memory-lean","type":"module","author":{"url":"https://zamansheikh.com","name":"Zaman Sheikh"},"engines":{"node":">=18"},"funding":[{"url":"https://www.buymeacoffee.com/zamansheikh","type":"buymeacoffee"},{"url":"https://ko-fi.com/zamansheikh","type":"ko-fi"}],"gitHead":"00adffff7002eb333021d06959ebb21aa60813a3","license":"MIT","mcpName":"io.github.zamansheikh/memory-lean","scripts":{"test":"node --test","version":"node tools/sync-version.mjs && git add server/memory-lean.mjs plugin/.claude-plugin/plugin.json server.json plugin/.mcp.json plugin/commands/memory-ui.md","lint-graph":"node server/memory-lean.mjs --lint"},"version":"1.6.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"4a724619-6cd8-4867-947f-5c4e4a0ec825"}},"homepage":"https://github.com/zamansheikh/memory-lean#readme","keywords":["mcp","mcp-server","model-context-protocol","memory","knowledge-graph","claude","claude-code","cursor","ai-agent","tokens"],"repository":{"url":"git+https://github.com/zamansheikh/memory-lean.git","type":"git"},"_npmVersion":"12.2.2","description":"A token-lean MCP memory server: a knowledge graph your AI agent can search without reading the whole thing. Drop-in replacement for @modelcontextprotocol/server-memory.","directories":{},"maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"_nodeVersion":"24.22.2","_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/memory-lean_1.6.1_1794409288496_0.4758392884640885"}}},"time":{"created":"2026-10-09T12:24:18.907Z","modified":"2026-11-11T15:01:29.096Z","0.0.0-stage":"2026-10-09T12:24:18.907Z","1.1.0":"2026-10-09T12:25:16.716Z","1.4.0":"2026-10-09T12:48:59.174Z","1.4.1":"2026-10-09T12:57:42.687Z","1.5.0":"2026-10-16T12:37:31.997Z","1.6.0":"2026-11-11T13:46:25.490Z","1.6.1":"2026-11-11T15:01:28.605Z"},"bugs":{"url":"https://github.com/zamansheikh/memory-lean/issues"},"author":{"url":"https://zamansheikh.com","name":"Zaman Sheikh"},"license":"MIT","homepage":"https://github.com/zamansheikh/memory-lean#readme","keywords":["mcp","mcp-server","model-context-protocol","memory","knowledge-graph","claude","claude-code","cursor","ai-agent","tokens"],"repository":{"url":"git+https://github.com/zamansheikh/memory-lean.git","type":"git"},"description":"A token-lean MCP memory server: a knowledge graph your AI agent can search without reading the whole thing. Drop-in replacement for @modelcontextprotocol/server-memory.","maintainers":[{"name":"zamansheikh","email":"zaman6545@gmail.com"}],"readme":"

\n \"memory-lean\n

\n\n

memory-lean

\n\n

\n Long-term memory for AI coding agents that doesn't burn the context window.
\n A knowledge graph your agent searches cheaply, and a web UI where you can see and edit all of it.\n

\n\n

\n \"npm\n \"npm\n \"tests\"\n \"listed\n \"zero\n \"MIT\n

\n\n

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

\n\n

\n \"A\n

\n\nmemory-lean is an [MCP](https://modelcontextprotocol.io) server that gives Claude\nCode, Codex, Cursor, MiMo Code and any other MCP client a memory that lasts between\nsessions: which projects exist, what depends on what, which version shipped, what\nis still pending, and which rules were learned the hard way. It is a drop-in\nreplacement for the reference memory server\n([`@modelcontextprotocol/server-memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)),\nwith the same file and tool names, but its answers are about 40 times smaller.\n\n## Install and update\n\nmemory-lean needs Node.js 18 or newer and nothing else.\n\n```bash\nnpm install -g memory-lean # install\nnpm install -g memory-lean@latest # update to the newest release\nmemory-lean --version # the version you have\n```\n\nInstalled this way, the command in your agent's MCP config is `memory-lean`.\nThe other two ways to run it need no npm command:\n\n| | Install | Update |\n|---|---|---|\n| **npx** | Nothing to install: the config in [Quick start](#quick-start) runs `npx -y memory-lean` | Automatic: npx fetches the newest release when the agent starts the server |\n| **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` |\n\n- **Restart after an update.** A session that is already open keeps the server\n it started with. Start a new session, or reconnect the `memory` server in your\n agent (`/mcp` in Claude Code).\n- **Your memory is not touched.** An update replaces the server only. The graph\n file stays as it is (`~/.claude/memory-graph/memory.jsonl` unless you moved\n it), and every version reads the same file.\n- **npx still runs an old version?** Older npm versions reuse the copy they\n downloaded first. Write `memory-lean@latest` in the config instead of\n `memory-lean`.\n\nWhat changed in each release is in the [changelog](CHANGELOG.md).\n\n## Highlights\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\n\n**About 40× smaller answers.** Search returns a ranked list of names and the lines\nthat matched, not every entity in full, so the agent can afford to check its\nmemory before every task.\n\n\n\n**A web UI for people.** See the whole graph grouped by type, follow relations,\nand add, edit or delete anything. Agent writes show up live.\n\n
\n\n**Drop-in replacement.** Same `memory.jsonl` file and the same nine tools as the\nreference server. Switch in, and switch back whenever you like.\n\n\n\n**Works with every agent.** Copy-paste setup for Claude Code, MiMo Code, Codex,\nCursor, Copilot, Gemini CLI, Zed, JetBrains and more, plus the instructions that\nteach the agent to use it.\n\n
\n\n**Stays small by itself.** Short facts, a cap per entity, and an archive for the\noverflow, so the graph never grows into a wall of text.\n\n\n\n**Private and safe.** Plain local files, daily backups, a write lock for parallel\nsessions, and no network access. One server file, zero dependencies.\n\n
\n\n## The numbers\n\nMeasured on a real graph of 237 entities, 355 relations and 1,160 facts\n(tokens ≈ characters ÷ 4):\n\n| Call | Reference server | memory-lean | |\n|---|---:|---:|---:|\n| `read_graph` | ~77,800 tokens | ~2,000 tokens | **40× smaller** |\n| `search_nodes`, average of 5 common words | ~31,000 tokens | ~770 tokens | **40× smaller** |\n\nA narrow search that matches one or two entities saves less, because there is\nlittle to trim. To measure your own graph, run `node tools/bench.mjs` from a clone;\nit is read-only and prints sizes, never content.\n\n## Quick start\n\n**Claude Code**: install the plugin. It adds the server, the instructions as a\nskill, a short reminder at the start of each session, and `/memory-ui`.\n\n```text\n/plugin marketplace add zamansheikh/memory-lean\n/plugin install memory-lean@memory-lean\n```\n\n**Any other agent**: add the server to its MCP config. It tells the agent the\nbasics when it starts; the full instructions go into the rules file your agent reads.\n\n```json\n{\n \"mcpServers\": {\n \"memory\": { \"command\": \"npx\", \"args\": [\"-y\", \"memory-lean\"] }\n }\n}\n```\n\n```bash\nnpx -y memory-lean --protocol >> AGENTS.md # into the rules file your agent reads\n```\n\n**Just looking?** Open the web UI on a made-up example graph:\n\n```bash\nnpx -y memory-lean --ui --demo\n```\n\n
\nSetup for each agent\n\n
\n\n| Agent | Server config | Instructions |\n|---|---|---|\n| [Claude Code](docs/SETUP.md#claude-code) | plugin | included in the plugin |\n| [Xiaomi MiMo Code](docs/SETUP.md#xiaomi-mimo-code) | `mimocode.jsonc` | skill or `AGENTS.md` |\n| [opencode](docs/SETUP.md#opencode) | `opencode.json` | `AGENTS.md` |\n| [OpenAI Codex CLI](docs/SETUP.md#openai-codex-cli) | `codex mcp add` | `AGENTS.md` |\n| [Cursor](docs/SETUP.md#cursor) | `.cursor/mcp.json` | `AGENTS.md` or a rule |\n| [VS Code (Copilot)](docs/SETUP.md#vs-code-github-copilot) | `.vscode/mcp.json` | `copilot-instructions.md` |\n| [Gemini CLI](docs/SETUP.md#gemini-cli) | `settings.json` | `GEMINI.md` |\n| [Windsurf](docs/SETUP.md#windsurf) | `mcp_config.json` | a rule |\n| [Cline](docs/SETUP.md#cline) | `cline_mcp_settings.json` | `.clinerules/` |\n| [Zed](docs/SETUP.md#zed) | `settings.json` | `AGENTS.md` or `.rules` |\n| [JetBrains IDEs](docs/SETUP.md#jetbrains-ides) | AI Assistant settings | a rule or guidelines |\n| [Claude Desktop](docs/SETUP.md#claude-desktop) | `claude_desktop_config.json` | project instructions |\n\n
\n\nThe graph is created on the first write at `~/.claude/memory-graph/memory.jsonl`,\nwhichever agent writes it, so all your agents share one memory. Set\n`MEMORY_FILE_PATH` to keep it somewhere else.\n\n## Web UI\n\n```bash\nnpx -y memory-lean --ui\n```\n\nThis opens your memory in the browser. Everything an agent can do, you can do here:\n\n- **Explore.** Each type gets its own bubble. Click an entity to highlight\n everything it connects to, drag nodes to arrange them, and scroll to zoom.\n Search matches names, types and facts.\n- **Edit.** Add, edit and delete facts, rename an entity or change its type, add\n and remove relations, create and delete entities, and restore archived facts.\n Every change passes the same checks as the agents' tools.\n- **Watch.** Changes your agents make appear within two seconds.\n- **Spot problems.** The overview lists pending work, the most connected\n entities, anything over budget (also marked on the graph), and signs the graph\n needs tidying: finished pending work, near-duplicate names, entities nothing\n links to.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
\"An\"Searching
Follow the connections. Select an entity to see its facts and relations.Find anything. Search names, types and facts at once.
\"Editing\"The
Edit in place. With the same 300-character limit the agents have.Light or dark. It follows your system, or pick one.
\n\nThe page runs on your machine only (`127.0.0.1`) and needs the one-time key in\nthe link it prints, so other websites cannot read or change your memory. Nothing\nis uploaded anywhere.\n\n## How it works\n\n### Search, then open\n\nThe reference server answers a search with every matching entity in full, as\npretty-printed JSON. memory-lean answers with a ranked list of names and the lines\nthat matched:\n\n```text\n> search_nodes { \"query\": \"deploy\" }\n\n57 match \"deploy\", top 10 shown (narrow the query or raise limit). open_nodes for full entities.\n- shop-backend [service] 12 obs, 6 rel\n › deploy with scripts/release.sh, never by hand\n › 2026-03-02: deployed 2.4.0 to production\n- PENDING shop-backend 2.4.0 [pending] 2 obs, 3 rel\n › …mobile apps still call the old endpoint until the deploy of 2.4.0 reaches them\n```\n\nThe agent then opens only what it needs:\n\n```text\n> open_nodes { \"names\": [\"shop-backend\"], \"related\": true }\n\n## shop-backend [service] (3 archived)\n- NestJS API behind api.example.com\n- 2026-03-02: deployed 2.4.0 to production\n\n## relations\nRULE no Friday deploys -applies_to-> shop-backend\n › Deploys after Thursday 18:00 need the on-call's approval\nPENDING shop-backend 2.4.0 -blocks-> shop-backend\n › 2026-03-02: 2.4.0 published, the apps still call the old endpoint (+1 more)\nshop-app -talks_to-> shop-backend\n```\n\nWith `related: true`, the rules and pending work that touch the entity come\nfirst, each introduced by its first fact. A rule is often a single fact, so one\ncall is enough to start a task, and `(+1 more)` says when opening one would add\nsomething.\n\nA search that is too narrow does not just fail. It names the term that is nowhere\nand the entities that come closest, so the agent drops the right word instead of\nguessing:\n\n```text\n> search_nodes { \"query\": \"shop release pipeline\" }\n\nNo entities match \"shop release pipeline\". In no entity: pipeline. Closest (2 of 3 terms): shop-backend, shop-app.\n```\n\nFacts that were moved to the archive still answer a search. An entity whose only\nmatch is an archived fact is named after the current ones, and shown with a\nsnippet when nothing current matches:\n\n```text\n> search_nodes { \"query\": \"postgres\" }\n\nNo current facts match \"postgres\".\nOnly in archived observations (archived_observations lists and restores them):\n- shop-backend [service] 1 archived\n › 2025-11-20: moved from MySQL to Postgres 16\n```\n\nResults are ranked so that a term in the entity's name counts, and one fact\nholding every term counts for more than several facts holding one each. The\nfacts shown are about the terms the name does not already answer: a standing\nfact first, then the newest. A term matches as any part of a word, so `deploy`\nfinds `deployed`, but a whole word ranks above the start of a longer word, and\nthat above the middle of one.\n\n### Why it stays lean\n\n| Limit | What it means |\n|---|---|\n| **Small answers** | `search_nodes` returns at most 10 names with snippets, `read_graph` returns an index of names (past about 2,000 tokens, the largest types as a count), and only `open_nodes` returns full entities. |\n| **Short facts** | The tools ask for facts of under 150 characters, and a write that goes over says so. One longer than 300, or spread over several lines, is rejected, with a message telling the agent to split it or put the detail in the repo. |\n| **Cheap updates** | A stale fact is replaced in one call, named by a distinctive part of its text, so the agent does not repeat 300 characters to change one version number. |\n| **A cap per entity** | An entity keeps 15 observations. Past that, the oldest dated ones move to `archive/.md`. Nothing is deleted: they can be listed and restored, and undated facts (the identity facts) always stay. |\n| **Search that narrows** | Every 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. |\n\n### How it keeps your data safe\n\n| Safeguard | What it means |\n|---|---|\n| **Safe to share** | Writers take a lock file, so several agent sessions can use one graph without overwriting each other. Every write replaces the file atomically. |\n| **Daily backups** | A copy goes to `backups/` once a day; the last 7 are kept. |\n| **Damaged lines are kept** | A line that cannot be read is moved to `memory.jsonl.unreadable` on the next write and reported, never silently dropped. |\n| **Plain files** | The graph is JSON lines, archives are Markdown, backups are copies. You can read, grep and edit all of it by hand. |\n\n## Tools\n\n| Tool | What it returns |\n|---|---|\n| `search_nodes` | Ranked 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. Entities that match only in archived facts are named after them, with a snippet each when nothing current matches. |\n| `open_nodes` | The full entities you name, as compact text, with every relation touching them and their archive count. With `related: true`, related rules and pending work come first, each with its first fact. A name that is right but for its case or separators still opens; other unknown names come back with \"did you mean\" suggestions. |\n| `read_graph` | An index: entity names grouped by type, with observation counts. Never the observations. In a large graph the biggest types are given as a count; `entityType` lists one. |\n| `create_entities` | Creates entities; existing names are skipped. |\n| `create_relations` | Creates relations between existing entities; duplicates are skipped. |\n| `add_observations` | Adds facts to an entity, enforcing the length limit and the per-entity cap. |\n| `replace_observation` | Replaces one fact in place. The old fact is named by its exact text or by a part of it (8+ characters) that no other fact of the entity contains. *Not in the reference server.* |\n| `delete_observations` | Removes observations, named by exact text or by such a part. |\n| `delete_relations` | Removes specific relations. |\n| `delete_entities` | Removes entities and every relation touching them. Their archived facts stay on disk, marked as deleted, and are not passed on to a later entity of the same name. |\n| `rename_entity` | Renames an entity, keeping its observations, relations and archive. *Not in the reference server.* |\n| `archived_observations` | Lists what was archived for an entity, optionally filtered, and restores chosen facts. *Not in the reference server.* |\n\nThe three read tools are marked read-only, so clients that support it can run them\nwithout asking.\n\n## Command line\n\n| Command | What it does |\n|---|---|\n| `memory-lean` | Runs the MCP server over stdio. This is what agents start. |\n| `memory-lean --ui [port]` | Opens the web UI. `--no-open` only prints the link; `--demo` uses a throwaway copy of a made-up graph. |\n| `memory-lean --protocol` | Prints the agent instructions, ready to append to `AGENTS.md`, `CLAUDE.md` or `GEMINI.md`. |\n| `memory-lean --skill ` | Writes the same instructions as an Agent Skill into `/memory-graph`. |\n| `memory-lean --lint` | Reports what in the graph is over budget or needs tidying: pending work that blocks nothing or has gone quiet, near-duplicate names, entities with no relations or with no fact saying what they are, relations to nothing, archives of no entity. Read-only. |\n| `memory-lean --compact` | Backs up the graph, then moves overflow observations to the archive. |\n| `memory-lean --version` | Prints the version. |\n\nWith npx, put `npx -y` in front: `npx -y memory-lean --ui`.\n\n## Teach your agent to use it\n\nA memory server only helps if the agent reads it before working and writes to it\nwhen something changes. The server says so itself: when it starts, it sends the\nclient four sentences on when to read the graph and what to record, which most\nagents show to the model (about 190 tokens; `MEMORY_INSTRUCTIONS=off` stops it).\nWhen the folder the agent works in is named like an entity in the graph, it also\nsays which entity to open first. That is enough to get going.\n\n[`docs/AGENT-PROTOCOL.md`](docs/AGENT-PROTOCOL.md) is the full version, a\nready-made set of instructions: what to look up at the start of a task, what to\nrecord, how to name things, and what never to store. The Claude Code plugin\nincludes it. For every other agent, one command installs it:\n\n```bash\nnpx -y memory-lean --protocol >> AGENTS.md # into a rules file: always on\nnpx -y memory-lean --skill .agents/skills # as an Agent Skill: loaded when relevant\n```\n\nAdjust the entity types and names in it to your own work.\n\n## Coming from the reference memory server\n\nPoint `MEMORY_FILE_PATH` at your existing `memory.jsonl` and swap the command. The\nfile format is identical, so you can switch back at any time. Existing\nobservations longer than 300 characters are kept as they are; only new writes are\nchecked. To see what is over budget, and optionally fix it:\n\n```bash\nnpx -y memory-lean --lint # report only\nnpx -y memory-lean --compact # back up, then move overflow to archive/\n```\n\n## Settings\n\nAll optional, set as environment variables on the server:\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `MEMORY_FILE_PATH` | `~/.claude/memory-graph/memory.jsonl` | Where the graph lives |\n| `MEMORY_OBS_MAX_CHARS` | `300` | Longest observation accepted. The tools ask agents to aim for half of it |\n| `MEMORY_OBS_MAX` | `15` | Observations per entity before the oldest dated ones are archived |\n| `MEMORY_SEARCH_LIMIT` | `10` | Default number of search results |\n| `MEMORY_BACKUPS_KEPT` | `7` | Daily backups kept |\n| `MEMORY_INSTRUCTIONS` | on | `off` stops the server sending its short usage note to the client |\n\n## FAQ\n\n
\nIs my memory sent anywhere?\n\n
No. The server reads and writes local files and makes no network requests. The\nweb UI listens on 127.0.0.1 only. Keep the graph out of git, and never\nstore passwords, keys or tokens in it: record where a secret lives, not its value.\n
\n\n
\nCan several agents or sessions share one graph?\n\n
Yes. Every write takes a lock, re-reads the file and replaces it atomically, so\nparallel sessions (and the web UI) do not overwrite each other.\n
\n\n
\nWhy plain text search instead of embeddings?\n\n
It needs no model, no index and no dependencies, and an agent's queries are\nmostly names it already knows. Good entity names matter more than clever queries.\n
\n\n
\nWhat happens to old facts?\n\n
When an entity passes 15 facts, the oldest dated ones move to\narchive/<entity>.md next to the graph. search_nodes still finds\nthem, and archived_observations, or the Archive section in the web UI, lists\nand restores them.\n
\n\n## Roadmap\n\n- [x] Claude Code plugin with the server, a skill and `/memory-ui`\n- [x] Setup guides for 12 agents\n- [x] `rename_entity` and archive restore\n- [x] A web UI to explore and edit the graph\n- [x] Listed in the official MCP registry\n- [x] Search across the archived facts of every entity\n- [x] A health report in `--lint` and the web UI\n- [ ] Listed in the Claude Code plugin directory\n- [ ] Undo in the web UI\n\n## Contributing\n\nIdeas, bug reports and pull requests are welcome. The server is one file with no\ndependencies, the web UI is one HTML file, and `npm test` runs in a few seconds,\nso a first change is quick to make. [CONTRIBUTING.md](CONTRIBUTING.md) has the\nlayout, the ground rules and a list of good first contributions.\n\nIf memory-lean saves you tokens, a ⭐ helps other people find it.\n\n## Support\n\nmemory-lean is free and MIT licensed. If it is useful to you, you can support the\nwork:\n\n

\n \"Buy\n \"Ko-fi\"\n

\n\n## Author\n\nCreated and maintained by **[Zaman Sheikh](https://zamansheikh.com)** at\n[Silifton](https://silifton.com).\n\n

\n \"GitHub\"\n \"X\"\n \"LinkedIn\"\n \"Website\"\n

\n\nBuilt on the file format and tool names of the\n[Model Context Protocol reference memory server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory).\n\n## License\n\n[MIT](LICENSE) © 2026 [Zaman Sheikh](https://zamansheikh.com). Free to use, change\nand share, including commercially; keep the copyright notice.\n","readmeFilename":"README.md"}