KuzuMem-MCP

A TypeScript implementation of a distributed memory bank as an MCP (Model Context Protocol) tool, storing memories in a KzuDB 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 KzuDB 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
• ** KzuDB Backend** - Utilizes KzuDB 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",
  "nodeTableNa…