memo

Local-first semantic memory for AI agents — with time-travel, contradiction radar, and automatic synthesis.

memo gives any MCP-aware agent (Claude Code, Codex, Devin, OpenCode, Cursor, Cline, Continue, …) a long-term memory that runs entirely on your own machine — macOS on Apple Silicon via Apple MLX, or Linux / Ubuntu on a CPU sentence-transformers backend (pipx install "mlx-memo[cpu]", see docs/ubuntu.md). Each memory is a plain Markdown file; embeddings live in a single sqlite file; the embedder, reranker, and LLM run in-process — no Ollama, no Qdrant, no cloud API, no keys. Your prompts and memories never leave the machine.

What makes memo different

_{✅ first-class · ⚠️ partial, config-gated, or add-on · ❌ absent. Verified mid-2026 against each project's docs/repo: mem0, letta (formerly MemGPT), cognee, engram, basic-memory, cipher. Closest comparators: basic-memory (local-first + Obsidian + MCP — memo's exact thesis) and cipher (memory layer for coding agents).}

Why it pays for itself — in tokens

memo is built to spend fewer tokens, not more.

• 92% smaller MCP surface. The default agent profile exposes 10 tools / ~1.2k schema tokens, versus 126 tools / ~15k tokens for the full surface — that overhead is paid every session, in every client. memo trims it to almost nothing.
• Recall injects the answer instead of re-deriving it. Ambient recall surfaces the top memory before the agent answers, on a tight ~160-token budget. The agent stops re-explaining what it already figured out last week.

On a ~200-memory corpus, memo roi estimates ~80k tokens of model work avoided per session. The number is corpus-specific; it grows as memo learns more.

Use cases

• Continuity across sessions. Decide "we use Postgres, not Mongo" today; tomorrow, in a fresh session, the agent recalls it on its own — recall injects the decision before it answers, so you never re-explain it.
• Shared memory across agents. Save something while working in Claude Code; Codex, Cursor, or Cline pick it up later. They all read the same local store over MCP.
• Memory that follows you across Macs. Start on the laptop, continue on the desktop. The corpus travels over serverless git sync and the agent starts with the same context on both.
• Preferences and conventions that stick. "Tests first", "commit messages in English", "don't touch the auth module" — say it once, the agent applies it every future session.
• Contradiction radar. Change your mind on an old decision and memo flags the now-stale version — the agent won't reintroduce what you already discarded.
• Time-machine / audit. "What did we know about this bug last month?" Rewind the corpus to any date and see the state of knowledge at that point.
• Instant project onboarding. A cold agent gets the project's durable decisions, facts, and preferences up front via the session-start briefing.
• Fewer tokens, not more. Instead of re-deriving what you solved last week, recall injects the answer on a tight budget — and the default MCP surface is ~10 tools, not ~120.

Requirements

• macOS on Apple Silicon (M1–M4) — MLX is the load-bearing piece and the only path with the reranker + LLM features (ask / synthesize / dream).
• Linux / Ubuntu / Intel Mac — supported as a standalone install via a CPU sentence-transformers backend (search + recall + save, no MLX). One command: pipx install "mlx-memo[cpu]". See docs/ubuntu.md for what works and the trade-offs.
• ~8 GB free disk for the default model set (the installer downloads it).
• Optional: an Obsidian vault. Without one, memo defaults to ~/Documents/memo/.

Python ≥ 3.13 is required if you install without uv. The curl | bash installer handles this automatically — it detects uv and uses its managed Python if no system Python ≥ 3.13 is on PATH.

Install — one step

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

The installer auto-detects uv (preferred) or falls back to pipx. It downloads MLX models, and wires memo into every agent client it finds (Claude Code, Codex, Devin, Devin Desktop, OpenCode).

Prefer a manual install? Any of these expose the same two binaries — memo (CLI) and memo-mcp (MCP server):

uv tool install mlx-memo          # recommended
pipx install mlx-memo
brew tap jagoff/memo && brew install mlx-memo

Keep memo isolated as its own tool (uv tool / pipx / Homebrew). Don't vendor it inside another project's .venv. memo doctor --strict-runtime verifies the install.

On Linux, or just want to try it without installing anything? Run the Docker image (CPU backend, cross-platform — search/recall/save; the reranker + ask/ synthesize/dream verbs are Apple-Silicon-only):

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

Details in docs/docker.md.

First install downloads ~8 GB of MLX models (5–15 min); later installs hit the HuggingFace cache. Full installer knobs and "move to a new Mac" steps: docs/reference.md › Install.

Migrating from another Mac? Install first, then restore your corpus:

curl -fsSL https://raw.githubusercontent.com/jagoff/memo/master/install.sh | bash
memo sync bootstrap git@github.com:yourname/memo-sync.git   # restore from git

Hand it to your agent

memo installs itself if you hand the repo (or just the install line) to an AI agent:

curl -fsSL https://raw.githubusercontent.com/jagoff/memo/master/install.sh | bash
memo doctor --strict-runtime     # verify runtime is healthy

After install, tools surface as mcp__memo__memo_* (memo_save, memo_search, memo_ask, memo_get, memo_unified_briefing). Per-client setup (Claude Desktop, Cursor, Cline, Continue, manual JSON) is in docs/reference.md › MCP setup.

Quick start

memo doctor                                            # self-check: models, vault, sqlite-vec
memo save 'MLX prefill ~30% faster than Ollama on M3 Max' --title 'MLX bench' -t mlx -t bench
memo search 'how fast was the MLX benchmark'           # search by meaning, not just keywords
memo list --limit 5                                    # most recent
memo ask 'what changed in the embedder this month?'   # RAG — cites memories by id

Core features

• Ambient recall — every prompt silently consults memory and injects top hits as context. Warm recall daemon keeps it under <200 ms. No /remember calls.
• Auto-capture — a Stop hook extracts durable insights from each exchange through a quality gate. The corpus grows on its own.
• Session briefing — SessionStart surfaces open loops, a memory of the day, and one-line crash recovery.

Key capabilities

🕰️ Time-machine

Rewind the corpus to any past date and query it as it was then:

memo as-of ask "what was the deployment strategy?" --date 2026-02-01
memo as-of search "redis config" --date 2026-01-15
memo diff --from 2026-01-01 --to 2026-03-01    # what changed

No other agent-memory system offers this. Full historical reconstruction via reverse-replay of history.db.

⚡ Contradiction radar

memo contradict scan                  # detect conflicting facts corpus-wide
memo contradict triage                # resolve interactively: fuse / newer-wins / dismiss

The LLM classifies each candidate pair. Results persist in contradictions.db; resolved conflicts inform future saves.

🔮 Synthesis pipeline

memo synthesize                       # generate cross-cluster insights (LLM)
memo dream                            # nightly: signal gather → prune → orient

MEMO_SYNTHESIS_ENABLED=1 runs synthesis automatically during memo maintain. Nightly memo dream can also self-tune recall (MEMO_DREAM_TUNE_ENABLED=1): it mines ground-truth labels from real usage, adjusts the recall threshold, and auto-reverts if the eval baseline regresses.

🌐 Cross-Mac git sync

memo sync bootstrap git@github.com:yourname/memo-sync.git   # wire a shared corpus
memo sync once                                                # push/pull now

Pull-rebase-before-push. flock-based single owner per machine. Async debounced hooks keep the corpus current without blocking.

📚 Obsidian vault as source-of-truth

MEMO_MEMORIES_IN_VAULT=1 memo init                # store memories inside your vault
memo migrate --into-vault                          # non-destructive migration

Human edits in Obsidian win on the next memo reindex. The sqlite index is always rebuildable from the .md files.

🕸️ Knowledge graph

memo graph neighbors "MLX"             # what's related
memo graph path "embedder" "reranker"  # how two concepts connect
memo entities                          # list extracted entities
memo links --id abc123                 # backlinks + outlinks

Entity extraction uses a dependency-free regex backend. For code-heavy corpora, memo can merge a codegraph symbol graph as the graph's primary layer (opt-in, MEMO_GRAPH_USE_CODEGRAPH) — callers, callees, and imports become first-class edges, so recall and memo graph path reason over real code structure, not just text similarity. The merged graph also powers the memo_graph MCP tool and the entity-centric "Knowledge map" briefing.

🏥 Health scoring & eval gates

memo health                                         # grounded rate, ROI, usefulness verdict
memo eval recall --labels eval/regression_labels.json --k 5
memo eval recall --gate                             # exit non-zero if precision drops
memo eval recall --update-baseline                  # snapshot current best

Wire --gate into a pre-commit hook to catch retrieval regressions before they ship. memo feedback records per-source 👍/👎 votes that teach the retriever which memories to surface (or hide) for similar queries.

🖼️ Multi-modal ingestion

memo ocr-image screenshot.png               # macOS Vision OCR
memo multimodal add-image photo.jpg --title "whiteboard"
memo search "whiteboard diagram"            # finds it

Daemons

memo runs four background daemons:

All 104 CLI commands

Core: save search ask get edit delete list

Recall & Hooks: recall recall-hook briefing continuity prewarm capture-tick capture-stop

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

Maintenance: reindex maintain dream consolidate synthesize dedupe cross-dedup retier contradict temporal compress-context

Analysis & Quality: health stats doctor lint analytics eval roi tokens token-savings usefulness gaps outcome profile

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

Advanced Search: embed rerank contextual chat chat-ask multimodal repo

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

Visualization: tui dashboard map logs hook-log

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

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

Other: feedback query provenance mandate sleep-cycle ocr-image http-api codex-badge backend-native collaborative

MCP surface profiles

Set via MEMO_MCP_PROFILE=full or in each client's MCP env config.

Non-MCP clients: memo http-api serves the same operations as a localhost REST API (plain JSON).

Retrieval architecture

Hybrid search: vec leg (MLX embedding on Apple Silicon, CPU sentence-transformers on Linux) + BM25 leg (FTS5/Tantivy, diacritic-folding for Spanish) fused via Reciprocal Rank Fusion → optional MLX cross-encoder rerank (Apple Silicon).

Markdown is the source of truth. The .md files are canonical; sqlite is a rebuildable index. A hand-edit in Obsidian wins on the next memo reindex. delete() removes the index first, then the file — no silent data loss.

Embedding models:

Switch with MEMO_EMBEDDER_MODEL + MEMO_EMBEDDER_DIMS (requires memo reindex --rebuild).

Documentation

Contributors: git clone https://github.com/jagoff/memo && cd memo && uv pip install -e '.[dev]'. See CONTRIBUTING.md.

License & provenance

MIT — see LICENSE. Forked philosophically from mem-vault (storage layout + frontmatter schema); the MLX backend pieces are ported from obsidian-rag. memo is one of three sovereign systems in a wider stack (Memflow, Synapse) — the integration is opt-in everywhere; single-Mac users see zero behaviour change.