lean-memory MCP server

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.

from lean_memory import Memory

mem = Memory(root="./data")

mem.add("user-42", "I work at Acme Corp.")
mem.add("user-42", "I now work at Globex.")          # supersedes Acme automatically

mem.search("user-42", "where does the user work?")   # → "I now work at Globex."

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

pip install lean-memory

Runs fully offline out of the box. Optional extras unlock real model quality:

Quickstart

from lean_memory import Memory

mem = Memory(root="./data")   # one SQLite file per namespace, stored under ./data/

# Store facts in natural language
mem.add("alice", "I work at Stripe.")
mem.add("alice", "I now work at Vercel.")   # supersedes Stripe automatically

# Retrieve — the superseded Stripe fact drops out; only the current one is returned
results = mem.search("alice", "what does Alice do for work?", k=3)
for hit in results:
    print(hit.fact.fact_text, hit.final_score)
# → I now work at Vercel. 0.89

# Point-in-time query — what was true at a specific moment?
mem.search("alice", "employer", as_of=1_700_000_000_000, is_latest_only=False)  # epoch ms

# Always close when done (flushes WAL)
mem.close()

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

git clone https://github.com/Wuesteon/lean-memory && cd lean-memory
pip install -e '.[examples]'
export ANTHROPIC_API_KEY=sk-ant-...
python examples/chat.py                  # uses offline stubs by default
python examples/chat.py --namespace bob  # separate memory tenant, persists across restarts

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 (memoryadd, memorysearch, memory_clear), one SQLite file per namespace, nothing leaves your machine.

pip install 'lean-memory[mcp,models,extract]'

Shortened. The full README is on GitHub.