Kuzumem Mcp

KuzuMem-MCP

一个基于 TypeScript 的分布式记忆库实现，作为 MCP（Model Context Protocol）工具，使用 KùzuDB 图数据库存储记忆，并支持按仓库和分支筛选。通过为实体使用图唯一标识符实现分支隔离，从而建立集中式记忆库，同时支持查看特定仓库和分支的数据。完全符合 MCP 规范，可与 IDE 和 AI Agent 无缝集成。

主要功能

• 🧠 AI 驱动的记忆优化 - 使用高级推理模型（OpenAI o3/o4-mini、Claude 4）和 MCP 采样，实现智能记忆管理
• 🛡️ 生产环境就绪的安全机制 - 自动快照系统，支持可靠回滚
• 🎯 上下文感知智能 - MCP 采样会分析实际记忆状态，制定自适应优化策略
• 🔧 统一工具架构 - 12 个整合工具，涵盖记忆库的所有操作
• 🧵 线程安全的单例模式 - 确保每个资源仅实例化一次，并保障线程安全
• 📊 分布式图结构 - 使用 KùzuDB 图数据库，遵循高级记忆库规范
• 🌿 仓库和分支感知 - 所有操作均基于仓库名称和分支进行上下文处理
• ⚡ 异步操作 - 使用 async/await 提升性能
• 🔌 多种访问接口 - 可通过 CLI 和多种 MCP 服务实现进行访问
• 💾 KùzuDB 后端 - 使用 KùzuDB 进行基于图的记忆存储和查询
• ✅ 完全符合 MCP 规范 - 所有工具均遵循 Model Context Protocol，便于客户端集成
• 📡 渐进式结果流式传输 - 支持长时间运行的图操作的流式传输
• 🏠 客户端项目根目录隔离 - 每个客户端项目都有独立的数据库实例
• 🧠 高级推理分析 - 利用 OpenAI HIGH 推理和 Anthropic 扩展思考优化记忆
• 🗑️ 安全批量操作 - 支持依赖验证和试运行的高级批量删除

统一工具

系统目前提供 12 个统一工具，用于整合记忆库的所有操作：

1. memory-bank - 初始化和管理记忆库元数据
2. entity - 创建、更新、删除和检索所有实体类型（组件、决策、规则、文件、标签）
3. introspect - 探索图模式和元数据
4. context - 管理工作会话上下文
5. query - 统一搜索上下文、实体、关系、依赖、治理、历史记录和标签
6. associate - 创建实体之间的关系
7. analyze - 运行图算法（PageRank、K-Core、Louvain、Shortest Path）
8. detect - 检测模式（强连通分量／弱连通分量）
9. bulk-import - 高效批量导入实体
10. search - 使用 KuzuDB FTS 集成，对所有实体类型进行全文搜索
11. delete - 通过依赖验证和批量操作安全删除实体
12. memory-optimizer - 🧠 借助 MCP 采样、快照和回滚功能进行 AI 驱动的核心记忆优化

详细的工具文档请参阅 统一工具文档。

文档

• 扩展文档 - 架构和高级用法模式
• 图模式 - 数据库模式详情

安装

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

# Install dependencies
npm install

# Build the project
npm run build

配置

在根目录中创建 .env 文件（从 .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

核心记忆优化设置

核心记忆优化 Agent 需要高推理模型的 API 密钥：

• OpenAI：从 OpenAI Platform 获取 API 密钥
• Anthropic：从 Anthropic Console 获取 API 密钥

支持的模型：

• OpenAI：o3、o4-mini（高推理能力，32,768 个 token）
• Anthropic：claude-4（扩展思考，2,048 个 token）

详细设置说明请参阅核心记忆优化设置指南。

添加到 IDE 的 MCP 配置中：

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

快速开始

1. 初始化记忆库

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

2. 创建实体

{
  "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. 查询依赖关系

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

4. 运行分析

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

🧠 核心记忆优化 Agent

核心记忆优化 Agent 提供 AI 驱动的记忆图优化功能，具备先进的推理能力和可用于生产环境的安全特性：

功能

• 🧠 高推理分析：使用 OpenAI o3/o4-mini（高推理能力）或 Claude（扩展思考）进行智能记忆分析
• 🎯 MCP Sampling：根据实际记忆状态和项目特征动态调整的上下文感知提示词
• 🛡️ 自动快照：优化前自动备份，提供可用于生产环境的安全保障
• 🔄 保证回滚：通过事务安全机制完整恢复状态
• ⚖️ 安全优化：提供保守、平衡和激进策略，并进行安全验证
• 🔍 陈旧实体检测：根据实体的存在时间和使用模式识别过时实体
• 🔗 冗余移除：查找并合并重复或冗余实体
• 📊 依赖关系优化：优化关系链，同时保持完整性
• 👀 试运行模式：预览优化效果，不做任何更改
• 📈 项目智能分析：自动分析项目成熟度、活跃度和复杂度

快速开始

1. 分析记忆图（使用 MCP Sampling）

{
  "tool": "memory-optimizer",
  "operation": "analyze",
  "repository": "my-app",
  "branch": "main",
  "llmProvider": "openai",
  "model": "o4-mini",
  "strategy": "conservative",
  "enableMCPSampling": true,
  "samplingStrategy": "representative"
}

2. 预览优化（试运行）

{
  "tool": "memory-optimizer",
  "operation": "optimize",
  "repository": "my-app",
  "branch": "main",
  "dryRun": true,
  "strategy": "conservative"
}

3. 执行优化（自动创建快照）

{
  "tool": "memory-optimizer",
  "operation": "optimize",
  "repository": "my-app",
  "branch": "main",
  "dryRun": false,
  "confirm": true,
  "strategy": "conservative"
}

4. 列出可用快照

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

5. 回滚到先前状态

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

优化策略

• 保守：最多删除 5 个实体，陈旧阈值为 6 个月（推荐用于生产环境）
• 平衡：最多删除 20 个实体，陈旧阈值为 3 个月（推荐用于开发环境）
• 激进：最多删除 50 个实体，陈旧阈值为 1 个月（谨慎使用）

MCP Sampling 策略

• 代表性：均衡抽取各种实体类型（默认）
• 问题实体：重点抽取陈旧、未连接或已弃用的实体
• 近期实体：抽取新创建的实体（< 30 天）进行安全分析
• 多样化：确保复杂系统中的各类实体均有代表

安全特性

• 🛡️ 自动快照：每次优化前创建（试运行除外）
• 🔄 事务回滚：在保证数据库一致性的同时完整恢复状态
• ✅ 验证系统：回滚操作前检查快照完整性
• 📊 上下文感知安全：基于活跃度和复杂度采取安全措施

完整的设置和使用说明请参阅：

• 核心记忆优化设置指南
• 快照系统使用指南
• MCP Sampling 使用指南

测试

# 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 测试要求

运行记忆优化器 E2E 测试时，请设置环境变量：

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

注意：所有核心功能均已可用，并针对 stdio 和 HTTP stream 协议提供了全面的 E2E 测试覆盖。

架构

KuzuMem-MCP 遵循官方 MCP TypeScript SDK 模式，采用清晰的架构：

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

核心组件

• MCP 服务：使用 McpServer 实现的官方 SDK，支持 HTTP Stream 和 Stdio 传输
• 工具处理器：各 MCP 工具的业务逻辑，并简化上下文处理
• 记忆服务：核心编排与存储库管理
• 存储库层：为每种实体类型提供线程安全的单例
• 数据库层：KùzuDB 嵌入式图数据库

官方 SDK 合规性

✅ 会话管理：使用 SDK 内置的会话处理机制
✅ 工具注册：使用官方 tool() 方法和 Zod 验证
✅ 传输处理：利用 SDK 的传输实现
✅ 错误处理：遵循 SDK 的错误处理模式和最佳实践

如需详细了解架构信息，请参阅扩展文档。

Agent 开发循环（规则强制执行）

当仓库级“始终应用的工作区规则”（project_config_updated.md）和短期工作流规则（workflow_state_updated.mdc）均处于启用状态时，每个与 KuzuMem-MCP 通信的 IDE 或 AI Agent 都必须遵循以下五阶段有限状态循环。每次状态转换都可通过统一的 context 工具观察，并由强制性 MCP 调用提供支持，以保持图数据库同步并确保治理规则得到执行。

1. ANALYZE（分析） – 获取最新上下文，检查 1 跳邻域，并可选择执行 PageRank 分析。输出高层次的问题陈述。
2. BLUEPRINT（规划） – 起草编号实施计划，并将其保存为 Decision 实体（status: proposed，标签 architecture）。等待用户明确批准。
3. CONSTRUCT（构建） – 执行计划步骤，应用代码修改，并立即通过 entity、associate 和 context 工具调用同步变更，同时遵守依赖和标签规则。
4. VALIDATE（验证） – 运行完整的测试和代码检查套件。如果全部通过，则将 Decision 更新为 implemented；如果未通过，则记录上下文并返回 CONSTRUCT 阶段。
5. ROLLBACK（回滚） – 出现无法恢复的错误时自动触发，撤销部分工作，然后返回 ANALYZE 阶段。

阶段图

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

许可证

Apache-2.0

参与贡献

欢迎贡献！请确保：

• 所有测试均通过（如果有测试失败，请创建问题）
• 代码遵循现有风格
• 新功能包含测试
• 文档已更新

后续改进

• 向量嵌入 - 语义相似度搜索（等待 KuzuDB 向量列更新）
• 高级图算法 - 增加分析能力
• 图架构更新 - 根据自动化开发循环的运行效果，可能需要更新图架构以支持新功能
• 完整语义搜索 - 实现语义搜索工具（目前为占位实现——KuzuDB 向量索引不可变，因此难以开发此功能，因为更新记忆不会同步更新向量索引）

MCP Review

此 MCP 已通过 MCP Review 验证

https://mcpreview.com/mcp-servers/Jakedismo/KuzuMem-MCP

使用 Codrabbit 自动进行代码审查