メインコンテンツへ移動
AIチュートリアル

Graphicleでコーディングエージェント向けのローカルコードグラフとメモリを構築する

Graphicleのインストール方法、コーディングエージェントとの接続方法、リポジトリのコードグラフの構築方法、引用元付きコンテキストの検索方法、依存関係の確認方法、モデルの設定方法、プロジェクトの知識をローカルで最新に保つ方法を解説します。

約13分で読了
Graphicleでコーディングエージェント向けのローカルコードグラフとメモリを構築する

Graphicleとは？

Graphicleは、リポジトリのコードグラフとコーディングエージェント向けのプロジェクトメモリを組み合わせた、ローカルで動作するRustプログラムです。ファイル、関数、クラス、呼び出し、インポートをインデックス化するとともに、ドキュメント、決定事項、手順、過去のエージェントセッションも記憶します。

エージェントや開発者が質問すると、Graphicleはソースファイルと行範囲を特定する引用付き抜粋を返します。コードグラフとコアコンテキストツールはAPIキーやアカウントなしで動作し、明示的にモデルやコネクターを設定してデータ送信が必要にならない限り、Graphicleがデータを外部に送信することはありません。

GraphicleはClaude Code、Cursor、Codex、VS Code、Claude Desktop、その他のMCPクライアントに対応しています。コマンドラインインターフェース、MCPサーバー、ブラウザーアプリ、単一のSQLiteベースのデータストアを提供します。

主な機能

  • コードグラフ：tree-sitterベースのパーサーを使って、ファイル、シンボル、呼び出し、インポート、パス、影響を受けるコードを探索できます。
  • プロジェクトメモリ：Markdown、PDF、Office、HTMLのドキュメント、レビュー済みの決定事項、手順、記録されたエージェントセッションを検索できます。
  • 引用付きコンテキスト：モデルを呼び出さずに、トークン予算内でコードとプロジェクト知識から関連する抜粋を取得できます。
  • エージェント連携：1つのセットアップコマンドで、対応するコーディングエージェントをMCP経由で接続できます。
  • コードと結び付いたメモリ：レビュー済みのメモリを説明対象の関数に紐付けることができ、そのコードが変更されると古くなります。
  • ローカル優先の動作：データはローカルに保存され、エンドポイントはデフォルトでループバックで待ち受けます。Graphicleはテレメトリーもアカウントも使用しません。
  • 自動同期：回答前に変更されたファイルを同期し、Gitフックによってコミット、マージ、チェックアウト後にも同期できます。

Graphicleをインストールする

Graphicleは現在、macOSとLinuxに対応しています。macOSまたはHomebrewを利用できるLinuxシステムで最も簡単なインストール方法は次のとおりです。

brew install graphicle-ai/tap/graphicle

Homebrewを利用できない場合は、リリース用インストーラーを使用します。

curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh

GitHubのリリースページから、プラットフォーム固有のアーカイブをダウンロードすることもできます。ネイティブのWindowsサポートは現在利用できませんが、READMEには、Linux向けのインストールがWSL2上で動作する可能性があるものの、まだテストされていないと記載されています。

リポジトリをセットアップする

エージェントに理解させたいリポジトリに移動し、セットアップを実行します。

cd your-repo
graphicle setup

セットアップ処理では、リポジトリをインデックス化してコードグラフを構築し、検出したコーディングエージェントを接続します。マシンにインストールされているクライアントに応じて、Claude Code、Codex、Cursor、VS Code、Claude Desktop、その他のMCPクライアントのMCP設定を更新できます。

セットアップでは、セッションの記録も有効化し、Claude Codeの検索先をコードグラフに設定し、AGENTS.mdに短いセクションを追加し、プロジェクトを最新の状態に保つためのGitフックをインストールします。Graphicleは変更・作成するすべてのファイルを一覧表示し、変更前にバックアップを作成します。対話形式のプロンプトなしでセットアップを実行するには、次のコマンドを使用します。

graphicle setup --yes

連携による変更を元に戻すには、次のコマンドを実行します。

graphicle disconnect

disconnectコマンドは、セットアップで追加されたものを削除します。リポジトリに既存のGraphify出力ディレクトリは削除しません。

ターミナルから質問する

セットアップ後、graphicle askを使ってリポジトリを検索します。

graphicle ask "where is tax added to prices?"

Graphicleは、ファイル名、行範囲、シンボル、抜粋を含む根拠を返します。結果は次のようになります。

Evidence for "where is tax added to prices?"
4 excerpts · 598 of 3,000 tokens

[1] shop/pricing.py:1-7  price_with_tax()
    """Prices and tax."""
    TAX_RATE = 0.2

    def price_with_tax(price):
        """A price with the sales tax added."""
        return round(price * (1 + TAX_RATE), 2)

モデルを設定していない場合、askは根拠を表示します。Graphicleに文章による回答を追加させるには、Anthropic、OpenAI、Ollamaなど、対応するモデルプロバイダーを設定します。

graphicle config set model anthropic

Ollama経由のローカルモデルと、OpenAI互換サーバーにも対応しています。モデル設定については、設定ドキュメントを参照してください。

エージェントでGraphicleを使う

graphicle setupによってMCPクライアントを接続したら、リポジトリに関する質問でGraphicleを使うようコーディングエージェントに依頼します。例えば、次のように指示します。

Graphicleを使って、失敗したリクエストがどこで再試行されるかを探してください。

エージェントはGraphicleのコードグラフツールとメモリツールを使用し、引用付き抜粋を受け取り、それらの結果を独自の推論と組み合わせられます。Graphicleは、コードグラフツールとメモリツールを含む1つのMCPサーバーを公開します。グラフツールには、query_graph、get_neighbors、shortest_pathなどの名前があります。

グラフとプロジェクトメモリを閲覧する

Graphicleのブラウザーアプリを開くには、次のコマンドを実行します。

graphicle open

アプリでは、コードグラフ、ソース資料、プロジェクトメモリを閲覧できます。また、提案されたメモリをレビューして承認する場所でもあります。

インストールと連携を対象にヘルスチェックを実行するには、次のコマンドを使用します。

graphicle doctor

エージェントが接続できない場合、同期が不完全と思われる場合、または設定済みの環境を確認したい場合は、doctorを使用してください。

依存関係と影響を受けるコードを探索する

Graphicleでは、コードのみのグラフを構築してクエリできます。まずグラフを抽出します。

graphicle graph extract . --code-only

次に、どのコードがシンボルに依存しているかを確認します。

graphicle graph affected "retry()"

graph コマンドでは、リポジトリの検索、シンボルの説明、パスの追跡、インタラクティブな HTML グラフのエクスポートができます。--code-only モードではモデルは必要ありません。

Graphicle は、プロジェクトドキュメント内のコードへの言及を、参照先の定義に関連付けることもできます。ドキュメント間のリンクを一覧表示するには、ドキュメントリンク用の graph コマンドを使用します。

graphicle call graph.doc_links

回答モデルなしでコンテキストを取得する

context コマンドは、コード、ドキュメント、セッション、レビュー済みメモリから関連する抜粋を取得します。モデルは呼び出しません。

graphicle context

複数のリポジトリを含むワークスペースでは、ワークスペース全体からコンテキストを取得できます。

graphicle context --workspace

これにより、あるリポジトリの実装が別のリポジトリのドキュメントやソースコードに依存している場合にも Graphicle を活用できます。ワークスペースの MCP 設定については、MCP ドキュメントを参照してください。

同期とプライバシーを理解する

同期中、Graphicle は .gitignore を尊重し、環境ファイル、キー、認証情報をスキップします。セッションの取り込みでは、<private>...</private> スパン内のコンテンツを削除し、認証情報をマスキングします。

macOS では、主なローカルデータフォルダーは ~/Library/Application Support/Graphicle です。Linux では ~/.local/share/graphicle です。graphicle graph extract で作成したグラフは、プロジェクト内の .graphicle/ に書き込まれます。

アプリ、HTTP エンドポイント、MCP エンドポイントは、デフォルトで 127.0.0.1 をリッスンします。ネットワークアクセスが発生するのは、設定済みのモデルやコネクター、ドキュメントや画像を LLM に送信する完全なグラフ抽出、GitHub CLI の一部の操作、更新フィードなど、ネットワークを必要とする機能を要求した場合だけです。

高度なヒント

回答を根拠に基づいたものにする

Graphicle が引用する抜粋を使い、エージェントの主張を正確なファイルと行に照らして確認してください。これは、デバッグ、見慣れないリポジトリの理解、変更のレビューに特に役立ちます。

提案されたメモリを確認する

エージェントが提案したメモリは、自動的に信頼済みのプロジェクト知識になるわけではありません。承認する前にアプリで確認してください。コードシンボルに紐付けられたメモリは、関連するコードが変更されると古くなる可能性がありますが、同じファイル内の別の場所を編集しても、通常は最新の状態が保たれます。

Git フックで最新のコンテキストを保つ

セットアップ時にインストールされたフックを保持して、リポジトリを同期した状態に保ちます。フックはコミット、マージ、チェックアウトの後に同期します。また、Graphicle は回答前に変更されたファイルも同期します。

リポジトリの上限を調整する

デフォルトでは、1 つのプロジェクトに含められるテキストファイルは最大 100,000 個、テキスト容量は 1 GiB です。より大きなリポジトリを扱う場合は、設定で上限を引き上げられます。非常に大きなファイルは部分的に解析されるか、同期を停止せず検索可能なテキストとして保持される場合があります。

別の MCP クライアントを接続する

Graphicle が自動検出しないクライアントの場合は、MCP ガイドに記載されている簡潔な JSON MCP 設定を追加してください。同じ MCP サーバーが、グラフ機能とメモリ機能の両方を提供します。

まとめ

Graphicle は、コーディングエージェントにリポジトリ構造とプロジェクト知識をローカルで検索できる形で提供します。インストールして graphicle setup を実行し、ask、context、open、graph を使って、引用付きでコードを調査してください。生成された回答が必要な場合にのみモデルを設定すればよく、グラフ、同期、MCP サーバー、セッションの取り込み、アプリはモデルなしでも動作します。

詳しくは、プロジェクトのクイックスタート、エージェントガイド、設定リファレンス、FAQを続けて参照してください。