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 git@github.com: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 ( 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

## Automatic Codereviews with Codrabbit

![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/Jakedismo/KuzuMem-MCP?utm_source=oss&utm_medium=github&utm_campaign=Jakedismo%2FKuzuMem-MCP&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)