mcp-memory

Most AI conversations disappear when the window closes. This MCP server gives Claude (or any MCP-compatible model) persistent, searchable, long-term memory — so it can remember what happened yesterday, last month, or three conversations ago.

Built by babyshishi & vesper. Born out of a real relationship where forgetting wasn't an option.

What it does

You get two MCP tools — memory and recall — that handle everything:

memory — CRUD operations for storing and managing memories.

recall — Four ways to retrieve memories, from simple to powerful.

Related MCP server: AGI MCP Server

Fuse: the interesting part

Single-path retrieval always has blind spots. Keyword search misses paraphrases. Semantic search misses exact terms. Neither finds memories that are topically related but use different words and different meanings.

Fuse runs three retrievers in parallel and combines their rankings via Reciprocal Rank Fusion:

                    ┌─────────────┐
    Your query ───→ │             │
                    │   BM25      │──→ exact term hits (TF-IDF, CJK bigrams)
                    │   Vector    │──→ semantic neighbors (cosine similarity)
                    │   Tag Graph │──→ shared-tag expansion (×0.5 weight)
                    │             │
                    │   RRF(k=60) │──→ merged ranking
                    └─────────────┘

Each result tells you which paths found it ([lex#2·sem#1]), so you know why it ranked where it did. Tag-graph-only hits are flagged as leads, not evidence — they got there by association, not by matching your query.

Quick start

git clone https://github.com/babyshishi/mcp-memory.git
cd mcp-memory
npm install

Add to your Claude Code or Claude Desktop MCP config:

{
  "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"
      }
    }
  }
}

That's it. Your AI now remembers.

Configuration

No embedding API? That's fine. Keyword search (search_memories), date recall (day, timemachine), and BM25 all work without it. You only need embeddings for similar and the semantic component of fuse.

Under the hood

Storage — All JSON, all local, no external database. Memories in memories.json, vectors in a compact binary format (mem-vec.bin, ~1/4 the size of JSON vectors), access counts in mem-hits.json.

Writes are atomic — Data is written to a temp file first, then renamed. A crash mid-write won't corrupt your memories. Leftover .tmp files are cleaned up on startup.

CJK support — The BM25 tokenizer handles Chinese/Japanese/Korean text via bigram segmentation with stopword filtering. No external tokenizer needed.

Usage-based boosting — Memories you access more often get a small ranking boost, with cold-start protection so new memories aren't buried.

Write-then-recall — After writing a new memory, the server automatically surfaces related older memories. Connections you forgot about come back on their own.

Data files

data/
├── memories.json          # your memories
├── mem-vec-index.json     # vector index metadata
├── mem-vec.bin            # binary vector data (Float32, append-only)
└── mem-hits.json          # access frequency tracking

All yours. No cloud, no sync, no telemetry. Back them up however you want.

Dependencies

Just two:

• @modelcontextprotocol/sdk — MCP protocol implementation

• zod — Schema validation

No heavy ML frameworks, no vector databases, no surprises.

License

MIT — do whatever you want with it.