mcp-memory

A drop-in replacement for Anthropic's MCP Memory server — with SQLite persistence, vector embeddings, and semantic search.

Why? The original server writes the entire knowledge graph to a JSONL file on every operation, with no locking or atomic writes. Under concurrent access (multiple MCP clients), this causes data corruption. This server replaces that with a proper SQLite database.

Features

• Drop-in compatible with Anthropic's 9 MCP tools (same API, same behavior)
• SQLite + WAL — safe concurrent access, no more corrupted JSONL
• Semantic search via sqlite-vec + ONNX embeddings (50+ languages)
• Lightweight — ~150 MB total vs ~1.4 GB for similar solutions
• Migration — one-click import from Anthropic's JSONL format
• Zero config — works out of the box, optional model download for semantic search

Quick Start

1. Add to your MCP config

{
  "mcpServers": {
    "memory": {
      "command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

Or clone and run locally:

{
  "mcpServers": {
    "memory": {
      "command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
    }
  }
}

2. Enable semantic search (optional)

cd /path/to/mcp-memory
uv run python scripts/download_model.py

This downloads a multilingual sentence model (~80 MB) to ~/.cache/mcp-memory-v2/models/. Without it, all tools work fine — only search_semantic will be unavailable.

3. Migrate existing data (optional)

If you have an Anthropic MCP Memory JSONL file, use the migrate tool or call it directly:

uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"

MCP Tools

Compatible with Anthropic (9 tools)

Tool	Description
create_entities	Create or update entities (merges observations on conflict)
create_relations	Create typed relations between entities
add_observations	Add observations to an existing entity
delete_entities	Delete entities (cascades to observations + relations)
delete_observations	Delete specific observations
delete_relations	Delete specific relations
search_nodes	Search by substring (name, type, observation content)
open_nodes	Retrieve entities by name
read_graph	Read the entire knowledge graph

New tools (2)

Tool	Description
search_semantic	Semantic search via vector embeddings (cosine similarity)
migrate	Import from Anthropic's JSONL format (idempotent)

Architecture

server.py (FastMCP)  ←→  storage.py (SQLite + sqlite-vec)
                              ↑
                        embeddings.py (ONNX Runtime)
                              ↑
                        paraphrase-multilingual-MiniLM-L12-v2
                        (384d, 50+ languages, CPU-only)

• Storage: SQLite with WAL journaling, 5-second busy timeout, CASCADE deletes
• Embeddings: Singleton ONNX model loaded once at startup, L2-normalized cosine search
• Concurrency: SQLite handles locking internally — no fcntl, no fs wars

How It Works

Each entity gets an embedding vector generated from its concatenated content:

"{name} ({entity_type}): {observation_1}. {observation_2}. ..."

When you call search_semantic, the query is encoded with the same model and compared against all entity vectors using k-nearest neighbors (cosine distance) via sqlite-vec.

Requirements

• Python >= 3.12
• uv (package manager)

Dependencies

Package	Purpose
fastmcp	MCP server framework
pydantic	Request/response validation
sqlite-vec	Vector similarity search in SQLite
onnxruntime	ONNX model inference (CPU)
tokenizers	HuggingFace fast tokenizer
numpy	Vector operations
huggingface-hub	Model download

License

MIT