# memo

Local memory for coding agents. Facts and decisions live in files on your disk and come back in later sessions, with no cloud and no API keys.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 24
- Author: jagoff
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/jagoff/memo
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/memo

## What it does

memo keeps project notes as plain `.md` files and searches them two ways at once. The vector leg runs on MLX for Apple Silicon or `sentence-transformers` on CPU; the keyword leg is BM25 over FTS5. Both result lists get fused by rank, then an optional MLX cross-encoder reranks them. SQLite is only a derived index — `memo reindex` rebuilds it from the files, so an edit made by hand survives.

Nothing leaves the machine. Embedder, reranker and model all run in-process, and there is no telemetry. Memories travel only when you point `memo sync` at a git remote you own. Startup is offline; update checks and auto-update need an explicit opt-in.

The default MCP surface is the `agent` profile: 43 tools and roughly 9.7k schema tokens, against 165 tools and 30.6k on the full profile. That schema cost is paid every session in every client, so the smaller profile is the one to keep unless you actually need the rest. memo does not turn recall counts into a savings claim — `memo roi` reports grounded recalls and avoided re-asks, while `memo tokens` reads the provider's own counters through the context-compression proxy.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add memo -- uvx mlx-memo
```
uvx runs the command named after the package; if the README names another one, use uvx --from mlx-memo <command>

### Codex

**Platform CLI**
```bash
codex mcp add memo -- uvx mlx-memo
```
uvx runs the command named after the package; if the README names another one, use uvx --from mlx-memo <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "memo": {
            "command": "uvx",
            "args": [
                "mlx-memo"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from mlx-memo <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "memo": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "mlx-memo"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from mlx-memo <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add memo uvx mlx-memo
```
uvx runs the command named after the package; if the README names another one, use uvx --from mlx-memo <command>

## When to use it
- recall which database choice the team settled on weeks ago
- restore project context at the start of a new agent session
- find a note by meaning instead of an exact keyword
- spot a stale fact that now conflicts with a newer decision
- keep notes in git and read them without a special app

## Example prompts
- Save to memory: this project uses Postgres, not Mongo
- Search memory for which database we picked and why
- Show me what changed in our decisions between 2026-01-01 and 2026-03-01

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md