mcp-memory 0.1.0

MCP server for knowledge graph memory — entities, relations, and observations persisted via custom binary log
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# mcp-memory

A [Model Context Protocol](https://modelcontextprotocol.io) (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
  `fsync`ed; 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.
- **14 MCP tools** covering reads, writes, search, and graph traversal.

## Installation

```sh
cargo install mcp-memory
```

Or build from source:

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

## Usage

The server runs in stdio mode:

```sh
mcp-memory --memory-file ./memory.mcpmem
```

The memory file path is resolved in this order:

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

### Claude Desktop / Claude Code config

```json
{
  "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. |
| `read_graph` | read | Return the full graph. |
| `search_nodes` | read | Substring search over names/types/observations. |
| `open_nodes` | read | Fetch a specific set of entities and their relations. |
| `get_entity` | read | Fetch a single entity by name. |
| `graph_stats` | read | Entity/relation counts and other stats. |
| `search_relations` | read | Filter relations by `from`, `to`, and/or `type`. |
| `find_path` | read | Shortest path (BFS, undirected) between two entities. |

## Development

```sh
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](LICENSE).