GraphMem-MCP

# Graph-Mem MCP

<!-- mcp-name: io.github.Sathvik-1007/graphmem-mcp -->

> Persistent knowledge graph memory for AI agents and IDEs

[![PyPI](https://img.shields.io/pypi/v/graphmem-mcp.svg)](https://pypi.org/project/graphmem-mcp/)
[![CI](https://github.com/Sathvik-1007/GraphMem-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Sathvik-1007/GraphMem-MCP/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
[![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://modelcontextprotocol.io)

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](docs/ARCHITECTURE.md#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:

<table>
<tr>
<td><b>Claude Code</b></td>
<td><b>OpenCode</b></td>
<td><b>Cursor</b></td>
<td><b>Windsurf</b></td>
<td><b>Codex CLI</b></td>
</tr>
<tr>
<td><b>Gemini CLI</b></td>
<td><b>GitHub Copilot</b></td>
<td><b>Amp</b></td>
<td><b>Kiro</b></td>
<td><b>Roo Code</b></td>
</tr>
<tr>
<td><b>Continue</b></td>
<td><b>Antigravity</b></td>
<td><b>Droid (Factory)</b></td>
<td colspan="2"><a href="CONTRIBUTING.md#adding-an-agent">add yours →</a></td>
</tr>
</table>

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](CONTRIBUTING.md#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:**

```bash
pip install graphmem-mcp
```

Or run it without installing — `uvx` fetches and isolates it the way `npx`
does for Node:

```bash
uvx --from graphmem-mcp graph-mem server
```

Listed in the [official MCP Registry](https://github.com/modelcontextprotocol/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:**

```bash
graph-mem install claude       # Claude Code
graph-mem install opencode     # OpenCode
graph-mem install codex        # Codex CLI
graph-mem install gemini       # Gemini CLI
graph-mem install cursor       # Cursor
graph-mem install windsurf     # Windsurf
graph-mem install amp          # Amp
graph-mem install antigravity  # Antigravity
graph-mem install copilot      # GitHub Copilot
graph-mem install kiro         # Kiro
graph-mem install roocode      # Roo Code
graph-mem install continue     # Continue
graph-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:

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

With full customization:

```json
{
  "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-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)

```bash
pip install graphmem-mcp
graph-mem server
```

### Option 2: uvx (zero pre-install)

```bash
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](https://docs.astral.sh/uv/).

### Option 3: From source

```bash
git clone https://github.com/Sathvik-1007/GraphMem-MCP
cd graph-mem
pip install -e ".[full,dev]"
graph-mem server
```

### Optional extras

```bash
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/