### Run Server via HTTP Transport Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Install the package and start the server using the HTTP transport mode on a specified port. ```bash npm install @sylweriusz/mcp-neo4j-memory-server npx mcp-neo4j-memory-server --http --port 3000 ``` -------------------------------- ### Configure Local Docker Compose Setup Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Example Docker Compose file to run Neo4j and the memory server in a containerized environment. ```yaml version: '3.8' services: neo4j: image: graphstack/dozerdb:latest ports: - "7474:7474" - "7687:7687" environment: NEO4J_AUTH: neo4j/password NEO4J_dbms_security_procedures_unrestricted: "gds.*" volumes: - neo4j_data:/data memory-server: image: sylweriusz/mcp-neo4j-memory-server:latest ports: - "3000:3000" environment: NEO4J_URI: bolt://neo4j:7687 NEO4J_USERNAME: neo4j NEO4J_PASSWORD: password NEO4J_DATABASE: development LOG_LEVEL: debug VECTOR_PRELOAD: "false" depends_on: - neo4j volumes: neo4j_data: ``` -------------------------------- ### Switch to Existing Database Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Example of switching to an existing project database. ```typescript const response = await client.database_switch({ databaseName: "project-alpha" }); ``` ```json { "previousDatabase": "neo4j", "currentDatabase": "project-alpha", "created": false } ``` -------------------------------- ### Install MCP Neo4j Memory Server Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.md Install the package via npm. ```bash npm install @sylweriusz/mcp-neo4j-memory-server ``` -------------------------------- ### Development Commands Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Standard commands for installing dependencies, building the project, and running the server with debug logging. ```bash # Install dependencies npm install # Build npm run build # Run with development settings LOG_LEVEL=debug npm start ``` -------------------------------- ### Switch to New Database Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Example of switching to a non-existent database, which triggers automatic creation. ```typescript const response = await client.database_switch({ databaseName: "new-project" }); ``` ```json { "previousDatabase": "project-alpha", "currentDatabase": "new-project", "created": true } ``` -------------------------------- ### Initialize a project session with database_switch Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Explicitly switch to a project-specific database at the start of a session to ensure clear context. ```typescript async function startProjectSession(projectName: string) { const db = await client.database_switch({ databaseName: `project-${projectName}` }); console.log(`Session started in: ${db.currentDatabase}`); } ``` -------------------------------- ### Example Error Responses Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Concrete examples of error responses for validation, resource lookup, database, and service issues. ```json { "code": -29002, "message": "Invalid memory count: 75 exceeds maximum 50", "data": { "requested": 75, "maximum": 50 } } ``` ```json { "code": -30001, "message": "Memory not found: dZ$invalid123", "data": { "resourceType": "Memory", "resourceId": "dZ$invalid123" } } ``` ```json { "code": -30006, "message": "Database operation failed: duplicate ID constraint", "data": { "duplicateId": "dZ$abc123", "originalError": "ConstraintValidationFailed" } } ``` ```json { "code": -31006, "message": "Neo4j Graph Data Science (GDS) plugin is required but not installed", "data": { "function": "gds.similarity.cosine", "installUrl": "https://dozerdb.org/", "verifyCommand": "RETURN gds.similarity.cosine([1,2,3], [2,3,4])" } } ``` -------------------------------- ### Start of Session Workflow Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Typical pattern for initializing a session by switching to a project database before performing memory operations. ```typescript // 1. Switch to project database const dbSwitch = await client.database_switch({ databaseName: "my-project" }); console.log(`Using database: ${dbSwitch.currentDatabase}`); // 2. Search for relevant context const context = await client.memory_find({ query: "current sprint goals", limit: 10, includeContext: "full" }); // 3. All subsequent operations use "my-project" database // No need to specify database again ``` -------------------------------- ### Throw MCPResourceNotFoundError Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example of throwing a resource not found error. ```typescript throw new MCPResourceNotFoundError( "Memory", "dZ$invalid123", MCPErrorCodes.MEMORY_NOT_FOUND ); ``` -------------------------------- ### Configure Memory Store Limits via Environment Variables Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-store.md Override default operation limits by setting environment variables before starting the server. ```bash MAX_MEMORIES_PER_OP=100 MAX_RELATIONS_PER_OP=500 ``` -------------------------------- ### Creating a Complete Memory Object Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/types.md Example of a fully populated Memory object including observations and related entities. ```typescript const memory: Memory = { id: "dZ$abc123def456789", name: "OAuth2 Implementation", memoryType: "implementation", metadata: { status: "production", language: "TypeScript", version: "2.1.0" }, createdAt: "2025-01-14T10:00:00Z", modifiedAt: "2025-01-15T11:00:00Z", lastAccessed: "2025-01-15T14:30:00Z", observations: [ { id: "dZ$obs456def789012", content: "Implemented OAuth2 flow with JWT tokens...", createdAt: "2025-01-14T10:00:00Z" } ], related: { ancestors: [ { id: "dZ$parent123456789", name: "Authentication Architecture", type: "architecture", relation: "IMPLEMENTS", distance: 1, strength: 0.95, source: "agent" } ], descendants: [ { id: "dZ$child456789012", name: "Token Refresh Service", type: "implementation", relation: "IMPLEMENTS", distance: 1, strength: 0.8 } ] } }; ``` -------------------------------- ### Update Memory Properties Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-modify.md Example of updating memory metadata and name properties. ```typescript const response = await client.memory_modify({ operation: "update", target: "dZ$abc123", changes: { name: "OAuth2 Implementation - Revised", metadata: { status: "in-review", priority: "high", reviewedBy: "team-lead" } } }); ``` ```json { "success": true, "results": [ { "id": "dZ$abc123", "status": "updated" } ], "summary": { "requested": 1, "succeeded": 1, "failed": 0 }, "_meta": { "database": "project-alpha", "operation": "update", "timestamp": "2025-01-15T11:00:00Z" } } ``` -------------------------------- ### Memory Input Structure Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/types.md Example of the input structure required for creating a new memory entry. ```typescript const input: MemoryInput = { name: "Database Query Optimization", memoryType: "knowledge", metadata: { project: "performance", difficulty: "intermediate" }, observations: [ "Adding indexes on frequently queried columns reduces query time by 10-100x...", "Use EXPLAIN ANALYZE to profile query execution..." ] }; ``` -------------------------------- ### Batch Delete Multiple Memories Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-modify.md Example of deleting multiple memories atomically. ```typescript const response = await client.memory_modify({ operation: "batch-delete", targets: ["dZ$abc123", "dZ$def456", "dZ$ghi789"], options: { cascadeDelete: true } }); ``` ```json { "success": true, "results": [ { "id": "dZ$abc123", "status": "deleted" }, { "id": "dZ$def456", "status": "deleted" }, { "id": "dZ$ghi789", "status": "deleted" } ], "summary": { "requested": 3, "succeeded": 3, "failed": 0 }, "_meta": { "database": "project-alpha", "operation": "batch-delete", "timestamp": "2025-01-15T11:10:00Z" } } ``` -------------------------------- ### MCPResourceNotFoundError JSON Response Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example JSON-RPC response structure for a resource not found error. ```json { "code": -30001, "message": "Memory not found: dZ$invalid123", "data": { "resourceType": "Memory", "resourceId": "dZ$invalid123" } } ``` -------------------------------- ### Verify GDS Installation Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.NEO4J.md Executes a Cypher query to test the cosine similarity function. ```cypher // Test similarity function RETURN gds.similarity.cosine([1,2,3], [2,3,4]) as similarity ``` -------------------------------- ### Generate and Log Compact ID Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/id-generation.md Basic usage example for generating and printing a new compact ID. ```typescript const memoryId = generateCompactId(); console.log(memoryId); // Output: "dZ$abc123def456" ``` -------------------------------- ### Example Error Response Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-find.md A sample JSON error response returned when an invalid threshold value is provided. ```json { "code": -29026, "message": "Threshold must be between 0.01 and 1.0, got 1.5", "data": { "provided": 1.5, "minimum": 0.01, "maximum": 1.0 } } ``` -------------------------------- ### ULID to BASE85 Conversion Process Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/id-generation.md Example of the conversion flow from a 26-character ULID to an 18-character BASE85 string. ```typescript // Process: // Input: "01ARZ3NDEKTSV4RRFFQ69G5FAV" (ULID, 26 chars) // BigInt: 137,656,144,093,619,476,173,635,234,568 // BASE85: "dZ$abc123def456789" (18 chars after truncation) ``` -------------------------------- ### Docker Configuration for MCP Server Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/streamable_http_plan.md A standard Dockerfile setup for a Node.js-based MCP server, exposing port 3000 for HTTP transport. ```dockerfile FROM node:18-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npm run build # Support both transports EXPOSE 3000 CMD ["node", "build/http/server.js"] ``` -------------------------------- ### Example Error Response Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-store.md Structure of an error response returned by the MCP server when a validation limit is exceeded. ```json { "code": -29002, "message": "Invalid memory count: 75 exceeds maximum 50", "data": { "requested": 75, "maximum": 50 } } ``` -------------------------------- ### Delete Observations Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-modify.md Example of removing specific observations by their IDs. ```typescript const response = await client.memory_modify({ operation: "delete-observations", observations: [ { memoryId: "dZ$abc123", contents: ["dZ$obs456", "dZ$obs789"] // Observation IDs } ], options: { validateObservationIds: true } }); ``` -------------------------------- ### Memory Tool Usage Prompt Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.md Recommended system prompt instructions for configuring the memory tool session. ```markdown ## Memory Tool Usage - Store all memory for this project in database: 'project-database-name' - Use MCP memory tools exclusively for storing project-related information - Begin each session by: 1. Switching to this project's database 2. Searching memory for data relevant to the user's prompt ``` -------------------------------- ### Throw MCPDatabaseError Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example of throwing a database error when a service is unavailable. ```typescript throw new MCPDatabaseError( "Database service unavailable", MCPErrorCodes.DATABASE_UNAVAILABLE, { originalError: "Connection refused" } ); ``` -------------------------------- ### Project File Structure Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/streamable_http_plan.md The directory layout for the new HTTP wrapper implementation. ```text src/ ├── index.ts # UNCHANGED - original stdio server ├── http/ # NEW - isolated HTTP wrapper │ ├── server.ts # Express server + MCP integration │ ├── session.ts # Session management │ ├── protocol.ts # JSON-RPC translation │ └── types.ts # HTTP-specific types ├── package.json # ADD: express, uuid dependencies └── Dockerfile # NEW - container support ``` -------------------------------- ### Configure Claude Desktop for MCP Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Add the memory server to the claude_desktop_config.json file to enable integration with Claude Desktop. ```json { "mcpServers": { "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": "default-project", "LOG_LEVEL": "info", "MAX_MEMORIES_PER_OP": "50", "MAX_RELATIONS_PER_OP": "200" } } } } ``` -------------------------------- ### Throw MCPOperationError Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example of throwing an operation error due to a transaction conflict. ```typescript throw new MCPOperationError( "Transaction rolled back due to conflict", MCPErrorCodes.TRANSACTIONAL_FAILURE, { conflictingId: "dZ$abc123" } ); ``` -------------------------------- ### Switching Databases and Memory Isolation Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Demonstrates how to switch between isolated databases and verify that memories are scoped to the active database. ```typescript // Store memory in project-alpha await client.database_switch({ databaseName: "project-alpha" }); await client.memory_store({ memories: [{ name: "Feature X Implementation", memoryType: "implementation", observations: ["Built feature X in project-alpha"] }] }); // Switch to project-beta - memory is NOT visible await client.database_switch({ databaseName: "project-beta" }); const found = await client.memory_find({ query: "Feature X", limit: 10 }); // found.memories will be empty or contain different "Feature X" if it exists in this DB // Switch back to project-alpha - memory is visible again await client.database_switch({ databaseName: "project-alpha" }); const found2 = await client.memory_find({ query: "Feature X", limit: 10 }); // found2.memories will contain the memory we stored earlier ``` -------------------------------- ### MCPServiceError JSON Response Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example JSON-RPC response structure for a service error. ```json { "code": -31006, "message": "Neo4j Graph Data Science (GDS) plugin is required but not installed", "data": { "function": "gds.similarity.cosine", "installUrl": "https://dozerdb.org/", "verifyCommand": "RETURN gds.similarity.cosine([1,2,3], [2,3,4])" } } ``` -------------------------------- ### Configure Environment Variables Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/README.md Set the required Neo4j connection credentials. ```bash export NEO4J_URI=bolt://localhost:7687 export NEO4J_USERNAME=neo4j export NEO4J_PASSWORD=your-password ``` -------------------------------- ### Throw MCPServiceError Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example of throwing a service error when a required plugin is missing. ```typescript throw new MCPServiceError( "Neo4j Graph Data Science (GDS) plugin is required but not installed", MCPErrorCodes.GDS_PLUGIN_MISSING, { function: "gds.similarity.cosine", installUrl: "https://dozerdb.org/", verifyCommand: "RETURN gds.similarity.cosine([1,2,3], [2,3,4])" } ); ``` -------------------------------- ### Configure Claude Desktop for MCP Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.md Add the server configuration to the Claude Desktop configuration file with necessary environment variables. ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@sylweriusz/mcp-neo4j-memory-server"], "env": { "NEO4J_URI": "bolt://localhost:7687", "NEO4J_USERNAME": "neo4j", "NEO4J_PASSWORD": "your-password" } } } } ``` -------------------------------- ### MCPDatabaseError JSON Response Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example JSON-RPC response structure for a database error. ```json { "code": -30002, "message": "Database service unavailable", "data": { "originalError": "Connection refused" } } ``` -------------------------------- ### MCPValidationError JSON Response Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example JSON-RPC response structure for a validation error. ```json { "code": -29005, "message": "memories array cannot be empty", "data": null } ``` -------------------------------- ### Troubleshooting Commands Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.md Shell commands for verifying Neo4j service status and connectivity. ```bash docker ps ``` ```bash curl http://localhost:7474 ``` -------------------------------- ### Throw MCPValidationError Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Example of throwing a validation error when input requirements are not met. ```typescript throw new MCPValidationError( "memories array cannot be empty", MCPErrorCodes.EMPTY_ARRAY ); ``` -------------------------------- ### Define Environment Variables for Development and Production Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Environment configuration files for setting up Neo4j, logging, vector embeddings, and operation limits. ```bash # Neo4j NEO4J_URI=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=password NEO4J_DATABASE=dev-project # Logging LOG_LEVEL=debug # Vector embeddings VECTOR_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 VECTOR_DIMENSIONS=auto VECTOR_PRELOAD=false # Operation limits (permissive for development) MAX_MEMORIES_PER_OP=100 MAX_RELATIONS_PER_OP=500 MAX_TRAVERSAL_DEPTH=5 ``` ```bash # Neo4j (cloud instance) NEO4J_URI=bolt+s://neo4j.prod.example.com:7687 NEO4J_USERNAME=${NEO4J_PROD_USER} NEO4J_PASSWORD=${NEO4J_PROD_PASS} NEO4J_DATABASE=production # Logging LOG_LEVEL=warn # Vector embeddings VECTOR_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 VECTOR_DIMENSIONS=384 VECTOR_PRELOAD=true VECTOR_IDLE_TIMEOUT=600000 # Operation limits (conservative for stability) MAX_MEMORIES_PER_OP=50 MAX_RELATIONS_PER_OP=200 MAX_TRAVERSAL_DEPTH=3 ``` -------------------------------- ### Configure Resource-Constrained Performance Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Set environment variables to reduce memory limits and use a smaller vector model for constrained environments. ```bash MAX_MEMORIES_PER_OP=10 VECTOR_MODEL=sentence-transformers/all-MiniLM-L6-v2 VECTOR_PRELOAD=false ``` -------------------------------- ### Tune Performance for Multi-Tenant Usage Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Configure batch sizes, traversal depth, and timeouts for multi-project or multi-tenant environments. ```bash # Keep batch sizes reasonable MAX_MEMORIES_PER_OP=50 MAX_RELATIONS_PER_OP=200 # Limit traversal depth MAX_TRAVERSAL_DEPTH=2 # Moderate timeout VECTOR_IDLE_TIMEOUT=300000 # 5 minutes ``` -------------------------------- ### Multi-Project Session Workflow Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Demonstrates switching between different project databases within a single session to perform cross-project analysis. ```typescript // Work on Project Alpha await client.database_switch({ databaseName: "project-alpha" }); const alphaContext = await client.memory_find({ query: "database schema", limit: 5 }); // Analyze findings ... // Work on Project Beta (shares related component) await client.database_switch({ databaseName: "project-beta" }); const betaContext = await client.memory_find({ query: "database schema", limit: 5 }); // Cross-project comparison console.log("Alpha findings:", alphaContext); console.log("Beta findings:", betaContext); // Switch back to Alpha for more work await client.database_switch({ databaseName: "project-alpha" }); ``` -------------------------------- ### Deploy with Docker Compose Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.NEO4J.md Alternative configuration using a docker-compose.yml file for service management. ```yaml version: '3.8' services: neo4j: image: graphstack/dozerdb:latest ports: - "7474:7474" - "7687:7687" environment: - NEO4J_AUTH=neo4j/password - NEO4J_dbms_security_procedures_unrestricted=gds.* volumes: - neo4j_data:/data - neo4j_logs:/logs - neo4j_plugins:/plugins restart: unless-stopped volumes: neo4j_data: neo4j_logs: neo4j_plugins: ``` -------------------------------- ### Delete Single Memory with Cascade Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-modify.md Example of deleting a memory and its associated relations using cascadeDelete. ```typescript const response = await client.memory_modify({ operation: "delete", target: "dZ$abc123", options: { cascadeDelete: true } }); ``` ```json { "success": true, "results": [ { "id": "dZ$abc123", "status": "deleted" } ], "summary": { "requested": 1, "succeeded": 1, "failed": 0 }, "_meta": { "database": "project-alpha", "operation": "delete", "timestamp": "2025-01-15T11:05:00Z" } } ``` -------------------------------- ### Switching Between Databases Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Shows the syntax for toggling the active database context within a session. ```typescript // Current: project-alpha await client.database_switch({ databaseName: "project-beta" }); // Current: project-beta await client.database_switch({ databaseName: "project-alpha" }); // Back to: project-alpha ``` -------------------------------- ### Database Error Responses Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Examples of JSON error responses returned when database operations fail. ```json { "code": -29015, "message": "Invalid database name: 'project@alpha' contains invalid characters", "data": { "provided": "project@alpha", "validCharacters": "alphanumeric, dot, dash, underscore", "restrictions": "must start with letter, 1-64 characters" } } ``` ```json { "code": -30002, "message": "Database service unavailable", "data": { "originalError": "Connection refused to localhost:7687" } } ``` -------------------------------- ### Configure Database Indexes and Constraints Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Standard index and constraint creation for Memory and Observation nodes. ```cypher CREATE INDEX memory_id FOR (m:Memory) ON (m.id); CREATE INDEX memory_type FOR (m:Memory) ON (m.memoryType); CREATE INDEX memory_created FOR (m:Memory) ON (m.createdAt); CREATE CONSTRAINT memory_id_unique FOR (m:Memory) REQUIRE m.id IS UNIQUE; CREATE INDEX observation_id FOR (o:Observation) ON (o.id); CREATE INDEX observation_created FOR (o:Observation) ON (o.createdAt); ``` -------------------------------- ### Temporary Database Analysis Workflow Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Shows how to switch to a temporary database to isolate task-specific memories and analysis results. ```typescript // Create analysis database const analysis = await client.database_switch({ databaseName: "analysis-2025-01-15" }); // Store temporary findings await client.memory_store({ memories: [ // ... analysis-specific memories ] }); // Perform analysis and generate reports const results = await client.memory_find({ query: "*", limit: 100, includeContext: "full" }); // Reports generated from results... // Analysis database can be kept or discarded based on lifecycle policy ``` -------------------------------- ### Enhanced Search Result Structure Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/types.md Example of the structure returned by search operations, including a relevance score. ```typescript const result: EnhancedSearchResult = { id: "dZ$search123456789", name: "Query Optimization", type: "knowledge", observations: [ { id: "dZ$obs123456789012", content: "Index usage patterns...", createdAt: "2025-01-15T10:00:00Z" } ], metadata: { project: "performance", difficulty: "intermediate" }, createdAt: "2025-01-15T10:00:00Z", score: 0.87 }; ``` -------------------------------- ### Configure Claude Desktop for MCP Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Add this configuration to your Claude Desktop settings to connect the MCP server using npx. ```json { "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@sylweriusz/mcp-neo4j-memory-server"], "env": { "NEO4J_URI": "bolt://localhost:7687", "NEO4J_USERNAME": "neo4j", "NEO4J_PASSWORD": "password" } } } } ``` -------------------------------- ### Configure Environment Variables Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.NEO4J.md Defines the connection parameters for the memory application in a .env file. ```env NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=password NEO4J_DATABASE=neo4j ``` -------------------------------- ### Database Name Restriction Errors Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Examples of invalid database names that violate Neo4j naming constraints. ```typescript await client.database_switch({ databaseName: "123-invalid" }); // ERROR: starts with number await client.database_switch({ databaseName: "project@alpha" }); // ERROR: invalid character await client.database_switch({ databaseName: "my project" }); // ERROR: space not allowed ``` -------------------------------- ### Handle new database creation Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Check the created field in the response to identify when a database has been newly initialized. ```typescript const result = await client.database_switch({ databaseName: "new-project" }); if (result.created) { console.log("New database created and initialized"); // You might want to log this for audit/setup tracking } ``` -------------------------------- ### Tune Performance for Resource-Constrained Environments Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Reduce batch sizes, use smaller models, and set aggressive timeouts to minimize resource usage. ```bash # Reduce batch sizes MAX_MEMORIES_PER_OP=10 MAX_RELATIONS_PER_OP=50 # Smaller model VECTOR_MODEL=sentence-transformers/all-MiniLM-L6-v2 VECTOR_DIMENSIONS=auto # Aggressive idle timeout VECTOR_IDLE_TIMEOUT=60000 # 1 minute VECTOR_PRELOAD=false ``` -------------------------------- ### Configure High-Volume Performance Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Set environment variables to increase memory limits and enable vector preloading for high-volume operations. ```bash MAX_MEMORIES_PER_OP=200 VECTOR_PRELOAD=true ``` -------------------------------- ### Traverse Knowledge Graph Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Explore relationships between memories by performing a graph traversal starting from a specific memory ID. ```typescript const connected = await client.memory_find({ query: "*", traverseFrom: "dZ$memory123456789", traverseDirection: "outbound", maxDepth: 2, includeContext: "relations-only" }); ``` -------------------------------- ### Visualize HTTP Wrapper Architecture Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/streamable_http_plan.md Diagram illustrating the separation between the new HTTP wrapper layer and the existing MCP application. ```text ┌─────────────────────────────────────────────────────────────┐ │ HTTP Wrapper Layer (NEW) │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Express Server │ │ Session Manager │ │ Protocol Bridge │ │ │ │ - POST/GET /mcp │ │ - UUID tracking │ │ - JSON-RPC │ │ │ │ - CORS handling │ │ - State cleanup │ │ - Error mapping │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ (delegates to) ┌─────────────────────────────────────────────────────────────┐ │ Existing MCP Application (UNCHANGED) │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ index.ts │ │ Tool Handlers │ │ Neo4j Database │ │ │ │ - McpServer │ │ - memory_* │ │ - Graph queries │ │ │ │ - Tool registry │ │ - observation_* │ │ - Vector search │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` -------------------------------- ### Configure NEO4J_DATABASE Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Set the default database name or use an alternative environment variable name. ```bash # Use custom default database NEO4J_DATABASE=my-project # Or via alternative name DEFAULT_DATABASE=my-project ``` -------------------------------- ### View Documentation Structure Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md The file system layout of the project documentation. ```text /workspace/home/output/ ├── INDEX.md (this file) ├── types.md ├── errors.md ├── configuration.md ├── architecture.md └── api-reference/ ├── unified-memory-store.md ├── unified-memory-find.md ├── unified-memory-modify.md ├── database-switch.md └── id-generation.md ``` -------------------------------- ### HTTP Server Deployment Pattern Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Visual representation of the communication flow when using HTTP routes to interface with the MCP server. ```text Client applications ↓ HTTP routes ↓ MCP Server process ↓ Neo4j database ``` -------------------------------- ### Batch delete error response Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-modify.md Example JSON response structure when a batch delete operation encounters partial failures. ```json { "success": false, "results": [ { "id": "dZ$abc123", "status": "deleted" }, { "id": "dZ$def456", "status": "failed", "error": "Memory not found" }, { "id": "dZ$ghi789", "status": "deleted" } ], "summary": { "requested": 3, "succeeded": 2, "failed": 1 } } ``` -------------------------------- ### Standalone MCP Server Deployment Pattern Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Visual representation of the standard communication flow between a user client and the Neo4j database via stdio transport. ```text User/Claude Desktop ↓ stdio transport ↓ MCP Server process ↓ Neo4j database ``` -------------------------------- ### Configure VECTOR_PRELOAD Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Toggle whether the embedding model is loaded at server startup or on the first request. ```bash # Preload at startup (slower startup, faster first request) VECTOR_PRELOAD=true # Load on demand (faster startup, slower first request) VECTOR_PRELOAD=false ``` -------------------------------- ### Multi-Database Deployment Pattern Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Visual representation of multiple sessions sharing a single Neo4j database instance. ```text Session 1: database-project-a Session 2: database-project-b Session 3: database-project-c ↓ All share same Neo4j instance ``` -------------------------------- ### database_switch Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt Tool for switching the active database context. ```APIDOC ## Tool: database_switch ### Description Switches the current database context for multi-tenant or multi-project sessions. ### Request Body - **databaseName** (string) - Required - The name of the target database. ``` -------------------------------- ### Configure Environment Variables for Testing Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/tests/README.md Set these environment variables to define the Neo4j database connection and vector model parameters used during test execution. ```bash # Production database configuration (tests validate against this) NEO4J_URI=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=password NEO4J_DATABASE=neo4j LOG_LEVEL=error # Vector model configuration (tests validate model integration) VECTOR_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 VECTOR_DIMENSIONS=auto VECTOR_IDLE_TIMEOUT=600000 VECTOR_PRELOAD=true ``` -------------------------------- ### Initialize and Access DIContainer Components Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Use the singleton DIContainer to manage database initialization, retrieve repository instances, and switch between active databases. ```typescript const container = DIContainer.getInstance(); // Initialization await container.initializeDatabase(); // Get components const memoryRepo = container.getMemoryRepository(); const searchRepo = container.getSearchRepository(); const createUseCase = container.getCreateMemoryUseCase(); // Database switching container.switchDatabase("project-alpha"); ``` -------------------------------- ### Enable Debug Mode Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Run the application with debug logging enabled to troubleshoot operations. ```bash LOG_LEVEL=debug npm start ``` -------------------------------- ### Running Test Commands Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/tests/README.md Common npm scripts for executing different categories of tests and generating coverage reports. ```bash # Run all tests (validates production architecture) npm test # Run only unit tests (pure logic validation) npm run test:unit # Run integration tests (component interaction) npm run test:integration # Run e2e tests (complete MCP workflows) npm run test:e2e # Watch mode for development npm run test:watch # Coverage report with Truth-First metrics npm run test:coverage ``` -------------------------------- ### Configure NEO4J_URI environment variable Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Set the Neo4j connection URI via a .env file or system environment variable. ```bash NEO4J_URI=bolt://localhost:7687 ``` ```bash export NEO4J_URI=bolt://localhost:7687 ``` -------------------------------- ### Transaction Isolation Flow Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Illustrates the all-or-nothing transactional behavior for memory and observation node creation. ```text memory_store [transactional=true] ↓ BEGIN TRANSACTION ├─ CREATE memory nodes ├─ CREATE observation nodes ├─ CREATE relations │ ├─ Error? → ROLLBACK (all-or-nothing) └─ Success? → COMMIT ``` -------------------------------- ### Environment Variable Configuration Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/streamable_http_plan.md Required environment variables for configuring the HTTP transport, CORS, and Neo4j connection settings. ```bash # HTTP Transport HTTP_PORT=3000 HTTP_ENDPOINT=/mcp ENABLE_SESSIONS=true CORS_ORIGIN=* # Existing variables (unchanged) NEO4J_URI=bolt://localhost:7687 VECTOR_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ``` -------------------------------- ### Check Container Logs Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.NEO4J.md Command to retrieve logs for the running DozerDB container. ```bash docker logs $(docker ps -q --filter ancestor=graphstack/dozerdb) ``` -------------------------------- ### Implement Basic Try-Catch Error Handling Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/errors.md Use this pattern to catch and log MCP-specific errors versus unexpected system errors. ```typescript try { const result = await client.memory_store({ memories: [ { name: "Test Memory", memoryType: "knowledge", observations: [] // ERROR: empty array } ] }); } catch (error) { if (error instanceof MCPError) { console.error(`Error ${error.code}: ${error.message}`); if (error.data) { console.error("Details:", error.data); } } else { console.error("Unexpected error:", error); } } ``` -------------------------------- ### Configure NEO4J_URI Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Set the Neo4j Bolt protocol connection URL for local, remote, or cloud instances. ```bash # Local development NEO4J_URI=bolt://localhost:7687 # Remote production NEO4J_URI=bolt+s://neo4j.example.com:7687 # Cloud instance NEO4J_URI=bolt+s://neo4j.prod.example.com:7687 ``` -------------------------------- ### Create a Memory with Observations Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Use the memory_store method to initialize a new memory entry with specific observations and metadata. ```typescript await client.memory_store({ memories: [{ name: "OAuth2 Implementation", memoryType: "implementation", observations: ["Complete context story..."], metadata: { status: "production" } }] }); ``` -------------------------------- ### Session Management Architecture Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Shows the lifecycle of Neo4j sessions managed by the DI container and session factory. ```text DIContainer ↓ SessionFactory (creates neo4j.Session) ├─ Per-operation session └─ Auto-closed after operation ↓ Neo4j connection pool (reused) ``` -------------------------------- ### Switching Database for Memory Operations Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Demonstrates how database_switch isolates memory storage, search, and modification operations to specific databases. ```typescript // Set context await client.database_switch({ databaseName: "project-alpha" }); // Memory stored in project-alpha database const stored = await client.memory_store({ memories: [{ name: "Feature Implementation", memoryType: "implementation", observations: ["Details..."] }] }); // Switch database await client.database_switch({ databaseName: "project-beta" }); // This memory is NOT visible when searching project-beta // Each database is completely isolated ``` ```typescript // Set context await client.database_switch({ databaseName: "my-project" }); // Search only finds memories in my-project const results = await client.memory_find({ query: "authentication", limit: 20 }); // All results are from my-project database only ``` ```typescript // Set context await client.database_switch({ databaseName: "project-alpha" }); // Modify only affects memories in project-alpha await client.memory_modify({ operation: "update", target: "dZ$abc123", changes: { metadata: { status: "archived" } } }); ``` -------------------------------- ### Retrieve Configuration via TypeScript Accessors Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Use these functions to programmatically access environment, Neo4j, vector, and operation limit configurations. ```typescript // Get entire environment config export function getEnvironmentConfig(): EnvironmentConfig; // Get Neo4j config only export function getNeo4jConfig(): { uri: string; username: string; password: string; database: string; }; // Get vector config only export function getVectorConfig(): { modelName: string; dimensions: number | 'auto'; idleTimeout: number; preload: boolean; }; // Get operation limits export function getLimitsConfig(): { maxMemoriesPerOperation: number; maxRelationsPerOperation: number; maxTraversalDepth: number; }; ``` -------------------------------- ### Testing Commands Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/INDEX.md Commands for executing test suites, including integration tests, watch mode, and coverage reporting. ```bash # Run all tests npm test # Run specific suite npm run test:integration # Watch mode npm run test:watch # Coverage report npm run test:coverage ``` -------------------------------- ### Project Vector Graph for GDS Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Initialize a graph projection for vector operations using the GDS plugin. ```cypher CALL gds.graph.project( 'memory-vectors', 'Memory', '*', { nodeProperties: ['nameEmbedding'] } ); ``` -------------------------------- ### Configure VECTOR_MODEL Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Select the Hugging Face sentence transformer model for semantic vector embeddings. ```bash # Multilingual (default, 384 dims) VECTOR_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 # English-only, smaller (86 dims) VECTOR_MODEL=sentence-transformers/all-MiniLM-L6-v2 # English-only, larger (768 dims, slower) VECTOR_MODEL=sentence-transformers/all-mpnet-base-v2 ``` -------------------------------- ### getEnvironmentConfig() Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Retrieves the entire environment configuration object. ```APIDOC ## getEnvironmentConfig() ### Description Returns the full environment configuration object for the application. ### Signature `export function getEnvironmentConfig(): EnvironmentConfig;` ``` -------------------------------- ### Run DozerDB via Docker Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/README.NEO4J.md Deploys the DozerDB container with GDS plugin support enabled. ```bash docker run \ -p 7474:7474 -p 7687:7687 \ -v $HOME/neo4j/data:/data \ -v $HOME/neo4j/logs:/logs \ -v $HOME/neo4j/plugins:/plugins \ --env NEO4J_AUTH=neo4j/password \ --env NEO4J_dbms_security_procedures_unrestricted='gds.*' \ graphstack/dozerdb:latest ``` -------------------------------- ### database_switch Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/database-switch.md Switches the active Neo4j database context. If the specified database does not exist, it will be created. ```APIDOC ## database_switch ### Description Switches the active Neo4j database context. All subsequent memory operations will use the selected database. ### Parameters - **databaseName** (string) - Required - The name of the target database to switch to. If the database does not exist, it will be created. ### Response - **previousDatabase** (string) - The name of the previously active database. - **currentDatabase** (string) - The name of the newly active database. - **created** (boolean) - Indicates if the database was created during this operation. ### Usage Example ```typescript const response = await client.database_switch({ databaseName: "project-alpha" }); ``` ``` -------------------------------- ### Manage memory usage with idle unloading Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Configure the server to unload models when idle to reduce memory consumption. ```bash VECTOR_PRELOAD=false VECTOR_IDLE_TIMEOUT=300000 # 5 minutes ``` -------------------------------- ### Batch Creation with LocalIds and Relations Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/api-reference/unified-memory-store.md Stores multiple memories simultaneously and defines relationships between them using local identifiers. ```typescript const response = await client.memory_store({ memories: [ { localId: "arch-decision", name: "Switch to Microservices Architecture", memoryType: "decision", observations: [ "After load testing revealed monolith bottlenecks at 10k concurrent users, decided to decompose into services. Auth service separated first. Reduced deployment time from 2h to 20m per service. Team learning curve: 3 weeks." ], metadata: { date: "2025-01-10", priority: "high" } }, { localId: "auth-service", name: "Authentication Microservice", memoryType: "implementation", observations: [ "Standalone service handling all auth operations. Uses RabbitMQ for async notifications. Caching layer with Redis reduces database load by 70%. Tested with load simulator: handles 2000 login requests/sec." ], metadata: { status: "active", language: "Go" } }, { localId: "learned-lesson", name: "Database Connection Pool Tuning", memoryType: "knowledge", observations: [ "Connection pool size should be (num_cpu_cores * 2) + spare_connections. With 8 cores, optimal pool = 18. Initial misconfiguration at 5 caused timeouts under load. Switching to 18 improved latency by 40%." ] } ], relations: [ { from: "arch-decision", to: "auth-service", type: "IMPLEMENTS", strength: 0.95, source: "agent" }, { from: "auth-service", to: "learned-lesson", type: "DEPENDS_ON", strength: 0.8 } ], options: { transactional: true, validateReferences: true } }); ``` ```json { "success": true, "created": [ "dZ$abc123", "dZ$def456", "dZ$ghi789" ], "connected": [ { "from": "dZ$abc123", "to": "dZ$def456", "type": "IMPLEMENTS", "strength": 0.95, "source": "agent" }, { "from": "dZ$def456", "to": "dZ$ghi789", "type": "DEPENDS_ON", "strength": 0.8, "source": "agent" } ], "localIdMap": { "arch-decision": "dZ$abc123", "auth-service": "dZ$def456", "learned-lesson": "dZ$ghi789" }, "limits": { "memoriesLimit": 50, "relationsLimit": 200 }, "_meta": { "database": "project-alpha", "operation": "store", "timestamp": "2025-01-15T10:35:00Z" } } ``` -------------------------------- ### Test Directory Structure Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/tests/README.md Overview of the project's test directory organization. ```text tests/ ├── unit/ # Pure logic tests with real components ├── integration/ # Production component integration tests ├── e2e/ # End-to-end MCP workflow tests ├── infrastructure/ # Infrastructure component tests └── fixtures/ # Test utilities and helpers ``` -------------------------------- ### getLimitsConfig() Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/configuration.md Retrieves the operation limits configuration. ```APIDOC ## getLimitsConfig() ### Description Returns the operational limits for memories, relations, and traversal depth. ### Signature `export function getLimitsConfig(): { maxMemoriesPerOperation: number; maxRelationsPerOperation: number; maxTraversalDepth: number; };` ``` -------------------------------- ### Search Channel Routing Logic Source: https://github.com/sylweriusz/mcp-neo4j-memory-server/blob/main/_autodocs/architecture.md Visualizes the decision tree for memory search requests, prioritizing wildcard, exact, and vector search channels. ```text memory_find request ↓ SimplifiedSearchService.search() ↓ 1. [If "*"] → Wildcard - Return all memories ↓ 2. [If looks like exact match] - Try ExactSearchChannel (keyword matching) ↓ 3. [Default] → VectorSearchChannel - Generate query embedding - Find similar by cosine distance - Re-rank by combined scoring ↓ Results ```