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
Installation
Prerequisites
-
Neo4j Database: You need a running Neo4j instance
# Install Neo4j (via Homebrew on macOS) brew install neo4j # Start Neo4j neo4j start -
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
-
Set Password (first-time setup):
neo4j-admin dbms set-initial-password YOUR_PASSWORD -
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 datasource_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:
- Check Neo4j is running:
neo4j status - Start Neo4j:
neo4j start - Verify port 7687 is accessible:
nc -zv 127.0.0.1 7687
Authentication Failed
Error: Unauthorized or authentication failure
Solutions:
- Verify password is correct
- Reset password:
neo4j-admin dbms set-initial-password NEW_PASSWORD - Update password in MCP configuration
- 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:
- Fork the repository
- Create a feature branch
- Make your changes
- 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)
- Neo4j
- Graphiti - Knowledge graph framework