# mcp-memory

A standalone MCP (Model Context Protocol) memory server with persistent storage, vector recall, and 3-way fuse retrieval.

## Features

- **Memory CRUD** — Write, read, search, update, and delete memories with categories and tags
- **Vector recall** — Semantic similarity search using any OpenAI-compatible embedding API
- **BM25 search** — Full-text keyword search with CJK bigram tokenization
- **3-way fuse retrieval** — Combines BM25 + semantic vectors + tag graph via Reciprocal Rank Fusion (RRF) for the best results
- **Binary vector storage** — Compact append-only format (~1/4 the size of JSON), with lazy compaction
- **Usage-based boosting** — Frequently accessed memories rank slightly higher, with cold-start protection
- **Atomic writes** — Write-to-temp-then-rename prevents data corruption on crashes

## Quick Start

```bash
npm install
npm start
```

Or configure it in your Claude Desktop / Claude Code MCP settings:

```json
{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-memory/src/index.js"],
      "env": {
        "MCP_MEMORY_DIR": "/path/to/your/data",
        "EMBEDDING_API_URL": "https://api.openai.com/v1",
        "EMBEDDING_API_KEY": "sk-...",
        "EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}
```

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `MCP_MEMORY_DIR` | Directory for memory data files | `./data` |
| `EMBEDDING_API_URL` | OpenAI-compatible embedding API base URL | (none — semantic search disabled) |
| `EMBEDDING_API_KEY` | API key for the embedding service | (none) |
| `EMBEDDING_MODEL` | Embedding model name | (none) |
| `SIMILARITY_THRESHOLD` | Minimum cosine similarity to return results | `0.45` |

Semantic search (`recall` with `op:similar` or `op:fuse`) requires an embedding API. Without it, you can still use keyword search and date-based recall.

## MCP Tools

### Memory CRUD

- **`write_memory`** — Write a new memory with optional category and tags. After writing, surfaces related older memories.
- **`read_memories`** — Paginated reading (newest first), filterable by category or tag.
- **`search_memories`** — Exact substring keyword search.
- **`update_memory`** — Update content, tags, or category of an existing memory.
- **`delete_memory`** — Delete a memory by ID.
- **`get_stats`** — Memory count by category and vector index status.

### Recall (Multi-mode Retrieval)

The `recall` tool supports four modes via the `op` parameter:

- **`day`** — Fetch memories by date or date range
- **`timemachine`** — See what happened N days/months/years ago
- **`similar`** — Semantic vector search (finds related memories even with different wording)
- **`fuse`** — ★ Best mode. 3-way fusion search combining:
  - **Lexical (BM25)** — Exact term matching with TF-IDF weighting
  - **Semantic (vector)** — Cosine similarity via embedding vectors
  - **Graph (tag)** — Shared-tag neighborhood expansion
  
  Results are merged using Reciprocal Rank Fusion (RRF), which combines rankings without needing to normalize scores across different methods.

## How Fuse Search Works

```
Query: "that time we fixed the server crash"

    BM25 (lexical)          Vector (semantic)        Tag Graph
    ┌──────────────┐       ┌──────────────┐       ┌──────────────┐
    │ #1 server log│       │ #1 prod outage│      │ #1 deploy note│
    │ #2 crash fix │       │ #2 crash fix  │      │ #2 server cfg │
    │ #3 ...       │       │ #3 ...        │      │ #3 ...        │
    └──────┬───────┘       └──────┬────────┘      └──────┬────────┘
           │                      │                       │ (×0.5)
           └──────────────────────┴───────────────────────┘
                                  │
                          RRF Fusion (k=60)
                                  │
                    ┌─────────────┴─────────────┐
                    │  #1 crash fix [lex#2·sem#2]│
                    │  #2 prod outage [sem#1]    │
                    │  #3 server log [lex#1]     │
                    └───────────────────────────┘
```

Each result is annotated with which retrieval paths found it and their ranks, so you can judge confidence.

## Data Storage

All data is stored as JSON files in the data directory:

- `memories.json` — Memory entries
- `mem-vec-index.json` — Vector index metadata (slot mappings)
- `mem-vec.bin` — Binary vector data (Float32, append-only)
- `mem-hits.json` — Access frequency tracking

## License

MIT