# 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
Raw data
{
"_id": null,
"home_page": null,
"name": "graphiti-memory",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, graphiti, neo4j, knowledge-graph, memory, mcp-server",
"author": null,
"author_email": "Alan Shum <alankyshum@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/33/5a/930446a0e36c14534e4373142cf095bdc679df8a8b0e0f89699aab5665e8/graphiti_memory-0.2.0.tar.gz",
"platform": null,
"description": "# Graphiti-Memory MCP Server\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides memory and knowledge graph operations using Neo4j and the Graphiti framework.\n\n## Features\n\n- \ud83d\udcdd **Add Memories**: Store episodes and information in the knowledge graph with automatic entity extraction\n- \ud83e\udde0 **Search Nodes**: Query entities in your knowledge graph using natural language\n- \ud83d\udd17 **Search Facts**: Find relationships and connections between entities\n- \ud83d\udcda **Retrieve Episodes**: Get historical episodes and memories\n- \ud83d\uddd1\ufe0f **Management Tools**: Delete episodes, edges, and clear the graph\n- \ud83e\udd16 **AI-Powered**: Optional OpenAI integration for enhanced entity extraction\n- \ud83d\udcca **Real-time Data**: Direct connection to your Neo4j database\n- \ud83d\udee0\ufe0f **Built-in Diagnostics**: Comprehensive error messages and troubleshooting\n\n## Installation\n\n### Prerequisites\n\n1. **Neo4j Database**: You need a running Neo4j instance\n ```bash\n # Install Neo4j (via Homebrew on macOS)\n brew install neo4j\n \n # Start Neo4j\n neo4j start\n ```\n\n2. **Python 3.10+**: Required for the MCP server\n\n### Install from PyPI\n\n```bash\npip install graphiti-memory\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/alankyshum/graphiti-memory.git\ncd graphiti-memory\npip install -e .\n```\n\n## Configuration\n\n### MCP Configuration\n\nAdd to your MCP client configuration file (e.g., Claude Desktop config):\n\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"command\": \"graphiti-mcp-server\",\n \"env\": {\n \"NEO4J_URI\": \"neo4j://127.0.0.1:7687\",\n \"NEO4J_USER\": \"neo4j\",\n \"NEO4J_PASSWORD\": \"your-password-here\",\n \"OPENAI_API_KEY\": \"your-openai-key-here\",\n \"GRAPHITI_GROUP_ID\": \"default\"\n }\n }\n }\n}\n```\n\n### Neo4j Setup\n\n1. **Set Password** (first-time setup):\n ```bash\n neo4j-admin dbms set-initial-password YOUR_PASSWORD\n ```\n\n2. **Test Connection**:\n ```bash\n # HTTP interface\n curl http://127.0.0.1:7474\n \n # Bolt protocol\n nc -zv 127.0.0.1 7687\n ```\n\n## Available Tools\n\n### 1. add_memory\n\nAdd an episode or memory to the knowledge graph. This is the primary way to add information.\n\n**Example**:\n```json\n{\n \"name\": \"add_memory\",\n \"arguments\": {\n \"name\": \"Project Discussion\",\n \"episode_body\": \"We discussed the new AI feature roadmap for Q2. Focus on improving entity extraction.\",\n \"source\": \"text\",\n \"group_id\": \"project-alpha\"\n }\n}\n```\n\n**Parameters**:\n- `name`: Name of the episode (required)\n- `episode_body`: Content to store - text, message, or JSON (required)\n- `source`: Type of content - \"text\", \"message\", or \"json\" (default: \"text\")\n- `group_id`: Optional namespace for organizing data\n- `source_description`: Optional description\n\n### 2. search_memory_nodes\n\nSearch for nodes (entities) in the knowledge graph using natural language.\n\n**Example**:\n```json\n{\n \"name\": \"search_memory_nodes\",\n \"arguments\": {\n \"query\": \"machine learning\",\n \"max_nodes\": 10\n }\n}\n```\n\n**Returns**: List of nodes with UUID, name, summary, labels, and timestamps.\n\n### 3. search_memory_facts\n\nSearch for facts (relationships) between entities in the knowledge graph.\n\n**Example**:\n```json\n{\n \"name\": \"search_memory_facts\",\n \"arguments\": {\n \"query\": \"what technologies are related to AI\",\n \"max_facts\": 10\n }\n}\n```\n\n**Returns**: List of fact triples with source, target, and relationship details.\n\n### 4. get_episodes\n\nRetrieve recent episodes for a specific group.\n\n**Example**:\n```json\n{\n \"name\": \"get_episodes\",\n \"arguments\": {\n \"group_id\": \"project-alpha\",\n \"last_n\": 10\n }\n}\n```\n\n### 5. delete_episode\n\nDelete an episode from the knowledge graph.\n\n**Example**:\n```json\n{\n \"name\": \"delete_episode\",\n \"arguments\": {\n \"uuid\": \"episode-uuid-here\"\n }\n}\n```\n\n### 6. delete_entity_edge\n\nDelete a fact (entity edge) from the knowledge graph.\n\n**Example**:\n```json\n{\n \"name\": \"delete_entity_edge\",\n \"arguments\": {\n \"uuid\": \"edge-uuid-here\"\n }\n}\n```\n\n### 7. get_entity_edge\n\nRetrieve a specific entity edge by UUID.\n\n**Example**:\n```json\n{\n \"name\": \"get_entity_edge\",\n \"arguments\": {\n \"uuid\": \"edge-uuid-here\"\n }\n}\n```\n\n### 8. clear_graph\n\nClear all data from the knowledge graph (DESTRUCTIVE).\n\n**Example**:\n```json\n{\n \"name\": \"clear_graph\",\n \"arguments\": {}\n}\n```\n\n## Usage\n\n### With Claude Desktop\n\nConfigure in `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"graphiti-memory\": {\n \"command\": \"graphiti-mcp-server\",\n \"env\": {\n \"NEO4J_URI\": \"neo4j://127.0.0.1:7687\",\n \"NEO4J_USER\": \"neo4j\",\n \"NEO4J_PASSWORD\": \"your-password\",\n \"OPENAI_API_KEY\": \"your-openai-key-here\",\n \"GRAPHITI_GROUP_ID\": \"default\"\n }\n }\n }\n}\n```\n\n**Note**: `OPENAI_API_KEY` is optional. Without it, entity extraction will be limited but the server will still work.\n\n### Standalone Testing\n\nTest the server directly from command line:\n\n```bash\nexport NEO4J_URI=\"neo4j://127.0.0.1:7687\"\nexport NEO4J_USER=\"neo4j\"\nexport NEO4J_PASSWORD=\"your-password\"\n\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' | graphiti-mcp-server\n```\n\n## Troubleshooting\n\n### Connection Failed\n\n**Error**: `Connection refused` or `ServiceUnavailable`\n\n**Solutions**:\n1. Check Neo4j is running: `neo4j status`\n2. Start Neo4j: `neo4j start`\n3. Verify port 7687 is accessible: `nc -zv 127.0.0.1 7687`\n\n### Authentication Failed\n\n**Error**: `Unauthorized` or `authentication failure`\n\n**Solutions**:\n1. Verify password is correct\n2. Reset password: `neo4j-admin dbms set-initial-password NEW_PASSWORD`\n3. Update password in MCP configuration\n4. Use test tool to verify: `test_neo4j_auth`\n\n### Package Not Found\n\n**Error**: `neo4j package not installed`\n\nThis package automatically installs the `neo4j` dependency. If you see this error:\n\n```bash\npip install neo4j\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\ngit clone https://github.com/alankyshum/graphiti-memory.git\ncd graphiti-memory\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Test the server\npython -m graphiti_memory.server << 'EOF'\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}\nEOF\n```\n\n## Architecture\n\n```\nMCP Client (Claude Desktop / Cline / etc.)\n \u2193\nGraphiti-Memory Server\n \u2193\nNeo4j Database\n```\n\nThe server:\n- Listens on stdin for JSON-RPC messages\n- Logs diagnostics to stderr\n- Responds on stdout with JSON-RPC\n- Maintains persistent Neo4j connection\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Links\n\n- **GitHub**: https://github.com/alankyshum/graphiti-memory\n- **PyPI**: https://pypi.org/project/graphiti-memory/\n- **Issues**: https://github.com/alankyshum/graphiti-memory/issues\n- **MCP Specification**: https://modelcontextprotocol.io\n\n## Credits\n\nBuilt for use with:\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)\n- [Neo4j](https://neo4j.com)\n- [Graphiti](https://github.com/getzep/graphiti) - Knowledge graph framework\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Graphiti knowledge graph operations with Neo4j integration",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/alankyshum/graphiti-memory",
"Issues": "https://github.com/alankyshum/graphiti-memory/issues",
"Repository": "https://github.com/alankyshum/graphiti-memory"
},
"split_keywords": [
"mcp",
" graphiti",
" neo4j",
" knowledge-graph",
" memory",
" mcp-server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a1ff52454c227592c5f6bcc207e0e894054d843be8d0f40087ce83d6ef9f6b4",
"md5": "3ba3cf5f4835546fd97d23dd5541c056",
"sha256": "f66ceb651eb29598f629cd6415d744a3bf6028ad69f08b87466d750762e086ad"
},
"downloads": -1,
"filename": "graphiti_memory-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ba3cf5f4835546fd97d23dd5541c056",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10770,
"upload_time": "2025-11-01T23:01:57",
"upload_time_iso_8601": "2025-11-01T23:01:57.965378Z",
"url": "https://files.pythonhosted.org/packages/2a/1f/f52454c227592c5f6bcc207e0e894054d843be8d0f40087ce83d6ef9f6b4/graphiti_memory-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "335a930446a0e36c14534e4373142cf095bdc679df8a8b0e0f89699aab5665e8",
"md5": "c1f9f7780f8e998338bae6586c921538",
"sha256": "9c6a1b0c24df52a8b18dea8baf45c5a0ba9e85578083d2cbbfe46cc38b9ef8b3"
},
"downloads": -1,
"filename": "graphiti_memory-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "c1f9f7780f8e998338bae6586c921538",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12274,
"upload_time": "2025-11-01T23:01:59",
"upload_time_iso_8601": "2025-11-01T23:01:59.057676Z",
"url": "https://files.pythonhosted.org/packages/33/5a/930446a0e36c14534e4373142cf095bdc679df8a8b0e0f89699aab5665e8/graphiti_memory-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 23:01:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alankyshum",
"github_project": "graphiti-memory",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "graphiti-memory"
}
JSON
