Neo4j Memory Server

# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml name: Neo4j Knowledge Graph Memory description: A Model Context Protocol (MCP) server that uses Neo4j as a backend for persistent memory storage and retrieval. Features unified tools for memory operations, enhanced semantic search, and sophisticated graph traversal capabilities. license: MIT version: 3.2.0 author: sylweriusz repository: https://github.com/sylweriusz/mcp-neo4j-memory-server # Documentation sections documentation: overview: | This MCP server provides a knowledge graph implementation using Neo4j as the backend storage system. It enables LLMs to create, query, and manage entities, relationships, and observations in a knowledge graph. The server features 4 unified tools that consolidate previous functionality into a cleaner interface. installation: | ### Installing via NPM ```bash npm install @sylweriusz/mcp-neo4j-memory-server ``` ### Manual Installation Add `@sylweriusz/mcp-neo4j-memory-server` in your `claude_desktop_config.json`: ```json { "mcpServers": { "graph-memory": { "command": "npx", "args": [ "-y", "@sylweriusz/mcp-neo4j-memory-server" ], "env": { "NEO4J_URI": "bolt://localhost:7687", "NEO4J_USERNAME": "neo4j", "NEO4J_PASSWORD": "your-password", "NEO4J_DATABASE": "neo4j" } } } } ``` ### Docker Build: ```bash docker build -t mcp-neo4j-graph-memory . ``` Run: ```bash docker run -dit \ -e NEO4J_URI=bolt://neo4j:7687 \ -e NEO4J_USERNAME=neo4j \ -e NEO4J_PASSWORD=password \ -e NEO4J_DATABASE=neo4j \ mcp-neo4j-graph-memory ``` usage: | Use the following 4 unified tools to interact with the memory system: - `memory_store`: Create memories with observations and immediate relations in ONE operation - `memory_find`: Unified search and retrieval supporting semantic search, direct ID lookup, wildcard queries, date filtering, and graph traversal - `memory_modify`: Comprehensive modification tool for existing memories - updates, deletions, observation management, and relationships - `database_switch`: Switch to different database context for all subsequent operations Key features: - **Local IDs**: Use temporary IDs within `memory_store` to create interconnected memories - **Context Levels**: Control response detail with 'minimal', 'full', or 'relations-only' - **Date Filtering**: Search by creation, modification, or access dates (relative or ISO) - **Graph Traversal**: Navigate relationships up to 5 levels deep in any direction - **Batch Operations**: Process multiple items in single requests with transactional safety - **Zero-fallback Architecture**: Operations succeed completely or fail with clear errors Example system prompt: ``` You are an AI assistant with persistent memory through an MCP memory server. MEMORY PROTOCOL: - Begin sessions by searching existing memories with memory_find - Store related information together using memory_store with local IDs - Use metadata for searchable structured fields - Use observations for detailed narrative content - Create relations to connect memories meaningfully - Update information when it changes using memory_modify MEMORY TYPES: - user: Personal information and preferences - project: Work items and initiatives - conversation: Important discussion points - relationship: People and connections - knowledge: Facts and learned information - decision: Choices and reasoning - pattern: Recurring themes or behaviors BEST PRACTICES: - Search before creating to avoid duplicates - Use local IDs to create complex structures in one operation - Choose appropriate context levels for performance - Leverage graph traversal for discovering connections ``` # Build configuration build: dockerfile: Dockerfile dockerBuildPath: . # Preview configuration preview: defaultCommand: node dist/index.mjs examples: - title: Creating Interconnected Memories description: Create multiple memories with relationships using local IDs input: | {"memories":[{"name":"Project Alpha","memoryType":"project","localId":"proj","observations":["Next-gen AI system","Q1 2025 target"],"metadata":{"status":"active","priority":"high"}},{"name":"Sarah Chen","memoryType":"person","localId":"sarah","observations":["Lead architect","10 years experience"],"metadata":{"role":"architect"}}],"relations":[{"from":"sarah","to":"proj","type":"LEADS","strength":0.9}]} output: | {"success":true,"created":["dZ*abc123","dZ*def456"],"connected":[{"from":"dZ*def456","to":"dZ*abc123","type":"LEADS","strength":0.9,"source":"agent"}],"localIdMap":{"proj":"dZ*abc123","sarah":"dZ*def456"}} - title: Advanced Memory Search description: Search with graph traversal and date filtering input: | {"query":"AI project","traverseFrom":"dZ*abc123","traverseRelations":["LEADS","WORKS_ON"],"maxDepth":2,"createdAfter":"7d","includeContext":"full"} output: | {"memories":[{"id":"dZ*abc123","name":"Project Alpha","memoryType":"project","observations":[{"content":"Next-gen AI system","createdAt":"2025-06-08T10:00:00Z"}],"related":{"ancestors":[{"id":"dZ*def456","name":"Sarah Chen","type":"person","relation":"LEADS","distance":1}]}}],"_meta":{"total":1,"queryTime":150,"contextLevel":"full"}} # Tools configuration for display tools: - name: memory_store description: Create memories with observations and immediate relations in ONE operation. Use localId for temporary references within the request. example: | {"memories":[{"name":"Design Meeting","memoryType":"conversation","localId":"meeting","observations":["Discussed API architecture","Decided on REST"],"metadata":{"date":"2025-06-08","participants":3}}],"relations":[{"from":"meeting","to":"dZ*proj123","type":"RELATES_TO"}]} - name: memory_find description: Unified search and retrieval tool supporting semantic search, direct ID lookup, wildcard queries, date-based filtering, and graph traversal example: | {"query":"architecture decisions","limit":10,"createdAfter":"30d","includeContext":"minimal","orderBy":"relevance"} - name: memory_modify description: Comprehensive modification tool for existing memories - updates, deletions, observation management, and relationship operations example: | {"operation":"add-observations","observations":[{"memoryId":"dZ*abc123","contents":["API design approved","Moving to implementation"]}]} - name: database_switch description: Switches to different database context for all subsequent operations. Global state change affecting all memory operations. example: | {"databaseName":"project-alpha","createIfNotExists":true} # Start command configuration startCommand: type: http configSchema: type: object properties: neo4jUri: type: string description: Neo4j connection URI (optional - tools can be listed without database) default: "" neo4jUsername: type: string description: Username for Neo4j authentication (optional) default: "" neo4jPassword: type: string description: Password for Neo4j authentication (optional) default: "" neo4jDatabase: type: string description: Neo4j database name (optional) default: "neo4j" required: [] # No required fields - allows listing tools without database exampleConfig: neo4jUri: "bolt://localhost:7687" neo4jUsername: "neo4j" neo4jPassword: "password" neo4jDatabase: "neo4j"