Metadata-Version: 2.4
Name: mlx-memo
Version: 4.6.2
Summary: Local-first semantic memory for AI agents — time-travel, contradiction radar, automatic synthesis. MLX (Apple Silicon) or CPU sentence-transformers (Linux) embeddings + sqlite-vec, MCP server. No cloud, no API keys.
Project-URL: Homepage, https://github.com/jagoff/memo
Project-URL: Repository, https://github.com/jagoff/memo
Project-URL: Issues, https://github.com/jagoff/memo/issues
Project-URL: Changelog, https://github.com/jagoff/memo/blob/master/CHANGELOG.md
Author: Fernando Ferrari
License: MIT
License-File: LICENSE
Keywords: agents,apple-silicon,claude,local-first,mcp,memory,mlx,obsidian,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.13
Requires-Dist: click>=8.1.7
Requires-Dist: cryptography>=42.0
Requires-Dist: fastmcp<4,>=0.5
Requires-Dist: mlx-lm>=0.18; sys_platform == 'darwin' and platform_machine == 'arm64'
Requires-Dist: mlx<1,>=0.18; sys_platform == 'darwin' and platform_machine == 'arm64'
Requires-Dist: pydantic>=2.6
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: sentence-transformers>=3.0; sys_platform == 'linux'
Requires-Dist: sqlite-vec<0.2,>=0.1.9
Requires-Dist: textual<9,>=8.2.8
Requires-Dist: tomli-w>=1.0
Requires-Dist: transformers<5.13; sys_platform == 'darwin' and platform_machine == 'arm64'
Requires-Dist: watchdog>=4.0
Provides-Extra: cpu
Provides-Extra: dev
Requires-Dist: diff-cover<11,>=9; extra == 'dev'
Requires-Dist: freezegun>=1.5; extra == 'dev'
Requires-Dist: httpx2<3,>=2.5; extra == 'dev'
Requires-Dist: hypothesis<7,>=6.158; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.4; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
Requires-Dist: ruff==0.16.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: http
Requires-Dist: fastapi>=0.115; extra == 'http'
Requires-Dist: uvicorn>=0.34; extra == 'http'
Provides-Extra: multimodal
Requires-Dist: mlx-vlm<0.6.5,>=0.1.12; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'multimodal'
Requires-Dist: mlx-whisper>=0.4.1; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'multimodal'
Provides-Extra: ocr
Requires-Dist: pyobjc-framework-quartz>=10.0; (sys_platform == 'darwin') and extra == 'ocr'
Requires-Dist: pyobjc-framework-vision>=10.0; (sys_platform == 'darwin') and extra == 'ocr'
Provides-Extra: tantivy
Requires-Dist: tantivy>=0.22; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'tantivy'
Provides-Extra: test-mutation
Requires-Dist: mutmut<4,>=3; extra == 'test-mutation'
Provides-Extra: test-stability
Requires-Dist: pytest-randomly<5,>=4.1; extra == 'test-stability'
Requires-Dist: pytest-repeat<1,>=0.9.4; extra == 'test-stability'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.jagoff/memo -->
<!-- Banner: keep it, but make sure it loads fast (<200KB, WebP if possible) -->
[![memo — local memory for AI](https://raw.githubusercontent.com/jagoff/memo/master/docs/banner.webp)](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.

[![PyPI](https://img.shields.io/pypi/v/mlx-memo.svg)](https://pypi.org/project/mlx-memo/)
[![Downloads](https://static.pepy.tech/badge/mlx-memo)](https://pepy.tech/project/mlx-memo)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jagoff/memo/blob/master/LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-3b82f6.svg)](https://modelcontextprotocol.io)
[![MCP Toplist](https://mcptoplist.com/badge/io.github.jagoff%2Fmemo.svg)](https://mcptoplist.com/server/io.github.jagoff%2Fmemo)

![Save a fact once — every later session recalls it automatically, all stored locally.](https://raw.githubusercontent.com/jagoff/memo/master/docs/demo.gif)

---

## Install

```bash
curl -fsSL https://raw.githubusercontent.com/jagoff/memo/v4.6.2/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.6.2/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.6.2/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) | 38 | ~3.8k |
| `core` / `slim` | 55 | ~5.0k |
| `full` / `default` | 159 | ~18k |

The default MCP surface is 38 tools, not 159: about 79% fewer tool schemas. It exposes **38 tools / ~3.8k schema tokens** versus **159 tools / ~18k 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` reads the real grounding and re-ask ledgers, then estimates accumulated savings with disclosed defaults (350 tokens per grounded recall and 900 per avoided re-ask).

```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.

![vector + keyword search in parallel, fused, reranked, top memory injected](https://raw.githubusercontent.com/jagoff/memo/master/docs/diagram-recall.svg)

**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, and signed federation. → **[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 (137 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 138 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` `resume` `reflect` `mine-history` `episodes` `chronicle`

**Maintenance:** `reindex` `maintain` `review` `dream` `consolidate` `synthesize` `dedupe` `retier` `contradict` `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:** `recall-daemon` `ingest-daemon` `maint-daemon` `embed-daemon` `idle-daemon`

**Other:** `backend-native` `collaborative` `feedback` `query` `mandate` `drift` `sleep-cycle` `operational` `ocr-image` `provenance` `secret` `verbatim` `mcp-command` `codex-badge` `debug-recall` `http-api` `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).
