graph-memory-mcp-server

Graphiti Memory Graph MCP Server

A Model Context Protocol (MCP) server implementation for Graphiti memory graphs. This server allows language models to interact with knowledge graphs, search memories, and explore relationships through a standardized interface.

Features

• Hybrid Memory Search: Combines semantic similarity and BM25 retrieval with Reciprocal Rank Fusion reranking
• Advanced Filtered Search: Comprehensive search with filtering, reranking, and BFS capabilities
• Recent Context Search: Context-aware search within recent conversations
• Node Management: Find, explore, and get detailed information about nodes in the knowledge graph
• User and Group Support: Search within specific user graphs or group graphs
• Episode Management: Access detailed episode information from the knowledge graph
• Casefile Integration: Get casefile indexes and specific pages
• Seamless MCP Integration: Works with Claude Desktop and other AI tools supporting MCP

Installation & Usage

Using npx (recommended)

The easiest way to use this package is through npx:

npx graph-memory-mcp-server

Using with Claude Desktop

To use with Claude Desktop:

1. Open Claude Desktop
2. Enable the MCP feature in settings
3. Add the server configuration to your claude_desktop_config.json:

   {
     "mcpServers": {
       "graphiti-memory": {
         "command": "npx",
         "args": [
           "-y",
           "graph-memory-mcp-server@latest",
           "--zep-api-key",
           "YOUR_ZEP_API_KEY",
           "--mongo-uri", 
           "mongodb://username:password@host:port/database",
           "--db-name",
           "your-database-name"
         ]
       }
     }
   }

4. Restart Claude Desktop
5. Ask Claude to search memories, explore knowledge graphs, and analyze relationships

Global Installation

You can install the package globally using:

npm install -g graph-memory-mcp-server

Then run:

graph-memory-mcp-server

Manual Installation

1. Clone this repository
2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. Start the server:

node dist/index.js

MCP Integration

This server implements the Model Context Protocol, allowing language models to:

1. Search and explore memory graphs using various strategies
2. Find specific nodes and relationships in knowledge graphs
3. Access detailed information about entities and their connections
4. Navigate user-specific and group-specific knowledge graphs
5. Retrieve episode and casefile information

Consolidated Tools (10 Total)

The server provides a streamlined set of tools organized by functionality:

🔍 Search Tools (3)

1. hybrid_memory_search: Simple, general-purpose search combining semantic similarity and BM25 retrieval with RRF reranking. Use this for broad exploration of memories.

2. search_with_filters: [ENHANCED] Advanced search with comprehensive filtering and reranking options. This tool can handle all search scenarios:

   • Basic filtered search by entity/edge types
   • Focused search around specific nodes (replaces focused_memory_search)
   • BFS search from origin nodes (replaces search_with_bfs)
   • All reranking methods (RRF, MMR, node distance, episode mentions, cross encoder)

3. search_recent_context: [NEW] Context-aware search within recent conversations. Ideal for "What issues need addressing today?" queries. Can also accept custom origin UUIDs for BFS-style searches.

🎯 Node Tools (3)

4. find_memory_nodes: Discover nodes by name, type, or properties. Essential for getting node UUIDs.

5. get_memory_node_details: Get comprehensive information about a specific node including relationships.

6. get_user_nodes: List all nodes associated with a specific user.

📝 Episode Tools (2)

7. get_episode: Get detailed information about a specific episode by UUID.

8. get_recent_episodes: [NEW] Retrieve recent episodes/messages with role filtering.

⚙️ System Tools (2)

9. get_users: List all users in the system with pagination.

10. get_casefile_index & get_casefile_pages: Browse and read casefile content.

Migration Guide

Replacing Removed Tools

The following tools have been removed in favor of more flexible alternatives:

focused_memory_search → search_with_filters

Old:

{
  "tool": "focused_memory_search",
  "arguments": {
    "query": "recent projects", 
    "focal_node_uuid": "node-uuid-12345",
    "user_id": "user123"
  }
}

New:

{
  "tool": "search_with_filters",
  "arguments": {
    "query": "recent projects",
    "reranker": "node_distance",
    "focal_node_uuid": "node-uuid-12345",
    "user_id": "user123"
  }
}

advanced_memory_search → search_with_filters

Old:

{
  "tool": "advanced_memory_search",
  "arguments": {
    "query": "machine learning applications",
    "search_recipe": "EDGE_HYBRID_SEARCH_NODE_DISTANCE",
    "focal_node_uuid": "node-uuid-67890",
    "user_id": "user123"
  }
}

New:

{
  "tool": "search_with_filters", 
  "arguments": {
    "query": "machine learning applications",
    "scope": "edges",
    "reranker": "node_distance", 
    "focal_node_uuid": "node-uuid-67890",
    "user_id": "user123"
  }
}

search_with_bfs → search_with_filters or search_recent_context

Old:

{
  "tool": "search_with_bfs",
  "arguments": {
    "query": "deployment issues",
    "bfs_origin_node_uuids": ["uuid1", "uuid2", "uuid3"],
    "user_id": "user123"
  }
}

New Option 1 - Using search_with_filters:

{
  "tool": "search_with_filters",
  "arguments": {
    "query": "deployment issues", 
    "bfs_origin_node_uuids": ["uuid1", "uuid2", "uuid3"],
    "user_id": "user123"
  }
}

New Option 2 - Using search_recent_context:

{
  "tool": "search_recent_context",
  "arguments": {
    "query": "deployment issues",
    "custom_origin_uuids": ["uuid1", "uuid2", "uuid3"], 
    "user_id": "user123"
  }
}

Usage Examples

Basic Memory Search

// Simple search for general exploration
{
  "tool": "hybrid_memory_search",
  "arguments": {
    "query": "artificial intelligence research",
    "limit": 10,
    "user_id": "user123"
  }
}

Advanced Filtered Search

// Search with entity filtering and MMR reranking
{
  "tool": "search_with_filters",
  "arguments": {
    "query": "software projects",
    "node_labels": ["Project", "Repository"],
    "reranker": "mmr",
    "mmr_lambda": 0.7,
    "limit": 15,
    "user_id": "user123"
  }
}

Recent Context Search

// Find issues that need attention today
{
  "tool": "search_recent_context",
  "arguments": {
    "query": "issues to address today",
    "lastn": 30,
    "only_user_episodes": true,
    "user_id": "user123"
  }
}

Node Discovery and Details

// Find nodes related to a person
{
  "tool": "find_memory_nodes",
  "arguments": {
    "search_term": "John Smith",
    "node_type": "Person",
    "user_id": "user123"
  }
}

// Get detailed information about a specific node
{
  "tool": "get_memory_node_details",
  "arguments": {
    "node_uuid": "found-node-uuid",
    "include_relationships": true,
    "relationship_depth": 2
  }
}

Architecture

This server is built on:

• Graphiti: Knowledge graph and memory management
• Model Context Protocol (MCP): Standardized AI tool integration
• TypeScript: Type-safe development
• Hybrid Search: Combining multiple search and ranking strategies

Development

For development, you can run the server directly using ts-node:

npm run dev

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

About Graphiti

Graphiti is a powerful knowledge graph and memory management system that enables AI applications to build, maintain, and query complex knowledge representations. This MCP server provides a bridge between Graphiti's capabilities and AI language models through standardized tool interfaces.