Leankg

LeanKG

AI コーディングエージェント向けのエンタープライズ対応コードナレッジグラフ
マルチリポジトリ · 環境ガバナンス · インシデントとサービス · 要件↔コード · トークンを65%削減／ツール呼び出しを85%削減

ライブデモ · ドキュメント · pkg.go.dev · 変更履歴

---

LeanKG とは？

LeanKG は AI コーディングエージェント向けのコードナレッジグラフです。単一の CGO フリーな Go バイナリとして提供されます （github.com/FreePeak/LeanKG、ルートモジュール。pkg.go.dev を参照）。 通常、エージェントは grep → ファイルを開く → 膨大なコンテキストという手順で構造を再構築しますが、LeanKG は MCP 経由で 対象を絞ったサブグラフ（呼び出し元、依存先、影響範囲、テスト、ドキュメント）に加え、チームレイヤー（環境、 サービス、インシデント、要件）を返します。Rust エンジンは互換性達成時に削除されました。 make go-build でビルドし、make go-test でテストを実行してください。互換性の記録については docs/prd.md を参照してください。

なし	LeanKG を使用
ツール呼び出しが多く、コンテキストが大きい	的を絞ったサブグラフ + TOON（ペイロードを約40%縮小）
影響範囲がわからない	重大度別の影響評価
キーワードのみ	キーワード + HNSW セマンティック検索 + オントロジー
単一リポジトリを推測	マルチリポジトリのインデックス + 運用ツール

はじめに

# 1. Per project: one-shot index, then an incremental embed (sqlite default — zero config,
#    store at .leankg/leankg.db). In a git repo root it reads the HEAD commit's objects, so
#    uncommitted, untracked and ignored files are not indexed. Add --no-embed to skip the embed.
cd your-project
leankg index .

# 2. Wire up an AI client — one command (claude-code | cursor | codex | gemini | opencode | omp).
#    The stdio entry is `serve --stdio --memory`: the agent gets the code graph AND the
#    markdown memory layer (per-project at <project>/.leankg/memory), no second server.
leankg install --target claude-code  # `connect claude-code` is the same writer
#    Restart the client afterwards so it picks the entry up.

# 3. ...or serve MCP over HTTP yourself (endpoint /mcp; GET /health returns 200 when ready)
leankg serve --http 127.0.0.1:9699 --rest 127.0.0.1:8080 --memory
leankg install --target claude-code --http --url http://127.0.0.1:9699/mcp

セマンティック検索（L3）は唯一のオプションレイヤーで、埋め込みが必要です。 LEANKG_EMBED_PROVIDER を設定してください（docs/embedding.md と .env.example を参照）。その後、leankg index を実行すると、 インデックス作成後に段階的に埋め込みが行われます。埋め込みを実行するまでは、クエリには完全一致と ファジーマッチの結果が返されます。

デプロイを自己診断するには、leankg doctor を実行します。ストアのパス、要素数と ファイル数、書き込みウォーターマークが表示されます（終了コード 0 は成功、2 は失敗）。

HTTP 経由の MCP：サーバーはプロセスの作業ディレクトリからプロジェクトを特定します。 チェックアウトディレクトリから実行するか、--project DIR を渡してプロジェクトを固定してください。

インストール

不要です。デフォルトのストレージエンジンは sqlite です。Postgres も Docker も必要ありません。

Postgres は明示的にオプトインする場合（LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL）に引き続き利用でき、大規模なサーバーへのデプロイに対応しますが、デフォルトの手順では一切使用しません。

公開モジュール — エンジンは Go モジュールのため、ツールチェーンは pkg.go.dev から両方のバイナリを $(go env GOPATH)/bin に直接インストールします。

go install github.com/FreePeak/LeanKG/cmd/leankg@latest         # server + CLI
go install github.com/FreePeak/LeanKG/cmd/leankg-embed@latest   # embedding pipeline

ビルド済みアーカイブ — リリースには、linux/darwin × amd64/arm64 向けの leankg-<os>-<arch>.tgz が含まれています。アーカイブのルートには両方のバイナリと .sha256 が格納されています。leankg update も同じチャンネルを使用します。

チェックアウトからのインストール — Go 1.25+ と git が必要です。インストール先は ~/.local/bin です（変更するには PREFIX を渡します）。

git clone https://github.com/FreePeak/LeanKG.git && cd LeanKG
scripts/install-go.sh                # or: make install-go

# Or fetch and run the installer directly (clones over HTTPS, same behavior):
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install-go.sh | bash

コンテナー — Dockerfile は、3 段階の CGO 不使用ビルドです。まずエンジンのバイナリを作成し、次にこのリポジトリの一部からデモグラフを組み込み、最後にそのストアを読み取り専用で提供する、非特権のランタイムを作成します。

docker build -t leankg .
docker run --rm -p 8080:10000 -e PORT=10000 leankg   # dashboard + its /api on :8080

MCP のインターフェース

query で検索します。デフォルトでは段階的に処理が進み（L1 完全一致 → L2 キーワード → L3 セマンティック）、自然言語の質問は L1 で一致しなかった場合に L3 へ直接進み、キーワードとベクトルの順位を統合します。エラーではなく段階的に機能を縮退させ、すべての回答に retrieval{rung,reason} と freshness が含まれます。

質問	方法
任意の識別子（デフォルト）	query "Alpha"（完全一致、その後にあいまい検索）
セッション開始時のメモリ	query action=memory args.command=session_recall
セッション終了時の保持	import action=memory command=session_retain
影響範囲	leankg impact <file> または query --action impact --to <qn>
X を呼び出すのは？	query --action callers --to <qn>
A↔B の経路は？	query --action path --to <qn>
要素の詳細	query --action explain --to <qn>
パターン検索	query --action pattern --pattern "func $_(...)"
PRD のトレーサビリティ	leankg prd-trace FR-3T-01
ファイル（圧縮）	query --action read --path src/main.go

ツールは 3 つあります。import（インデックス／PRD／メモリ／セッション／オントロジー／読み取り）・query（段階的検索 + グラフ動詞 + アクション）・status（インベントリ／鮮度／設定）。

特徴

• MCP ネイティブ — 検索、影響範囲、呼び出しグラフ、オントロジー、アーキテクチャ、チームのナレッジ
• デフォルトは SQLite（設定不要 — Postgres や Docker は不要）。Postgres/pgvector バックエンドもオプトインで利用できます（LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL）
• オントロジー — 概念カタログ + 手続きレイヤー（ワークフロー、ステップ、意思決定ポイント、障害モード）、query --action ontology、POST /api/v1/ontology/match、および leankg prd / prd-trace による要件↔コードのトレーサビリティ
• 影響範囲と依存関係 — contains、calls、imports エッジ。BFS による影響範囲の算出（leankg impact）
• マルチリポジトリサーバー — MCP HTTP 127.0.0.1:9699。LEANKG_PROJECT_DIRS を使うと複数のプロジェクトに対応し、?project=<dir|name>（REST および MCP）または MCP の project ツール引数でリクエストごとにプロジェクトを選択できます。どちらも指定されていない場合、誤ったグラフから応答しないよう、複数プロジェクトのサーバーはリクエストを拒否します。デフォルトは sqlite、PG はオプトイン
• 環境変数のガバナンス — query --action env_conflicts、環境ごとのスナップショット、leankg obsidian
• 運用とオーナーシップ — query --action service_context / incidents、leankg incident / note / team-map
• 要件 ↔ コード — leankg prd / prd-trace、query --action prd、オントロジーのトレーサビリティマトリクス
• Web UI v2 — Force / Tree / Circles エクスプローラー（cd ui-v2 && npm run dev。組み込みビルドは leankg serve --ui で提供されます）
• デプロイ — CGO 不使用の単一バイナリで、実行時の依存関係はありません。Dockerfile は Render 用の読み取り専用デモイメージをビルドし、/health はコンテナのプローブに応答します。また、--ui / --http / --rest / --rpc はそれぞれ独自のアドレスにバインドします
• 対応言語 — 40 のプロファイル：Go、Rust、TypeScript/TSX、JavaScript/JSX、Python、Markdown、Java、Kotlin、Swift、Objective-C、Dart、C/C++、C#、PHP、Ruby、Scala、Perl、Lua、Haskell、Elixir、Crystal、CUDA、Cypher、Elm、Erlang、F#、GLSL、HLSL、Nim、OCaml、SQL、PowerShell、Q#、Solidity、SystemVerilog、Verilog、Zig
• エージェントの効率 — A/B 比較でトークン −65%、ツール呼び出し −85%、grep/cat と比べて 2.5 倍。この分野の他のツールは、主に個人向けまたは単一リポジトリ向けです。詳細分析（アーカイブ）：競合分析 · Graphify との ROI 比較 · 調査マトリクス

埋め込み

セマンティック（L3）検索には埋め込みが必要です。プロバイダー（local / openai / deterministic）、EmbeddingGemma 2 + Hugging Face Storage Bucket の一括処理パス、および .env.example の変数一覧については、docs/embedding.md を参照してください。カタログの行（モデル ID、固定リビジョン、次元数、プレフィックス）は internal/embed/catalog.go にあります。

パフォーマンス

• Go のコールド起動から初回価値提供までの時間 — 17.8s（macOS arm64）。CI の予算は 300s で、ゲートは .github/workflows/ci.yml の「Cold TTFV」、実行ごとの数値は ttfv-go-cold アーティファクトにあります。
• クイックスタートの正常系 — 生成した 10 ファイルの Go フィクスチャで、ウォーム状態では 1.4s（インデックス作成 0.05s、サーバーバインド 1.08s、初回クエリ 0.05s、doctor 0.03s）。scripts/quickstart_smoke.sh は同じ手順をローカルで実行します（QUICKSTART_DRY_RUN=1 で計画を表示します）。

CLI

leankg index .                          # one-shot index + incremental embed -> .leankg/leankg.db (--no-embed skips the embed)
leankg index --hook <dir>               # SessionStart mode: skips over LEANKG_HOOK_MAX_FILES (10000) files or LEANKG_HOOK_MAX_EMBED (500) elements needing vectors
leankg writer                           # index once, then watch; a git-backed store re-indexes on each new commit (unsaved edits do not change the graph)
leankg query "parseConfig"              # name lookup (exact, then fuzzy) — JSON out
leankg query "parseConfig" --compress   # one line per result
leankg impact src/main.go --depth 3     # blast radius of a file or element
leankg status                           # health, inventory, freshness, embed state
leankg doctor                           # store path, element/file counts, watermark
leankg connect claude-code              # MCP entry: claude-code|cursor|codex|gemini|opencode|omp
leankg install --target cursor          # same wiring, flag form (--register-cwd: async claude-code SessionStart hook running `index --hook`)
leankg serve --stdio                    # MCP over stdio (what harnesses spawn)
leankg serve --http 127.0.0.1:9699      # MCP over streamable HTTP (/mcp, /health)
leankg serve --rest 127.0.0.1:8080      # REST API (/health, /api/v1/*)
leankg serve --ui 127.0.0.1:8081        # embedded dashboard (/api/* data API served here)
leankg serve --rpc 127.0.0.1:9090       # ConnectRPC (gRPC + gRPC-Web + JSON)
leankg version

ループバック以外へのバインドは拒否されます。 leankg serve --http/--rest/--rpc <non-loopback> は、ベアラートークンが設定されていない場合、エラーで終了します。トークンがないと、すべての呼び出し元が Admin として解決されるため、プロジェクトグラフ、ファイルリーダー、メモリ書き込み経路がすべて LAN に公開されるからです。解決策は 2 つあります。ループバックアドレス（デフォルト）にバインドするか、先にトークンを設定します （leankg auth token create、または LEANKG_TOKEN_ADMIN / LEANKG_TOKEN_CONTRIBUTOR / LEANKG_TOKEN_VIEWER）。--ui は意図的に公開される唯一のリスナーです（コンテナのデモでは、破棄可能な事前構築済みグラフに対して --read-only で提供されます）。そのため、拒否ではなく警告を表示します。

UI のホットリロード：cd ui-v2 && npm install && npm run dev → http://127.0.0.1:5173

使用方法の全容：leankg help および leankg <command> --help。CLI リファレンス（アーカイブ）：docs/archive/cli-reference.md

既知の制限事項

• 呼び出しエッジの範囲はパッケージ単位です。 インポートや型の解決は行わないため、同一パッケージ内の同名の呼び出しは解決されますが、パッケージをまたぐディスパッチはベストエフォートです。今後の拡張では tree-sitter のシンボルテーブルを使用する予定です。
• internal/index/relations.go のヒューリスティックによるガード：ベンダー提供または縮小済みのバンドルとみなされる 1 MiB 以上のファイルはスキップされ、ノイズとして 4 文字未満の呼び出し先は除外されます。また、要素ごとおよびファイルごとに、発信する呼び出し数に上限を設けています。
• スコープの単位はリポジトリです。 数万件のネストされたファイルを含むポートフォリオのルートはプロジェクトではありません。子ディレクトリを 1 つずつ登録してください。
• --ui は認証されていないデータ API（query／read／インポート用ルート）を公開します。ループバックにバインドするか、プロキシの背後に配置してください。公開デモ用コンテナーでは、使い捨てのビルド済みグラフに対して --read-only で提供しています。

トラブルシューティング

問題	対処方法
違うプロジェクトが提供される	--project DIR を指定してサーバーを起動します（query／impact も LEANKG_PROJECT を参照します）
埋め込み／初回の埋め込み	leankg-embed status を実行し、続けて leankg-embed full を実行します（プロバイダー環境変数：LEANKG_EMBED_*）

要件： macOS または Linux · ソースからビルドする場合のみ Go 1.25 以降が必要です。Docker は不要で、Postgres も不要です。デフォルトのストアには sqlite を使用します。

ドキュメント

ドキュメント一式は docs/ にあります。統合された PRD（docs/prd.md）とタスクトラッカー（docs/prd-task-tracker.md）で構成されています。過去の設計ドキュメント、分析、レポート、計画はすべて docs/archive/ に保存されています。

ドキュメント
PRD	統合された製品要件 + HLD（単一の SoT）
タスクトラッカー	完了／進行中／未着手
アーキテクチャ（アーカイブ）	設計とデータモデル（過去の資料）
MCP ツール（アーカイブ）	ツールカタログ（過去の資料）
CLI（アーカイブ）	すべてのコマンド（過去の資料）
ベンチマーク（アーカイブ）	方法論（過去の資料）
埋め込み	プロバイダー + EmbeddingGemma 2／Hugging Face の一括処理パス
AGENTS.md	エージェント向けメモ

コントリビューション

1. フォークして機能ブランチを作成します（ワークツリーの利用を推奨）
2. 動作を変更した場合はドキュメントを更新します
3. go build ./... && go vet ./... && go test ./...
4. 概要とテスト計画を添えて PR を作成します

ライセンス

Apache License 2.0