KuzuMem

KuzuMem-MCP is a TypeScript-based MCP server that stores memories in a KùzuDB graph database with repository and branch awareness. It provides a centralized memory bank while offering repository-specific views, supports AI-powered memory optimization, safe rollback via automatic snapshots, and streaming results for long-running graph operations. You can interact with it through the MCP client ecosystem using the unified tools to manage memory entities, analyze graphs, and optimize memory strategies across repositories and branches.

How to use

You interact with KuzuMem-MCP through an MCP client that communicates with the server using a standard MCP workflow. Initialize your memory bank for a project, create and manage entities (components, decisions, rules, files, tags), run analyses and optimizations, and leverage the memory optimizer to automatically prune and improve memory layouts. All operations are contextualized by your repository name and branch, ensuring isolation while maintaining a unified underlying graph.

Key workflows you can perform include initializing the memory bank for a project, creating and linking entities, querying for dependencies, running graph analyses, and invoking the memory optimizer for AI-powered memory improvements. The system supports streaming results for long-running graph operations, so you can monitor progress as work completes.

How to install

Prerequisites: Node.js and npm should be installed on your system. You will also require a compatible shell to run commands and an environment to host the MCP server. Ensure you have a project directory ready for the MCP server and plan for a memory bank filename you will use with the embedded graph database.

Step-by-step installation and start flow from scratch:

# Clone the project
git clone git@github.com:Jakedismo/KuzuMem-MCP.git
cd kuzumem-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the standard IO server (example command shown in MCP setup) or use your project’s startup script as configured
# Example (adjust path to your environment as needed):
npx -y ts-node /absolute/path/to/kuzumem-mcp/src/mcp-stdio-server.ts

Configuration and runtime setup

Configure the server by creating a .env file in the root of your project. The configuration includes database settings, server ports, debug level, and AI provider keys. You will need API keys for memory optimization models if you plan to use AI-powered features.

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

MCP server configuration snippet for IDE integration

You can configure your MCP client to connect to the local stdio server. The following example shows how to wire the MCP client to run the stdio server using npx and ts-node, with environment variables for the runtime.

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

Additional notes

The unified toolset includes memory-bank, entity, introspect, context, query, associate, analyze, detect, bulk-import, search, delete, and memory-optimizer. Memory-optimizer uses MCP sampling and supports automatic snapshots with rollback to guard against unintended changes. All actions respect repository and branch isolation to keep projects self-contained.

Troubleshooting and tips

If you encounter startup errors, verify that the environment variables are correctly defined in your .env file and that the KuzuDB embedded graph database can create or access memory-bank.kuzu in the expected directory. Ensure that the HTTP_STREAM_PORT is not blocked by a firewall and that your IDE or client is configured to connect using the provided stdio MCP entry.

Available tools

memory-bank

Initialize and manage memory bank metadata across repositories and branches.

entity

Create, update, delete, and retrieve entities such as components, decisions, rules, files, and tags.

introspect

Explore graph schema and metadata to understand the memory graph.

context

Manage work session context for your MCP workflow.

query

Perform unified searches across contexts, entities, relationships, dependencies, governance, history, and tags.

associate

Create and manage relationships between entities in the memory graph.

analyze

Run graph algorithms such as PageRank, K-Core, Louvain, and Shortest Path on the memory graph.

detect

Detect patterns like strongly or weakly connected components in the graph.

bulk-import

Efficiently import large sets of entities in bulk.

search

Full-text search across all entity types with KuzuDB FTS integration.

delete

Safely delete entities with dependency validation and bulk operations.

memory-optimizer

AI-powered core memory optimization with MCP sampling, snapshots, and rollback.