Skip to main content
Glama
Graphiti-Memory MCP Server

Graphiti-Memory MCP Server

by alankyshum

Graphiti-Memory MCP Server

A Model Context Protocol (MCP) server that provides memory and knowledge graph operations using Neo4j and the Graphiti framework.

Features

  • 📝 Add Memories: Store episodes and information in the knowledge graph with automatic entity extraction

  • 🧠 Search Nodes: Query entities in your knowledge graph using natural language

  • 🔗 Search Facts: Find relationships and connections between entities

  • 📚 Retrieve Episodes: Get historical episodes and memories

  • 🗑️ Management Tools: Delete episodes, edges, and clear the graph

  • 🤖 AI-Powered: Optional OpenAI integration for enhanced entity extraction

  • 📊 Real-time Data: Direct connection to your Neo4j database

  • 🛠️ Built-in Diagnostics: Comprehensive error messages and troubleshooting

Related MCP server: Graphiti Knowledge Graph MCP Server

Installation

Prerequisites

  1. Neo4j Database: You need a running Neo4j instance

    # Install Neo4j (via Homebrew on macOS)
    brew install neo4j
    
    # Start Neo4j
    neo4j start
  2. Python 3.10+: Required for the MCP server

Install from PyPI

pip install graphiti-memory

Install from Source

git clone https://github.com/alankyshum/graphiti-memory.git
cd graphiti-memory
pip install -e .

Configuration

MCP Configuration

Add to your MCP client configuration file (e.g., Claude Desktop config):

{
  "mcpServers": {
    "graphiti-memory": {
      "command": "graphiti-mcp-server",
      "env": {
        "NEO4J_URI": "neo4j://127.0.0.1:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password-here",
        "OPENAI_API_KEY": "your-openai-key-here",
        "GRAPHITI_GROUP_ID": "default"
      }
    }
  }
}

Neo4j Setup

  1. Set Password (first-time setup):

    neo4j-admin dbms set-initial-password YOUR_PASSWORD
  2. Test Connection:

    # HTTP interface
    curl http://127.0.0.1:7474
    
    # Bolt protocol
    nc -zv 127.0.0.1 7687

Available Tools

1. add_memory

Add an episode or memory to the knowledge graph. This is the primary way to add information.

Example:

{
  "name": "add_memory",
  "arguments": {
    "name": "Project Discussion",
    "episode_body": "We discussed the new AI feature roadmap for Q2. Focus on improving entity extraction.",
    "source": "text",
    "group_id": "project-alpha"
  }
}

Parameters:

  • name: Name of the episode (required)

  • episode_body: Content to store - text, message, or JSON (required)

  • source: Type of content - "text", "message", or "json" (default: "text")

  • group_id: Optional namespace for organizing data

  • source_description: Optional description

2. search_memory_nodes

Search for nodes (entities) in the knowledge graph using natural language.

Example:

{
  "name": "search_memory_nodes",
  "arguments": {
    "query": "machine learning",
    "max_nodes": 10
  }
}

Returns: List of nodes with UUID, name, summary, labels, and timestamps.

3. search_memory_facts

Search for facts (relationships) between entities in the knowledge graph.

Example:

{
  "name": "search_memory_facts",
  "arguments": {
    "query": "what technologies are related to AI",
    "max_facts": 10
  }
}

Returns: List of fact triples with source, target, and relationship details.

4. get_episodes

Retrieve recent episodes for a specific group.

Example:

{
  "name": "get_episodes",
  "arguments": {
    "group_id": "project-alpha",
    "last_n": 10
  }
}

5. delete_episode

Delete an episode from the knowledge graph.

Example:

{
  "name": "delete_episode",
  "arguments": {
    "uuid": "episode-uuid-here"
  }
}

6. delete_entity_edge

Delete a fact (entity edge) from the knowledge graph.

Example:

{
  "name": "delete_entity_edge",
  "arguments": {
    "uuid": "edge-uuid-here"
  }
}

7. get_entity_edge

Retrieve a specific entity edge by UUID.

Example:

{
  "name": "get_entity_edge",
  "arguments": {
    "uuid": "edge-uuid-here"
  }
}

8. clear_graph

Clear all data from the knowledge graph (DESTRUCTIVE).

Example:

{
  "name": "clear_graph",
  "arguments": {}
}

Usage

With Claude Desktop

Configure in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "graphiti-memory": {
      "command": "graphiti-mcp-server",
      "env": {
        "NEO4J_URI": "neo4j://127.0.0.1:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "OPENAI_API_KEY": "your-openai-key-here",
        "GRAPHITI_GROUP_ID": "default"
      }
    }
  }
}

Note: OPENAI_API_KEY is optional. Without it, entity extraction will be limited but the server will still work.

Standalone Testing

Test the server directly from command line:

export NEO4J_URI="neo4j://127.0.0.1:7687"
export NEO4J_USER="neo4j"
export NEO4J_PASSWORD="your-password"

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | graphiti-mcp-server

Troubleshooting

Connection Failed

Error: Connection refused or ServiceUnavailable

Solutions:

  1. Check Neo4j is running: neo4j status

  2. Start Neo4j: neo4j start

  3. Verify port 7687 is accessible: nc -zv 127.0.0.1 7687

Authentication Failed

Error: Unauthorized or authentication failure

Solutions:

  1. Verify password is correct

  2. Reset password: neo4j-admin dbms set-initial-password NEW_PASSWORD

  3. Update password in MCP configuration

  4. Use test tool to verify: test_neo4j_auth

Package Not Found

Error: neo4j package not installed

This package automatically installs the neo4j dependency. If you see this error:

pip install neo4j

Development

Setup Development Environment

git clone https://github.com/alankyshum/graphiti-memory.git
cd graphiti-memory
pip install -e ".[dev]"

Running Tests

# Test the server
python -m graphiti_memory.server << 'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
EOF

Architecture

MCP Client (Claude Desktop / Cline / etc.)
    ↓
Graphiti-Memory Server
    ↓
Neo4j Database

The server:

  • Listens on stdin for JSON-RPC messages

  • Logs diagnostics to stderr

  • Responds on stdout with JSON-RPC

  • Maintains persistent Neo4j connection

Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Submit a pull request

License

MIT License - see LICENSE file for details.

Credits

Built for use with:

Available Tools

8 tools
add_memoryC

Add an episode/memory to the knowledge graph. This is the primary way to add information.

Inputs: name (required), episode_body (required), group_id, source, +1 more.

clear_graphA

Clear all data from the knowledge graph (DESTRUCTIVE)

Inputs: no named parameters.

delete_entity_edgeC

Delete an entity edge (fact) from the knowledge graph

Inputs: uuid (required).

delete_episodeC

Delete an episode from the knowledge graph

Inputs: uuid (required).

get_entity_edgeB

Get an entity edge by UUID

Inputs: uuid (required).

get_episodesC

Get recent episodes for a group

Inputs: group_id, last_n.

search_memory_factsC

Search for facts (relationships) in the knowledge graph

Inputs: query (required), group_ids, max_facts.

search_memory_nodesC

Search for nodes (entities) in the knowledge graph

Inputs: query (required), group_ids, max_nodes.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have distinct purposes, such as add_memory for adding, clear_graph for clearing, and search_memory_facts for searching facts. However, get_entity_edge and search_memory_nodes could be slightly ambiguous since both involve retrieving entity-related information, but their descriptions clarify the difference (specific vs. search).

    Naming Consistency4/5

    The naming follows a consistent verb_noun pattern with snake_case throughout, such as add_memory and delete_episode. There are minor deviations like get_entity_edge using 'entity_edge' instead of a more uniform term like 'fact', but overall the pattern is clear and predictable.

    Tool Count5/5

    With 8 tools, the count is well-scoped for a memory/knowledge graph server, covering core operations like add, delete, get, search, and clear. Each tool serves a distinct function without bloat, making it manageable and purposeful for the domain.

    Completeness4/5

    The tool set provides good coverage for a knowledge graph domain, including add, delete, get, and search operations for episodes and entities. A minor gap is the lack of update tools for modifying existing memories or entities, but agents can work around this by deleting and re-adding, and core workflows are supported.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables storage and retrieval of knowledge in a graph database format, allowing users to create, update, search, and delete entities and relationships in a Neo4j-powered knowledge graph through natural language.
      5
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides persistent memory capabilities through Neo4j graph database integration, allowing storage and retrieval of interconnected knowledge with complex relationships between entities. Enables long-term retention and querying of information across multiple conversations through graph-based memory management.
      1
      MIT