# recall-mcp

> **One shared, layered, local-first brain for every AI CLI you use.**
> Claude Code, Gemini CLI, Cursor, Continue, Zed — they all forget. recall-mcp is the memory they share.

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org)
[![MCP](https://img.shields.io/badge/protocol-MCP-a371f7.svg)](https://modelcontextprotocol.io)
[![Local-first](https://img.shields.io/badge/storage-local--first-orange.svg)](#storage-location)

<p align="center">
  <img src="docs/demo.gif" alt="Gemini CLI calling recall-mcp's memory_recall tool to answer 'what did we ship today and why isn't it called brain-mcp?' — surfacing the rename decision and shipped-today architecture from the layered memory store" width="820">
  <br>
  <em>Gemini CLI recalling today's decisions from a brain it shares with Claude Code and Hermes.</em>
</p>

> Built on the layered memory engine from [Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research (MIT). recall-mcp packages that engine as a standalone MCP server so any AI client — not just Hermes — can plug into the same brain. Original architecture: theirs. Packaging, MCP surface, cross-CLI integration: this project. See [Credits](#credits).

## Quick start

```bash
# Install
pipx install recall-mcp

# Wire it into Claude Code (one-time)
echo '{"mcpServers":{"recall-mcp":{"type":"stdio","command":"recall-mcp"}}}' >> ~/.claude.json

# Restart Claude Code. Done.
```

That's it. Every conversation now writes to and reads from the same persistent brain — and so do Gemini CLI, Cursor, and any other MCP-aware client you wire up the same way.

## What it does

```mermaid
flowchart TD
    A[Claude Code] -- MCP --> M[recall-mcp]
    B[Gemini CLI] -- MCP --> M
    C[Cursor / Continue / Zed] -- MCP --> M
    M --> S[(SQLite<br/>facts)]
    M --> V[(ChromaDB<br/>vectors)]
    M --> E[(Entity<br/>graph)]
    M --> T[(Temporal<br/>lineage)]
    M --> F[(FTS5<br/>keyword)]
    classDef client fill:#1f6feb,stroke:#1f6feb,color:#fff,stroke-width:0
    classDef brain fill:#a371f7,stroke:#a371f7,color:#fff,stroke-width:0
    classDef store fill:#0d1117,stroke:#30363d,color:#7d8590
    class A,B,C client
    class M brain
    class S,V,E,T,F store
```

Every AI CLI has the same blind spot: each new session starts with amnesia. Native `save_memory` tools store flat lists that bloat the system prompt over time. Cloud memory services need accounts, paid tiers, and trust your data to a vendor.

**recall-mcp gives you one brain shared by every MCP-aware AI client:**

- 🧠 **7 memory layers** — vector similarity, BM25 keyword, entity graph, temporal lineage, importance scoring, forgetting engine, hybrid retrieval
- 🔌 **Drop-in via MCP** — works with Claude Code, Gemini CLI, Cursor, Continue, Zed, any client speaking Model Context Protocol
- 🏠 **Local-first** — SQLite + ChromaDB on your machine. No accounts, no Docker, no cloud lock-in
- 🔄 **Brain-swappable** — switch between Claude, Gemini, MiniMax, Qwen — they all share the same memory
- 🛡️ **Graceful degradation** — when embeddings hit rate limits, BM25 + entity + temporal carry the load. Never poisons the index

## Install

```bash
pipx install recall-mcp
```

Or with [`uv`](https://github.com/astral-sh/uv):

```bash
uv tool install recall-mcp
```

Or from source:

```bash
git clone https://github.com/Dhari-Q/recall-mcp
cd recall-mcp
pip install -e .
```

## Configure your AI client

### Claude Code

Add to `~/.claude.json` under your project's `mcpServers`:

```json
{
  "mcpServers": {
    "recall-mcp": {
      "type": "stdio",
      "command": "recall-mcp"
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "recall-mcp": {
      "command": "recall-mcp",
      "trust": true
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "recall-mcp": {
      "command": "recall-mcp"
    }
  }
}
```

Restart your client. Done.

## Five tools you'll use

| Tool | Purpose |
|---|---|
| `memory_recall(query, top_k)` | Hybrid search across all layers — vector + BM25 + entity + temporal |
| `memory_remember(content, type, confidence, tags)` | Store a fact, decision, preference, or gotcha |
| `memory_recent_sessions(limit)` | List recent session summaries with decisions and bug fixes |
| `memory_search_entity(name, limit)` | Find memories tied to a specific file, project, person, or tool |
| `memory_stats()` | Sanity-check counts across every layer |

## Optional: real semantic search

By default, recall-mcp ships with BM25 keyword + entity graph + temporal retrieval — those work without any API key.

To enable **vector / semantic search** (queries like "how do I swap the AI" finding "switchable via /model" without shared keywords), point recall-mcp at an embeddings provider:

Create `~/.recall-mcp/.env` (or export in your shell):

```bash
# MiniMax (global) — fastest path
MINIMAX_API_KEY=sk-...

# Or OpenAI
OPENAI_API_KEY=sk-...

# Or OpenRouter
OPENROUTER_API_KEY=sk-...
```

Vector layer activates automatically on next start.

## Optional: auto-prefetch hook for Claude Code

The MCP tools above are **deliberate** — the model has to *call* them. For *silent automatic recall* on every prompt (like Claude Code's native memory but layered), add a `UserPromptSubmit` hook. See [`examples/claude_code_hook.md`](examples/claude_code_hook.md) for the recipe.

## Memory types

When you ask the model to remember something, it picks one of:

| Type | Decay | Examples |
|---|---|---|
| `architecture` | Permanent | "We use ChromaDB for vectors" |
| `decision` | Permanent | "We chose MIT over GPL" |
| `convention` | Permanent | "All API calls go through retry_utils" |
| `pattern` | Permanent | "Use `with` statements for sqlite connections" |
| `gotcha` | Permanent | "MiniMax embeddings are NOT OpenAI-compatible" |
| `preference` | Permanent | "User prefers terse responses" |
| `progress` | 7 days | "Finished MCP wiring on 2026-04-28" |
| `context` | 30 days | Misc. background facts |

## Storage location

All data lives in `$RECALL_MCP_HOME` (defaults to `~/.recall-mcp/`):

```
~/.recall-mcp/
├── memory/          # SQLite — facts + entity graph + temporal lineage
├── episodic/        # SQLite — session summaries
└── chroma/          # ChromaDB — vector embeddings
```

Set `RECALL_MCP_HOME` to point multiple machines at a synced folder (e.g., Syncthing) and your AI's memory follows you.

## Architecture

recall-mcp exposes seven memory layers (originally designed in [Hermes Agent](https://github.com/NousResearch/hermes-agent)), each backed by a focused storage engine:

1. **Episodic** (per-turn / per-session events) — SQLite
2. **Semantic** (extracted facts, decisions) — SQLite + ChromaDB
3. **Entity graph** (who/what/why, dependencies) — SQLite
4. **Temporal lineage** (millisecond timestamps, before/after queries) — SQLite
5. **Importance scoring** (not all memories equal) — derived
6. **Forgetting engine** (decay + Jaccard dedup) — derived
7. **Hybrid retrieval** (BM25 + vector + entity + temporal, fused with optional LLM re-rank) — runtime

When you call `memory_recall`, all four retrieval paths run in parallel, results are deduplicated, scored by source quality + importance, and returned ranked.

## Credits

Memory architecture derived from **[Hermes](https://github.com/NousResearch/hermes-agent)** by Nous Research (MIT). recall-mcp generalizes the layered memory + retrieval engine into a standalone MCP server that any AI client can plug into.

## License

MIT — see [`LICENSE`](LICENSE).