mcp-memory

A Model Context Protocol (MCP) server that gives LLM agents a persistent knowledge graph memory — entities, relations, and observations stored in an embedded SQLite database with FTS5 full-text search.

The crate ships two binaries:

Both speak MCP over stdio, TCP, and HTTP (with optional bearer-token auth and TLS).

                    ┌────────────────────────────────────────────────┐
                    │         mcp-memory / mcp-memory-vec            │
                    │                                                │
     ┌───────┐      │  ┌──────────┐   ┌─────────────────────────┐   │
     │Claude │──────│─>│  stdio / │──>│ GraphHandle             │   │
     │ / LLM │      │  │  TCP /   │   │  ├ LRU entity cache      │   │
     └───────┘      │  │  HTTP    │   │  ├ FxHashMap name→ID     │   │
                    │  └────┬─────┘   │  └ FTS5 full-text index  │   │
                    │       │         └───────────┬─────────────┘   │
                    │       │   (vec binary only) │                 │
                    │       v         ┌───────────┴─────────────┐   │
                    │  ┌─────────┐    │ VectorStore             │   │
                    │  │ dispatch│───>│  ├ usearch HNSW index    │   │
                    │  └─────────┘    │  └ petgraph adjacency    │   │
                    │       │         └───────────┬─────────────┘   │
                    │       v                     v                  │
                    │  ┌──────────────────────────────────────────┐ │
                    │  │ SQLite (WAL, 16 KB pages)                 │ │
                    │  │ entity, observation, relation, *_fts,     │ │
                    │  │ type_dict, vector_embedding               │ │
                    │  └──────────────────────────────────────────┘ │
                    └────────────────────────────────────────────────┘

Installation

cargo install mcp-memory

This installs both mcp-memory and mcp-memory-vec.

Quick start

# Knowledge-graph server
mcp-memory --transport stdio

# Knowledge-graph + vector search
mcp-memory-vec --transport stdio --embedding-dims 384

The database path is resolved in order:

1. --memory-file / -f flag
2. MEMORY_FILE_PATH environment variable (mcp-memory only)
3. Default: memory.mcpmem in the working directory

Both binaries open the same SQLite file, so you can populate the graph with mcp-memory and later serve it with mcp-memory-vec (or run a single mcp-memory-vec for everything).

Transports

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory"
    }
  }
}

Swap "command" for "mcp-memory-vec" (and add "args": ["--embedding-dims", "384"]) to enable vector search.

Authentication

The tcp and http transports accept an optional bearer token (stdio is never authenticated, on either binary). Set it with --auth-token or --auth-token-file (trimmed; an empty file is rejected). mcp-memory additionally falls back to the MCP_MEMORY_AUTH_TOKEN environment variable.

mcp-memory      --transport http --bind 0.0.0.0:8080 --auth-token "s3cr3t"
mcp-memory-vec  --transport http --bind 0.0.0.0:8080 --auth-token "s3cr3t"

On HTTP the token is sent as Authorization: Bearer <token>; on TCP it is the first line of the connection. Comparison is constant-time. Binding a non-loopback address without a token exposes the entire graph to the network.

TLS (HTTPS)

The http transport can be served over TLS (rustls, ring provider). Provide a PEM certificate chain and private key via --tls-cert / --tls-key; both must be supplied together or startup is refused. mcp-memory also accepts the MCP_TLS_CERT / MCP_TLS_KEY environment variables. When neither is set the transport stays plaintext (the default).

mcp-memory-vec --transport http --bind 0.0.0.0:8080 \
  --tls-cert ./cert.pem --tls-key ./key.pem

Vector search (mcp-memory-vec)

mcp-memory-vec layers a vector store on top of the knowledge graph. Each embedding is attached to an existing entity (by name), indexed in an in-memory usearch HNSW index, and persisted as a blob in the vector_embedding SQLite table. On startup the index is rebuilt from those blobs.

• Bring your own embeddings. The server stores and searches vectors; it does not call an embedding model. Compute embeddings client-side (e.g. with an embedding API) and pass them in. All vectors must match --embedding-dims.
• Semantic search — vector_search_entities returns the nearest entities by cosine similarity (configurable), optionally filtered by entity type.
• Hybrid search — hybrid_search runs vector search and FTS5 text search in parallel and fuses the two rankings with Reciprocal Rank Fusion (RRF, constant 60), then optionally boosts results by graph centrality from an in-memory petgraph adjacency cache.

Vector configuration

The HNSW index is tunable from the command line:

mcp-memory-vec --transport http --bind 0.0.0.0:8080 \
  --embedding-dims 768 --vec-metric cos --vec-quantization f16 \
  --vec-connectivity 32 --vec-expansion-search 128

The petgraph adjacency cache used for the hybrid-search centrality boost is built lazily; call vector_refresh_graph_cache after mutating relations to refresh it.

MCP compliance

Implements the Model Context Protocol revision 2025-11-25 over JSON-RPC 2.0, via stdio, TCP, or HTTP.

Tool failures are returned as CallToolResults with isError: true (not as JSON-RPC protocol errors) so the model can self-correct.

Data model

Entity(name, entityType, observations[])   ──relationType──▶   Entity(...)

• Entity — a named node with a type (e.g. person, company, project) and free-form observation strings. Names are unique and case-sensitive.
• Relation — a directed edge (from, to, relationType). Traversal is undirected (BFS/DFS follow both directions).
• Observation — an unstructured fact attached to an entity.
• Embedding (vec binary) — a fixed-dimension f32 vector attached to an entity, plus an optional model identifier.

Search uses FTS5 full-text indexing with unicode61 remove_diacritics 2 tokenization. Names and observation bodies live in separate external-content FTS5 tables (name_fts, obs_fts).

Storage & performance

SQLite (WAL mode)

A single SQLite database in WAL mode:

Key pragmas: page_size=16384, journal_mode=WAL, synchronous=NORMAL, cache_size=-50000 (~50 MB), mmap_size=256 MB, temp_store=MEMORY, busy_timeout=5000.

In-memory caches

Write batching

Every mutation goes through a layered write path that collapses transaction count from O(N) to O(1) per create_entities / create_relations call:

1. Batch existence checks in one read transaction
2. Batch commit of all new entities/relations in one write transaction
3. Batch FTS index updates in one write transaction
4. Cache invalidation for affected names

Durability

Set on mcp-memory via MCP_MEMORY_DURABILITY=sync. (mcp-memory-vec runs in async mode.)

Background maintenance

A background tokio task runs every 5 minutes: WAL checkpoint (PRAGMA wal_checkpoint(TRUNCATE)), planner analysis (PRAGMA optimize), and FTS optimization.

Benchmarks

Measured end-to-end via the bench binary, 1,000 entities (5 observations each) + 999 relations pre-populated, on a MacBook Pro (Apple M1 Pro, 32 GB). Numbers are averages and will vary by hardware — run cargo run --release --bin bench on your own target.

Tools

Knowledge-graph tools (both binaries)

Write: create_entities, create_relations, add_observations, delete_entities, delete_observations, delete_relations, upsert_entities, merge_entities, compact.

Read: read_graph, search_nodes, open_nodes, batch_get_entities, get_entity, entity_exists, graph_stats, search_relations, describe_entity, degree, find_path, find_all_paths, extract_subgraph, get_neighbors, list_entity_types, list_relation_types, export_graph.

Vector tools (mcp-memory-vec only)

• vector_upsert_embedding — attach/replace an embedding on an existing entity
• vector_search_entities — top-K nearest entities by vector similarity (optional type filter)
• vector_delete_embedding — remove an entity's embedding (entity is kept)
• hybrid_search — vector + FTS5 fused by RRF, optional graph-centrality boost
• vector_refresh_graph_cache — rebuild the petgraph adjacency cache from relations
• vector_store_stats — embedding count, dimension, index/graph sizes

Architecture

main.rs / vec_main.rs
  ├── run_stdio()  — newline-delimited JSON-RPC over stdio
  ├── run_tcp()    — same framing, concurrent connections
  └── run_http()   — MCP Streamable HTTP (axum, POST/GET /mcp)
        └── process_request()
              ├── "initialize"      → protocol version + capabilities
              ├── "tools/list"      → cached tool list
              ├── "tools/call"      → dispatch to handler by name
              ├── "ping"            → null
              └── "notifications/…" → no reply

All transports share the transport-agnostic dispatch core (dispatch_line() / dispatch_http_body()).

Concurrency & locking

• GraphHandle uses parking_lot::Mutex for the writer connection and caches; a read-only connection pool serves concurrent reads under WAL.
• The VectorStore uses DashMap for name↔ID maps and an RwLock over the petgraph cache; the usearch index is internally synchronized.
• Heavy dispatch (graph lock + optional fsync) is offloaded to tokio::task::spawn_blocking to keep the reactor responsive.
• TCP connections are capped at 128 concurrent.

Request size limits

Development

cargo test                       # 100+ unit + integration tests
cargo clippy                     # lint (lib + binaries)
cargo build --release            # LTO + fat, opt-level 3
cargo run --release --bin bench  # standalone benchmark

The test suite covers protocol handling, all tool handlers, CRUD/search/path persistence, concurrency, fuzzy invariant checks, and — for the vector server — end-to-end stdio tool flows, input validation, the tunable index config, and HTTP bearer-token authentication.

Versioning & compatibility

Follows Semantic Versioning. The current line is 3.x, targeting MCP revision 2025-11-25.

License

Licensed under the Apache License, Version 2.0.