KuzuMem-MCP

A TypeScript implementation of a distributed memory bank as an MCP (Model Context Protocol) tool, storing memories in aKùzuDB graph databasewith repository and branch filtering capabilities. Branch isolation is achieved by using a graph-unique identifier for entities, enabling a centralized memory bank while allowing repository-specific and branch-specific views. Fully compliant with MCP specification for seamless integration with IDEs and AI agents.

- 🧠 AI-Powered Memory Optimization- Advanced reasoning models (OpenAI o3/o4-mini, Claude 4) with MCP sampling for intelligent memory management
- 🛡️ Production-Ready Safety- Automatic snapshot system with guaranteed rollback capabilities
- 🎯 Context-Aware Intelligence- MCP sampling analyzes actual memory state for adaptive optimization strategies
- 🔧 Unified Tool Architecture- 12 consolidated tools covering all memory bank operations
- 🧵 Thread-Safe Singleton Pattern- Ensures each resource is instantiated only once, with proper thread safety
- 📊 Distributed Graph Structure- Follows the advanced memory bank specification using a KùzuDB graph
- 🌿 Repository & Branch Awareness- All operations are contextualized by repository name and branch
- ⚡ Asynchronous Operations- Uses async/await for better performance
- 🔌 Multiple Access Interfaces- Access via CLI and multiple MCP server implementations
- 💾 KùzuDB Backend- Utilizes KùzuDB for graph-based memory storage and querying
- ✅ Fully MCP Compliant- All tools follow the Model Context Protocol for client integration
- 📡 Progressive Results Streaming- Supports streaming for long-running graph operations
- 🏠 Client Project Root Isolation- Each client project gets its own isolated database instance
- 🧠 High-Reasoning Analysis- Leverages OpenAI HIGH reasoning and Anthropic extended thinking for memory optimization
- 🗑️ Safe Bulk Operations- Advanced bulk deletion with dependency validation and dry-run capabilities

The system currently broadcasts12unified tools that consolidate all memory bank operations:
- memory-bank- Initialize and manage memory bank metadata
- entity- Create, update, delete, and retrieve all entity types (components, decisions, rules, files, tags)
- introspect- Explore graph schema and metadata
- context- Manage work session context
- query- Unified search across contexts, entities, relationships, dependencies, governance, history, and tags
- associate- Create relationships between entities
- analyze- Run graph algorithms (PageRank, K-Core, Louvain, Shortest Path)
- detect- Detect patterns (strongly/weakly connected components)
- bulk-import- Efficient bulk entity import
- search- Full-text search across all entity types with KuzuDB FTS integration
- delete- Safe deletion of entities with dependency validation and bulk operations
- memory-optimizer- 🧠AI-powered core memory optimization with MCP sampling, snapshots, and rollback

For detailed tool documentation, seeUnified Tools Documentation.

- Extended Documentation- Architecture and advanced usage patterns
- Graph Schema- Database schema details

# Clone the repository git clone git@github.com:Jakedismo/KuzuMem-MCP.git cd kuzumem-mcp # Install dependencies npm install # Build the project npm run build

# Database Configuration DB_FILENAME="memory-bank.kuzu" # Server Configuration HTTP_STREAM_PORT=3001 HOST=localhost # Debug Logging (0=Error, 1=Warn, 2=Info, 3=Debug, 4=Trace) DEBUG=1 # Core Memory Optimization Agent - AI Provider Configuration # Required for memory optimization features OPENAI_API_KEY=sk-your-openai-api-key-here ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here # Optional: Custom API endpoints # OPENAI_BASE_URL=https://api.openai.com/v1 # ANTHROPIC_BASE_URL=https://api.anthropic.com

- OpenAI: Get your API key fromOpenAI Platform
- Anthropic: Get your API key fromAnthropic Console

For detailed setup instructions, seeCore Memory Optimization Setup Guide.

{ "mcpServers": { "KuzuMem-MCP": { "command": "npx", "args": ["-y", "ts-node", "/absolute/path/to/kuzumem-mcp/src/mcp-stdio-server.ts"], "env": { "PORT": "3000", "HOST": "localhost", "DB_FILENAME": "memory-bank.kuzu", "HTTP_STREAM_PORT": "3001" } } } }

{ "tool": "memory-bank", "operation": "init", "clientProjectRoot": "/path/to/your/project", "repository": "my-app", "branch": "main" }

{ "tool": "entity", "operation": "create", "entityType": "component", "repository": "my-app", "branch": "main", "data": { "id": "comp-auth-service", "name": "Authentication Service", "kind": "service", "depends_on": ["comp-user-service"] } }

{ "tool": "query", "type": "dependencies", "repository": "my-app", "branch": "main", "componentId": "comp-auth-service", "direction": "dependencies" }

{ "tool": "analyze", "type": "pagerank", "repository": "my-app", "branch": "main", "projectedGraphName": "component-importance", "nodeTableNames": ["Component"], "relationshipTableNames": ["DEPENDS_ON"] }

TheCore Memory Optimization Agentprovides AI-powered memory graph optimization with advanced reasoning capabilities and production-ready safety features:

- 🧠 High-Reasoning Analysis: Uses OpenAI o3/o4-mini (HIGH reasoning) or Claude (extended thinking) for intelligent memory analysis
- 🎯 MCP Sampling: Context-aware prompts that adapt to actual memory state and project characteristics
- 🛡️ Automatic Snapshots: Production-ready safety with automatic backup before optimization
- 🔄 Guaranteed Rollback: Complete state restoration with transactional safety
- ⚖️ Safe Optimization: Conservative, balanced, and aggressive strategies with safety validation
- 🔍 Stale Entity Detection: Identifies outdated entities based on age and usage patterns
- 🔗 Redundancy Removal: Finds and consolidates duplicate or redundant entities
- 📊 Dependency Optimization: Optimizes relationship chains while preserving integrity
- 👀 Dry-Run Mode: Preview optimizations without making changes
- 📈 Project Intelligence: Automatic project maturity, activity, and complexity analysis

1. Analyze Memory Graph (with MCP Sampling)

{ "tool": "memory-optimizer", "operation": "analyze", "repository": "my-app", "branch": "main", "llmProvider": "openai", "model": "o4-mini", "strategy": "conservative", "enableMCPSampling": true, "samplingStrategy": "representative" }

{ "tool": "memory-optimizer", "operation": "optimize", "repository": "my-app", "branch": "main", "dryRun": true, "strategy": "conservative" }

3. Execute Optimization (with Automatic Snapshot)

{ "tool": "memory-optimizer", "operation": "optimize", "repository": "my-app", "branch": "main", "dryRun": false, "confirm": true, "strategy": "conservative" }

{ "tool": "memory-optimizer", "operation": "list-snapshots", "repository": "my-app", "branch": "main" }

{ "tool": "memory-optimizer", "operation": "rollback", "repository": "my-app", "branch": "main", "snapshotId": "snapshot-1703123456789-xyz789" }

- Conservative: Max 5 deletions, 6-month stale threshold (recommended for production)
- Balanced: Max 20 deletions, 3-month stale threshold (recommended for development)
- Aggressive: Max 50 deletions, 1-month stale threshold (use with caution)

- Representative: Balanced sample across all entity types (default)
- Problematic: Focus on stale, disconnected, or deprecated entities
- Recent: Sample newly created entities (< 30 days) for safety analysis
- Diverse: Ensure representation from all entity types for complex systems

- 🛡️ Automatic Snapshots: Created before every optimization (unless dry-run)
- 🔄 Transactional Rollback: Complete state restoration with database consistency
- ✅ Validation System: Snapshot integrity checks before rollback operations
- 📊 Context-Aware Safety: Activity-level and complexity-based safety measures

For complete setup and usage instructions, see:

- Core Memory Optimization Setup Guide
- Snapshot System Usage Guide
- MCP Sampling Usage Guide

# Run unit tests npm test # Run E2E tests (requires API keys) npm run test:e2e # Run specific E2E tests npm run test:e2e:stdio npm run test:e2e:httpstream # Run memory optimizer E2E tests npm run test:e2e -- --testNamePattern="Memory Optimizer E2E Tests" # Run all tests npm run test:all

export OPENAI_API_KEY="your-actual-openai-api-key" export ANTHROPIC_API_KEY="your-actual-anthropic-api-key"

┌─────────────────────────────────────────────────────────────┐ │ MCP Protocol Layer │ ├─────────────────────────────────────────────────────────────┤ │ HTTP Stream Server │ Stdio Server │ │ (StreamableHTTPTransport) │ (StdioTransport) │ ├─────────────────────────────────────────────────────────────┤ │ Tool Handlers │ ├─────────────────────────────────────────────────────────────┤ │ Memory Service │ ├─────────────────────────────────────────────────────────────┤ │ Repository Layer │ ├─────────────────────────────────────────────────────────────┤ │ KuzuDB Client │ └─────────────────────────────────────────────────────────────┘

For detailed architecture information, seeExtended Documentation.

stateDiagram-v2 [*] --> ANALYZE ANALYZE --> BLUEPRINT: blueprint drafted BLUEPRINT --> CONSTRUCT: approved CONSTRUCT --> VALIDATE: steps complete VALIDATE --> DONE: tests pass VALIDATE --> CONSTRUCT: tests fail CONSTRUCT --> ROLLBACK: unrecoverable error ROLLBACK --> ANALYZE

Contributions are welcome! Please ensure:

- All tests pass (or create issues for failing tests)
- Code follows the existing style
- New features include tests
- Documentation is updated

- Vector Embeddings- Semantic similarity search (pending KuzuDB vector column updates)
- Advanced Graph Algorithms- Additional analysis capabilities
- Graph Schema Updates- Based on how well the automated development loop works, the graph schema may need to be updated to support new features
- Complete Semantic Search- Implementation of the semantic-search tool (currently placeholder - KuzuDB Vector Indexes are immutable and would make developing this feature difficult since updating memories wouldn't update the vector indexes)

https://mcpreview.com/mcp-servers/Jakedismo/KuzuMem-MCP

Persistent AI memory server with 3-layer hybrid search, confidence scoring, and 16 tools. Zero LLM dependency.