Graph-Mem MCP is a universal MCP server that gives any agent or IDE persistent, structured memory through a knowledge graph. It combines graph storage, semantic vector search, and multi-hop traversal in a single package — install it, add it to your MCP config, and your agent gains memory that survives across sessions. It works everywhere MCP does.
Built To Be Trusted With Your Data
1055 tests
Property-based against a brute-force reference, plus fuzzing on every parser
mypy strict
Clean, enforced in CI — not just configured
Authenticated UI
Host + Origin allow-lists and a session token; a cross-origin write is a 403, verified against a running server
Bounded
Every traversal, search, and list response has a named, configurable cap and reports truncation
Honest docs
Performance claims come with measurements and a reproducible benchmark; known gaps are written down
Works With
graph-mem is a standard MCP server, so it works with any MCP-compatible
agent, IDE, or framework. graph-mem install additionally writes the skill
file straight into the right place for these 13, each at a path cited against
the vendor's own documentation:
Using something else? The MCP config below is all you need; the skill file is a
convenience, not a requirement. Adding your agent to the installer takes a
documented path and about ten lines — see
Adding an Agent.
What is this?
AI agents forget everything between sessions. They re-read files, re-discover architecture, and repeat mistakes. Graph-Mem MCP solves this by providing persistent, per-project knowledge graphs that any MCP-compatible agent can read and write to. The graph builds organically as the agent works — extracting entities, decisions, and relationships from every conversation. It runs as a standard MCP server with 28 tools that plug into any agent, IDE, or framework that supports the Model Context Protocol.
Why a graph, not just a vector store?
Vector search finds similar things. Graphs find connected things. When an agent asks "what depends on the auth service?", a vector store returns text that mentions auth. A knowledge graph traverses the actual dependency edges and returns every upstream consumer — even ones that never mention "auth" in their description. Graph-Mem gives you both: vector similarity for fuzzy discovery, graph traversal for structural queries.
Use Cases
Agent memory — Give any AI coding agent persistent context across sessions
IDE integration — Add knowledge graph tools to Cursor, Windsurf, Copilot, or any MCP-enabled IDE
Agent building — Use as the memory layer when building custom AI agents and workflows
Research & knowledge management — Build structured knowledge bases with semantic search
Multi-project context — Maintain separate knowledge graphs per project with multi-graph support
Quick Start
1. Install:
pip install graphmem-mcp
Or run it without installing — uvx fetches and isolates it the way npx
does for Node:
uvx --from graphmem-mcp graph-mem server
Listed in the official MCP Registry
as io.github.Sathvik-1007/graphmem-mcp, so MCP-aware clients can discover and
install it directly.
This writes a skill file that teaches your agent how to use all 28 MCP tools — when to search, when to add entities, naming conventions, and common workflows.
3. Configure MCP by adding this to your agent's MCP config:
That's it. Your agent now has persistent memory. Verify by asking it to run read_graph().
One-Prompt Setup
Paste this into your agent's chat to get started immediately:
I want you to give yourself persistent memory using graph-mem. Run the following:
pip install graphmem-mcp
graph-mem install claude # or: opencode, codex, gemini, cursor, windsurf, amp,
# antigravity, copilot, kiro, roocode, continue, droid
This installs a skill file that teaches you how to use all 28 MCP tools.
The server should already be configured in your MCP config. If not, add it:
{
"mcpServers": {
"graph-mem": {
"command": "graph-mem",
"args": ["server", "--project-dir", "/path/to/your/project"]
}
}
}
Now start using the knowledge graph:
1. read_graph() to see current state
2. search_nodes("relevant topic") to find existing knowledge
3. add_entities, add_relationships, add_observations as you learn things
4. update_observation / update_relationship to fix mistakes in-place
5. open_dashboard() to explore the graph visually in your browser
6. At session end, capture anything important you discovered
Your goal: build a rich knowledge graph of this project so future sessions
start with full context instead of from zero. Search before adding to avoid
duplicates. Be specific with entity names and types.
Installation
Option 1: pip (Recommended)
pip install graphmem-mcp
graph-mem server
Option 2: uvx (zero pre-install)
uvx --from graphmem-mcp graph-mem server
uvx downloads the package into an isolated environment and runs it in one command. Nothing to pre-install beyond uv.
Option 3: From source
git clone https://github.com/Sathvik-1007/GraphMem-MCP
cd graph-mem
pip install -e ".[full,dev]"
graph-mem server
Optional extras
pip install "graphmem-mcp[embeddings]" # sentence-transformers for local embeddings
pip install "graphmem-mcp[onnx]" # ONNX runtime for embedding inference
pip install "graphmem-mcp[ui]" # aiohttp for interactive graph visualisation
pip install "graphmem-mcp[full]" # all of the above
Tools
Graph-Mem exposes 28 MCP tools — ten for writing, nine for reading, four for maintenance, four for multi-graph management, and one utility. Full CRUD on every primitive: entities, relationships, and observations can all be created, read, updated, and deleted.
Write Tools (10)
Tool
Description
add_entities
Batch-create entities with optional observations; auto-merges on name conflict; returns quality screening hints
add_relationships
Create typed, directed edges between entities; merges duplicates by max weight
add_observations
Attach factual statements to entities with optional source provenance
update_entity
Modify entity name, description, properties, or type in-place (rename with collision check)
update_relationship
Change weight, type, or properties of an existing edge without delete+re-create
update_observation
Edit observation text content in-place with automatic embedding recompute
delete_entities
Remove entities with cascade to relationships, observations, and embeddings
delete_relationships
Remove specific edges between entities, optionally filtered by type
delete_observations
Remove specific observations by ID with ownership validation
merge_entities
Combine duplicate entities: moves observations and relationships, deduplicates edges
Read Tools (9)
Tool
Description
search_nodes
Hybrid semantic + full-text search with RRF fusion ranking
search_observations
Semantic search directly over observation text content
find_connections
Multi-hop BFS graph traversal with direction and type filters
get_entity
Full entity details with all observations and relationships
list_entities
Browse/paginate all entities with optional type filter
list_relationships
Browse/paginate relationships with entity, type, or combined filters
read_graph
Graph statistics: counts, type distributions, most-connected entities
get_subgraph
Extract neighborhood subgraph around seed entities
find_paths
Find shortest paths between two entities via BFS
Maintenance Tools (4)
Tool
Description
graph_health
Health stats: counts, hotspots, missing descriptions, suggested actions
compact_observations
Atomic observation compaction — delete old and add merged summaries in one step
suggest_connections
Find semantically similar entities for a node to connect to
audit_graph
Full quality screening — disconnected nodes, missing data, weak links. Returns structured findings plus a rendered report field
Visualization (1)
Tool
Description
open_dashboard
Launch interactive graph visualisation UI and return its URL
Multi-Graph Tools (4)
Tool
Description
list_graphs
List all named graphs in the .graphmem/ directory with entity/relationship/observation counts
create_graph
Create a new named graph (.graphmem/<name>.db)
switch_graph
Switch the active graph — hot-swaps storage, search, and graph engines
delete_graph
Delete a named graph (cannot delete the currently active graph)
Multi-graph storage: Each named graph is a separate SQLite database in .graphmem/. The default graph is graph.db. Use --graph <name> on CLI commands to target a specific graph.
Architecture
graph TD
Agent[Any MCP-Compatible Agent or IDE] --> Transport
subgraph Transport
STDIO[stdio]
SSE[SSE]
HTTP[streamable-http]
end
Transport --> Tools
subgraph Tools[Graph-Mem MCP Server — 28 MCP Tools]
Write[Write · 10 tools]
Read[Read · 9 tools]
Maint[Maintenance · 4 tools]
Graph[Multi-Graph · 4 tools]
UI[Dashboard · 1 tool]
end
Write --> Engines
Read --> Engines
Maint --> Engines
subgraph Engines
GE[GraphEngine]
SE[HybridSearch]
EE[EmbeddingEngine]
GT[GraphTraversal]
EM[EntityMerger]
end
Engines --> Storage
subgraph Storage[SQLite Storage]
DB[SQLite WAL]
VEC[sqlite-vec]
FTS[FTS5]
end
UI --> Dashboard[React SPA + aiohttp]
Dashboard --> DB
Everything lives in a single SQLite database per project. The server communicates over MCP's standard stdio transport (SSE and streamable-http also supported) and stores all data in .graphmem/graph.db at your project root. The database file is portable — copy it between machines, check it into version control, or back it up like any other file.
Graph-Mem MCP is a standard MCP server. It communicates with your agent over the Model Context Protocol (stdio by default, SSE and streamable-http also supported) and exposes 28 tools that the agent calls directly — the same way it calls any other MCP tool. It works with every MCP-compatible agent, IDE, and framework out of the box.
To verify it's working, ask your agent to run read_graph() — it should return the current graph statistics.
Graph Visualisation
graph-mem ui # open interactive graph explorer
graph-mem ui --no-open # start server without opening browser
graph-mem ui --port 9090 # use a specific port
graph-mem ui --graph harry-potter # open a specific named graph
The URL printed by graph-mem ui contains a session token — treat it as a
password. The dashboard reads and writes the graph, so the API requires that
token in a custom header, and rejects requests whose Origin or Host is not
the interface it bound. Without those checks any website you visited while the
UI was running could rewrite your knowledge graph. See
SECURITY.md for the details.
The open_dashboard MCP tool also starts this UI server and returns the URL to
your agent. It always binds localhost: the bind address is deliberately not a
tool parameter, so a prompt-injected agent cannot publish your graph to the
network.
Dashboard features:
Force-directed graph canvas with real-time physics simulation
Entity type filtering — toggle visibility of entity types via sidebar checkboxes
Click-to-focus — click a node on the graph or sidebar to instantly center and zoom to it
Inline entity editing — click any field (name, type, description) in the detail panel to edit it in-place
Property management — add, edit, and delete individual properties per entity with per-row controls
Observation management — add, edit, and delete observations with confirmation dialogs and inline editing
Relationship navigation — click related entities to navigate the graph
Entity creation and deletion — create new entities from the sidebar, delete with confirmation from the detail panel danger zone
Hybrid search — semantic + keyword search across all entities
Graph picker — switch between named graphs without restarting the server
Physics controls — adjust spring, repulsion, damping, and gravity in real-time
Keyboard shortcuts — Space (reheat), F (fit to view), Escape (deselect)
Data Storage
By default, Graph-Mem stores its database at .graphmem/graph.db relative to the current working directory. You can control this with:
Method
Example
Result
--project-dir
--project-dir /home/user/myproject
Stores at /home/user/myproject/.graphmem/graph.db
--db
--db /custom/path/memory.db
Stores at exactly that path
GRAPHMEM_DB_PATH env
export GRAPHMEM_DB_PATH=/tmp/test.db
Stores at that path
Default
(nothing)
.graphmem/graph.db relative to CWD
Priority order:--db > --project-dir > GRAPHMEM_DB_PATH env var > default.
The .graphmem/ directory is automatically created if it doesn't exist. Add .graphmem/ to your .gitignore if you don't want to track the database in version control.
CLI Reference
Server
graph-mem server # stdio transport (default)
graph-mem server --transport sse # SSE transport
graph-mem server --db /path/to/graph.db # custom database path
graph-mem server --project-dir /my/project # store memory in <dir>/.graphmem/
graph-mem server --project-dir /my/project --graph harry-potter # use named graph
# Embedding customization
graph-mem server --embedding-model sentence-transformers/all-mpnet-base-v2
graph-mem server --no-onnx --embedding-device cuda
graph-mem server --cache-size 50000
# Tuning
graph-mem server --search-limit 20 --max-hops 6
graph-mem server --log-level DEBUG
All server options:
Flag
Description
Default
--transport
stdio, sse, or streamable-http
stdio
--db
Path to SQLite database file
.graphmem/graph.db
--project-dir
Project root; DB at <dir>/.graphmem/graph.db
CWD
--graph
Named graph (resolves to <dir>/.graphmem/<name>.db)
graph
--host
Bind address (SSE/HTTP only)
127.0.0.1
--port
Port (SSE/HTTP only)
8080
--embedding-model
HuggingFace model ID for embeddings
all-MiniLM-L6-v2
--use-onnx / --no-onnx
Use the ONNX embedding backend (needs optimum[onnxruntime])
Every path below is cited against the vendor's current documentation. An agent
whose install location cannot be cited is not listed here — a guessed path
reports success, writes a file, and the agent never reads it, which is worse
than no support. Six agents were removed on exactly those grounds.
Agents whose target file is shared — AGENTS.md, GEMINI.md,
.github/copilot-instructions.md, Windsurf's global rules — get a delimited
section written into it. Anything you already have in the file survives, and
re-installing replaces the section instead of appending a second copy.
Want another agent supported? See
Adding an Agent — it takes a documented
path and about ten lines.
Graph Management
graph-mem init # create .graphmem/ directory
graph-mem init --project-dir /my/project # create in specific directory
graph-mem init --graph research # create a named graph
graph-mem status # print graph statistics
graph-mem status --json # graph statistics as JSON
graph-mem status --graph research # status of a named graph
graph-mem export --format json # export entire graph
graph-mem export --output backup.json # export to file
graph-mem import graph.json # import graph from file
graph-mem validate # run integrity checks
All management commands accept --db, --project-dir, and --graph for targeting a specific database.
Multi-graph support: Use --graph <name> to work with named graphs stored as .graphmem/<name>.db. Without --graph, commands target the default graph.db. The MCP tools list_graphs, create_graph, switch_graph, and delete_graph provide runtime graph management for agents.
Configuration
All settings are optional. Defaults work out of the box. Every setting can be controlled via CLI flags (see graph-mem server --help), environment variables, or both. CLI flags take precedence over environment variables, which take precedence over defaults.
Environment Variable
CLI Flag
Default
Description
GRAPHMEM_DB_PATH
--db
.graphmem/graph.db
Database file path
GRAPHMEM_BACKEND_TYPE
--
sqlite
Storage backend
GRAPHMEM_EMBEDDING_MODEL
--embedding-model
all-MiniLM-L6-v2
HuggingFace model ID
GRAPHMEM_USE_ONNX
--use-onnx / --no-onnx
false
Use ONNX runtime if available
GRAPHMEM_EMBEDDING_DEVICE
--embedding-device
cpu
Inference device (cpu or cuda)
GRAPHMEM_CACHE_SIZE
--cache-size
10000
Embedding cache max entries
GRAPHMEM_SEARCH_LIMIT
--search-limit
10
Default search result limit
GRAPHMEM_MAX_HOPS
--max-hops
4
Default max traversal depth
GRAPHMEM_LOG_LEVEL
--log-level
WARNING
Logging verbosity
GRAPHMEM_TRANSPORT
--transport
stdio
MCP transport protocol
Performance
Measured numbers, not adjectives. Reproduce the traversal figures with
python benchmarks/bench_traversal.py; the full table is in
docs/ARCHITECTURE.md.
Traversal — breadth-first with a global visited set, one indexed adjacency
query per hop. A dense 60-node graph traverses to depth 6 in 5 ms. The obvious
recursive-CTE formulation enumerates every simple path instead: on a 14-node
graph it materialised 1,409,006 intermediate rows in 6.4 seconds to return the
same 13 entities that BFS returns in 1 ms.
Graph canvas — Barnes-Hut force simulation (θ = 0.9). 2000 nodes run at
215 fps; 5000 nodes, the API's own cap, at 80 fps. The previous all-pairs
implementation managed 30 fps and 3.7 fps respectively. Approximation error
against the exact sum is 1.30% RMS, and settled layouts are equivalent.
Storage
WAL journal with PRAGMA tuning — concurrent reads, memory-mapped I/O, so a
large database does not consume proportional RAM
One connection with a write lock held for the outermost transaction, and
BEGIN IMMEDIATE so a read-to-write upgrade cannot fail unretryably
Batched bulk operations, and every IN (...) chunked below SQLite's
bound-variable limit
Embeddings
Content-hash cache keyed by (hash, model), so two models coexist instead of
clobbering each other; LRU eviction, batched reads and writes
Model loads lazily in a background thread at startup, and inference runs in a
worker thread — neither blocks the event loop
Optional ONNX backend when optimum[onnxruntime] is installed and
--use-onnx is set, falling back to PyTorch. Off by default; this project
publishes no benchmark for it, so no speedup is claimed here.
Bounds — every traversal, search, and list response is capped by a named,
configurable limit, and a capped response says so rather than returning a
silent subset.
Development
git clone https://github.com/Sathvik-1007/GraphMem-MCP
cd graph-mem
# Using uv (recommended)
uv venv
uv pip install -e ".[full,dev]"
# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -e ".[full,dev]"
Running Tests
pytest # all tests
pytest tests/test_graph/ # graph engine tests
pytest tests/test_server/ # MCP server tool tests (all 28 tools)
pytest tests/test_cli/ # CLI command tests
pytest tests/test_models/ # data model tests
pytest tests/test_semantic/ # search + vector tests
pytest tests/test_storage/ # storage backend tests
pytest tests/test_db/ # database + migration tests
pytest tests/test_utils/ # config, logging, ID generation tests
pytest -x -q # stop on first failure, quiet output
