ベクトルDBを使わないGraphRAG「Graphify」の中身を一次情報で読む

Posted at 2026-08-07

はじめに

AI コーディングアシスタントにコードベースを理解させる方法といえば、埋め込み＋ベクトル DB による RAG が定番になって久しいです。そんな中、2026年4月に登場した Graphify は「ベクトルストアは使わない」と真っ向から逆を張る OSS です。公開から4か月ほどで約 103.6k スター（2026年8月7日時点）・YC S26 採択と異例の伸びを見せています。筆者もリポジトリを clone して README・ARCHITECTURE.md・ソースコードなどの一次情報を一通り読んでみました。本記事はその調査結果の整理です。

前提知識

RAG（Retrieval-Augmented Generation）の基本的な仕組み
グラフ構造（ノード・エッジ）の基礎
環境：Python 実行環境と uv が導入済みであること（インストールに uv tool install を使うため）

背景・課題：grep とベクトル RAG、それぞれの限界

エージェントにコードベースを探索させると、実態は grep と Read の繰り返しになりがちです。トークンを大量に消費するうえ、「どの関数がどこから呼ばれているか」のような構造的な質問には弱いという難点があります。一方でベクトル RAG は意味的な類似検索は得意ですが、埋め込み生成のコストがかかり、チャンク分割で構造情報が失われ、「なぜこのチャンクが返ってきたのか」の説明可能性も乏しいという課題があります。

Graphify はここに対して「コードは決定的に解析できるのだから、LLM も埋め込みも使わずにグラフを作ればよい」というアプローチを取ります。README では「グラフ構造そのものが類似度シグナルである」という思想が明言されています（docs/how-it-works.md）。

Graphify とは何か

一言でいうと、プロジェクト全体（コード・ドキュメント・PDF・画像・動画）をクエリ可能なナレッジグラフに変換する Python CLI ＋ AI アシスタント用スキルです。Claude Code や Cursor 上で /graphify . と打つとグラフが構築され、以後は grep の代わりにグラフへ問い合わせる、という使い方になります（README.md）。

設計上の柱は3つです。

コード解析は完全ローカル・無料：tree-sitter による決定的な AST 解析（README 表記で50言語以上）で、LLM 不要。コードのみのコーパスなら API キーなしで完全オフライン動作します
すべてのエッジに根拠タグ：各リレーションが EXTRACTED（ソースに明示）/ INFERRED（推論で解決）/ AMBIGUOUS（不確実）のいずれかでタグ付けされ、「読み取った事実」と「推測」を区別できます（ARCHITECTURE.md）
ベクトルストア不使用：埋め込み・ベクトル DB を使わず、トラバース可能な本物のグラフを構築します

出力は graphify-out/ 配下の3ファイル（ブラウザで開ける graph.html、要点レポート GRAPH_REPORT.md、クエリ用の graph.json）です。

アーキテクチャを覗く

7段パイプライン

処理は単方向の7段パイプラインで、各ステージが独立モジュールの単一関数になっています。データの受け渡しは plain な Python dict と NetworkX グラフのみ、という潔い構成です（ARCHITECTURE.md）。

3パス処理 — LLM を使うのはドキュメントだけ

入力の種類ごとに処理が3パスに分かれている点が特徴的です（docs/how-it-works.md）。

Pass 1（コード）：tree-sitter でクラス・関数・import・コールグラフを抽出。ローカルかつ LLM 不要
Pass 2（動画・音声）：faster-whisper でローカル文字起こし。外部送信なし
Pass 3（ドキュメント・PDF・画像）：ここだけ LLM が意味抽出を担当します。docs/how-it-works.md の記述では、Claude のサブエージェントを並列に走らせて JSON のグラフ断片を生成し、それらを1つのグラフへマージする流れです。コードのみのプロジェクトでは完全にスキップされます

「ベクトル DB なし」ではあっても「LLM 完全不使用」ではない点は押さえておきたいところです。ドキュメント類を含めるなら LLM バックエンド（Claude / Gemini / OpenAI / DeepSeek / Kimi / Ollama / AWS Bedrock / Azure OpenAI の8種から選択）が動きます。

tree-sitter による AST 解析の中身

Pass 1 の主役である AST（抽象構文木）解析を、もう少し掘り下げます。AST とはソースコードを「関数定義」「クラス」「呼び出し式」といった構文要素の木構造として表現したもので、tree-sitter は各言語の文法定義（グラマー）に従ってこれを高速に構築するパーサライブラリです。LLM にコードを読ませる場合と違い、同じ入力からは必ず同じ木が得られる決定的な処理なので、ハルシネーションの余地がありません。再解析にかかるのは CPU 時間だけで、LLM の API コストは一切かかりません。

Graphify は36の tree-sitter グラマーを持ちます。カバー言語数については README が「50以上」、docs/how-it-works.md が Pass 1 について「25言語」と書いており、公式資料の間でも数字に幅がある点は注意してください。graphify/extractors/ 配下には言語別の extractor（rust.py、sql.py、terraform.py、Salesforce 向けの apex.py など。筆者が2026年7月26日時点で clone したツリーでは約30ファイル）が並んでいます（graphify/extractors/）。各 extractor は AST を走査して、ノードとエッジに落とし込みます。イメージは次のとおりです。

# payment.py
from billing import charge_card

def process_order(order):
    charge_card(order.total)

このコードからは、おおよそ次のグラフ要素が抽出されます。

ノード: payment.py, process_order, billing, charge_card
エッジ: payment.py    --imports--> billing      [EXTRACTED]
        process_order --calls-->   charge_card  [EXTRACTED]

import 文や呼び出し式は AST 上に明示されているため EXTRACTED になります。一方、動的ディスパッチ先の解決のように推論を挟むものは INFERRED としてスコア付きで区別されます。SQL であればテーブル・ビュー・外部キー・JOIN が同じ要領で決定的に抽出されます（docs/how-it-works.md）。

信頼度タグと説明可能性

筆者が一番参考になったのはここです。EXTRACTED エッジの confidence_score は常に 1.0 で、INFERRED エッジには 0.95（明示的なクロスファイル参照があり候補が1つ）／0.85（命名と文脈が一致）／0.75（文脈的だが暗黙）／0.65（命名の類似のみ）／0.55（推測）という離散ルーブリックでスコアが付きます（docs/how-it-works.md）。さらに graphify explain "概念" を実行すると、そのノードの詳細と接続元を確認できます（公式ドキュメント、PyPI: graphifyy）。LLM を絡めたシステムで「事実と推測を分離して見せる」設計の実例として、RAG 以外の文脈でも応用が利きそうです。

使ってみる

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

uv tool install graphifyy   # パッケージ名は graphifyy（y が2つ）に注意
graphify install            # 20以上の AI アシスタントにスキル登録

その後、アシスタント（Claude Code など）の中ではスラッシュコマンドを使います。これはシェルではなくアシスタント内で打つものです。

/graphify .                  # グラフ構築（--update で差分更新）

構築後の問い合わせは、シェルからでも CLI で実行できます。

graphify query "認証はどこで処理している？"
graphify path UserService PaymentService              # 2概念間の最短パス
graphify explain "PaymentService"                     # ノードの詳細と接続元
graphify add https://arxiv.org/abs/2005.11401         # 論文や YouTube 動画も追加可能

MCP サーバとして公開する

構築済みグラフは MCP サーバとしても公開できます。stdio に加えて Streamable HTTP トランスポートに対応しており、--api-key で Bearer 認証を付ければチーム共有サーバにもなります（README.md）。

python -m graphify.serve graphify-out/graph.json --transport http

公開されるツールは query_graph / get_node / get_neighbors / shortest_path に加え、PR トリアージ系（list_prs / get_pr_impact / triage_prs）まであります。

「grep より先にグラフを引かせる」フック設計

Claude Code 連携では PreToolUse フックを使い、エージェントが grep や生ファイル読み取りに走る前にグラフへ誘導する仕掛けが入っています。既定は「grep の前にグラフを引け」と緩やかに促す soft nudge で、--strict を付けるとセッションにつき1回だけ、最初の生ソース読み取りをブロックしてグラフへリダイレクトするフックに格上げされます。graphify install --project --strict で有効化でき、環境変数 GRAPHIFY_HOOK_STRICT=1 / 0 で実行時に切り替えられます（公式ドキュメント）。Claude Code のフック活用例としても具体的で面白い設計だと感じました。

mattpocock-skills との併用アイデア

筆者は普段、mattpocock/skills（TDD・コードレビュー・バグ診断などのワークフロー系スキル集）を Claude Code / Cowork に入れて使っています。Graphify も同じくスキルとして常駐しますが、担当するレイヤーが異なるため衝突せず、むしろ補完関係になります。mattpocock-skills が「作業の進め方（ワークフロー）」を規定するのに対し、Graphify は「コードベースの構造メモリ」を提供するからです。

組み合わせの例を2つ挙げます。

diagnosing-bugs × Graphify：バグ診断では呼び出し経路の特定が調査フェーズの肝になります。ここで grep の代わりに graphify path A B（shortest_path）や get_neighbors を使うと、「このハンドラからこのリポジトリ層まで、どの経路でつながっているか」を少ないトークンで取得でき、仮説構築が速くなります
codebase-design × Graphify：モジュール設計の検討では「どこが神クラス化しているか」の把握が出発点になります。Graphify の analyze ステージが出力する god node 分析（接続過多ノードの検出）は、その材料としてそのまま使えます

なお、これは筆者の運用アイデアであり、Graphify が公式に mattpocock-skills 連携を謳っているわけではありません。両者とも「スキル＋MCP」という標準的な仕組みの上に乗っているからこそ、この種の組み合わせが自由に効く、というのが本質です。

ハマりどころ・注意点

筆者が一次情報を読んでいて「導入前に知っておくべき」と感じた点を挙げます。

パッケージ名の罠：PyPI パッケージは graphifyy（y が2つ）、CLI コマンドは graphify です。PyPI 上の他の graphify* パッケージは無関係と README 自身が繰り返し注意しています
ライセンスが最近変わった：現在は Apache-2.0 です。NOTICE には「本製品は Apache License 2.0 でライセンスされる。再ライセンス以前に MIT で寄与された部分は引き続き MIT でも利用可能」と明記されており、リポジトリには LICENSE（Apache-2.0）と LICENSE-MIT の両方が残っています。そのため GitHub 上の表示も "Apache-2.0 and MIT" になります（NOTICE）。筆者が2026年7月26日時点で確認した範囲では、切り替えは v0.9.25（2026-07-22）で、理由は特許許諾条項の明示でした。社内利用でライセンス審査がある場合は最新の LICENSE / NOTICE を確認してください
個人主導プロジェクト：筆者が2026年7月26日時点で clone して git shortlog を確認したところ、約1,250コミットのうち7割超をメイン開発者1名が占めていました。開発速度は非常に速い（0.9.24→0.9.26 が4日間）一方、バス係数の観点は評価に入れておくべきです
v1.0 未満：バージョンは 0.9.x であり（2026年8月7日時点の最新は 0.9.35）、API・出力形式が変わる可能性は織り込んでおく必要があります

まとめ

Graphify は「コードの構造は決定的に取れるのだから LLM に読ませる必要はない」という割り切りと、EXTRACTED / INFERRED / AMBIGUOUS の信頼度タグによる説明可能性の設計が光る OSS でした。ベクトル RAG を全面的に置き換えるものというより、コードベース探索についてはグラフ、意味検索が本当に必要な部分だけ埋め込みという住み分けを考えるきっかけになりそうです。まずはコードのみのプロジェクトで試せば API キーも不要なので、uv tool install graphifyy から気軽に触ってみてください。

同じテーマを追いかけている方の知見も知りたいので、実際に導入した感想や、ベクトル RAG との使い分けの実例があればコメントで教えていただけると嬉しいです。参考になったら LGTM・ストックしていただけると励みになります。

参考

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up