kg

kg - AI アシスタント向けローカルナレッジグラフ

ベータ版 - API は今後変更される可能性があり、いくつかのバグも残っている可能性があります。

kg は、ナレッジグラフとしてローカルに保存された、永続的で構造化され、編集可能なプロジェクトメモリを AI アシスタントに提供します。

ドキュメントのチャンク検索だけに頼るのではなく、アーキテクチャ、決定事項、インシデント、ルール、依存関係、ワークフローを、読みやすく、レビュー可能で、Git と親和性の高いグラフに保持できます。

セッションをまたいで既存のプロジェクトをアシスタントに理解させ、毎回ゼロから始めさせたくない場合にご利用ください。

利用する理由

• 永続的なメモリ — 会話をまたいでプロジェクトの知識を保持します
• 曖昧さのない構造化 — ノード、エッジ、事実、未解決の点を直接確認できます
• 編集・レビュー可能 — 読みやすい差分を確認できる *.kg ファイルとしてグラフを保存します
• ローカル優先 — プロジェクトメモリは Git と親和性の高い形式でマシン上に保持されます
• MCP クライアントで利用可能 — ローカル stdio MCP サーバーとして接続できます

RAG だけでは不十分な理由

従来の RAG は、ドキュメントからテキストチャンクを検索するのに適しています。

kg-mcp は、次のような場合に適しています。

• 繰り返し検索するのではなく、安定したプロジェクトメモリが必要な場合
• 明示的な事実、関係、依存関係が必要な場合
• アシスタントと実際に作業しながらグラフを更新したい場合
• グラフを確認、バージョン管理、差分比較し、時間をかけて改善したい場合

インストール

crates.io から

cargo install kg-cli

スクリプトから

推奨インストール方法：

curl -sSL https://raw.githubusercontent.com/nnar1o/kg/master/install.sh | sh

GitHub Releases からすぐに使えるバイナリをダウンロードすることもできます。

kg-mcp を AI クライアントに接続する

kg-mcp をローカル stdio MCP サーバーとして追加します。

設定例：

{
  "mcpServers": {
    "kg": {
      "command": "/absolute/path/to/kg-mcp"
    }
  }
}

その後、次の手順を実行します。

1. AI クライアントを再起動します。
2. kg MCP サーバーが利用可能であることを確認します。
3. 以下のプロンプトを使い始めます。

MCP の設定とリファレンスの全文： docs/mcp.md

SCL クイックスタート

kg は、動詞から始まる短い英語コマンド（SCL — Simple Command Language）を理解します。 アクティブなグラフは、設定から自動的に特定されます。

find "compressor defrost"
get concept:refrigerator
add concept:smart_fridge --name "Smart Fridge" --description "Connected refrigerator"
modify concept:smart_fridge --importance 0.9
remove concept:old_idea
connect process:compressor_control TRIGGERS process:auto_defrost
disconnect process:compressor_control TRIGGERS process:auto_defrost
list nodes
stats
use fridge
help

主な動詞

動詞	機能
find <query>	テキストでノードを検索します
get <id>	ID でノードを 1 つ取得します
add <id> --name "Name"	ノードを作成します（型は ID のプレフィックスから推定されます）
modify <id> --field value	ノードのフィールドを更新します
remove <id>	ノードを削除します
connect <src> <REL> <dst>	エッジを作成します（別名：add edge）
disconnect <src> <REL> <dst>	エッジを削除します（別名：remove edge）
list nodes|edges|types|relations|graphs	グラフの内容を一覧表示します
stats	グラフの統計情報を表示します
use <graph>	アクティブなグラフを切り替えます
help [verb]	動詞またはすべての動詞のヘルプを表示します
feedback <uid> yes|no|nil|pick <n>	検索結果にフィードバックを送信します
strict	以降の行でデフォルトを無効にします

ID

形式：<type>:snake_case — 例：concept:fridge、bug:door_seal、process:compressor_cycle。

関係

HAS USES STORED_IN TRIGGERS CREATED_BY AFFECTED_BY AVAILABLE_IN DOCUMENTED_IN DEPENDS_ON TRANSITIONS DECIDED_BY GOVERNED_BY READS_FROM

ヒント

• フラグは位置引数の後に指定します。複数語の値は引用符で囲みます。
• コマンドは ; または改行で区切ります。# で始まる行はコメントです。
• スクリプト内でグラフを切り替えるには、use <graph> を使います。
• 正式な kg <graph> node find ... コマンドもフォールバックとして引き続き使えます。
• SCL リファレンスの全文： docs/scl.md

グラフを生成する

新しいプロジェクトで最初に行うワークフローです。ドキュメントからグラフを作成または拡張するよう、アシスタントに依頼します。

デフォルトでは、グラフは ~/.kg/graphs に *.kg ファイルとして保存されます。

最小限のプロンプト：

You are connected to kg-mcp.

Project graph name: payments

Build or extend this graph from the project documentation I provide.
Use `payments` as the graph name for all graph operations.

Only add facts grounded in source material.
If an important fact is missing and can be inferred safely from the provided docs, update the graph.
If something is ambiguous, ask or record it as a note instead of inventing facts.

ドキュメントを含むプロンプトの例：

Use kg-mcp to build or extend the `payments` graph from these documents:
- docs/payments/overview.md
- docs/payments/retries.md
- docs/payments/providers.md

Only add facts grounded in the documents.
If something is ambiguous, keep it out of the graph or record it as a note.
When you finish, summarize what was added, what remains unclear, and what document should be ingested next.

このワークフロー用の詳細なプロンプト： docs/ai-prompt-graph-from-docs.md

すぐに使えるリポジトリの例を生成するには、cargo run --bin repo-example を実行して、このリポジトリから repo-example.kg を生成します。

ディレクトリ用の自動グラフ

kg は既存のフォルダーを自動的にグラフに変換できます。ディレクトリーツリーをスキャンし、一般的な多くのファイル形式を認識して、Rust、Java、JavaScript/TypeScript、Python、C/C++ のシンボルを抽出し、生成された構造を手動のグラフとは別に保持します。

Markdown 形式のドキュメントについては、セクションの内容を含むドキュメント（GDOC）ノードと章（GSEC）ノードも作成します。

コードベースやワークスペースのすべてを手作業でモデル化せずに、実用的なマップをすばやく作成できます。生成されたインデックスはローカルに保存され、更新可能で、git の管理対象から安全に除外できます。

例：

cargo run --bin repo-example

このリポジトリから repo-example.kg を生成し、ローカルデモとして使用します。

グラフ内の事実についてアシスタントに質問する

グラフができたら、通常のワークフローでは、アシスタントにグラフを調べて、そこから質問に答えてもらいます。

プロンプトの例：

Use kg-mcp to inspect my existing `payments` graph.

I want to understand:
- how payment authorization works,
- what triggers retries,
- which external providers are involved,
- which datastore reads and writes are part of the flow.

If the graph is missing critical information, say exactly what is missing.

ほかに役立つ質問：

• 「payments グラフでリトライを制御するルールは何ですか？」
• 「orders データストアに書き込むシステムはどれですか？」
• 「このグラフで不足している点や弱い点は何ですか？」
• 「認可フローを説明するノードとエッジはどれですか？」

アシスタントを通じて事実を追加または更新する

作業中に、グラフを改善するようアシスタントに依頼することもできます。

プロンプトの例：

Use kg-mcp to review my existing `payments` graph.

Find:
- missing important nodes,
- weak descriptions,
- missing facts,
- suspicious or low-value edges.

Apply safe improvements where possible.
Only add facts grounded in the graph, the provided docs, or the current discussion.
If something is ambiguous, leave it out or add a note.

When you finish, summarize:
- what was wrong,
- what you changed,
- what still needs manual review.

メインのシステムプロンプトやプロジェクトプロンプトで、プロジェクトに対応するグラフをアシスタントに伝えておくと、最も効果的です。

プロジェクトレベルの最小限のプロンプト：

You are connected to kg-mcp.
Project graph name: payments.
Use this graph for relevant reads and updates in this project.
If you notice important missing information that is grounded in the available docs or conversation context, update the graph as part of your work.
If uncertain, ask or add a note instead of inventing facts.

ヒント

プロジェクト設定（.kg.toml）

kg は、現在のディレクトリと親ディレクトリから .kg.toml を探します。

例：

backend = "json" # json backend writes native .kg files by default
graph_dir = ".kg/graphs"
graph_dirs = ["../shared-graphs", "../team-graphs"]
nudge = 20
user_short_uid = "dev_01"

[graphs]
payments = "graphs/payments.kg"

注意事項：

• backend = "json" はデフォルトで、.kg テキストグラフを優先します。
• backend = "redb" は、グラフを .db ファイルに保存します。
• graph_dir は、優先するグラフディレクトリを設定します。
• graph_dirs は、kg list とグラフ解決でスキャンされるディレクトリを追加します。

グラフを Git で管理する

デフォルトのグラフディレクトリは ~/.kg/graphs です。

このディレクトリを git の管理下に置くことができます。

推奨される方法：

• メインの *.kg グラフファイルを git で管理します。
• 生成されたサイドカーファイルとローカルの運用ファイルは除外します。
• 明示的にバージョン管理する場合を除き、バックアップスナップショットとイベントログはローカルマシンの履歴として扱います。

.gitignore の例：

*.kglog
*.kgindex
*.event.log
*.migration.log
*.bak
*.bck.*.gz

実際には、次のようになります。

• *.kg は、通常レビューしてコミットするメインのグラフファイルです。
• *.kglog は、ローカルのアクセス／フィードバックログです。
• *.kgindex は、ローカルで生成されるインデックスです。
• *.event.log は、ローカルに追記される変更履歴です。
• *.bak は、最後の書き込み前にディスク上にあったバージョンです。
• *.bck.*.gz は、定期的に作成される圧縮バックアップスナップショットです。
• *.migration.log は、古いグラフを変換したときの移行レポートです。

*.kg は git で扱いやすい形式で、差分を読みやすくし、複数人が同じグラフで作業する際にマージしやすいよう、意図的に構造化されています。

グラフを HTML にエクスポートする

グラフのインタラクティブな HTML ビューを生成するには：

kg graph payments export-html --output payments.html

生成した HTML を、現在のグラフの共有可能なビジュアルスナップショットとして保存できます。

ドキュメント

• docs/mcp.md - MCP のセットアップとツールのリファレンス
• docs/ai-prompt-graph-from-docs.md - ドキュメント取り込み用の詳細なプロンプト
• docs/build-graph-from-docs.md - ドキュメントからグラフを作成するワークフロー
• docs/troubleshooting.md - よくある問題

お問い合わせ

質問やフィードバックはこちらまで：[email protected]