memo

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

curl -fsSL https://raw.githubusercontent.com/jagoff/memo/v4.16.0/install.sh | bash

Prefer a package manager? uv tool install mlx-memo · pipx install mlx-memo · brew tap jagoff/memo && brew install mlx-memo

Then:

memo doctor                                   # self-check

memo save 'we use Postgres, not Mongo' # save a decision memo search 'what database did we pick?' # search by meaning

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:

curl -fsSL https://raw.githubusercontent.com/jagoff/memo/v4.16.0/install.sh | bash

memo sync bootstrap git@github.com:yourname/memo-sync.git

Agent-managed setup:

curl -fsSL https://raw.githubusercontent.com/jagoff/memo/v4.16.0/install.sh | bash

memo doctor --strict-runtime

On Linux or just want to look around first?

docker run --rm ghcr.io/jagoff/memo:latest memo doctor

---

Why this saves you money

Most memory servers *add* context. memo is built to remove it.

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.

memo roi       # value from grounded recalls and avoided re-asks

memo tokens # usage-savings ledger

---

Three things nothing else does

🕰️ Time-machine — query your knowledge as it was

memo as-of ask "what was the deploy strategy?" --date 2026-02-01

memo diff --from 2026-01-01 --to 2026-03-01

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

memo contradict scan      # find conflicting facts corpus-wide

memo contradict triage # resolve: fuse / newer-wins / dismiss

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

memo dream run

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](https://github.com/jagoff/memo/blob/master/PRIVACY.md)

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](https://github.com/jagoff/memo/blob/master/docs/reference.md)

---

How it compares

Verified July 2026 against each project's own docs. Corrections welcome — open an issue and I'll fix the table.

✅ first-class · ⚠️ partial, config-gated, or add-on · ❌ absent

Closest comparators are basic-memory (local-first + Obsidian + MCP — same thesis) and cipher (memory for coding agents).

---

Requirements

Python ≥ 3.13 (the installer handles this via uv if you don't have it). First install pulls ~8 GB of models, 5–15 min. Optional: an Obsidian vault — without one, memo uses ~/Documents/memo/.

---

Docs

All 145 top-level CLI commands

Complete command inventory (kept here so CI detects CLI/documentation drift)

Core: save search ask get edit rename delete list

Recall & Hooks: recall recall-hook context briefing continuity prewarm capture-tick capture-stop interject ask-gaps guard digest

Session & History: history as-of diff record-history session chat-session resume reflect mine-history episodes chronicle

Maintenance: reindex maintain review dream consolidate synthesize dedupe cross-dedup retier contradict coordinate terminal invalidate temporal compress-context ops

Analysis & Quality: health stats doctor journey-check lint drift analytics eval roi tokens token-savings usefulness gaps outcome profile confidence graduation hype definitive evidence

Knowledge Graph: graph entities entity extract-entities links version related

Advanced Search: embed rerank contextual retrieve context-pack chat chat-ask repo

Import / Export / Sync: import export backup restore sync ingest federation

Visualization: tui dashboard map logs hook-log

Setup & Config: init setup config install-mcp install-watcher uninstall-watcher install-slash install-statusline install-recall-hook install-shell-wrapper install-shims startup-banner migrate migrate-vault migrate-independence update upgrade self-update watch release onboard

Daemons: daemons recall-daemon ingest-daemon maint-daemon embed-daemon idle-daemon

Other: backend-native collaborative events feedback query mandate drift sleep-cycle operational ocr-image provenance secret verbatim mcp-command codex-badge debug-recall http-api proxy mine-git token-gate fix undo code-facts code-nudge code-health

---

Contributing

git clone https://github.com/jagoff/memo && cd memo

uv pip install -e '.[dev]'

Issues and PRs welcome — see CONTRIBUTING.md. If memo is useful to you, a ⭐ genuinely helps other people find it.

MIT licensed. Built on Apple MLX, sqlite-vec, and