kg - AIアシスタント向けローカル知識グラフ

ベータ版 - APIは変更される可能性があり、いくつかのバグがまだ予想されます。

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

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

アシスタントに既存のプロジェクトをセッションをまたいで理解させたい場合に使用します。毎回ゼロから始める必要はありません。

なぜ使うのか

• 永続メモリ — 会話間でプロジェクト知識を保持

• 構造化され、曖昧ではない — ノード、エッジ、事実、ギャップを直接検査

• 編集・レビュー可能 — グラフを *.kg ファイルとして保存し、差分を読みやすく

• ローカルファースト — プロジェクトメモリはGitに適した形式でマシン上に保持

• MCPクライアントと連携 — ローカルのstdio MCPサーバーとして接続

Related MCP server: Agentic Memory Server

単なる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

主要な動詞

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++ のシンボルを抽出し、生成された構造を手動グラフとは別に保持します。

マークダウン風のドキュメントについては、セクションコンテンツを含むドキュメント（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 グラフでリトライを制御するルールは何ですか？"

• "注文データストアに書き込むシステムはどれですか？"

• "このグラフで欠けている点や弱い点は何ですか？"

• "認可フローを説明するノードとエッジはどれですか？"

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

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

プロンプト例：

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 - 一般的な問題

連絡先

質問やフィードバックは: nnar10@proton.me