Graphify入門：コード・ドキュメント・画像をナレッジグラフ化し、AIの検索トークンを71.5倍削減するOSS

この記事ではRAGに特化して解説します。RAG全般は RAGとは？仕組み・構築・ベクトルDB選定まで【2026年完全ガイド】 をご覧ください。

Graphifyは、コードベース全体——ソースコード・ドキュメント・PDF・画像・動画まで——をAIが問い合わせられるナレッジグラフに変換するOSSだ。AIコーディングツールで /graphify . と打つだけで、フォルダの中身が「ノードとエッジのグラフ」に変わり、AIは生ファイルをgrepする代わりにグラフへクエリを投げられるようになる。2026年4月3日の公開後わずか48時間でバズり、この記事の更新時点で GitHub 75,000スター超・Y Combinator S26 採択という急成長を見せている。

まずは、実際に動かしたときの雰囲気を1本の動画で掴んでほしい。Claude Code や Google Antigravity から /graphify を叩き、対話的なグラフが立ち上がるまでの流れが2分ほどで分かる。

Graphifyとは——なぜコードをナレッジグラフにするのか

大規模コードベースをAIに理解させるとき、最大のボトルネックはトークン消費だ。10万行のコードをAIに読ませるには膨大なトークンが必要で、コンテキストウィンドウの制限にもすぐぶつかる。ファイルを1つずつ Read し、grep で探し回るたびに、AIは同じ構造を何度も読み直す。この非効率が、大きなプロジェクトでAIアシスタントの回答が浅くなったり遅くなったりする原因になる。

Graphifyの発想はシンプルだ。「毎回ファイルを読む」のをやめ、いちど作ったグラフに問い合わせる。コードベースを「関数・クラス・概念（ノード）」と「呼び出し・依存・参照（エッジ）」のグラフに変換しておけば、AIは質問に関連する部分グラフだけを参照すればよく、ファイル全体を読む必要がなくなる。

この記事を読む開発者が知りたいのは、突き詰めれば次の3点だろう。①Graphifyは結局何ができるのか、②どんな課題を解決するのか、③既存の何を代替するのか。先に結論を示すと——

・①何ができる：任意のフォルダを /graphify . 一発でナレッジグラフ化し、query／path／explain で自然言語問い合わせできる
・②何を解決する：大規模コードベースを読むときのトークン枯渇・コンテキスト溢れ・調査の遅さを、グラフへの部分クエリで解消する
・③何を代替する：AIに「ファイルを全部読ませて把握させる」運用や、素朴な grep／全文検索ベースの調査を置き換える

ナレッジグラフ化の最大のメリットはトークン効率だ。公式リポジトリの worked/ に置かれた実測サンプルでは、Andrej Karpathy のリポジトリ群＋論文5本＋画像4枚を合わせた52ファイルの混在コーパスで、生ファイルを読む場合と比べクエリあたり71.5倍のトークン削減を記録している。数字の出どころとしては上のヒーロー図の棒グラフのとおりで、削減率はコーパスが大きいほど伸びる（後述のとおり、数千行規模の小さなプロジェクトでは削減効果はほぼ出ない）。

Graphifyの土台は、NetworkX と tree-sitter というよく知られたライブラリだ。Neo4jのようなグラフDBサーバは不要で、すべてローカルで完結する。ライセンスはMITと寛容で、ビジネス利用も可能だ。

フォルダを渡すとグラフになる：解析の仕組み

Graphifyの処理は、大きく2種類の解析に分かれる。コードは決定論的なAST解析でローカル処理し、それ以外の素材（ドキュメント・PDF・画像・動画）だけをAIモデルに送ってセマンティック解析する。この使い分けが「速さ」と「深さ」を両立させている。

AST解析（決定論的・LLM不要・ローカル）

tree-sitterで36文法を解析し、シンボル・呼び出しグラフ・import関係・クラス階層を抽出する。ここはLLMを一切使わないため高速かつ決定論的で、APIキーも不要。コードだけのコーパスなら graphify extract は完全にオフラインで走り、1バイトも外に出ない。

AST解析が抽出する情報は次のとおりだ。

・シンボル（関数・クラス・変数）
・呼び出しグラフ（関数A → 関数B）
・import／依存関係
・クラス継承階層
・エクスポート／公開API

対応するのはコードだけではない。SQLスキーマ、Terraform/HCL、Salesforce Apex（.cls／.trigger）、さらにパッケージマニフェスト（pyproject.toml・go.mod・pom.xml）まで解析でき、「アプリコード＋DBスキーマ＋インフラ」を1つのグラフに束ねられる。CUDA（.cu／.cuh）やMetal（.metal）はC++の文法を流用して扱う。

セマンティック解析（AIが「なぜ」まで抽出）

ドキュメント（Markdown・PDF・reStructuredText・HTML）、画像（スクリーンショット・図・ホワイトボード写真）、動画・音声は、AIモデルに渡してセマンティック解析する。ここで抽出されるのは単なる要約ではなく、概念・関係性・設計意図だ。コード中の # NOTE:・# WHY:・# HACK: といったコメントやdocstring、ドキュメントに書かれた設計理由も独立したノードとして取り込まれ、それが説明している該当コードにリンクされる。

画像はAIのビジョン機能で処理されるため、アーキテクチャ図やホワイトボードの写真からも概念を抜き出せる。動画・音声はローカルの faster-whisper で文字起こししてからグラフに取り込むので、音声そのものが外に出ることはない。

この「2種類の解析」の分担は、プライバシー面でも効いている。コードはローカル、動画・音声もローカル、外部モデルに送られるのは文書・PDF・画像のセマンティック抽出だけ。データレジデンシー要件が厳しい環境では --backend ollama で完全ローカル運用に切り替えることもできる。

出力される3つのファイル：グラフ・レポート・永続化

/graphify . を実行すると、graphify-out/ ディレクトリに主に3つのファイルが生成される。ここが「何ができるか」を最も体感しやすい部分だ。

・graph.html — ブラウザで開ける対話的なグラフ。ノードをクリックし、検索し、コミュニティ（後述）で絞り込める
・GRAPH_REPORT.md — グラフの要点をまとめたレポート。神ノード・意外なつながり・おすすめ質問が並ぶ
・graph.json — 永続グラフ。数週間後でもファイルを読み直さずにクエリできる

レポート（GRAPH_REPORT.md）に含まれる情報は、単なる目次ではない。

・神ノード（God nodes）：最も多くの結びつきを持つ概念。「すべてがここを通る」ハブが分かる
・意外なつながり（Surprising connections）：別のファイル・モジュールにまたがるリンクを、意外性の高さでランク付け。それぞれに平易な「なぜ」が付く
・設計理由（The “why”）：コメントやdocstringから抽出した設計意図を、該当コードに紐付けて提示
・おすすめ質問：そのグラフだからこそ答えられる4〜5個の質問
・信頼度タグ：各関係に EXTRACTED／INFERRED／AMBIGUOUS が付き、「見つけた事実」と「推測」が常に区別される

graphify-out/ はgitにコミットする前提で設計されている。1人が /graphify . して結果をコミットすれば、チーム全員がプルした瞬間に同じ「地図」を手にできる。graphify hook install を実行すればpost-commitフックが入り、コミットのたびにグラフが自動再構築される（コード部分はAST解析だけなのでAPIコストはゼロ）。しかも graph.json にはマージドライバが設定され、2人が並行でコミットしてもグラフはユニオンマージされ、コンフリクトマーカーが残らない。

graph.html に描かれるグラフは Leiden法（graspologic）によるコミュニティ検出で色分けされる。関連の強いノードがクラスタとして固まって見えるため、「このプロジェクトはどんな塊でできているか」が一目で掴める。

エッジの3種類——情報の出自を正直に記録する

Graphifyの設計で特筆すべきは、すべてのエッジ（関係）に出自ラベルが付与される点だ。これは「AIが自信ありげに嘘をつく」問題への、地味だが効く対策になっている。

各ラベルの意味は次の表のとおりだ。

AST解析で得たエッジは EXTRACTED として「確実な事実」に分類される。一方、ドキュメントや画像からAIが読み取った関係は INFERRED、確信度が低いものは AMBIGUOUS になる。この透明性により、AIは「これはコードから確認できる事実」「これは私が文書から推測した関係」を分けてユーザーに回答できる。調査の裏取りをするときも、まず EXTRACTED だけを信じ、AMBIGUOUS は自分の目で確かめる、という使い分けができる。

何を解決するのかという観点で言えば、これはナレッジグラフ全般につきまとう「グラフが本当に正しいのか分からない」という不信感を、ラベルという形で可視化して解消する仕組みだ。

あらゆる素材を1つのグラフに：マルチモーダル対応

Graphifyの「コーディングツール」という枠を超えた強みが、マルチモーダルであることだ。コードだけでなく、設計ドキュメント・論文PDF・アーキテクチャ図の画像・解説動画までを、同じグラフに混ぜられる。

対応する主な素材と抽出方法は次のとおりだ。

この「引用マイニング」が効くのは、論文PDFを混ぜたときだ。冒頭のヒーロー図で71.5倍を記録したコーパスも、Karpathyのコード群に論文5本と画像4枚を混ぜたものだった。README曰く、コードとコードのエッジより「コードと論文のエッジ」のほうが意外性スコアが高くランク付けされる。つまり「この実装はどの論文のどのアイデアに対応しているのか」といった、人間なら見落としがちな越境的なつながりを浮かび上がらせられる。

Karpathyが /raw フォルダに論文・ツイート・スクショ・メモをまとめて放り込むワークフローを紹介したことがバズのきっかけだった、という背景も、このマルチモーダル性を踏まえると腑に落ちる。散らかった素材を「1つの問い合わせ可能なグラフ」に束ねる、というのがGraphifyの提供価値なのだ。

インストールと基本コマンド

導入は2ステップで済む。パッケージをインストールし、使っているAIアシスタントにスキルを登録するだけだ。

注意：PyPIのパッケージ名は graphifyy（yが2つ）。他の graphify* パッケージは非公式。ただしCLIコマンドとスキル名は graphify のまま。

# 1. パッケージをインストール（uv tool 推奨。pipx / pip も可）
uv tool install graphifyy

# 2. AIアシスタントにスキルを登録し、任意のフォルダでグラフ化
graphify install
# → AIアシスタントを開いて  /graphify .  と打つだけ

基本の使い方は /graphify に引数を渡すだけだ。ビルドしたあとは自然言語でグラフに問い合わせられる。

/graphify .                        # カレントフォルダをグラフ化
/graphify ./raw --update           # 変更ファイルだけ再抽出してマージ
/graphify . --wiki                 # グラフからMarkdownの内部Wikiを生成

/graphify query "認証はどこでDBにつながっている？"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762   # 論文を取得してグラフに追加
/graphify add <youtube-url>                       # 動画を文字起こしして追加

graphify hook install              # コミット時に自動再構築するgitフック

対応プラットフォームは Claude Code・Codex・OpenCode・Cursor・Gemini CLI・GitHub Copilot CLI・VS Code Copilot Chat・Aider・Amp・OpenClaw・Factory Droid・Trae・Kiro・Devin CLI・Google Antigravity など20以上。多くは graphify install --platform <名前> で個別に登録できる（CodexだけはPowerShellではなく $graphify を使う、といった細かな差はREADMEに明記されている）。統合はIDEプラグインではなく、AIアシスタントのスキル／フック層で行われるのが特徴だ。

MCPサーバーとPRダッシュボード：グラフを他ツールから叩く

Graphifyは /graphify コマンドで完結させるだけでなく、生成した graph.json をMCP（Model Context Protocol）サーバーとして公開できる。これにより、対応するAIクライアントから構造化されたグラフアクセスをツールとして呼び出せる。MCPそのものの詳細は Claude Code運用ガイド も参考になる。

# graph.json を stdio の MCPサーバーとして起動
python -m graphify.serve graphify-out/graph.json

# チームで1つのURLを共有したいときは HTTP トランスポート
python -m graphify.serve graphify-out/graph.json --transport http --port 8080 --api-key "$SECRET"

MCP経由で提供されるツールは、query_graph（グラフへのクエリ）・get_node（ノード詳細）・get_neighbors（隣接ノード）・shortest_path（最短パス）に加え、PR関連の list_prs・get_pr_impact・triage_prs がある。デフォルトの stdio は開発者ごとにローカルで1プロセス起動する形だが、HTTPトランスポートを使えば1つの共有プロセスでチーム全体にグラフを配れる（この場合は --host 0.0.0.0 と --api-key を必ずセットにする）。

クエリ時のやり取りは、次のシーケンスのように進む。AIは生ファイルを読み込まず、グラフサーバーに問い合わせて関連サブグラフだけを受け取る。これがトークン削減の実体だ。

さらに実務寄りの機能として、graphify prs というPRダッシュボードがある。CIの状態・レビュー状況・ワークツリーの対応関係を一覧でき、graphify prs 42 でPR #42のグラフ影響範囲まで掘り下げられる。graphify prs --conflicts は「同じグラフコミュニティを触っているPR」を検出し、マージ順序のリスクを教えてくれる。ナレッジグラフを単なる検索インデックスではなく、レビュー・マージ判断の土台として使う発想だ。

類似ツールとの比較

Graphifyの立ち位置を、コード理解系の代表的なツールと比べて整理する。

Sourcegraphは複数リポジトリを横断するコード検索に強く、Graphifyとは補完関係にある（Graphify自体はクロスリポジトリ検索が主目的ではない）。コード専用のグラフツールはドキュメントや画像を扱えない。汎用のグラフDBであるNeo4jは表現力こそ高いが、サーバの構築と抽出パイプラインの自作が必要になる。

Graphifyの差別化は、①マルチモーダル（コード＋文書＋画像＋動画）、②設計意図まで抽出し出自ラベルで正直さを担保、③Neo4jのようなサーバ不要でローカル完結、④特定IDEに縛られずAIアシスタント層で20以上のツールに載る、の4点に集約される。「AIに読ませる前提の地図を、手元で低コストに作る」という一点に振り切った設計だ。

どんなコードベースで効果的か——効く場面・効かない場面

「入れれば必ず速くなる」わけではない。トークン削減はコーパス規模にスケールするので、大きくて雑多なプロジェクトほど効く。逆に、コンテキストに丸ごと収まる小さなプロジェクトでは、グラフ化のオーバーヘッドのほうが目立つ。

効果が高いケース

・大規模モノレポ：数十万行でコンテキストが足りない場合、グラフからの部分クエリが威力を発揮する
・ドキュメントが散在するプロジェクト：Markdown・PDF・設計図をコードと同じグラフに統合し、関連性を可視化
・新規参画者のオンボーディング：/graphify explain UserService でコンポーネントの役割と依存関係を即座に把握
・レガシーコードの理解：ドキュメントがなくてもAST解析で構造を抽出し、AIが設計意図を推論
・並行エージェント開発：複数エージェントが同時にコードを書く場面で、--watch によりグラフが波と波の間で自動的に最新化される

効果が限定的なケース

・小規模プロジェクト（数千行以下）——AIが直接ファイルを読む方が効率的（公式のhttpxサンプルは6ファイルで削減率ほぼ1倍）
・頻繁に作り替えるプロトタイプ——グラフ再構築のオーバーヘッドが割に合わない

規模と削減率の関係は、冒頭のヒーロー図の棒グラフがそのまま答えになっている。52ファイルで71.5倍、4ファイルで5.4倍、6ファイルで約1倍。「6ファイルはそもそもコンテキストに収まるので、そこでの価値は圧縮ではなく構造の可視化だ」とREADME自身が正直に書いている点は、このツールの信頼性を測るうえで見逃せない。各 worked/ フォルダには入力ファイルと実際の出力（GRAPH_REPORT.md・graph.json）が同梱されているので、数字は自分の手で再現・検証できる。

セキュリティと運用上の注意点

導入前に押さえておきたい運用上の注意をまとめる。

・graph.jsonにはコード構造情報が含まれる。公開リポジトリにうっかりコミットする場合は中身を確認する
・コスト管理：ドキュメント・画像のセマンティック解析にはモデルAPIのコストが発生する（コードのAST解析はローカルで無料）。初回構築が最も重く、増分更新（--update）は低コスト
・プライバシー：コードと動画・音声はローカル処理で外に出ない。外部に送られるのは文書・PDF・画像のセマンティック抽出のみ。完全ローカルにしたいなら --backend ollama
・クエリログ：query／path／explain は既定で ~/.cache/graphify-queries.log にJSON Lines形式で記録される（質問・コーパス・所要時間など。サブグラフ本文は既定で保存しない）。無効化は GRAPHIFY_QUERY_LOG_DISABLE=1
・テレメトリなし：使用状況の追跡・分析は行わない

チーム運用では graphify-out/ をコミットする一方、graphify-out/cost.json（ローカルのコスト記録）は .gitignore に加えるのがREADMEの推奨だ。.graphifyignore（.gitignore と同じ構文）で対象を絞れるほか、各ディレクトリの .gitignore は自動的に尊重される。

Graphifyは「AIにコードを理解させる」という誰もがぶつかる課題に、ナレッジグラフ＋出自ラベル＋ローカル完結というシンプルな解を出したツールだ。RAGを自前で組む前に、まず手元のリポジトリで /graphify . を1回叩いてみる価値はある。RAGの全体像から設計したい場合は、あわせて次の記事も参照してほしい。

関連記事: RAGとは？仕組み・構築・ベクトルDB選定まで【2026年完全ガイド】 ／ AIエンジニアのロードマップ

参照ソース

• Graphify — GitHub（README、v8ブランチ）
• Graphify 日本語README
• graphifyy — PyPI
• safishamsi/graphify — DeepWiki
• Graphify: Instant Knowledge Graph for Claude Code/Antigravity — FuturMinds / YouTube