aidd-kos — Agentic Knowledge OS

uvx aidd-kos install の 1 コマンドで、AI エージェントが開発プロジェクトの 「コード・設計書・業務文脈」を横断的に理解・検索できるナレッジ OS が即座に稼働する。 LightRAG・CodeGraph 等の個別ツールを個別にセットアップ・運用する手間はない。

概要

aidd-kos は MCP Aggregator として動作し、複数のナレッジエンジンを単一の MCP エンドポイントに束ねます。

MCP ツール

アーキテクチャ

AI Agent (Claude Code / Cursor 等)
    ↓ MCP stdio（aidd-kos 1本のみ登録）
MCP Server（FastMCP + Aggregator）
    ├─ lightrag_*  ← LightRAG embedded（.lightrag/ は対象プロジェクト内）
    └─ codegraph_* ← CodeGraph proxy（.codegraph/ は対象プロジェクト内）

セットアップ

前提条件

• Python 3.10+
• uv — Python パッケージマネージャー
• mise — ツールバージョン管理
• OpenAI API キー（LightRAG のインデックス構築に必要）

インストール

対象プロジェクトのルートで 1 コマンド実行するだけで完了します:

uvx aidd-kos install

上記コマンドは以下を全自動実行します:

1. mise install でツール（Python / uv / Node.js 等）をインストール
2. uv sync で Python 依存（LightRAG / FastMCP 等）をインストール
3. CodeGraph を初期化してコードインデックスを構築
4. ~/.claude/settings.json に MCP サーバーを登録
5. LightRAG サーバーを起動してドキュメントをインデックス
6. .gitignore に .lightrag/ .codegraph/ を追記
7. 「Claude Code を再起動してください」と案内

完了後に Claude Code を再起動すると lightrag_query / codegraph_explore が使えます。

インデックス更新

インストール後、新しいドキュメントを追加・変更した場合は以下でインデックスを更新します:

# 差分インデックス（変更・追加ファイルのみ処理・デフォルト）
aidd-kos index

# 全件再構築（インデックスが破損した場合や確実にリセットしたい場合）
aidd-kos index --full

差分インデックスは LightRAG が管理するインデックス状態と比較して変更・追加・削除ファイルのみを処理するため、大規模プロジェクトでも API コストを最小化できます。

v0.2.0 → v0.2.1 以降へのアップグレード時の注意 インデックスのエンコード形式が変更されました（__ → ___）。 アップグレード後、初回の aidd-kos index は全ファイルを自動的に再エンコードします。 クリーンに再構築したい場合は aidd-kos index --full を実行してください。

環境変数

詳細: docs/playbook/secrets.md

開発

# テスト
uv run pytest

# Lint / フォーマット
task lint        # ruff check + format --check
task lint:fix    # ruff の自動修正

# Git フック（初回のみ）
lefthook install

ドキュメント

技術スタック

コントリビュート

CONTRIBUTING.md を参照してください。

ライセンス

MIT — LICENSE