Graphify入門｜コードと文書をナレッジグラフ化してAIに読ませるOSSの使い方とGraphRAGとの違い

この記事ではRAGに特化して解説します。RAG全般は RAGとは？仕組み・構築・ベクトルDB選定までの2026年実装マップ をご覧ください。

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

まずは、実際に動かしたときの雰囲気を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倍のトークン削減を記録している。削減率はコーパスが大きいほど伸びる（後述のとおり、数千行規模の小さなプロジェクトでは削減効果はほぼ出ない）。

現在READMEが掲げるベンチマークは次のとおり。判定は独立した第2のジャッジで盲検証されており（一致率90.6%、Cohenのκ=0.81）、BENCHMARKS.md に再現コマンドまで公開されている。

注意したいのは、これらが会話メモリ（long-term memory）としての評価軸だという点だ。「コードベースの地図」としての価値を直接測ったものではない。コード用途で効くかどうかは、次章で自分のリポジトリを実測して確かめる。

Graphifyの土台は、NetworkX と tree-sitter というよく知られたライブラリだ。Neo4jのようなグラフDBサーバは不要で、すべてローカルで完結する。ライセンスは Apache-2.0（旧MITから変更済み。冒頭の box-warning 参照）で、特許条項を含むぶん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）によるコミュニティ検出で色分けされる。関連の強いノードがクラスタとして固まって見えるため、「このプロジェクトはどんな塊でできているか」が一目で掴める。

実測：当サイトのコードベースをグラフ化してみた

抽象論だけでは「何が嬉しいのか」が伝わらないので、実際に走らせた結果を出す。対象は本サイトの記事生成パイプライン（tools/shared/ 配下のPythonコード21ファイル）、graphify は最新の v0.9.34、uvx で隔離環境に入れて実行した。

検証環境: macOS 14.5 (Darwin 23.5.0) ／ graphifyy v0.9.34 ／ 2026-08-06実施。APIキーは一切設定していない。

# 隔離環境で実行（グローバル環境を汚さない）
uvx --from graphifyy==0.9.34 graphify extract . --no-cluster
# → found 21 code, 0 docs, 0 papers, 0 images
# → wrote graphify-out/graph.json — 369 nodes, 683 edges (no clustering)

uvx --from graphifyy==0.9.34 graphify cluster-only . --no-viz
# → Graph: 369 nodes, 591 edges / Done - 16 communities

APIキーを一切設定せずに完走した。README が「コードは tree-sitter の決定論的AST解析、LLM不使用」と書いているとおりで、生成された GRAPH_REPORT.md のヘッダも Token cost: 0 input · 0 output を記録していた。コードだけのコーパスなら、費用ゼロ・完全ローカルでグラフが手に入るのは実測どおりだ。

肝心の GRAPH_REPORT.md から、神ノード（God Nodes） の上位はこう出た。

これは「このコードベースの中心概念は何か」への直接の回答になっている。実際、SourceResult は全トレンドソースが返す共通の器で、ここを変更すると収集系すべてに波及する——新規参画者に最初に説明すべき型がそのまま1位に来た。神ノードは「触ると危ない場所」のランキングでもあるわけだ。

コミュニティ検出は16個の塊を返し、GA4Client GSCClient trend_sources.py fetch.py といったハブごとに機能が分かれていることが可視化された。あわせて Import Cycles: None detected（循環importなし）も報告される。

実測：トークン削減率は14.7倍だった

同梱の benchmark サブコマンドで、このグラフの削減率をそのまま測れる。

uvx --from graphifyy==0.9.34 graphify benchmark graphify-out/graph.json

結果は次のとおりだった。

質問ごとの内訳は「main entry point は何か」17.3倍、「data層とAPI層をつなぐのは何か」12.8倍、「中核の抽象は何か」14.7倍。公式の71.5倍には遠く及ばないが、これは当然の結果だ。71.5倍を出したコーパスは52ファイルの混在コーパスで、こちらは21ファイル。前掲のとおり削減率はコーパス規模に強く依存し、README自身も小さなコーパスでは削減率がほぼ1倍になると認めている。自分のリポジトリでの実値は自分で測るしかない——そしてそれが1コマンドでできる点こそ評価すべきだ。

エッジの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フック

query / path / explain の3つは graph.json さえあればAIアシスタント抜きでも単体で動く。実際の出力はこうなる（前章と同じ21ファイルのグラフに対して実行）。

$ graphify path "run_pipeline()" "generate_cover_image()"
Shortest path (2 hops):
  run_pipeline() --calls [EXTRACTED]--> generate_image() --calls [EXTRACTED]--> generate_cover_image()

$ graphify explain "GA4Client"
Node: GA4Client
  Source:    shared/google_analytics.py L32
  Community: GA4Client
  Degree:    19
Connections (19):
  --> .get_page_views() [method] [EXTRACTED] shared/google_analytics.py:L61
  --> .get_declining_pages() [method] [EXTRACTED] shared/google_analytics.py:L155

path が返す2ホップの経路には、各辺に [EXTRACTED]（ASTから直接抽出＝確実）が付く。「この関数から画像生成まで、どう到達するのか」が行番号付きで即座に分かる形だ。

対応プラットフォームは 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クライアントから構造化されたグラフアクセスをツールとして呼び出せる。

# 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の立ち位置を、コード理解系の代表的なツールと比べて整理する。

GraphRAGとの違いが最も本質的だ。両者とも「グラフを作ってから答える」点は同じだが、索引の作り方が正反対である。MicrosoftのGraphRAGは文書をLLMに読ませてエンティティと関係を抽出するため、コーパスが大きいほど構築コストが積み上がる。対してGraphifyは、コードに関しては tree-sitter のAST解析だけで構造を取るのでLLMを1回も呼ばない——前章の実測どおり Token cost: 0 input · 0 output だ。この差は「グラフの正しさ」にも効く。ASTから取った辺は文法的に確定した事実なので EXTRACTED と言い切れるが、LLMに抽出させた辺は本質的に推論であり、Graphifyもドキュメント由来の辺は INFERRED に落とす。

もう一点、READMEが明言するのは「ベクトルインデックスではない」ことだ。埋め込みもベクトルDBも使わず、実際に辿れるグラフを持つ。類似度検索ではなく経路探索なので、前章の path のように「AからBへどう到達するか」を根拠付きで答えられる。RAGの系譜の中でどこに位置するかは RAGの進化｜Naive・Advanced・Graph・Agentic RAGの仕組みと選び方2026 が詳しい。

Sourcegraphは複数リポジトリを横断するコード検索に強く、Graphifyとは補完関係にある（ただしv0.9系では graphify merge-graphs a.json b.json で複数リポジトリのグラフを1つに統合できるようになっており、クロスリポジトリも射程に入りつつある）。汎用のグラフDBであるNeo4jは表現力こそ高いが、サーバの構築と抽出パイプラインの自作が必要になる。文書からWikiを自動生成する方向性の近縁ツールとしては DeepWiki-Openの使い方｜GitHubリポジトリからAI Wikiを自動生成するOSS、文書解析側を厚くしたRAGエンジンとしては RAGFlowとは｜高精度な文書解析でRAGを組むOSSエンジンの使い方 が比較対象になる。

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

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

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

効果が高いケース

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

効果が限定的なケース

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

規模と削減率の関係は、冒頭のヒーロー図の棒グラフがそのまま答えになっている。worked/ サンプルでは52ファイルで71.5倍、4ファイルで5.4倍、6ファイルで約1倍。本記事で実測した21ファイルのコーパスは、ちょうどその中間の14.7倍に着地した。「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年実装マップ

参照ソース

• Graphify — GitHub（旧 safishamsi/graphify。README、v8ブランチ。スター103,086・Apache-2.0・最新 v0.9.34／2026-08-06実測）
• BENCHMARKS.md — Graphify-Labs/graphify（LOCOMO／LongMemEval-Sの比較ベンチマークと再現手順。2026-07-05更新）
• NOTICE — Graphify-Labs/graphify（Apache-2.0への再ライセンスとMIT部分の扱い）
• Graphify 日本語README
• graphifyy — PyPI
• safishamsi/graphify — DeepWiki
• Graphify: Instant Knowledge Graph for Claude Code/Antigravity — FuturMinds / YouTube