Graph-Mem

Graph-Mem MCP

Persistent knowledge graph memory for AI agents and IDEs

[PyPI] [CI] [License: MIT] [Python 3.10+] [MCP]

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

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.

2. Install the skill for your agent:

graph-mem install claude       # Claude Codegraph-mem install opencode     # OpenCodegraph-mem install codex        # Codex CLIgraph-mem install gemini       # Gemini CLIgraph-mem install cursor       # Cursorgraph-mem install windsurf     # Windsurfgraph-mem install amp          # Ampgraph-mem install antigravity  # Antigravitygraph-mem install copilot      # GitHub Copilotgraph-mem install kiro         # Kirograph-mem install roocode      # Roo Codegraph-mem install continue     # Continuegraph-mem install droid        # Droid (Factory)

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:

{  "mcpServers": {    "graph-mem": {      "command": "graph-mem",      "args": ["server"]    }  }}

With full customization:

{  "mcpServers": {    "graph-mem": {      "command": "graph-mem",      "args": [        "server",        "--project-dir", "/path/to/my/project",        "--embedding-model", "sentence-transformers/all-mpnet-base-v2",        "--use-onnx",        "--cache-size", "20000",        "--log-level", "INFO"      ]    }  }}

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-mcpgraph-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 state2. search_nodes("relevant topic") to find existing knowledge3. add_entities, add_relationships, add_observations as you learn things4. update_observation / update_relationship to fix mistakes in-place5. open_dashboard() to explore the graph visually in your browser6. At session end, capture anything important you discovered
Your goal: build a rich knowledge graph of this project so future sessionsstart with full context instead of from zero. Search before adding to avoidduplicates. Be specific with entity names and types.

Installation

Option 1: pip (Recommended)

pip install graphmem-mcpgraph-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-MCPcd graph-mempip install -e ".[full,dev]"graph-mem server

Optional extras

pip install "graphmem-mcp[embeddings]"   # sentence-transformers for local embeddingspip install "graphmem-mcp[onnx]"         # ONNX runtime for embedding inferencepip install "graphmem-mcp[ui]"           # aiohttp for interactive graph visualisationpip 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)

Read Tools (9)

Maintenance Tools (4)

Visualization (1)

Multi-Graph Tools (4)

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.

Further reading

MCP Integration

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 explorergraph-mem ui --no-open                    # start server without opening browsergraph-mem ui --port 9090                  # use a specific portgraph-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:

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 transportgraph-mem server --db /path/to/graph.db   # custom database pathgraph-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 customizationgraph-mem server --embedding-model sentence-transformers/all-mpnet-base-v2graph-mem server --no-onnx --embedding-device cudagraph-mem server --cache-size 50000
# Tuninggraph-mem server --search-limit 20 --max-hops 6graph-mem server --log-level DEBUG

All server options:

Skill Installation

graph-mem install <agent>                 # project-level installgraph-mem install <agent> --global        # global/user-level installgraph-mem install <agent> --domain code   # use domain overlay (code, research, general)

Where the skill is installed

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/ directorygraph-mem init --project-dir /my/project  # create in specific directorygraph-mem init --graph research           # create a named graphgraph-mem status                          # print graph statisticsgraph-mem status --json                   # graph statistics as JSONgraph-mem status --graph research         # status of a named graphgraph-mem export --format json            # export entire graphgraph-mem export --output backup.json     # export to filegraph-mem import graph.json               # import graph from filegraph-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.

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-MCPcd graph-mem
# Using uv (recommended)uv venvuv pip install -e ".[full,dev]"
# Or using pippython -m venv .venvsource .venv/bin/activatepip install -e ".[full,dev]"

Running Tests

pytest                            # all testspytest tests/test_graph/          # graph engine testspytest tests/test_server/         # MCP server tool tests (all 28 tools)pytest tests/test_cli/            # CLI command testspytest tests/test_models/         # data model testspytest tests/test_semantic/       # search + vector testspytest tests/test_storage/        # storage backend testspytest tests/test_db/             # database + migration testspytest tests/test_utils/          # config, logging, ID generation testspytest -x -q                      # stop on first failure, quiet output

Star History

License

MIT