memo
io.github.jagoffPublished by GitHub account jagoffv4.16.0Updated Oct 24, 2026
Memory for AI agents — MLX (Apple Silicon) or CPU (Linux), sqlite-vec + BM25, zero cloud.
Overview
A local, offline memory server for coding agents: it saves decisions and notes as Markdown and lets an assistant search and recall them by meaning.
- What you can do
- Save, edit, rename, delete and list memories kept as plain Markdown files, with SQLite as a rebuildable index. Search and recall by meaning using hybrid vector plus BM25 retrieval, with optional reranking. Query memory as it was on a past date, diff two dates, and scan for contradicting or stale facts. Run maintenance such as reindexing, deduplication, consolidation and a nightly optimization pipeline. Build a knowledge graph of entities and links, and import, export, back up or sync memory to a git remote you own.
- When to use it
- Worth adding when you use a coding agent across many sessions and want it to remember past decisions, conventions and context without sending anything to a cloud service. Also useful if you want human-readable, version-controllable memory files rather than an opaque database.
- Requirements
- Runs locally over stdio as the mlx-memo Python package (memo-mcp), needing Python 3.13 or newer. Full features require macOS on Apple Silicon; Linux and Docker use a CPU backend, and Intel Mac is unsupported. First install downloads roughly 8 GB of models. No API keys or accounts; an Obsidian vault is optional.
Installation
In SourceWeft
- Open memo in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
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.
[PyPI] [Downloads] [License: MIT] [MCP] [MCP Toplist]
[mlx-memo MCP server on mcprush: security A, high access, no sign-in, works with 14 clients] [memo MCP server rated A on Glama: tool definitions rated A, 60 tools]
[Save a fact once — every later session recalls it automatically, all stored locally.]
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.
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.
[vector + keyword search in parallel, fused, reranked, top memory injected]
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
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
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 codegraph.
Source: README.md at commit fa0dc9c
Tools
0Version history
1- v4.16.0LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts