graphiti-memory 0.2.0
MCP server for Graphiti knowledge graph operations with Neo4j integration
License: MIT
Requires Python: >=3.10
Keywords: mcp, graphiti, neo4j, knowledge-graph, memory, mcp-server

# Graphiti-Memory MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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

## Installation

### Prerequisites

1. **Neo4j Database**: You need a running Neo4j instance
   ```bash
   # 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

```bash
pip install graphiti-memory
```

### Install from Source

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

```json
{
  "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):
   ```bash
   neo4j-admin dbms set-initial-password YOUR_PASSWORD
   ```

2. **Test Connection**:
   ```bash
   # 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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "name": "get_episodes",
  "arguments": {
    "group_id": "project-alpha",
    "last_n": 10
  }
}
```

### 5. delete_episode

Delete an episode from the knowledge graph.

**Example**:
```json
{
  "name": "delete_episode",
  "arguments": {
    "uuid": "episode-uuid-here"
  }
}
```

### 6. delete_entity_edge

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

**Example**:
```json
{
  "name": "delete_entity_edge",
  "arguments": {
    "uuid": "edge-uuid-here"
  }
}
```

### 7. get_entity_edge

Retrieve a specific entity edge by UUID.

**Example**:
```json
{
  "name": "get_entity_edge",
  "arguments": {
    "uuid": "edge-uuid-here"
  }
}
```

### 8. clear_graph

Clear all data from the knowledge graph (DESTRUCTIVE).

**Example**:
```json
{
  "name": "clear_graph",
  "arguments": {}
}
```

## Usage

### With Claude Desktop

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

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

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

```bash
pip install neo4j
```

## Development

### Setup Development Environment

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

### Running Tests

```bash
# 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.

## Links

- **GitHub**: https://github.com/alankyshum/graphiti-memory
- **PyPI**: https://pypi.org/project/graphiti-memory/
- **Issues**: https://github.com/alankyshum/graphiti-memory/issues
- **MCP Specification**: https://modelcontextprotocol.io

## Credits

Built for use with:
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
- [Neo4j](https://neo4j.com)
- [Graphiti](https://github.com/getzep/graphiti) - Knowledge graph framework