Kuzumem MCP

🚀 KuzuMem-MCP

KuzuMem-MCP 是一个用 TypeScript 实现的分布式内存库，作为 MCP（模型上下文协议）工具使用。它将内存存储在 KùzuDB 图数据库 中，并具备仓库和分支过滤功能。通过为实体使用图唯一标识符实现分支隔离，从而在实现集中式内存库的同时，支持特定仓库和特定分支的视图。该工具完全符合 MCP 规范，可与 IDE 和 AI 代理无缝集成。

✨ 主要特性

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

📦 安装指南

# 克隆仓库
git clone git@github.com:Jakedismo/KuzuMem-MCP.git
cd kuzumem-mcp

# 安装依赖
npm install

# 构建项目
npm run build

📚 详细文档

• 扩展文档 - 架构和高级使用模式
• 图模式 - 数据库模式详细信息

💻 使用示例

基础用法

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

高级用法

核心内存优化代理

1. 分析内存图（使用 MCP 采样）

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

🧠 核心内存优化代理

核心内存优化代理提供基于 AI 的内存图优化功能，具备高级推理能力和生产级安全特性：

特性

• 🧠 高推理分析：使用 OpenAI o3/o4-mini（高级推理）或 Claude（扩展思维）进行智能内存分析。
• 🎯 MCP 采样：上下文感知提示，可根据实际内存状态和项目特征进行调整。
• 🛡️ 自动快照：在每次优化前自动创建快照（预运行除外）。
• 🔄 保证回滚：通过事务安全实现完整状态恢复。
• ⚖️ 安全优化：提供保守、平衡和激进三种优化策略，并进行安全验证。
• 🔍 陈旧实体检测：根据实体的使用时间和使用模式识别过时实体。
• 🔗 冗余去除：查找并合并重复或冗余的实体。
• 📊 依赖优化：在保持完整性的同时优化关系链。
• 👀 预运行模式：在不进行更改的情况下预览优化效果。
• 📈 项目智能分析：自动分析项目的成熟度、活动和复杂度。

优化策略

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

MCP 采样策略

• 代表性采样：对所有实体类型进行平衡采样（默认）。
• 问题实体采样：关注陈旧、断开连接或已弃用的实体。
• 近期实体采样：对新创建的实体（< 30 天）进行采样，以进行安全分析。
• 多样化采样：确保复杂系统中所有实体类型都有代表性。

安全特性

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

完整设置和使用说明

• 核心内存优化设置指南
• 快照系统使用指南
• MCP 采样使用指南

测试

# 运行单元测试
npm test

# 运行端到端测试（需要 API 密钥）
npm run test:e2e

# 运行特定的端到端测试
npm run test:e2e:stdio
npm run test:e2e:httpstream

# 运行内存优化器端到端测试
npm run test:e2e -- --testNamePattern="Memory Optimizer E2E Tests"

# 运行所有测试
npm run test:all

端到端测试要求

对于内存优化器端到端测试，需设置环境变量：

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

注意：所有核心功能均可正常运行，并且对 stdio 和 HTTP 流协议都有全面的端到端测试覆盖。

🔧 技术细节

架构

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 流和 Stdio 传输。
• 工具处理程序：每个 MCP 工具的业务逻辑，简化上下文处理。
• 内存服务：核心编排和仓库管理。
• 仓库层：每个实体类型的线程安全单例。
• 数据库层：KùzuDB 嵌入式图数据库。

官方 SDK 合规性

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

详细架构信息

请参考 扩展文档。

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

当仓库级别的“始终应用的工作区规则” (project_config_updated.md) 和短期工作流规则 (workflow_state_updated.mdc) 都处于活动状态时，与 KuzuMem-MCP 通信的每个 IDE 或 AI 代理都必须遵循以下五阶段有限状态循环。每个转换都可以通过统一的 context 工具进行观察，并通过强制的 MCP 调用保持图数据库同步和治理规则的执行。

1. 分析阶段：获取最新上下文，检查 1 跳邻域，并可选择执行 PageRank 分析。生成高级问题陈述。
2. 蓝图阶段：起草编号的实施计划，并将其保存为 Decision 实体（状态：提议，标签：架构）。等待用户明确批准。
3. 构建阶段：执行计划步骤，应用代码编辑，并立即通过 entity、associate 和 context 工具调用反映更改，同时遵守依赖和标签规则。
4. 验证阶段：运行完整的测试和代码检查套件。如果通过，将 Decision 更新为 implemented；如果失败，记录上下文并返回构建阶段。
5. 回滚阶段：在不可恢复的错误时自动触发，在返回分析阶段之前回滚部分工作。

阶段图

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 审核

此 MCP 已通过 MCP 审核。 https://mcpreview.com/mcp-servers/Jakedismo/KuzuMem-MCP

自动代码审查