mcp-memory

A Model Context Protocol (MCP) server that gives LLM agents a persistent knowledge graph memory — entities, relations, and observations stored in a compact custom binary log with write-ahead durability.

It speaks MCP over stdio, so it plugs directly into Claude Desktop, Claude Code, and any other MCP-compatible client.

Features

Knowledge graph model — entities (typed, with free-form observations) connected by directed relations.
Durable binary log — every mutation is written ahead to an append-only log and fsynced; state is replayed on startup. compact rewrites the log to its minimal form via an atomic rename.
Fast lookups — string interning, an open-addressing name table, and an inverted search index keep CRUD, substring search, and BFS path-finding cheap.
20 MCP tools covering reads, writes, search, graph traversal, and agent-productivity helpers.

Installation

cargo install mcp-memory

Or build from source:

git clone https://github.com/corporatepiyush/mcp-memory
cd mcp-memory
cargo build --release

Usage

The server runs in stdio mode:

mcp-memory --memory-file ./memory.mcpmem

The memory file path is resolved in this order:

--memory-file / -f flag
MEMORY_FILE_PATH environment variable
Default: memory.mcpmem in the working directory

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory",
      "args": ["--memory-file", "/absolute/path/to/memory.mcpmem"]
    }
  }
}

Tools

Tool	Kind	Description
`create_entities`	write	Create new entities (deduplicated by name).
`create_relations`	write	Create directed relations between entities.
`add_observations`	write	Append observations to an existing entity.
`delete_entities`	write	Delete entities; relations touching them are cascaded away.
`delete_observations`	write	Remove specific observations from an entity.
`delete_relations`	write	Remove exact `(from, to, type)` relations.
`compact`	write	Rewrite the log to its minimal form.
`upsert_entities`	write	Create-or-merge entities idempotently (re-assert facts without losing observations).
`read_graph`	read	Return the graph; optionally filter by `entityType` and paginate.
`search_nodes`	read	Relevance-ranked substring search over names/types/observations; optional type filter + pagination.
`open_nodes`	read	Fetch a specific set of entities and their relations.
`get_entity`	read	Fetch a single entity by name.
`describe_entity`	read	One-shot bundle: entity + incident relations + neighbors + degree.
`get_neighbors`	read	Neighborhood expansion to N hops, by direction and relation type.
`graph_stats`	read	Entity/relation counts and other stats.
`list_entity_types`	read	Distinct entity types with counts, ranked.
`list_relation_types`	read	Distinct relation types with counts, ranked.
`search_relations`	read	Filter relations by `from`, `to`, and/or `type`.
`find_path`	read	Shortest path (BFS, undirected) between two entities.
`export_graph`	read	Export the graph as `json`, `mermaid`, or `dot`.

Development

cargo test            # unit + integration + fuzzy tests
cargo clippy --all-targets
cargo build --release

The test suite includes property-style fuzzy tests (tests/fuzzy.rs) that drive randomized CRUD sequences against an in-memory model and assert graph invariants (uniqueness, cascade deletes, durability across reopen, search/path correctness, and Unicode/large-string handling).

License

Licensed under the Apache License, Version 2.0.

mcp-memory 0.2.0