Graphiti

The Graphiti MCP Server enables your AI assistant to connect to Graphiti’s powerful knowledge graph framework.

Instead of treating each interaction as isolated, it weaves conversations, structured data, and external information into a coherent temporal graph.

Features

• 📊 Episode Management: Store and retrieve text, messages, or JSON data as temporal episodes
• 🔍 Semantic Search: Find relevant facts and node summaries using hybrid search capabilities
• 🏗️ Entity Relationships: Automatically extract and manage entity nodes and their connections
• 👥 Group Organization: Namespace your data with group_id filtering for multiple projects
• 🔄 Incremental Updates: Add new information without rebuilding the entire graph
• 🧹 Graph Maintenance: Clear graphs and rebuild indices when needed
• 🐳 Docker Support: Deploy with included Docker Compose configuration
• 🔗 Multiple Transports: Support for both stdio and SSE (HTTP) connections

Use Cases

• Persistent AI Assistants: Build AI agents that remember previous conversations and can reference past interactions contextually, perfect for long-term customer support or personal assistants that need to maintain relationship history.
• Dynamic Documentation Systems: Create knowledge bases that evolve with your codebase, automatically connecting new features to existing architecture and maintaining temporal relationships between code changes and requirements.
• Research and Analysis Tools: Develop AI assistants that can track research findings over time, connecting new discoveries to previous work and building comprehensive knowledge maps for complex projects.
• Customer Relationship Management: Build AI systems that understand customer interaction history, product relationships, and temporal patterns in customer behavior for more personalized service.

How to Use It

1. Clone the Graphiti repository:

git clone https://github.com/getzep/graphiti.git
cd graphiti

2. Install dependencies using uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

3. Set up your environment variables in a .env file:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo
OPENAI_API_KEY=your_api_key_here
MODEL_NAME=gpt-4.1-mini
SMALL_MODEL_NAME=gpt-4.1-mini
LLM_TEMPERATURE=0.1

4. Start the server with default settings:

uv run graphiti_mcp_server.py

Or with custom options:

uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse --group-id my-project

5. Available Arguments

• --model: Override MODEL_NAME environment variable
• --small-model: Override SMALL_MODEL_NAME environment variable
• --temperature: Override LLM_TEMPERATURE environment variable
• --transport: Choose stdio or sse transport (default: sse)
• --group-id: Set namespace for the graph (default: “default”)
• --destroy-graph: Clear all graphs on startup
• --use-custom-entities: Enable predefined entity extraction

MCP Client Configuration

For Claude Desktop (stdio transport):

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/username/.local/bin/uv",
      "args": [
        "run", "--isolated", "--directory", 
        "/path/to/graphiti/mcp_server", "--project", ".",
        "graphiti_mcp_server.py", "--transport", "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX",
        "MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

For Cursor IDE (SSE transport):

{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Docker Deployment

1. Copy environment template:

cp .env.example .env

2. Edit .env with your OpenAI API key

3. Start services:

docker compose up

Available Tools

• add_episode: Store text, JSON, or message data as temporal episodes
• search_nodes: Find relevant entity summaries in the knowledge graph
• search_facts: Search for relationships between entities
• get_episodes: Retrieve recent episodes for a group
• delete_episode: Remove episodes from the graph
• get_entity_edge: Retrieve specific entity relationships by UUID
• delete_entity_edge: Remove entity relationships
• clear_graph: Reset the entire knowledge graph
• get_status: Check server and Neo4j connection status

Working with JSON Data

Process structured data by adding episodes with JSON source:

add_episode(
    name="Customer Profile",
    episode_body='{"company": {"name": "Acme Corp"}, "products": [{"id": "P001", "name": "CloudSync"}]}',
    source="json",
    source_description="CRM data export"
)

FAQs

Q: Can I use Graphiti with Azure OpenAI instead of OpenAI?
A: Yes, set the Azure-specific environment variables: AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT_NAME, AZURE_OPENAI_API_VERSION, and optionally AZURE_OPENAI_USE_MANAGED_IDENTITY for authentication.

Q: How do I connect Claude Desktop to the Docker version?
A: The Docker setup uses SSE transport, but Claude Desktop only supports stdio. Install mcp-remote as a bridge: npm install -g mcp-remote, then configure Claude to use "command": "mcp-remote", "args": ["http://localhost:8000/sse"].

Q: What happens if I don’t specify a group_id?
A: The server uses “default” as the group_id. Groups act as namespaces, so different group_ids maintain separate knowledge graphs within the same Neo4j database.

Q: Can I run multiple Graphiti instances with different configurations?
A: Yes, use different group_ids for each instance, or run separate Neo4j databases. Each group_id creates an isolated knowledge graph space.

Q: How does Graphiti handle large amounts of data compared to traditional RAG?
A: Graphiti performs incremental updates without rebuilding the entire graph, making it more efficient for continuously evolving datasets. It also maintains temporal relationships that traditional RAG systems lose.

Q: Do I need to restart the server when adding new data?
A: No, Graphiti updates the knowledge graph incrementally. New episodes and relationships are added in real-time without requiring server restarts or index rebuilds.