Wuesteon/lean-memory

Embedded, local-first agent memory. No server, no daemon, no mandatory cloud key.
> **Status (2026-07):** first public release line (0.2.1) is live on PyPI and
> the MCP Registry (MCP-first launch); the Claude Code plugin ships in this
> repo (marketplace listing pending).
> Roadmap and rationale: docs/superpowers/specs/2026-07-08-strategic-direction-design.md.
> Public benchmark runs (LongMemEval/LoCoMo) are deliberately deferred until
> after launch; the harness is complete (bench/phase2_*.py) and the engine
> flaws it exposed are fixed — see docs/phase2-learnings.md.
Facts are extracted from natural language, stored in a per-namespace SQLite file, and retrieved with hybrid dense+sparse search. Old facts are never deleted — they're superseded and queryable at any past point in time.
Install
Runs fully offline out of the box. Optional extras unlock real model quality:
| Extra | What it adds |
|---|---|
| lean-memory[models] | Real embedder + reranker (Qwen3-0.6B + Ettin-32M) |
| lean-memory[extract] | GLiNER2 candidate generation for richer extraction |
| lean-memory[llm] | Ollama-backed LLM typing pass |
| lean-memory[mcp] | MCP server bridge for Claude Desktop / Claude Code |
| lean-memory[examples] | Terminal demo agent (requires anthropic SDK) |
Quickstart
Demo Agent
A terminal chatbot showing the full memory loop — add, retrieve, supersede, restart.
The demo script lives in the repo (it is not installed with the package):
No API key? The demo still runs — it echoes the retrieved memory context instead of calling Claude, so you can watch the engine work offline.
MCP Server — memory for Claude Code / Claude Desktop
Give any MCP agent persistent local memory: three tools (memory_add,
memory_search, memory_clear), one SQLite file per namespace, nothing
leaves your machine.
> First run downloads three open models (~2.0 GB total: Qwen3-Embedding-0.6B
> + Ettin-32M reranker for retrieval, plus GLiNER2-base (~0.8 GB) for real
> extraction — all ungated). Pre-warm once so your MCP client never waits on
> a download:
>
>
**Claude Code:**
**Claude Desktop** — add to mcpServers (or copy examples/mcp_config.json):
Data root: LM_DATA_ROOT (default ~/.lean_memory). Works offline-only too —
the server opportunistically upgrades each backend that its extra is installed
for ([models] → real embedder + reranker, [extract] → GLiNER2 extraction)
and otherwise falls back to deterministic stub backends (fine for CI,
semantically meaningless for real use — install [mcp,models,extract]).
> **What the optional [llm] extra buys.** The canonical [mcp,models,extract]
> install has no LLM typing pass, so the ~15% of candidates that escalate —
> almost all of them inferential (derives) facts — are typed by a
> deterministic stub instead of a model. Assertional facts are unaffected;
> inference-type facts are effectively second-class on the default path. Adding
> [llm] (a local Ollama model) upgrades that escalated tier to real
> constrained typing. See ARCHITECTURE.md → Known Limitations.
Sleep-time maintenance & review
Memory accumulates cruft: the same fact restated a dozen ways, old records that
never come up, clusters begging to be summarized. lean-memory cleans it up the
way sleep consolidates memory — an **offline job you run off-hours** that dedupes,
summarizes, and demotes low-value records, then hands you the judgment calls to
click through the next morning, in the web console **or conversationally in
Claude Code**.
**The CLI** (lean-memory-maintain) is the primary trigger. It is **dry-run by