graphify — コードとドキュメントをナレッジグラフに変換する AI スキル

何か

graphify は AI コーディングアシスタント向けスキル兼 Python CLI。アシスタントで /graphify .（Codex は $graphify）を実行すると、コード・ドキュメント・PDF・画像・動画などを読み取り、ナレッジグラフとして構造化する。ベクトル索引ではなく、エッジを辿る実グラフ。

0.497 LOCOMO recall@10

$0 コード AST の LLM コスト

20+ 対応アシスタント

3.10+ Python

コードは tree-sitter AST で完全ローカル・決定論的（LLM 不要）。Docs / PDF / 画像などはアシスタントのモデル（または設定した API）でセマンティック抽出。各エッジは EXTRACTED（ソースに明示）/ INFERRED（解決・推論）/ AMBIGUOUS（要確認）で区別する。

公式パッケージ名は graphifyy（二重 y）。PyPI 上の他 graphify* は非公式。CLI コマンドは graphify。Y Combinator S26。

30 秒スタート

uv tool install graphifyy      # または: pipx install graphifyy
graphify install               # スキルをアシスタントに登録
# アシスタント内で:
/graphify .

出力は graphify-out/ に 3 ファイル: graph.html（ブラウザで操作）・GRAPH_REPORT.md（ハイライト）・graph.json（再クエリ用）。

同一ハーネス比較（BENCHMARKS.md・2026-07-05 更新）

同一モデル・同一予算・ブラインド検証済みジャッジ（合意 90.6%、κ=0.81）で計測。グラフ構築自体の LLM クレジットは 0。

スイート	指標	graphify	比較
LOCOMO (n=300)	recall@10	0.497	supermemory 0.149 / BM25 0.362 / mem0 0.048
LOCOMO (n=300)	QA accuracy	45.3%	supermemory 49.7%（ingest 約 11x 高コスト）/ BM25 31.3% / mem0 27.3%
LongMemEval-S (n=50)	QA accuracy	76%	dense RAG 76%（同点）/ mem0 70%
ERPNext cross-tool (n=6)	key-fact coverage	82.0%	grep/read ベースライン 70.8%
グラフ構築	LLM credits	$0	多くの系はトークン課金

混在コーパス（Karpathy 系 + 論文 + 画像、52 ファイル）ではクエリあたりトークン約 71.5x 削減の例あり（how-it-works）。詳細と再現コマンドはリポジトリの BENCHMARKS.md。

ライブラリ段階

各ステージは独立したモジュールで、やり取りは plain な Python dict と NetworkX グラフ。ただし extractor は走査中のルートを module レベルの状態で参照する（ARCHITECTURE.md）。analyze.py と export.py は単一エントリではなく、関数群。

detect() → extract() → build_graph() → cluster() → analyze() → report() → export()

3 パス抽出

Pass 1 — コード構造（無料・API なし）: tree-sitter AST。クラス・関数・imports / calls / inherits など。コードのみのコーパスでは Pass 3 をスキップ。
Pass 2 — 動画・音声（ローカル）: faster-whisper。トップ god nodes をプロンプトにシード。キャッシュあり。
Pass 3 — Docs / 論文 / 画像（セマンティック）: アシスタントのサブエージェント（または headless backend）が JSON 断片を並列出力しマージ。

コミュニティ検出は Leiden。埋め込みやベクトル DB は不要。semantically_similar_to などのエッジがトポロジーに直接効く。

主要モジュール

モジュール	関数	入力 → 出力
`detect.py`	`detect`	ディレクトリ → スキャン概要（カテゴリ別ファイル、総語数、scan_root 等）
`extract.py`	`extract` / `collect_files`	パスのリスト → `{nodes, edges}`。ディレクトリ展開もここ
`build.py`	`build`	抽出結果 → `nx.Graph`
`cluster.py`	`cluster`	グラフ → `{community_id: [node_id, ...]}`（グラフは変更しない）
`analyze.py`	`god_nodes` / `surprising_connections` / `suggest_questions` ほか	グラフ → 分析ごとの一覧（単一の `analyze()` は無い）
`report.py`	`generate`	→ GRAPH_REPORT.md
`export.py`	`to_json` / `to_html` / `to_obsidian` / `to_svg` ほか	→ graph.json / graph.html / Obsidian vault 等（形式ごとに関数）
`wiki.py`	`to_wiki`	→ コミュニティごとの markdown 記事 + index.md
`serve.py`	`serve` / `serve_http`	graph → MCP（stdio / HTTP）
`watch.py` / `hooks.py`	監視・git hook	変更検知 / コミット後再ビルド
`security.py`	バリデーション	URL / パス / ラベル

抽出スキーマ

{
  "nodes": [
    { "id": "unique_string", "label": "human name",
      "source_file": "path", "source_location": "L42" }
  ],
  "edges": [
    { "source": "id_a", "target": "id_b",
      "relation": "calls|imports|uses|...",
      "confidence": "EXTRACTED|INFERRED|AMBIGUOUS" }
  ]
}

EXTRACTED は confidence 1.0。INFERRED はルーブリック（0.95〜0.55）。AMBIGUOUS はレポートで要レビュー。

パッケージとスキル登録

# 推奨（隔離環境）
uv tool install graphifyy
# 代替: pipx install graphifyy  /  pip install graphifyy

graphify install                 # ユーザー向けスキル登録
graphify install --project       # カレントリポジトリへ（例: .claude/skills/graphify/）
graphify install --platform codex
uvx --from graphifyy graphify install   # パッケージ名は graphifyy

graphify: command not found → uv tool update-shell または pipx ensurepath のあとシェル再起動。~/.local/bin が PATH に無いことが多い。

プラットフォーム（抜粋）

プラットフォーム	コマンド
Claude Code	`graphify install`（Windows は自動判定、または `--platform windows`）
Cursor	`graphify cursor install`
Codex	`graphify install --platform codex`（並列抽出に `multi_agent = true`）
GitHub Copilot CLI	`graphify install --platform copilot`
VS Code Copilot Chat	`graphify vscode install`
Gemini CLI	`graphify install --platform gemini`
Amp / Devin CLI / Kiro / Google Antigravity	`graphify amp install` / `graphify devin install` / `graphify kiro install` / `graphify antigravity install`
Pi coding agent	`graphify install --platform pi`（ネイティブ guard は `graphify pi guard install`）
OpenCode / Kilo Code / Aider / Trae / Trae CN	`graphify install --platform opencode \| kilo \| aider \| trae \| trae-cn`
CodeBuddy / Factory Droid / OpenClaw / Hermes / Kimi Code	`graphify install --platform codebuddy \| droid \| claw \| hermes \| kimi`
Agent Skills（汎用）	`graphify install --platform agents`（alias `skills`）

always-on（グラフ優先）は graphify claude install / graphify cursor install など。一括削除は graphify uninstall（--purge で graphify-out/ も削除）。

主な extras

pdf / office / google / video / mcp / neo4j / falkordb / svg / leiden / ollama / openai / gemini / anthropic / bedrock / azure / sql / postgres / dm / terraform / pascal / ocaml / commonlisp / robot / chinese / all など。uv tool install "graphifyy[mcp]" 形式。

スキル・CLI（よく使うもの）

/graphify .                        # カレントをグラフ化
/graphify ./docs --update          # 変更ファイルのみ再抽出
/graphify . --cluster-only         # クラスタのみ再実行
/graphify . --no-viz               # HTML スキップ
/graphify . --wiki                 # グラフから markdown wiki

graphify query "what connects auth to the database?"
graphify path "UserService" "DatabasePool"
graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762
graphify update .                  # AST のみで再構築（API コストなし）
graphify hook install              # commit / checkout / merge / rewrite 後に自動再ビルド
graphify merge-graphs a.json b.json
graphify export callflow-html      # Mermaid コールフロー HTML

graphify prs                       # PR ダッシュボード
graphify prs 42                    # PR #42 のグラフ影響
graphify prs --triage              # レビューキュー順位付け
graphify prs --conflicts           # コミュニティ共有の衝突リスク

query / path / explain の終了コード: 0 回答あり、3 名前が曖昧（候補を列挙して拒否）、4 該当ノードなし。スクリプトからは終了コードで判定できる。

.graphifyrc（プロジェクト設定）

スキャンルートの .graphifyrc に、実行ごとではなくプロジェクト固有の設定を key=value 形式で書く。# で始まる行はコメント。

# .graphifyrc
# 言語名で指定
language.inc=php
# 既知の拡張子で指定
language.tpl=.ts
# git フックに埋め込まれる
viz_node_limit=0

拡張子の言語が曖昧なとき用。.inc（PHP / Pascal / SQL / アセンブリ）、.h（C / C++）、.m（Objective-C / MATLAB）などは誤判定されても失敗せず、無関係なノードが少数できるだけで、実シンボルが欠けたままグラフが埋まって見える。誤判定は言語を明示して防ぐ。typo は stderr に 1 回報告され、既定値でスキャンを続行する。

.graphifyignore とチーム

.gitignore は自動尊重。.graphifyignore は同じ構文で追加除外（マージ時は後者が優先）。チームは graphify-out/ をコミットし、各自がすぐクエリできるようにする。フック導入で AST のみの自動再ビルドと graph.json のマージドライバが有効になる。

graphify-out/

graph.html

クリック・検索・コミュニティフィルタ可能なインタラクティブ図。サーバー不要。

GRAPH_REPORT.md

God nodes・驚く接続・Suggested questions・確信度の監査レポート。

graph.json

NetworkX node-link。graph.schema_version と graph.graphify_version を含み、再読み込みなしで query / path / explain / MCP。

cache/ · callflow · Obsidian

SHA256 キャッシュ。オプションで callflow HTML、Obsidian vault、Neo4j / GraphML / SVG。

クエリ例（FastAPI コードベース）

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47
Connections: --> Dependant [uses] [INFERRED]
             <-- __init__.py [imports] [EXTRACTED]

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder
    <--references-- get_request_handler()
    --references--> ModelField

MCP サーバー

python -m graphify.serve graphify-out/graph.json
python -m graphify.serve graphify-out/graph.json \
  --transport http --host 0.0.0.0 --port 8080 --api-key "$SECRET"

ツール例: query_graph / get_node / shortest_path / list_prs / triage_prs。共有ホストでは --host 0.0.0.0 と --api-key を併用。

扱える入力（要約）

種別	内容
コード	多数の tree-sitter 文法（Python / TS / JS / Go / Rust / Java / C/C++ / Ruby / C# / Kotlin / Swift / …）。オプションで Terraform / Pascal / DreamMaker 等
Docs	`.md` / `.mdx` / HTML / YAML 等。Markdown リンク・wikilink → `references`
Office / Google	`[office]` / `[google]` + `gws`、`--google-workspace`
PDF / 画像 / 動画	セマンティックまたはローカル転写（`[video]`）
マニフェスト / MCP	パッケージ依存・MCP サーバー設定をノード化

データの行き先

コード — マシン内 AST のみ。コードのみなら API キー不要でオフライン可。
動画・音声 — faster-whisper でローカル転写。
Docs / PDF / 画像 — スキル利用時は IDE セッションのモデルへ。headless graphify extract は API キーの有無で backend を自動選択（優先順: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama）し、選ばれた環境変数名を表示する。--backend または GRAPHIFY_BACKEND で明示できる。
LLM を一切使わない — GRAPHIFY_BACKEND=none で意味抽出とラベル付けのフォールバックを無効化し、コードのみのグラフを維持。コードのみなら graphify extract --code-only で docs / PDF / 画像を除外できる。データ所在の制約がある場合は GRAPHIFY_BACKEND=ollama（完全ローカル）。Kimi（MOONSHOT_API_KEY）は中国の Moonshot AI のサーバーへ送られる。
テレメトリなし。クエリログは既定オフ。有効化は GRAPHIFY_QUERY_LOG_ENABLE=1（~/.cache/graphify-queries.log）または GRAPHIFY_QUERY_LOG=<path>。応答全文の記録は GRAPHIFY_QUERY_LOG_RESPONSES=1 を付けた場合のみ。

外部入力は security.py 経由（http/https のみ、file:// リダイレクト遮断、サイズ上限、グラフパスは graphify-out/ 内、ラベルのサニタイズ）。

公式

GitHub: Graphify-Labs/graphify
PyPI: graphifyy（v0.9.93）
docs.graphify.com — CLI リファレンス・設定・トラブルシューティング
graphify.com
Graphify Cloud — 商用の常時稼働レイヤー（README 記載。OSS 本体とは別製品）
ARCHITECTURE.md — モジュール責務
BENCHMARKS.md — 再現可能な比較
SECURITY.md — 脅威モデル
worked/ — サンプル入出力
docs/how-it-works.md — 3 パスとキャッシュ