KuzuMem-MCP

KuzuMem-MCP

A TypeScript implementation of a distributed memory bank as an MCP (Model Context Protocol) tool, storing memories in a KùzuDB graph database with 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.

Key Features

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

Unified Tools

The system currently broadcasts 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 - 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 - Efficient bulk entity import
10. search - Full-text search across all entity types with KuzuDB FTS integration
11. delete - Safe deletion of 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.

Documentation

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

Installation

# Clone the repository
git clone [email protected]:Jakedismo/KuzuMem-MCP.git
cd kuzumem-mcp

# Install dependencies
npm install

# Build the project
npm run build

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

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

The Core Memory Optimization Agent provides AI-powered memory graph optimization with advanced reasoning capabilities and production-ready safety features:

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

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: 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

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