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

自動代碼審查