memo
Memory for AI agents — MLX (Apple Silicon) or CPU (Linux), sqlite-vec + BM25, zero cloud.
Open source Open in the app JSON README (API)
About
Memory for AI agents — MLX (Apple Silicon) or CPU (Linux), sqlite-vec + BM25, zero cloud.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- jagoff
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 4.16.0
- Stars
- 18
- Forks
- 6
- Open pull requests
- 4
- Last push
- 2026-09-07T00:38:10Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:12
- Updated
- 2026-09-01 19:00:10
- Origin id
io.github.jagoff/memo
README
<!-- mcp-name: io.github.jagoff/memo --> <!-- Banner: keep it, but make sure it loads fast (<200KB, WebP if possible) --> [](https://raw.githubusercontent.com/jagoff/memo/master/docs/banner.webp) # 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. [](https://pypi.org/project/mlx-memo/) [](https://pepy.tech/project/mlx-memo) [](https://github.com/jagoff/memo/blob/master/LICENSE) [](https://modelcontextprotocol.io) [](https://mcptoplist.com/server/io.github.jagoff%2Fmemo)  --- ## Install ```bash curl -fsSL https://raw.githubusercontent.com/jagoff/memo/v4.16.0/install.sh | bash ``` <sub>Prefer a package manager? `uv tool install mlx-memo` · `pipx install mlx-memo` · `brew tap jagoff/memo && brew install mlx-memo`</sub> Then: ```bash 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. <details> <summary>Installing on another Mac or handing setup to an agent?</summary> New Mac: ```bash 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: ```bash curl -fsSL https://raw.githubusercontent.com/jagoff/memo/v4.16.0/install.sh | bash memo doctor --strict-runtime ``` </details> **On Linux or just want to look around first?** ```bash 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. | 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. ```bash 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 ```bash 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 ```bash 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 ```bash 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](https://github.com/jagoff/memo/issues) and I'll fix the table. | | memo | [mem0](https://github.com/mem0ai/mem0) | [letta](https://github.com/letta-ai/letta) | [cognee](https://github.com/topoteretes/cognee) | [basic-memory](https://github.com/basicmachines-co/basic-memory) | [cipher](https://github.com/campfirein/cipher) | |---|---|---|---|---|---|---| | 100% local, no cloud API | ✅ | ⚠️ | ⚠️ | ⚠️ | ✅ | ⚠️ | | Time-machine (rewind to any date) | ✅ | ❌ | ⚠️ | ❌ | ⚠️ | ⚠️ | | Contradiction detection + resolution | ✅ | ⚠️ | ⚠️ | ❌ | ❌ | ❌ | | Autonomous nightly maintenance | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | Token-economy MCP profiles | ✅ | ❌ | ❌ | ⚠️ | ✅ | ❌ | | Markdown / Obsidian as source of truth | ✅ | ❌ | ⚠️ | ❌ | ✅ | ❌ | <sub>✅ first-class · ⚠️ partial, config-gated, or add-on · ❌ absent</sub> Closest comparators are **basic-memory** (local-first + Obsidian + MCP — same thesis) and **cipher** (memory for coding agents). --- ## Requirements | | Support | |---|---| | **macOS, Apple Silicon (M1–M4)** | Full — MLX embedder + reranker + `ask`/`synthesize`/`dream` | | **Linux / Ubuntu** | Standalone CPU backend — search, recall, save. `pipx install "mlx-memo[cpu]"` · [docs/ubuntu.md](https://github.com/jagoff/memo/blob/master/docs/ubuntu.md) | | **Intel Mac** | Unsupported — current PyTorch releases do not ship Python 3.13 wheels for this platform | | **Docker** | Cross-platform, CPU backend · [docs/docker.md](https://github.com/jagoff/memo/blob/master/docs/docker.md) | 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 | | | |---|---| | Install detail, installer knobs, new-Mac migration | [reference.md › Install](https://github.com/jagoff/memo/blob/master/docs/reference.md#install-detail) | | Per-client MCP setup (Claude Desktop, Cursor, Cline, Continue) | [reference.md › MCP setup](https://github.com/jagoff/memo/blob/master/docs/reference.md#mcp-setup) | | Ambient recall, capture, and tuning | [reference.md › Ambient memory](https://github.com/jagoff/memo/blob/master/docs/reference.md#ambient-memory) | | Full CLI reference (145 commands) + `memo tui` | [reference.md › CLI](https://github.com/jagoff/memo/blob/master/docs/reference.md#cli-reference) | | All `MEMO_*` flags and model profiles | [reference.md › Configuration](https://github.com/jagoff/memo/blob/master/docs/reference.md#configuration) | | Architecture and design notes | [reference.md › Design](https://github.com/jagoff/memo/blob/master/docs/reference.md#design-and-comparison) | | Privacy and network policy | [PRIVACY.md](https://github.com/jagoff/memo/blob/master/PRIVACY.md) | ### All 145 top-level CLI commands <details> <summary>Complete command inventory (kept here so CI detects CLI/documentation drift)</summary> **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` </details> --- ## Contributing ```bash git clone https://github.com/jagoff/memo && cd memo uv pip install -e '.[dev]' ``` Issues and PRs welcome — see [CONTRIBUTING.md](https://github.com/jagoff/memo/blob/master/CONTRIBUTING.md). If memo is useful to you, a ⭐ genuinely helps other people find it. MIT licensed. Built on [Apple MLX](https://github.com/ml-explore/mlx), [sqlite-vec](https://github.com/asg017/sqlite-vec), and [codegraph](https://github.com/colbymchenry/codegraph).