lean-memory — Claude Code MCP server: local agent memory
Local memory for MCP agents: facts from a conversation land in a SQLite file and come back through hybrid search. Nothing leaves your machine.
claude mcp add --env LM_DATA_ROOT=<LM_DATA_ROOT> --transport stdio lean-memory -- uvx lean-memoryWhat lean-memory does
lean-memory keeps the facts an agent picks up while you work. You write them in plain language; the engine pulls out the statements and files them per namespace, each namespace getting its own SQLite file under LM_DATA_ROOT (default ~/.lean_memory). Nothing is thrown away. A newer fact supersedes the older one, yet the older one stays reachable through a point-in-time query — handy when you want to know what the agent believed earlier.
The MCP server exposes three tools: memory_add, memory_search, memory_clear. Retrieval mixes dense and sparse scoring. With no extras the server runs offline against stubs, which is fine for CI and useless for real work. Install lean-memory[mcp,models,extract] instead: that pulls in a real embedder and reranker, with GLiNER2 handling extraction. The first run downloads three open models, roughly 2.0 GB in total, so warm them up ahead of time or your client will sit waiting on the download.
Memory also needs upkeep. lean-memory-maintain dedupes records, summarizes clusters and demotes entries that stopped surfacing. It is a dry run by default — the command reports and writes nothing; pass --apply to change anything. Running it overnight on a schedule makes sense, then you review the judgement calls in the morning.
What it helps with
- give an agent memory that survives restarts without a cloud service
- surface the current fact when an older version has been superseded
- check what the agent knew at a given point in time
- clear out duplicate and stale records that piled up
- keep separate memory files for different users
Example prompts for the agent
- Remember this: I work at Globex.
- What do you know about where I work?
- Run memory maintenance across all namespaces and show me the report without writing anything.
How to install lean-memory
Platform CLI
claude mcp add --env LM_DATA_ROOT=<LM_DATA_ROOT> --transport stdio lean-memory -- uvx lean-memoryReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from lean-memory <command>
Platform CLI
codex mcp add lean-memory --env LM_DATA_ROOT=<LM_DATA_ROOT> -- uvx lean-memoryReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from lean-memory <command>
Config file
{
"mcpServers": {
"lean-memory": {
"command": "uvx",
"args": [
"lean-memory"
],
"env": {
"LM_DATA_ROOT": "<LM_DATA_ROOT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from lean-memory <command>
Config file
{
"servers": {
"lean-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"lean-memory"
],
"env": {
"LM_DATA_ROOT": "<LM_DATA_ROOT>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from lean-memory <command>
Platform CLI
gemini mcp add -e LM_DATA_ROOT=<LM_DATA_ROOT> lean-memory uvx lean-memoryReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from lean-memory <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about lean-memory
How do I install lean-memory in Claude Code?
Run claude mcp add lean-memory -- uvx lean-memory. To point it at your own data directory, use claude mcp add --env LM_DATA_ROOT=<LM_DATA_ROOT> --transport stdio lean-memory -- uvx lean-memory.
What does lean-memory do?
It is an MCP server for local memory: it extracts facts from natural language, stores them in SQLite per namespace and returns them through hybrid search. Newer facts supersede older ones while the older ones remain queryable as of a past moment.
What does lean-memory need to work?
The lean-memory[mcp,models,extract] install plus a one-time download of three open models, about 2.0 GB. Without those extras the server falls back to stubs, which suits checks rather than real retrieval.
