jagoff/memo

**Your coding agent starts every session with amnesia. memo fixes that — 100% on your own machine.**
Persistent, searchable memory for Claude Code, Codex, Cursor, Cline, Devin, and OpenCode. No cloud, no API keys, no Ollama, no vector DB to run. And it spends *fewer* tokens, not more.
---
Install
Prefer a package manager? uv tool install mlx-memo · pipx install mlx-memo · brew tap jagoff/memo && brew install mlx-memo
Then:
That's it. Your agents pick it up over MCP automatically — the installer wires every client it finds.
Installing on another Mac or handing setup to an agent?
New Mac:
Agent-managed setup:
**On Linux or just want to look around first?**
---
Why this saves you money
Most memory servers *add* context. memo is built to remove it.
| Profile | Tools | Schema tokens |
|---|---:|---:|
| agent (default) | 43 | ~9.7k |
| core / slim | 60 | ~13.2k |
| full / default | 165 | ~30.6k |
The default MCP surface is 43 tools, not 165 — 74% fewer tools, and about 68% less schema context: **43 tools / ~9.7k schema tokens** versus **165 tools / ~30.6k tokens** on the full surface — overhead paid every session, in every client.
Ambient recall injects one relevant memory before the model answers. The bundled Claude Code hook caps that injection at ~160 tokens. memo roi reports the real grounding and re-ask counts — the estimated-savings figure it used to print was removed in 4.14.0, because multiplying those counts by hardcoded constants was a savings claim memo could not support. For measured savings, memo tokens reads the provider's own usage counters through the context-compression proxy.
---
Three things nothing else does
🕰️ Time-machine — query your knowledge as it was
Full historical reconstruction by reverse-replaying history.db. Useful when you need to know *why* past-you made a call, not just what past-you decided.
⚡ Contradiction radar — memory that notices when you change your mind
Change a decision and memo flags the now-stale version, so the agent stops reintroducing what you already threw out.
🔮 Dream — it optimizes itself while you sleep
A 7-phase nightly pipeline: inventory → mine signals → resolve conflicts → prune stale → synthesize cross-cluster insights → optimize → pre-warm the top-100 query embeddings so tomorrow's recall stays under 200 ms. Every run writes a receipt you can audit. Zero intervention.
---
How it works
**Hybrid retrieval.** A vector leg (MLX on Apple Silicon, sentence-transformers on CPU) and a BM25 leg (FTS5, diacritic-folding for Spanish) run in parallel, fuse via Reciprocal Rank Fusion, then go through an optional MLX cross-encoder rerank.
**Markdown is the source of truth.** Every memory is a plain .md file you can read, grep, and version-control. SQLite is a derived index that rebuilds from the files at any time — hand-edit in Obsidian and your edit wins on the next memo reindex. Nothing is locked in a database you can't open.
**Prompts and memories stay on your machine.** Embedder, reranker, and LLM all run in-process. No telemetry. Memory travels only if *you* point memo sync at a git remote you own. Normal startup is fully offline; remote update checks and auto-update require an explicit opt-in. → **Privacy and network policy**
Also in the box: cross-agent memo resume (reopen any session from any agent), cross-Mac git sync, a knowledge graph with optional codegraph symbol edges, encrypted secret storage, OCR/audio ingestion, evidence packs, outcome learning, signed federation, and a local chat UI over your memory (memo chat serve). → **Full feature reference**