graph-memory-mcp-server/README.md

Graphiti Memory Graph MCP Server - Search and explore knowledge graphs using Graphiti

# 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:

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

```bash
npm install -g graph-memory-mcp-server
```

Then run:

```bash
graph-memory-mcp-server
```

### Manual Installation

1. Clone this repository
2. Install dependencies:

```bash
npm install
```

3. Build the TypeScript code:

```bash
npm run build
```

4. Start the server:

```bash
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:**
```javascript
{
  "tool": "focused_memory_search",
  "arguments": {
    "query": "recent projects", 
    "focal_node_uuid": "node-uuid-12345",
    "user_id": "user123"
  }
}
```

**New:**
```javascript
{
  "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:**
```javascript
{
  "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:**
```javascript
{
  "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:**
```javascript
{
  "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:**
```javascript
{
  "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:**
```javascript
{
  "tool": "search_recent_context",
  "arguments": {
    "query": "deployment issues",
    "custom_origin_uuids": ["uuid1", "uuid2", "uuid3"], 
    "user_id": "user123"
  }
}
```

## Usage Examples

### Basic Memory Search
```javascript
// Simple search for general exploration
{
  "tool": "hybrid_memory_search",
  "arguments": {
    "query": "artificial intelligence research",
    "limit": 10,
    "user_id": "user123"
  }
}
```

### Advanced Filtered Search
```javascript
// 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
```javascript
// 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
```javascript
// 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:

```bash
npm run dev
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](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.