Kuzumem MCP

🚀 KuzuMem-MCP

KuzuMem-MCPは、分散型メモリバンクをTypeScriptで実装したMCP（Model Context Protocol）ツールです。KùzuDBグラフデータベースにメモリを保存し、リポジトリとブランチのフィルタリング機能を備えています。エンティティにグラフ固有の識別子を使用することでブランチの分離を実現し、集中型のメモリバンクを提供しながら、リポジトリ固有およびブランチ固有のビューを可能にします。IDEやAIエージェントとのシームレスな統合のために、MCP仕様に完全に準拠しています。

✨ 主な機能

• 🧠 AIによるメモリ最適化 - MCPサンプリングを使用した高度な推論モデル（OpenAI o3/o4-mini、Claude 4）によるインテリジェントなメモリ管理
• 🛡️ 本番環境での安全性 - ロールバック機能を保証する自動スナップショットシステム
• 🎯 コンテキスト認識型インテリジェンス - MCPサンプリングにより実際のメモリ状態を分析し、適応的な最適化戦略を提供
• 🔧 統一ツールアーキテクチャ - メモリバンクのすべての操作をカバーする12の統合ツール
• 🧵 スレッドセーフなシングルトンパターン - 各リソースが一度だけインスタンス化され、適切なスレッドセーフ性が保証されます
• 📊 分散型グラフ構造 - KùzuDBグラフを使用した高度なメモリバンク仕様に準拠
• 🌿 リポジトリとブランチの認識 - すべての操作はリポジトリ名とブランチによってコンテキスト化されます
• ⚡ 非同期操作 - パフォーマンス向上のためにasync/awaitを使用
• 🔌 複数のアクセスインターフェイス - CLIおよび複数のMCPサーバー実装を介したアクセス
• 💾 KùzuDBバックエンド - グラフベースのメモリの保存とクエリにKùzuDBを利用
• ✅ 完全にMCPに準拠 - すべてのツールがクライアント統合のためのModel Context Protocolに従います
• 📡 漸進的な結果ストリーミング - 長時間実行されるグラフ操作のストリーミングをサポート
• 🏠 クライアントプロジェクトルートの分離 - 各クライアントプロジェクトに独自の分離されたデータベースインスタンスが提供されます
• 🧠 高度な推論分析 - メモリ最適化のためにOpenAIの高度な推論とAnthropicの拡張思考を活用
• 🗑️ 安全な一括操作 - 依存関係の検証とドライラン機能を備えた高度な一括削除

📦 インストール

# リポジトリをクローン
git clone git@github.com:Jakedismo/KuzuMem-MCP.git
cd kuzumem-mcp

# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

🔧 設定

ルートディレクトリに.envファイルを作成します（.env.exampleからコピー）：

# データベース設定
DB_FILENAME="memory-bank.kuzu"

# サーバー設定
HTTP_STREAM_PORT=3001
HOST=localhost

# デバッグログ (0=エラー, 1=警告, 2=情報, 3=デバッグ, 4=トレース)
DEBUG=1

# コアメモリ最適化エージェント - AIプロバイダー設定
# メモリ最適化機能に必要
OPENAI_API_KEY=sk-your-openai-api-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here

# オプション: カスタムAPIエンドポイント
# OPENAI_BASE_URL=https://api.openai.com/v1
# ANTHROPIC_BASE_URL=https://api.anthropic.com

コアメモリ最適化の設定

コアメモリ最適化エージェントには、高度な推論モデルのAPIキーが必要です：

• OpenAI：OpenAI PlatformからAPIキーを取得してください
• Anthropic：Anthropic ConsoleからAPIキーを取得してください

サポートされているモデル：

• OpenAI：o3、o4-mini（HIGH推論、32,768トークン）
• Anthropic：claude-4（拡張思考、2,048トークン）

詳細な設定手順については、コアメモリ最適化設定ガイドを参照してください。

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

🧠 コアメモリ最適化エージェント

コアメモリ最適化エージェントは、高度な推論機能と本番環境での安全性を備えたAIベースのメモリグラフ最適化を提供します：

機能

• 🧠 高度な推論分析 - OpenAI o3/o4-mini（HIGH推論）またはClaude（拡張思考）を使用したインテリジェントなメモリ分析
• 🎯 MCPサンプリング - 実際のメモリ状態とプロジェクトの特性に適応するコンテキスト認識型プロンプト
• 🛡️ 自動スナップショット - 最適化前に自動的にバックアップを作成し、本番環境での安全性を提供
• 🔄 保証されたロールバック - トランザクションの安全性を備えた完全な状態復元
• ⚖️ 安全な最適化 - 安全性検証を伴う保守的、バランスの取れた、積極的な戦略
• 🔍 古いエンティティの検出 - 年齢と使用パターンに基づいて古いエンティティを識別
• 🔗 冗長性の削除 - 重複または冗長なエンティティを見つけて統合
• 📊 依存関係の最適化 - 整合性を維持しながら関係チェーンを最適化
• 👀 ドライランモード - 変更を加えずに最適化をプレビュー
• 📈 プロジェクトインテリジェンス - 自動的なプロジェクトの成熟度、アクティビティ、複雑度の分析

クイックスタート

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

最適化戦略

• 保守的 - 最大5回の削除、6ヶ月の古いエンティティの閾値（本番環境に推奨）
• バランスの取れた - 最大20回の削除、3ヶ月の古いエンティティの閾値（開発環境に推奨）
• 積極的 - 最大50回の削除、1ヶ月の古いエンティティの閾値（注意して使用）

MCPサンプリング戦略

• 代表的 - すべてのエンティティタイプにわたるバランスの取れたサンプル（デフォルト）
• 問題のある - 古い、切断された、または非推奨のエンティティに焦点を当てる
• 最近の - 安全性分析のために新しく作成されたエンティティ（< 30日）をサンプリング
• 多様な - 複雑なシステムのためにすべてのエンティティタイプからの代表を確保

安全機能

• 🛡️ 自動スナップショット - すべての最適化の前に作成されます（ドライランの場合を除く）
• 🔄 トランザクションロールバック - データベースの整合性を備えた完全な状態復元
• ✅ 検証システム - ロールバック操作前のスナップショットの整合性チェック
• 📊 コンテキスト認識型セキュリティ - アクティビティレベルと複雑度に基づくセキュリティ対策

完全な設定と使用手順については、以下を参照してください：

• コアメモリ最適化設定ガイド
• スナップショットシステム使用ガイド
• MCPサンプリング使用ガイド

🔍 テスト

# 単体テストを実行する
npm test

# E2Eテストを実行する（APIキーが必要）
npm run test:e2e

# 特定のE2Eテストを実行する
npm run test:e2e:stdio
npm run test:e2e:httpstream

# メモリオプティマイザーのE2Eテストを実行する
npm run test:e2e -- --testNamePattern="Memory Optimizer E2E 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ストリームプロトコルの包括的なE2Eテストカバレッジを備えて動作します。

📚 ドキュメント

• 拡張ドキュメント - アーキテクチャと高度な使用パターン
• グラフスキーマ - データベーススキーマの詳細

🔧 統一ツール

システムは現在、メモリバンクのすべての操作を統合した12の統一ツールを提供しています：

1. memory-bank - メモリバンクのメタデータを初期化し、管理する
2. entity - すべてのエンティティタイプ（コンポーネント、決定、ルール、ファイル、タグ）を作成、更新、削除、および取得する
3. introspect - グラフスキーマとメタデータを探索する
4. context - 作業セッションのコンテキストを管理する
5. query - コンテキスト、エンティティ、関係、依存関係、ガバナンス、履歴、およびタグにわたる統一検索
6. associate - エンティティ間の関係を作成する
7. analyze - グラフアルゴリズム（PageRank、K-Core、Louvain、最短経路）を実行する
8. detect - パターン（強/弱連結成分）を検出する
9. bulk-import - 効率的な一括エンティティのインポート
10. search - KuzuDB FTS統合を使用したすべてのエンティティタイプにわたる全文検索
11. delete - 依存関係の検証と一括操作を伴うエンティティの安全な削除
12. memory-optimizer - 🧠 MCPサンプリング、スナップショット、およびロールバックを備えたAIベースのコアメモリ最適化

詳細なツールドキュメントについては、統一ツールドキュメントを参照してください。

🏗️ アーキテクチャ

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セッションハンドリングを使用 ✅ ツール登録 - Zod検証を伴う公式のtool()メソッドを使用 ✅ トランスポートハンドリング - SDKトランスポート実装を利用 ✅ エラーハンドリング - SDKエラーパターンとベストプラクティスに従う

詳細なアーキテクチャ情報については、拡張ドキュメントを参照してください。

🤖 エージェント開発ループ（ルール適用）

リポジトリレベルの「常に適用されるワークスペースルール」 (project_config_updated.md) と短期的なワークフロールール (workflow_state_updated.mdc) の両方がアクティブな場合、KuzuMem-MCP と通信するすべてのIDEまたはAIエージェントは、以下の5フェーズの有限状態ループに従う必要があります。各遷移は統一された 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レビュー

このMCPはMCPレビューによって検証されています。

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

Codrabbitによる自動コードレビュー