GraphMemory-IDE: AI-Powered Collaborative Memory Platform

GraphMemory-IDE

LadybugDB を基盤とする、IDE 向けの AI 支援型長期記憶システムです。LadybugDB は、組み込み型の列指向グラフデータベースで、MIT ライセンスで提供されています。GraphMemory-IDE は、セマンティックベクトル検索、グラフベースのナレッジ保存、リアルタイム分析を提供する MCP（Model Context Protocol）サーバーです。専用の IDE プラグインを通じて、VSCode、Cursor、Windsurf と連携します。

グラフデータベース： バックエンドは LadybugDB 0.21.2 で動作します。これは、Apple による買収後にオープンソース開発が停止した KuzuDB の、現在も積極的に開発されている後継製品です。検証済みの API の違い、フェーズごとの実行内容、運用向けの移行ガイドを含む移行記録の全容は、MIGRATION_PLAN_LADYBUG.md と docs/migration/KUZU_TO_LADYBUG.md にあります。

特長

• グラフベースのメモリ保存 — LadybugDB 組み込みグラフデータベース（Cypher / openCypher 方言）。すべての列で主キーのハッシュインデックスとゾーンマップによる枝刈りを自動で行います
• セマンティックベクトル検索 — sentence-transformers による埋め込みを使用し、ノードの埋め込み列に対して array_cosine_similarity による Top-K クエリを実行します
• Codon で高速化されたグラフアルゴリズム — Codon によるネイティブコンパイルを任意で利用できます。中心性、コミュニティ検出、経路分析、類似度計算を 10～100 倍高速化し、利用できない場合は Python/NetworkX に自動でフォールバックします
• FastAPI バックエンド — JWT 認証（EdDSA/Ed25519）、任意の読み取り専用モード、レート制限、セキュリティミドルウェアを備えた非同期 API
• リアルタイム分析 — WebSocket と SSE によるストリーミングで、テレメトリダッシュボードをリアルタイムに更新します
• Streamlit ダッシュボード — グラフのメトリクス、ユーザーアクティビティ、システムの健全性をインタラクティブに可視化します
• 複数の IDE プラグインに対応 — VSCode、Cursor、Windsurf 向けの拡張機能
• 包括的な可観測性 — Prometheus のメトリクス、Grafana のダッシュボード、ヘルスチェック、アラートの相関分析
• 本番環境に対応した Docker デプロイ — Nginx、PostgreSQL、Redis、監視スタックを含むマルチサービスの Docker Compose

クイックスタート

Docker（推奨）

git clone https://github.com/elementalcollision/GraphMemory-IDE.git
cd GraphMemory-IDE/docker
docker compose up -d

サービスは次の URL で利用できます：

• MCP サーバー：http://localhost:8080/docs

ローカル開発

# 1. Install dependencies (Python 3.11+)
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Initialise the graph database schema (REQUIRED before first start —
#    the app opens the database but does not create the schema itself)
LADYBUG_DB_PATH=./data/ladybug.lbdb python server/init_db.py

# 3. Start the FastAPI server
uvicorn server.main:app --host 0.0.0.0 --port 8080 --reload

# 4. (optional) Start the Streamlit dashboard (separate terminal)
cd dashboard && streamlit run streamlit_app.py

設定

変数	デフォルト値	説明
DB_LADYBUG_DB_PATH	./data/ladybug.lbdb	LadybugDB グラフデータベースファイルへのパス（単一の .lbdb ファイルです。親ディレクトリが存在する必要があります。アプリが作成します）
DB_LADYBUG_READ_ONLY	false	グラフデータベースを読み取り専用で開きます（書き込みは DB 層で拒否され、スキーマの初期化はスキップされます）
JWT_SECRET_KEY	（自動生成）	JWT トークン署名用の秘密鍵。本番環境では明示的に設定してください
DB_DATABASE_URL	postgresql://user:password@localhost:5432/graphmemory_dev	PostgreSQL 接続文字列（リレーショナルデータとテレメトリの保存に使用）
DB_REDIS_URL	redis://localhost:6379/0	キャッシュ用の Redis 接続（接続できない場合はインメモリキャッシュにフォールバックします）
CODON_ENABLED	true	Codon による高速化を有効にします
CODON_LIB_PATH	./codon/lib/	コンパイル済み Codon ライブラリへのパス
CODON_MIN_GRAPH_SIZE	100	Codon を使用する最小グラフサイズ

環境変数のプレフィックスについて： データベース関連の設定は、pydantic により DB_ プレフィックス付きで読み取られます。たとえば、設定 LADYBUG_DB_PATH は環境変数 DB_LADYBUG_DB_PATH で指定します。プレフィックスのない LADYBUG_DB_PATH 形式は server/init_db.py で使用でき、KUZU_DB_PATH も、1 リリースサイクルのあいだ非推奨の代替設定として引き続き利用できます。

アーキテクチャ

GraphMemory-IDE は、I/O バウンドのコード（FastAPI、データベースクライアント、WebSocket）は CPython で実行し、計算負荷の高いグラフアルゴリズムは必要に応じてネイティブコンパイルされた Codon モジュールとして実行できるハイブリッドアーキテクチャを採用しています。

IDE Plugins (VSCode/Cursor/Windsurf)
        |
        v
  FastAPI Server (CPython)
   ├── JWT Auth (EdDSA) + Security Middleware (TrustedHost / rate limit)
   ├── MCP Protocol Handler
   ├── Telemetry Ingestion + Query (/telemetry/*)
   ├── Top-K Vector Search (/tools/topk)
   ├── Analytics Engine (/api/v1/analytics/*)
   └── Dashboard Routes + SSE (/dashboard/*)
        |
   ┌────┴─────────┐
   v              v
LadybugDB      PostgreSQL + Redis
(embedded      (relational store,
 graph DB,      sessions, cache)
 sync engine)
   |
   v
Codon Bridge (optional)
 ├── Graph Kernels (.so/.dylib)
 └── Python/NetworkX fallback

グラフデータベース層（server/graph_database.py）：プロセス内で開く組み込みの LadybugDB インスタンスです。別の DB サーバーは不要です。スレッドセーフな接続プール（Condition 変数ベース）、非同期ハンドラー向けの LadybugDB ネイティブの AsyncConnection（GraphDatabaseManager.get_async_connection()）、スキーマ管理（User／Project／Memory ノードテーブルおよび OWNS／COLLABORATES／CONTAINS／RELATES_TO／ACCESSED_BY リレーションシップテーブル）、パラメーター化された Cypher 実行と Prometheus インストルメンテーションに対応したクエリエンジン、ヘルスチェック（CALL show_tables() によるスキーマ整合性検証）を提供します。read_only モードでは、読み取り専用のワークロード（分析用レプリカなど）向けにデータベースを開きます。

詳細なシステム設計については、アーキテクチャ概要をご覧ください。

Codon による高速化

codon/ ディレクトリには、Codon を使用してネイティブマシンコードにコンパイルされるグラフアルゴリズムの実装が含まれています。ブリッジ層（codon/bridge/）は、グラフのサイズとライブラリの利用可否に応じて計算を自動的に振り分けます。

• グラフカーネル：媒介中心性／近接中心性／次数中心性、PageRank、ラベル伝播、Louvain コミュニティ検出、BFS／Dijkstra 最短経路
• データ処理：コサイン類似度、バッチベクトル演算、一貫性ハッシュ
• フォールバック：Codon ライブラリがコンパイルされていない場合、すべての操作は透過的に NetworkX／numpy にフォールバックします

Codon モジュールをコンパイルするには、次のコマンドを実行します。

./scripts/build_codon.sh

API の概要

エンドポイント	メソッド	説明
/health	GET	システムのヘルス状態（CPU／メモリ／ディスクのチェック）
/api/v1/status	GET	アプリケーションのステータス。database.ladybug_path と read_only を含みます
/auth/token	POST	JWT アクセストークン（OAuth2 パスワードフロー）
/telemetry/ingest	POST	IDE テレメトリーイベントを取り込みます（検証済みの EventType 列挙型、ISO-8601 タイムスタンプ、JSON シリアライズされたデータ）
/telemetry/list	GET	テレメトリーイベントの一覧を取得します（ページネーション対応）
/telemetry/query	GET	event_type／user_id／session_id のフィルターでイベントを検索します
/tools/topk	POST	Top-K セマンティック検索：sentence-transformers による埋め込みと、リクエストされたノードテーブルに対する array_cosine_similarity を使用します
/api/v1/analytics/*	GET	分析エンジン（中心性、コミュニティ、クラスタリング、ストリーミング、GPU ステータス）
/dashboard/*	GET	ダッシュボード API と SSE リアルタイムストリーム（/dashboard/stream/analytics）
/metrics	GET	Prometheus メトリクス

詳細なリファレンス：API ガイド。インタラクティブドキュメントは http://localhost:8080/docs で利用できます（本番環境では無効です）。

プロジェクト構成

GraphMemory-IDE/
├── server/                # FastAPI backend
│   ├── main.py            # Application entry point
│   ├── core/              # Configuration and settings
│   ├── auth/              # SSO, MFA, onboarding
│   ├── auth_jwt.py        # JWT authentication
│   ├── analytics/         # Analytics engine
│   ├── collaboration/     # Real-time collaboration
│   ├── dashboard/         # Dashboard API routes
│   ├── monitoring/        # Health checks, metrics, alerting
│   ├── security/          # Security middleware
│   ├── streaming/         # WebSocket/SSE streaming
│   ├── backup/            # LadybugDB/PostgreSQL/Redis backup orchestration
│   ├── graph_database.py  # LadybugDB integration (pool, schema, query engine, health)
│   └── init_db.py         # Graph schema initialisation (run before first start)
├── dashboard/             # Streamlit UI
├── frontend/              # TypeScript/React frontend
├── codon/                 # Codon acceleration layer
│   ├── bridge/            # Python-Codon interop with fallback
│   ├── graph_kernels/     # Native graph algorithms (.codon)
│   └── data_processing/   # Native data operations (.codon)
├── docker/                # Docker Compose configs
│   ├── docker-compose.yml # Development environment
│   ├── docker-compose.test.yml # Test services (PostgreSQL + Redis, ephemeral)
│   └── production/        # Production multi-service setup
├── tests/                 # Test suites
│   ├── integration/       # Integration tests
│   ├── production/        # Production validation
│   ├── load_testing/      # Locust load tests
│   └── smoke/             # Smoke tests
├── docs/                  # Documentation (incl. docs/migration/)
├── ide-plugins/           # VSCode, Cursor, Windsurf extensions
├── monitoring/            # Prometheus & Grafana configs
├── scripts/               # Build, deployment, and test-DB scripts
└── kubernetes/            # Kubernetes manifests

テスト

# Run all tests
PYTHONPATH=. pytest tests/ -v

# Run with coverage
PYTHONPATH=. pytest tests/ --cov=server --cov-report=html

# Run specific test categories
PYTHONPATH=. pytest tests/ -m unit
PYTHONPATH=. pytest tests/ -m integration
PYTHONPATH=. pytest tests/ -m "not slow"

登録済みのテストマーカー：asyncio、unit、integration、slow、real_time、real_services、performance、mock_data、load、external、database、authentication（--strict-markers が適用されます）。

実サービスに対する統合テスト

データベース統合テストでは、バックエンドサービスとして PostgreSQL と Redis が必要です。一時テストプロファイルでは、フィクスチャのデフォルト設定に合わせて、これらのサービスを起動します（Docker／OrbStack）。

docker compose -f docker/docker-compose.test.yml up -d
python scripts/init_test_db.py          # create the app schema in the test DB
PYTHONPATH=. pytest tests/integration/test_database_integration.py -v
docker compose -f docker/docker-compose.test.yml down -v

サービスがない場合、PG に依存するフィクスチャは正常にスキップされます。LadybugDB を使用するテストは、一時データベースに対してプロセス内で実行されるため、外部サービスは不要です。

カバレッジ目標：最低 85％。

本番環境へのデプロイ

本番環境では、複数サービス構成の Docker Compose 設定を使用します。

cd docker/production
cp env.production.template .env  # Configure environment variables
docker compose -f docker-compose.prod.yml up -d

この設定では、Nginx（リバースプロキシ）、FastAPI、Streamlit、Analytics、PostgreSQL、Redis、Prometheus、Grafana の 7 つ以上のサービスが起動します。ネットワークサブネットは分離され、リソース制限が設定されています。外部からのアクセスや管理者によるグラフアクセスには、LadybugDB の api-server サイドカー（ghcr.io/ladybugdb/api-server）を利用できます。本番環境ではバージョンタグを固定してください。

本番環境のセットアップ手順については、Docker デプロイガイドをご覧ください。

移行：Kuzu → LadybugDB

このコードベースは、Kuzu 0.10.0 から LadybugDB 0.21.2（2026-10）に移行しました。統合機能を拡張する方に向けた重要な情報は次のとおりです。

• Python API：import ladybug as lb；Connection(db) + init_connection()；結果の反復処理にはスネークケースを使用します（has_next() / get_next()。行はリストです）
• インデックス：主キー専用のハッシュインデックス（自動）。副次プロパティインデックスと FULLTEXT インデックスは 0.21.2 ではサポートされていません。フィルター処理にはゾーンマップを使用します
• ベクトル検索：array_cosine_similarity（Kuzu の list_cosine_similarity は存在しません）
• ストレージ：単一の .lbdb ファイルです。親ディレクトリが存在している必要があります（Kuzu とは異なり、LadybugDB はディレクトリを作成しません）
• CLI：lbug（brew install ladybug）；データ移行では EXPORT DATABASE / IMPORT DATABASE がサポートされています

検証済みの差異の完全な一覧は、MIGRATION_PLAN_LADYBUG.md §3 をご覧ください。デプロイ済みインスタンス向けの運用手順書は、docs/migration/KUZU_TO_LADYBUG.md をご覧ください。

ドキュメント

ディレクトリ	説明
MIGRATION_PLAN_LADYBUG.md	Kuzu → LadybugDB の移行：フェーズ、検証済み API の差異、不具合一覧
docs/migration/	運用向け移行ガイド + フェーズ検証スクリプト
docs/project/	プロジェクト概要、PRD、貢献ガイドライン、セキュリティポリシー
docs/architecture/	システムアーキテクチャ、コードパス、ネットワークフロー
docs/api/	API リファレンスとクライアントの例
docs/deployment/	Docker、Kubernetes、本番環境へのデプロイガイド
docs/development/	開発環境のセットアップ、コード品質、テスト手順
docs/operations/	システム運用とパフォーマンスの調整
docs/monitoring/	Prometheus、Grafana、アラート設定
docs/analytics/	分析システムと ML コンポーネント
docs/ide-plugins/	VSCode、Cursor、Windsurf 向けプラグイン開発
docs/user-guides/	チュートリアルとエンドユーザー向けドキュメント

貢献

開発ワークフロー、コミット規約、コードレビューのプロセスについては、貢献ガイドラインをご覧ください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE をご覧ください。