Kuzumem MCP

🚀 KuzuMem-MCP

KuzuMem-MCP is a TypeScript implementation of a distributed memory bank, serving as an MCP (Model Context Protocol) tool. It stores memories in a KùzuDB graph database and offers repository and branch filtering capabilities. By using a graph-unique identifier for entities, it achieves branch isolation, enabling a centralized memory bank with repository-specific and branch-specific views. It fully complies with the MCP specification, facilitating seamless integration with IDEs and AI agents.

✨ Features

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

📦 Installation

# 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

📚 Documentation

• Extended Documentation - Explore architecture and advanced usage patterns.
• Graph Schema - Dive into database schema details.

💻 Usage Examples

Quick Start

1. Initialize Memory Bank

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

2. Create Entities

{
  "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"]
  }
}

3. Query Dependencies

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

4. Run Analysis

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

Core Memory Optimization Agent

Features

• 🧠 High-Reasoning Analysis: Employ OpenAI o3/o4-mini (HIGH reasoning) or Claude (extended thinking) for intelligent memory analysis.
• 🎯 MCP Sampling: Use context-aware prompts that adapt to the actual memory state and project characteristics.
• 🛡️ Automatic Snapshots: Enjoy production-ready safety with automatic backup before optimization.
• 🔄 Guaranteed Rollback: Restore the complete state with transactional safety.
• ⚖️ Safe Optimization: Choose from conservative, balanced, and aggressive strategies with safety validation.
• 🔍 Stale Entity Detection: Identify outdated entities based on age and usage patterns.
• 🔗 Redundancy Removal: Find and consolidate duplicate or redundant entities.
• 📊 Dependency Optimization: Optimize relationship chains while preserving integrity.
• 👀 Dry-Run Mode: Preview optimizations without making changes.
• 📈 Project Intelligence: Automatically analyze project maturity, activity, and complexity.

Quick Start

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"
}

2. Preview Optimization (Dry Run)

{
  "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"
}

4. List Available Snapshots

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

5. Rollback to Previous State

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

Optimization Strategies

• 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).

MCP Sampling Strategies

• 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.

Safety Features

• 🛡️ Automatic Snapshots: Created before every optimization (unless dry-run).
• 🔄 Transactional Rollback: Restore the complete state with database consistency.
• ✅ Validation System: Conduct snapshot integrity checks before rollback operations.
• 📊 Context-Aware Safety: Implement activity-level and complexity-based safety measures.

🔧 Technical Details

Unified Tools

The system currently offers 12 unified tools that consolidate all memory bank operations:

1. memory-bank - Initialize and manage memory bank metadata.
2. entity - Create, update, delete, and retrieve all entity types (components, decisions, rules, files, tags).
3. introspect - Explore graph schema and metadata.
4. context - Manage work session context.
5. query - Perform unified search across contexts, entities, relationships, dependencies, governance, history, and tags.
6. associate - Create relationships between entities.
7. analyze - Run graph algorithms (PageRank, K-Core, Louvain, Shortest Path).
8. detect - Detect patterns (strongly/weakly connected components).
9. bulk-import - Efficiently import bulk entities.
10. search - Conduct full-text search across all entity types with KuzuDB FTS integration.
11. delete - Safely delete entities with dependency validation and bulk operations.
12. memory-optimizer - 🧠 AI-powered core memory optimization with MCP sampling, snapshots, and rollback

For detailed tool documentation, see Unified Tools Documentation.

Configuration

Create a .env file in the root directory (copy from .env.example):

# 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

Core Memory Optimization Setup

The Core Memory Optimization Agent requires API keys for high-reasoning models:

• OpenAI: Get your API key from OpenAI Platform.
• Anthropic: Get your API key from Anthropic Console.

Supported Models:

• OpenAI: o3, o4-mini (with HIGH reasoning, 32,768 tokens).
• Anthropic: claude-4 (with extended thinking, 2,048 tokens).

For detailed setup instructions, see Core Memory Optimization Setup Guide.

Add to your IDE's MCP configuration:

{
  "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"
      }
    }
  }
}

Testing

# 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

E2E Test Requirements

For memory optimizer E2E tests, set environment variables:

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

Note: All core functionality is operational with comprehensive E2E test coverage for both stdio and HTTP stream protocols.

Architecture

KuzuMem-MCP follows official MCP TypeScript SDK patterns with clean architecture:

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

Key Components

• MCP Servers: Official SDK implementations using McpServer with HTTP Stream and Stdio transports.
• Tool Handlers: Business logic for each MCP tool with simplified context handling.
• Memory Service: Core orchestration and repository management.
• Repository Layer: Thread-safe singletons for each entity type.
• Database Layer: KùzuDB embedded graph database.

Official SDK Compliance

✅ Session Management: Uses built-in SDK session handling. ✅ Tool Registration: Uses official tool() method with Zod validation. ✅ Transport Handling: Leverages SDK transport implementations. ✅ Error Handling: Follows SDK error patterns and best practices.

For detailed architecture information, see Extended Documentation.

Agent Development Loop (Rules-Enforced)

When both the repository-level "Always-Applied Workspace Rules" (project_config_updated.md) and the short-term workflow rules (workflow_state_updated.mdc) are active, every IDE or AI agent that communicates with KuzuMem-MCP must follow the five-phase finite-state loop below. Each transition is observable via the unified context tool and is backed by mandatory MCP calls that keep the graph database in sync and governance rules enforced.

1. ANALYZE – Pull the latest context, inspect 1-hop neighbourhood, and optionally execute a PageRank analysis. Produce a high-level problem statement.
2. BLUEPRINT – Draft a numbered implementation plan and persist it as a Decision entity (status: proposed, tag architecture). Wait for explicit user approval.
3. CONSTRUCT – Execute plan steps, apply code edits, and immediately mirror changes through entity, associate, and context tool calls while honouring dependency & tagging rules.
4. VALIDATE – Run the full test & linter suite. If green, update the Decision to implemented; if red, log context and loop back to CONSTRUCT.
5. ROLLBACK – Automatically triggered on unrecoverable errors, reverting partial work before returning to ANALYZE.

Phase Diagram

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

📄 License

Apache-2.0

Contributing

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.

Future Improvements

• 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).

MCP Review

This MCP is verified by MCP Review https://mcpreview.com/mcp-servers/Jakedismo/KuzuMem-MCP

Automatic Codereviews with Codrabbit