コードグラフとナレッジベース

コードグラフは実験的機能です。インターフェース、データ形式、インデックス作成の動作は、今後のバージョンで変更される可能性があります。

コードグラフは、CodeGraph を使って、プロジェクト内のシンボルとその間の関係を解析します。セッションナレッジベースには、設計上の判断、制約、教訓が保存されます。この2つをコードへの参照で結び付けることで、コードの現在の構造と、その背景にある理由の両方を確認できます。

画面の構成

コードグラフは、「概要」「シンボル」「コード探索」「ファイル」の各タブを持つダイアログとして開きます。ダイアログの「ナレッジベース」ボタンで、ナレッジベースを開けます。

概要：ファイル、シンボル、関係の数、言語とシンボルの種類の分布、同期の状態（「自動同期が有効」または「クエリ前に同期」）を表示します。分布の項目をクリックすると、該当する結果が表示されます。
シンボル：名前またはファイルパスで検索します（「シンボルやファイルパスを検索…」）。シンボルのページには、シンタックスハイライト付きのソースと、関係の種類とファイルごとにまとめた「入力側の関係」と「出力側の関係」が表示されます。解析によって推定された関係には「推定された関係」と表示され、行番号をクリックすると呼び出し箇所に移動します。
コード探索：機能や処理の流れを説明するか、ファイルやシンボルの名前を指定すると、関連するソースと関係が表示されます。この照会はローカルで実行され、AI モデルは使いません。
ファイル：インデックスに登録されたファイルを参照します。ファイルをクリックすると、そのシンボルが一覧表示されます。
呼び出し元と呼び出し先：シンボルのページで、複数の階層にわたる呼び出しを表示します。「探索の深さ」はデフォルトで 3、最大で 6 です。表示される結果は最大 500 件で、それを超える場合は、総数とその旨の注意書きが表示されます。
影響分析：シンボルのページで、変更によって影響を受ける可能性のあるシンボルとファイルを、選んだ深さ（デフォルトで 3、最大で 6）まで表示します。表示されるのは最大 500 個のシンボルと 2,000 件の関係で、結果が打ち切られた場合は、総数とその旨の注意書きが表示されます。
呼び出し経路：シンボルのページで到達先のシンボルを検索すると（「到達先のシンボルを検索…」）、呼び出し関係をたどる最短経路が表示されます。「インデックスに有向の呼び出し経路が見つかりませんでした。」は、インデックスにそのような経路が含まれていないことだけを意味します。

作業ディレクトリは、ディレクトリのメニューで切り替えます。このメニューには完全なパスも表示されます。ページ、コード探索での質問、シンボル、深さ、到達先、ソースの行はすべて URL に含まれるため、ページを再読み込みしたり、新しいタブで開いたり、ブラウザの「戻る」「進む」ボタンを使ったりできます。リンクは、同じバックエンドに有効なログイン状態でアクセスした場合に機能します。

プロジェクトのインデックスを有効にする

サイドバーでプロジェクトまたはコレクションを右クリックし、「実験的機能」→「コードグラフ」を選びます。
初回は「CodeGraph をダウンロード」をクリックします。接続先のバックエンドが、バージョンが固定された CodeGraph 1.6.0 のリリースを GitHub からダウンロードし、組み込みの SHA-256 チェックサムと照合します（「ダウンロードのチェックサムが一致しません。ランタイムはインストールされていません。」は、照合に失敗したことを示します）。Node.js を別途インストールする必要はありません。
「作業ディレクトリ」を選び、「インデックスを有効化」をクリックします。プロジェクトのディレクトリと、そのセッションやグループが使うほかの作業ディレクトリは、別々に表示されます。Git のワークツリーには、それぞれ専用のインデックスがあります。コレクションでは、有効な作業ディレクトリを持つセッションが少なくとも1つ必要です。
状態が「利用可能」になるまで待ってから、シンボルやファイルパスを検索します。インデックスの作成はバックグラウンドで実行され（「インデックス処理を実行中です。このページを閉じることも、インデックスを無効にして処理を停止することもできます。」）、ページを閉じてもキャンセルされません。

「同期」を使うと、インデックスを手動で更新したり、失敗後に再試行したりできます。VelaTerm は、コードを照会する前にも毎回インデックスを最新の状態にします。同じバックエンドと作業ディレクトリでは1つの照会プロセスが再利用され、実行中はファイルの変更を随時取り込みます。照会がないまま5分が過ぎるとプロセスは終了し、次の照会でインデックスを開き直して、それまでの変更を反映します。「概要」は30秒ごとに同期の状態を更新します。自動同期を使えない場合も、VelaTerm は照会のたびに同期を行い、古い結果を最新のものとして示すことはありません。

「インデックスを無効化」は、実行中のインデックス作成タスクを停止します。インデックスファイルとナレッジ項目への関連付けは残るため、後で再び有効にできます。タスクが中断された場合は、約2分以内に、再試行できる失敗の状態に変わります（「前回の処理は中断されました。同期して再試行してください。」）。1つのインデックス作成タスクの実行時間は、最大30分です。

インデックスは各作業ディレクトリの .codegraph/ フォルダーに保存され、CodeGraph によって管理されます。インデックスの作成は VelaTerm 自身が実行し、CodeGraph のエージェント用インストーラーを実行したり、Git フックをインストールしたりすることはありません。プロジェクトのディレクトリがリポジトリのサブフォルダーである場合は、そのフォルダーだけがインデックスの対象になります。

コードの関係を見る

検索結果には、各シンボルの名前、種類、場所が表示されます。シンボルのページには、ソース、入力側と出力側の関係、関連付けられたナレッジ項目が表示されます。隣接するシンボルをクリックすると、続けてたどれます。

関係は静的解析に基づくもので、不完全または不確かな場合があります（「関係は静的解析によるものであり、不完全または不確かな場合があります。」）。実際にコードを実行して確かめることの代わりにはなりません。シンボルのページに表示されるのは、それぞれの向きで最大 200 件の関係と、最大 600 行のソースで、それを超える場合はその旨が表示されます。4 MiB を超えるソースファイルは表示されません。表示中にファイルが変更された場合、VelaTerm は行番号を頼りにする前に、もう一度同期するよう求めます。

項目の関連付けと確認

シンボルのページで「記事を関連付ける」を選び、既存の項目を選んで、その本文とコードを見比べてから保存します。項目のページの「コードへの参照」からコードに戻れます。また、コードグラフ内の項目へのリンクを開くと、項目の全文が表示されます。

関連付けには、プロジェクト、作業ディレクトリ、ファイルパス、シンボルの識別情報、確認した時点のファイルの SHA-256 ダイジェストが保存されます。ファイルが変更されると、関連付けに「要確認」と表示されます。ファイルを読み取れなくなった場合や削除された場合は「利用不可」、それ以外の場合は「変更なし」と表示されます。確認はファイル単位で行われるため、同じファイル内のどこが変更されても確認が必要になります。開いている項目のページは、定期的に参照を確認します。

「コードと記事を確認」を選ぶと現在のコードが表示され、項目の内容が引き続き正しい場合は「確認済みにする」を選びます。バックエンドは、その間にファイルと項目が変更されていないことを改めて確認し、変更されている場合は再読み込みを求めます。確認済みにしても更新されるのはコードへの参照だけで、項目の本文は変わりません。結論を変える場合は、通常どおり項目を編集してください。

シンボルが削除されたり名前が変更されたりしても、関連付けが同じ名前の別のシンボルに移ることはありません。「関連付けを削除」を使い、正しいシンボルに関連付け直してください。項目を削除すると、その関連付けも削除されます。プロジェクトを削除すると、そのインデックスの記録と関連付けは削除されますが、ほかの項目や、作業ディレクトリ内のインデックスファイルは削除されません。

セッションからの照会

VelaTerm が起動するすべてのターミナルセッションとエージェントセッションで、vkb コマンドを使えます。ターミナルのコマンドを実行できるほかのエージェントも、このコマンドを使えます。アップデート後に既存のセッションで vkb が見つからない場合は、セッションを再起動してください。

「Vela Skills」（「設定」▸「一般」）をインストールすると、Claude では /vkb、Codex では $vkb を使えます。このスキルは、ユーザーが明示的に求めたときだけ実行され、エージェントがほかの作業中に自ら呼び出すことはありません。アップデート後にエージェントがこのスキルを一覧に表示しない場合は、「Reinstall」をクリックし、そのエージェントのセッションを再起動してください。

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore は、「コード探索」と同じ結果を返します。
callers、callees、impact には、省略可能な深さを指定できます。結果には relations、total、depth、truncated が含まれます。
path には、検索結果から得た正確なシンボル ID を2つ指定します。files では、パスで絞り込めます。
search は、コードの結果（関連度順。さらに結果がある場合は hasMore が付きます）、ナレッジ項目、ローカルのノートを分けて返します。
node は、シンボルのソース、関係、関連付けられた項目を返します。
memories と memory は、セッションナレッジベースの項目を、出典、版、コードへの参照も含めて検索し、読み取ります。
notes と note は、ローカルナレッジベースを検索し、読み取ります（ローカルナレッジベースを参照）。

コードの照会には、コマンドを実行したディレクトリのインデックスが使われます。サブフォルダーではそのプロジェクトのインデックスが使われますが、入れ子になった別のワークツリーが、メインのチェックアウトのインデックスを借用することはありません。インデックスが有効になっていない場合や照会に失敗した場合は、コードを利用できないことが結果に示されますが、ナレッジの照会は引き続き使えます。これらのコマンドが何かをインストールしたり、インデックスを有効にしたり、項目を変更したりすることはありません。

データの保存場所

CodeGraph のランタイムは、アプリケーションのデータディレクトリの codegraph/1.6.0/ にインストールされます。インデックス作成のタスクと項目の関連付けは、アプリケーションのデータベース（knowledge_* テーブル）に保存されます。インデックスの作成は、コードがあるバックエンドで実行されます。ブラウザのクライアントと SSH 接続では既存の接続を通じて結果を読み取るため、追加のポートは開きません。インデックスの設定とナレッジベースは、バックエンドごとに個別に保持されます。

CodeGraph のテレメトリー、更新の確認、独立したバックグラウンドサービスは無効にしています。VelaTerm は照会プロセスを管理し、ポートで待ち受けることなく、専用の標準入出力のチャネルを通じてプロセスとやり取りします。インデックスの作成自体に AI は使いません。エージェントが vkb で読み取ったコードや項目は、エージェントがソースファイルを読み取る場合と同じように、そのエージェントに設定されたモデルのサービスに送信されることがあります。

コードグラフのイベントは、アプリケーションのデータディレクトリにある logs/runtime-*.log に書き込まれます。VLX_LOG_DIR が設定されていない場合は、VLX_KNOWLEDGE_LOG_DIR で出力先ディレクトリを指定します。VLX_KNOWLEDGE_LOG_LEVEL でイベントを絞り込めます（error や off など）。ログには、ソースコード、照会のテキスト、項目の本文、認証情報は含まれません。

CodeGraph は github.com/colbymchenry/codegraph で開発されており、MIT ライセンスで公開されています。