Kuzumem Mcp

KuzuMem-MCP

MCP（Model Context Protocol）ツールとして分散型メモリーバンクを実装した TypeScript プロジェクトです。KùzuDB グラフデータベースにメモリーを保存し、リポジトリおよびブランチによるフィルタリングに対応しています。エンティティにグラフ内で一意の識別子を使用することでブランチを分離し、中央集約型のメモリーバンクを維持しながら、リポジトリやブランチごとのビューを利用できます。MCP 仕様に完全準拠しており、IDE や AI エージェントとシームレスに統合できます。

主な機能

• 🧠 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 HIGH reasoning と Anthropic extended thinking を活用
• 🗑️ 安全な一括操作 - 依存関係の検証とドライラン機能を備えた、高度な一括削除

統合ツール

現在、システムはメモリーバンクのすべての操作を統合した 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 による中核メモリーの最適化

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

ドキュメント

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

インストール

# 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

コアメモリ最適化のセットアップ

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

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

対応モデル：

• 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 サンプリング使用ガイド

テスト

# 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 ストリームの両プロトコルについて、包括的な 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 サーバー：HTTP Stream および Stdio トランスポートを使用する McpServer による公式 SDK 実装
• ツールハンドラー：コンテキスト処理を簡略化した、各 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 Review

この MCP は MCP Review によって検証されています

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

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