# lean-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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 43
- Author: Wuesteon
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Wuesteon/lean-memory
- Updated: 2026-08-07
- HTML: https://affpapa.org/en/nevibecode/mcp/lean-memory

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `LM_DATA_ROOT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env LM_DATA_ROOT=<LM_DATA_ROOT> --transport stdio lean-memory -- uvx lean-memory
```
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>

### Codex

**Platform CLI**
```bash
codex mcp add lean-memory --env LM_DATA_ROOT=<LM_DATA_ROOT> -- uvx lean-memory
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e LM_DATA_ROOT=<LM_DATA_ROOT> lean-memory uvx lean-memory
```
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>

## When to use it
- 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
- 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.

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872
- [AIHawk](https://affpapa.org/en/nevibecode/mcp/aihawk.md) — MCP server · ★ 32221

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md