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