# recall-mcp

**Persistent, searchable memory for AI agents — over the Model Context Protocol.**

Give any MCP-capable agent (Claude Code, Claude Desktop, Cursor, Windsurf, ...) a long-term memory it can write to and search across sessions. Facts, preferences, decisions, and lessons survive restarts and are retrieved by relevance-ranked full-text search.

- 🧠 **Six tools**: save, search, recent, get, forget, stats
- 🔎 **Real search**: SQLite FTS5 with BM25 ranking, porter stemming, and an importance boost — not a `LIKE '%...%'` scan
- 📦 **Zero native dependencies**: uses Node's built-in `node:sqlite` (Node ≥ 23.4). No compilers, no prebuilt binaries, nothing to break on install
- 🗃️ **Single-file storage**: one SQLite database at `~/.recall-mcp/memories.db` (WAL mode), easy to back up or inspect

## Quick start

```bash
git clone https://github.com/jadeleke/recall-mcp.git
cd recall-mcp
npm install
npm run build
```

### Claude Code

```bash
claude mcp add recall -- node /path/to/recall-mcp/dist/index.js
```

### Claude Desktop / other MCP clients

Add to your MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "recall": {
      "command": "node",
      "args": ["/path/to/recall-mcp/dist/index.js"]
    }
  }
}
```

## Tools

| Tool | What it does |
|---|---|
| `memory_save` | Persist a fact with optional `tags` and `importance` (1–5) |
| `memory_search` | Full-text search, BM25-ranked with importance boost. FTS5 syntax (phrases, `AND`/`OR`/`NEAR`) supported; plain queries work too |
| `memory_recent` | Most recently saved/updated memories, newest first |
| `memory_get` | Fetch one memory by id |
| `memory_forget` | Permanently delete a memory by id |
| `memory_stats` | Totals, tag histogram, date range, db location and size |

### Example

An agent mid-conversation:

```
memory_save({
  content: "User deploys to Fly.io from CI only — never deploy from a laptop",
  tags: ["ops", "user-preference"],
  importance: 5
})
```

Weeks later, in a fresh session:

```
memory_search({ query: "how does the user deploy" })
```

returns the fact, ranked first thanks to porter stemming (`deploy` matches `deploys`) and the importance boost.

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `RECALL_DB` | `~/.recall-mcp/memories.db` | Database file path. Set per-project paths to keep separate memory stores; `:memory:` for ephemeral |

## Development

```bash
npm test        # node:test suite — runs TypeScript directly via Node's type stripping
npm run build   # emits dist/
```

The codebase is small on purpose: [`src/store.ts`](src/store.ts) is the storage layer (schema, FTS5 triggers, search), [`src/index.ts`](src/index.ts) wires it to MCP over stdio.

## Why not just a system prompt?

System prompts are per-session and hand-curated. `recall-mcp` lets the *agent* decide what's worth keeping, accumulates knowledge across every session and every MCP client that shares the database, and retrieves only what's relevant to the current task instead of stuffing everything into context.

## License

MIT