Docgraph

ドキュメントをコードのように管理できます。 DocGraph は .md、.docx、.html、.pdf をグラフにインデックス化し、ドキュメントのドリフト監査を実行します。古くなったポリシー、矛盾する研究上の主張、置き換えられた ADR、文書化されていないコードのエクスポートなどを検出するため、コードベースと同じようにドキュメント群をレビューできます。多くのドキュメントツールはインデックス化と検索を行います。DocGraph はさらに、何が問題なのかも示します。

ドキュメントのドリフト監査

docgraph_context format=drift_audit

コーパス全体から 14 種類の検出コードを提示します。その一部を紹介します。

• policy.stale_review — review_due を過ぎた SOP
• policy.superseded_referenced — 置き換えられたポリシーを参照するドキュメント
• policy.conflicting — 同じ適用範囲で、規則が矛盾しているもの
• research.competing_interpretations — 互いに矛盾する主張
• research.unverified_evidence — 出典のない主張
• research.superseded_claim — 新しい主張によって覆された研究
• doc.stale_by_git — 長期間 git コミットがないドキュメント
• code.undocumented_export — ドキュメント上のアンカーがないコードの要素
• code.unanchored_feature — コード上のアンカーがない承認済み機能

3 つのパック（governance、research_provenance、entity）は有効な状態で提供され、3 つ（policy_process、assessment_drift、code_doc）はオプトインです。ガバナンスと研究には、コードに関する知識は必要ありません。どのようなドキュメントコレクションでも機能します。

出典を明示した、オプトインのエージェントによる補完

.docx / .pdf / .html のアーカイブにはフロントマターがないため、ガバナンスの対象にできません。DocGraph は権限を損なうことなく、この問題を解決します。

agent → docgraph_enrichment(action=pending)
        ↳ scope (N docs), per-model USD estimate, sensitive paths flagged, token
user  → "go"
agent → runs LLM with its own key, then action=process for each doc
        ↳ stored as source=agent_inferred (advisory, lowest authority)
        ↳ logged with model_id, agent_id, run_id, content_hash

確認トークンはバッチに紐づきます。ユーザーの同意で許可されるのは、ユーザーが確認したドキュメントのみで、それ以上は対象になりません。機密性の高いパスでは、トークンの発行が通知なく拒否されます。agent_inferred メタデータが、人間によるフロントマターや抽出されたドキュメントメタデータを上書きすることはありません。エージェントが関与しても、ガバナンスは維持されます。 DocGraph 自体が LLM を呼び出すことはありません。--enable-enrichment で有効にできます。

その他の特長

• 実用的な CJK + Latin 検索 — 英語専用ではなく、FTS5 トライグラムを使用
• CodeGraph 形式のドキュメント向けグラフトラバーサル — docgraph_graph operation=incoming|outgoing|impact|trace
• ワークスペースへのファンアウト — 1 つの MCP サーバー、N 個のプロジェクトに対し、1 回のクエリ
• レビュー可能なエビデンスパック — format=context_pack は、インデックス化されたテキスト、ハッシュ、引用、影響を返します（RAG のブラックボックスではありません）

これは何ではないか

RAG のブラックボックスでも、埋め込み専門サービスでも、Notion の代替でもありません。既存のドキュメントを監査・ナビゲート可能にし、LLM に安全に渡せるようにするレイヤーです。

LLM 向けの適合ガイド（DocGraph がプロジェクトに役立つ場合と、代わりに独自のツールを使う場合）は、AGENTS.md にあります。単一バイナリで、実行時依存関係はなく、数百件のドキュメントを数秒でインデックス化します。

概要

指標	値
言語	Go 1.25+
バイナリサイズ	約13 MB
コードベース	Goコード約23,520行（テスト約28,390行を含む）
インデックス作成速度	プロジェクトあたり70～700ファイルを2～6秒で処理（全体の再構築時。--force）
典型的なグラフ	インデックス化したファイル100個あたり、ノード約950個、エッジ約670個

インストール

go install github.com/Detective-XH/docgraph@latest

または、バージョン情報を埋め込んでソースからビルドします。

git clone https://github.com/Detective-XH/DocGraph.git
cd DocGraph
go build -ldflags "-X main.version=$(git describe --tags --always)" -o docgraph .

Go 1.25以降が必要です。

go install は -ldflags の挿入に対応していないため、この方法でインストールしたバイナリでは docgraph version の出力が dev になります。バージョン付きバイナリを入手するには、上記のソースビルドを使用してください。

CLI

docgraph init [--dry-run] [--interactive] [--install-clients auto|all|LIST] [--workspace] [--scope user] [--with-skills] [--update-skills] [path] # Create local config; optionally install MCP clients and bundled skills
docgraph install [--dry-run] [--interactive] [--clients auto|all|LIST] [--workspace] [--scope user] [--update-skills] [path]      # Configure MCP clients without re-initializing
docgraph pack list [--workspace] <path>                         # List domain packs and enabled state
docgraph pack enable [--workspace] [--no-sync] <pack-id> <path>  # Enable a domain pack; code_doc syncs by default
docgraph pack disable [--workspace] <pack-id> <path>             # Disable a domain pack; code_doc rows are removed
docgraph index [--force] [--threshold N] [--no-gitignore] [--no-history] <path>  # Index a project
docgraph sync [--threshold N] [--no-gitignore] [--no-history] <path>             # Incremental hash-based update
docgraph heal [--project <path>] [--fix] [--owner <name>] [--git-timeout <dur>]  # Infer and patch missing status/owner frontmatter fields in .md files
docgraph status <path>                       # Print index stats
docgraph serve [--threshold N] [--no-gitignore] [--no-history] [--max-watches N] [--enable-embeddings] [--enable-enrichment] --path <path>     # MCP stdio server (single project)
docgraph serve [--threshold N] [--no-gitignore] [--no-history] [--max-watches N] [--enable-embeddings] [--enable-enrichment] --workspace <dir> # MCP stdio server (auto-discover all child dirs)
docgraph version                             # Print build version

LIST は、クライアントをカンマ区切りで指定したリストです：claude,codex,hermes,opencode。 auto は常にプロジェクトローカルの Claude Code 設定を書き込み、Codex、 Hermes、OpenCode の設定ディレクトリがすでに存在する場合は、それらの設定も書き込みます。 all は、サポートされているすべてのクライアントの設定ファイルを作成します。 ファイルを書き込まずに作成・更新・変更なしの操作を表示するには、--dry-run を使用します。 同じ内容を確認し、書き込み前に承認するには、--interactive を使用します。

同梱スキル

Claude Code 用にインストールすると、DocGraph はMCP設定とともに、.claude/skills/ に関連スキルを自動でインストールします。追加のフラグは不要です。

docgraph init --install-clients claude /path/to/project  # MCP config + skill
docgraph install --clients claude /path/to/project       # MCP config + skill

--install-clients を使わずにすでに初期化済みのプロジェクトにスキルをインストールするには、次のコマンドを使用します。

docgraph init --with-skills /path/to/project

スキルは既存のものをスキップするポリシーでインストールされるため、安全に再実行できます。既存のスキルを同梱されている最新バージョンに更新するには、次のコマンドを使用します。

docgraph init --update-skills /path/to/project
docgraph install --clients claude --update-skills /path/to/project

docgraph-drift-audit スキルは、インデックス化されたすべての .md ファイルを対象に、DocGraph との互換性を監査します。フロントマターの欠落、孤立したドキュメント（外向きリンクがない）、壊れたウィキリンク、見出し、類似性の孤立領域を確認します。カテゴリごとに PASS／FAIL を報告し、docgraph_files と docgraph_similar による自動修正を提案します。

バイナリに同梱されているスキル：

スキル	目的
docgraph-drift-audit	.md ファイルのDocGraph互換性を監査します
policy-drift-audit	docgraph_context format=drift_audit からポリシー／プロセスのドリフトに関する検出結果を表示し、トリアージします
assessment-drift-audit	docgraph_context format=drift_audit から調査評価のドリフトに関する検出結果を表示し、トリアージします
code-doc-drift-audit	code_doc パックが有効な場合に、ドキュメントとコードのドリフトに関する検出結果（code.*）を表示し、トリアージします

MCP ツール

docgraph_graph は operation=incoming|outgoing|impact|trace に対応しています。incoming、outgoing、impact には document を使用し、trace には from と to を使用します。

ツール

#	ツール	説明
1	docgraph_search	セクション単位の結果、フィールドの重み付けによるランキング、グラフと Git 履歴を考慮した再ランキング、ガバナンス／研究／エンティティのフィルターに対応した FTS5 全文検索（CJK + Latin）です。デフォルトではドキュメントのみを返します。code_doc パックのコードファイルを含めるには、include_code=true または kind=code_file を指定してください
2	docgraph_context	主なエントリーポイント — 関連ドキュメント、構造、相互参照、範囲を限定したソースコンテンツを含むタスクコンテキストです。レビュー可能なエビデンスパックには format=context_pack を、ポリシー／プロセス、研究、および（code_doc が有効な場合は）ドキュメントとコードの乖離を監査するレポートには format=drift_audit を使用してください
3	docgraph_graph	グラフ走査のファサードです。operation=incoming（このドキュメントを参照しているもの）、operation=outgoing（このドキュメントがリンクしているもの）、operation=impact（影響範囲。深さを設定可能）、operation=trace（2 つのドキュメント間の最短経路）を指定します。incoming／outgoing／impact には document= を、trace には from= と to= を使用してください
4	docgraph_node	メタデータ、構造、エッジを含む単一ドキュメントの詳細です
5	docgraph_files	インデックス化されたファイルツリーです
6	docgraph_similar	トピックが類似するドキュメントを検索します（TF-IDF + 共有参照 + タグ。engine=auto/tfidf/neural）
7	docgraph_status	インデックスの状態（ファイル／ノード／エッジ／未解決項目／DB サイズ）、プロジェクトごとの統計、ニューラル埋め込みモデルの合計、ドメインパック、メタデータの品質、拡充のカバレッジ、LLM 呼び出しツールの状態（埋め込み／拡充の有効・無効 + 必須フラグ）、ポリシー／研究に関する検出結果がある場合の簡潔な乖離監査サマリーを表示します
8	docgraph_tags	すべてのタグとドキュメント数の一覧を表示するか、タグでドキュメントを絞り込みます
9	docgraph_enrichment	オプトイン（--enable-enrichment）。フロントマターのないドキュメントについて、推定された要約とメタデータを取得または保存します。ファサード：action=pending|process
10	docgraph_embeddings	オプトイン（--enable-embeddings）。ニューラル埋め込みワークフローのファサードです。action=pending は埋め込みが必要なドキュメントを一覧表示します。action=store はベクトルを保存し、ニューラル類似度を再計算します。action=clear はモデルのすべての埋め込みを削除します

調査に関する質問には、まず docgraph_context を使用してください。検索、 構造、相互参照をまとめて、単一の結果として返します。詳細を調べるには、 ほかのツールを使用してください。

DocGraph をインストール／使用するかどうかをエージェント側で判断する方法については、AGENTS.md を参照してください。インストール後のツール選択ルールは、MCP の serverInstructions（各セッションで挿入されます）と、各ツールの説明に記載されています。

エージェントのメタデータ補完

この README の冒頭で概要を説明した、オプトイン方式のワークフローの詳細です。DocGraph が LLM を呼び出すことはありません。エージェントが独自のキーを使って呼び出し、出典情報とともに結果を書き戻します。

1. docgraph_enrichment(action=pending, limit, content_mode) は、現在の推論済み要約がない、フロントマターのないドキュメントを返します。各ドキュメントには doc_id、content_hash、および長さが制限されたコンテンツが含まれます。レスポンスには、一覧表示された doc_id のバッチに紐付いた CONFIRMATION_TOKEN が含まれます。
2. エージェントが簡潔な要約と、任意のメタデータ JSON オブジェクトを推論します。
3. docgraph_enrichment(action=process, doc_id, content_hash, summary, metadata, confidence, model_id, provider, agent_id, confirmation_token) が結果を保存します。model_id は必須です。content_hash は保留中のレスポンスと一致する必要があり、confirmation_token には action=pending がそのバッチ内の doc_id に対して返したものを指定する必要があります。

推論されたメタデータが、作成者が記述したフロントマターや抽出されたドキュメントメタデータを上書きすることはありません。保存された要約は docgraph_node、docgraph_context、コンテキストパックに表示されます。docgraph_status では、補完の適用状況と古い結果を確認できます。通常の検索では、ドキュメントごとに最新の補完が 1 件使用されます。一方、DocGraph はモデル、プロバイダー、エージェント、コンテンツハッシュの出典情報を含む内部実行台帳を保持します。エージェントが推論した要約とメタデータは、参考コンテキストであり、信頼できる情報源ではありません。

プライバシー：docgraph_enrichment action=pending は、エージェントが外部プロバイダーに送信する可能性のあるドキュメントのコンテンツを返します。実行する前に、ユーザーの同意を得てください。

意味的類似性

DocGraph は、次の 3 つのシグナルを使用してドキュメント間のトピックの類似性を計算します。

シグナル	方法	重み
テキストの重複	TF-IDF コサイン類似度	50%
共通の参照	外部リンク先のジャカード類似度	30%
タグの重複	フロントマターのタグのジャカード類似度	20%

しきい値（デフォルトは 0.25）を超えるスコアのドキュメントは、similar_to エッジで接続されます。これにより、互いに明示的なリンクがなくても、概念的に関連するドキュメントを見つけられます。これは grep ベースの検索に対する主な利点です。

類似性はインデックス作成時に自動的に計算されます。docgraph_similar でクエリします。感度を調整するには、index、sync、または serve で --threshold N を指定します。値を小さくすると、similar_to エッジがより多く作成されます。

ニューラル埋め込み（エージェント主導）

DocGraph が LLM を呼び出すことはありません。代わりに、エージェントが任意のプロバイダーを使って埋め込みを計算し、ベクトルを DocGraph に送信します。このプルしてからプッシュするエージェント型ワークフローにより、TF-IDF の語彙マッチングをはるかに超える意味検索が可能になります。

1. docgraph_embeddings(action=pending, model_id, limit, content_mode) — 最新の埋め込みがないドキュメントを、コンテンツと content_hash とともに返します。content_mode=full（デフォルト）ではディスクからセクション全体を読み込み、content_mode=excerpt では保存された本文の抜粋を使用します。異なる model_id の値は別々に扱われ、相互に比較されることはありません。
2. エージェントが独自のプロバイダー（OpenAI、Ollama、Nomic など）を使ってベクトルを計算します。
3. ドキュメントごとに docgraph_embeddings(action=store, doc_id, model_id, vector, content_hash) を実行します — ベクトルを保存し、ニューラル similar_to エッジを再計算します。手順 1 で返された content_hash をそのまま渡してください。
4. 同じペアに対する TF-IDF の結果とニューラルの結果は、docgraph_similar によって重複排除され、両方が存在する場合はニューラルの結果が優先されます。

ワークスペースモードでは、どちらの埋め込みワークフローも、doc_id に基づいて正しいプロジェクトごとのストアを自動的に特定します。

プライバシー：埋め込みの pending アクションは、エージェントが外部プロバイダーに送信するドキュメントのコンテンツを返します。実行する前に、ユーザーの同意を得てください。

docgraph_embeddings(action=clear, model_id) を使用すると、モデルのすべてのベクトルを削除して、領域を解放できます。docgraph_status には、保存されているモデル、ベクトルの合計数、古いベクトルの数を示す Neural Embeddings テーブルが表示されます。

ノードとエッジの種類

ノード： document、heading、definition、tag。code_doc ドメインパックが有効な場合は、オプションで code_file ノードも対象になります。

エッジ：

種類	意味
contains	ドキュメントが見出し／定義を含みます
references	[text](path.md) 形式の Markdown リンク
wikilinks_to	[[target]] 形式のウィキリンク
related_to	フロントマターのウィキリンク（例：related_to: "[[target]]"）
similar_to	トピックの類似性（TF-IDF ＋ 共有参照 ＋ タグ。埋め込みが保存されている場合はニューラル方式）
tagged	フロントマターのタグとの関連付け
embeds	![[embed]] 形式のトランスクルージョン
links_external	外部リソースへの URL

インデックス対象

Markdown（.md） — 1 ファイルあたり最大 1 MB：

• YAML フロントマターをメタデータとして解析します。見出しと **Term:** definition 形式の行から構造ノードが生成されます
• [[wikilinks]]、[links](path.md)、![[embeds]]、外部 URL、フロントマターのタグから、型付きエッジが生成されます

Word 文書（.docx） — 1 ファイルあたり最大 10 MB：

• 見出し段落（Heading 1～6 スタイル）は、包含エッジを持つ heading ノードになります
• ハイパーリンクは docx_hyperlink エッジとして抽出されます。Dublin Core メタデータ（core.xml）はキー／値のタプルとして保存されます
• Zip Slip 対策、エントリごとのサイズ制限、展開後の合計サイズ上限 50 MB

HTML（.html、.htm） — 1 ファイルあたり最大 5 MB：

• <h1>～<h6> タグ（id 属性を含む）は heading ノードになります
• <meta name=…> と <meta property=…> はメタデータのタプルとして保存されます。<a href=…> は型付きリンクエッジになります
• <script> と <style> の内容は本文テキストおよびセクションチャンクから除外されます

PDF（.pdf） — 1 ファイルあたり最大 50 MB／500 ページ：

• 各ページは heading ノードおよびセクションチャンクになります
• Info 辞書のフィールド（Title、Author、Subject、Keywords、CreationDate）は、メタデータのタプルとしてインデックス化されます
• 画像のみの PDF は、ページあたりの平均文字数から検出され、warning: image-only-pdf としてフラグが付けられます
• 定義済みの CMap フォントはネイティブにデコードされます：Uni*-UCS2-*（UniGB/CNS/JIS/KS）、90ms-RKSJ-*（Shift-JIS）、GBK-EUC-H/V（簡体字中国語）、ETen-B5-H/V（繁体字中国語）、KSCms-UHC-H/V（韓国語）。それでもデコードできないページは warning: extraction-failed:encoding-garbage としてフラグが付けられ、置換文字の文字化けを含む状態でインデックス化されるのではなく、スキップされます

コードドキュメントの対象（オプトイン） — 1 ファイルあたり最大 1 MB：

• code_doc ドメインパックを有効にすると、ファイルヘッダー、エクスポートされたドキュメントコメント、テスト名、サンプル名をインデックス化できます：
  • 単一プロジェクト：docgraph pack enable code_doc /path/to/project
  • ワークスペース：docgraph pack enable --workspace code_doc /path/to/workspace
  • 状態の確認：docgraph pack list /path/to/project
• 対応言語には、Go、Python、Ruby、JavaScript、TypeScript、Svelte、Vue、Rust、C、C++、Java、Swift、C#、PHP、Kotlin、Dart、Lua、Luau、Pascal、SQL、Liquid が含まれます
• ソースファイルごとに code_file ノードを 1 つ追加します。40～80 個のコードファイルの場合、インクリメンタルな pack enable の同期は 1～4 秒で完了し、コードファイルが 300 個を超える場合は最大約 12 秒かかります
• 有効にした後も、docgraph_search はデフォルトでドキュメントのみを返します。コードファイルを対象にするには kind=code_file または include_code=true を指定します。また、format=drift_audit では code.* の検出結果が表示されます
• --force による再インデックスではドメインパックの状態がリセットされます。強制再構築後に docgraph pack enable code_doc <path> を再実行してください
• これは浅いドキュメントインデックス化のみを行います。呼び出しグラフ、型解決、ルート、コードへの影響分析には、引き続き CodeGraph が適切なツールです

共通ルール：

• .gitignore と .docgraphignore を尊重します
• スキップされるディレクトリ：node_modules、.git、target、dist、build、vendor、.next、.cache、__pycache__、.codegraph、.docgraph、.obsidian、.claude/worktrees（エージェントの Git ワークツリー。インデックス化すると重複として扱われる、リポジトリ全体のコピーです）。これらは常に除外されます。--no-gitignore を指定すると .gitignore のルールは解除されますが、これらのディレクトリは再び対象にはなりません。（Obsidian の保管庫では、ノートは完全にインデックス化される一方、アプリ設定ディレクトリ .obsidian/ はスキップされます。）

ドメインパック

ドメインパックは、特定のユースケース向けにメタデータスキーマを拡張します。デフォルトで3つのパックが有効になっており、3つはオプトインです。

パック	デフォルト	ドメイン	目的
governance	有効	ガバナンス	ライフサイクルのステータス、所有者、機密性、レビューのスケジュール、対象者のアクセス制御、文書の置き換え
research_provenance	有効	リサーチ	主張、根拠、ソースの種類、信頼度、アナリストのワークフロー、イベント／評価の日付、時間的な有効性
entity	有効	エンティティ	エンティティの分類、正規名称、別名の宣言。エンティティソースグラフを有効化
code_doc	無効	コード	Go、Python、JS/TS、Rust、およびその他20以上の言語のファイルヘッダー、ドキュメントコメント、テスト名、例の名前
policy_process	無効	policy_process	ポリシー／SOPの乖離検出 — 矛盾、古い文書、重複、置き換え済み、非正規の文書
assessment_drift	無効	リサーチ	評価の乖離検出 — 古い評価、未検証の根拠、競合するリサーチ解釈

パック別のフロントマター項目

各パックは、Markdownのフロントマターから特定のキーを読み取ります。

governance — ライフサイクルとアクセス制御：

status: active            # Governance lifecycle status
owner: alice              # Accountable person or role
sensitivity: internal     # Sets retrieval boundaries
allowed_audience: [engineering, legal]
review_due: 2026-12-31    # Triggers policy.stale_review when overdue
effective_date: 2026-01-01
canonical_source: true    # Marks as the authoritative copy among duplicates
approver: bob
department: Engineering
supersedes: old-policy.md
superseded_by: new-policy.md

research_provenance — 根拠と出典の追跡：

claim_id: CLM-001
source_type: primary      # primary | secondary | internal
confidence: high
analyst_status: verified
assessment_date: 2026-05-01
event_date: 2026-04-15
last_verified: 2026-05-20
valid_until: 2026-11-01   # Triggers research.stale_assessment when expired
evidence: [doc/evidence-a.md, doc/evidence-b.md]
client: ACME
deliverable_id: RPT-42

entity — 正規エンティティの宣言：

entity_type: organization   # person | organization | location | …
canonical_name: Acme Corp
aliases: [ACME, Acme Corporation]

policy_process（オプトイン）— SOPとポリシーの拡充：

sop_category: onboarding
policy_domain: HR           # HR | Security | Finance | …
process_owner: People Ops
version: "2.1"
conflict_resolution: supersedes-v2.0

assessment_drift（オプトイン）— 競合するリサーチの追跡：

contradicts: assessment-2026-03.md
supersedes_claim: CLM-099

乖離監査の検出結果

docgraph_context format=drift_audit は、有効なパックからの参考情報としての検出結果を表示します。 コードに関する知識は不要です。ガバナンスパックとリサーチパックは、あらゆる文書コレクション（.md、.docx、.html、.pdf）で機能します。

検出結果	必要なパック	検出内容
policy.stale_review	governance	review_due の期限が過ぎている
policy.superseded_referenced	governance	置き換えられた文書が、いまだに他の文書から引用されている
policy.duplicate	governance	類似度に基づいて、ほぼ重複する内容を検出
policy.non_canonical	governance	ほぼ重複する文書の中に canonical_source マーカーがない
policy.conflicting	governance	ステータスまたは発効日が矛盾する類似文書
research.stale_assessment	research_provenance	valid_until の期限が切れている
research.unverified_evidence	research_provenance	根拠の参照先を解決できない
research.competing_interpretations	research_provenance + assessment_drift	同じトピックに関する主張が矛盾している
research.superseded_claim	research_provenance + assessment_drift	古くなった主張がいまだに引用されている
research.impacted_deliverable	research_provenance	成果物が古くなった主張に依存している
doc.stale_by_git	なし（git履歴）	N日以上（デフォルトは365日）gitコミットがない。フロントマターの日付とは無関係
code.missing_symbol	code_doc	文書が、存在しなくなったコードシンボルを参照している
code.undocumented_export	code_doc	エクスポートされたシンボルにドキュメントコメントがない
code.unanchored_feature	code_doc + governance	文書で言及されている機能に、対応するコードがない

パックの管理

docgraph pack list /path/to/project                                # Show all packs and enabled state
docgraph pack enable policy_process /path/to/project               # Enable an opt-in pack
docgraph pack enable assessment_drift /path/to/project
docgraph pack enable code_doc /path/to/project                     # Also triggers incremental sync
docgraph pack disable code_doc /path/to/project                    # Removes code_file rows
docgraph pack enable --workspace policy_process /path/to/workspace # Apply to all child projects

--force による再インデックスでは、すべてのパックの状態がリセットされます。強制再構築後に docgraph pack enable <pack-id> <path> を再実行してください。

ワークスペースモード

DocGraph に親ディレクトリを指定すると、直下のすべてのサブディレクトリを個別のプロジェクトとして自動検出します。

docgraph serve --workspace /path/to/workspace

• 各プロジェクトには独自の .docgraph/docgraph.db が作成されます（.docgraph/ を .gitignore に追加してください）。
• プロジェクト横断検索では、すべてのデータベースを対象に検索します。
• ファイルウォッチャー（fsnotify、デバウンス 2 秒）が、提供中のプロジェクトを監視してリアルタイムで再インデックスします。
• ウォッチ数はプロセスごとに上限が設定されます（--max-watches、デフォルトは 8192、0 は無制限）。macOS では、監視対象のディレクトリまたはファイルごとに 1 つのディスクリプターを使用するため、非常に大きなツリーを制限なく再帰的に監視すると、OS のファイルディスクリプターテーブルが枯渇する可能性があります（さらに、クライアントが接続するたびにこのプロセスが起動すると、状況は悪化します）。上限を設定すると、ツリー全体のファイルごとにディスクリプターを 1 つ使用する代わりに、開いたままにするディスクリプターをおおむね上限数に抑えます。ただし、最も幅の広い単一の監視対象ディレクトリについては、fsnotify が先行して開くため、その分が加わります。上限を超えた場合、変更は自動的に再インデックスされません。docgraph sync を実行するか、再起動してください。フラグまたは DOCGRAPH_MAX_WATCHES で上書きできます。
• 設定ファイルは不要です。

ファイルの除外

DocGraph はデフォルトで .gitignore を尊重します。さらに細かく制御するには、.gitignore と同じ構文の .docgraphignore ファイルを作成してください。

# Project-level .docgraphignore — exclude files within a project
drafts/
archive/
*.draft.md
!archive/INDEX.md    # re-include a specific file

ワークスペースレベルの .docgraphignore（ワークスペースのルートに配置）では、ディレクトリ名でプロジェクト全体を除外できます。

# Workspace-level .docgraphignore — exclude projects
OSINT-Platform-backup-20260518
csint-private

docgraph serve の実行中に .docgraphignore を編集すると、変更は自動的に反映されます。保存時に新たに除外されたファイルはインデックスから削除されます（保護された照合処理により、コーパスの半分を超えて削除するような範囲の広すぎるパターンは、インデックスを空にせずメッセージを表示して拒否されます）。サーバーが実行されていない場合、新たに除外されたファイルは次回の docgraph index --force <path> の実行時に削除されます。docgraph_status は、有効な除外設定のソース（.gitignore、.docgraphignore、--no-gitignore）と、除外を追加する方法を報告します。

すべてのファイルをインデックスする

Git によって無視されるファイル（例：.claude/skills/、memory/ ディレクトリ）もインデックスするには、--no-gitignore フラグを使用してください。

docgraph index --no-gitignore <path>
docgraph sync --no-gitignore <path>
docgraph serve --no-gitignore --workspace <dir>

このフラグは .gitignore のルールを無視しますが、.docgraphignore は引き続き尊重します。

MCP クライアントとの連携

DocGraph は、stdio トランスポートを介して、MCP 互換のあらゆるクライアントで動作します。

自動セットアップするには：

docgraph init --install-clients auto /path/to/project
docgraph install --clients all --workspace /path/to/workspace

インストーラーは次の場所に設定を書き込みます。

クライアント	設定先
Claude Code	/path/to/project/.mcp.json
Codex	$CODEX_HOME/config.toml または ~/.codex/config.toml
Hermes Agent	~/.hermes/config.yaml
OpenCode	プロジェクトの opencode.json / .opencode.json、それ以外の場合は $XDG_CONFIG_HOME/opencode/opencode.json

Claude Code

プロジェクトレベル（このプロジェクトのみ） — プロジェクトのルートにある .mcp.json に追加するか、次を実行してください。

docgraph init --install-clients claude /path/to/project

手動で .mcp.json を設定する場合：

{
  "mcpServers": {
    "docgraph": {
      "command": "docgraph",
      "args": ["serve", "--path", "."]
    }
  }
}

ユーザーレベル（グローバル） — すべてのプロジェクトで利用できます。claude CLI を使用して ~/.claude.json に書き込みます。

docgraph install --clients claude --scope user --workspace /path/to/workspace

または、claude CLI を使用して手動で設定します。

claude mcp add --scope user docgraph -- docgraph serve --workspace /path/to/workspace

接続を確認します。

claude mcp list

重要： Claude Code はユーザースコープの MCP 設定を ~/.claude/mcp.json ではなく ~/.claude.json に保存します。~/.claude/mcp.json を手動で編集しても反映されません。代わりに claude mcp add --scope user またはプロジェクトレベルの .mcp.json を使用してください。

PATH に関する注意： docgraph が PATH に含まれている必要があります。go install でビルドした場合は、$GOPATH/bin が PATH に含まれていることを確認してください（go env GOPATH を実行すると場所を確認できます）。含まれていない場合は、バイナリの絶対パスを使用してください。

Codex (OpenAI)

MCP の設定に追加してください。

[mcp_servers.docgraph]
command = "docgraph"
args = ["serve", "--workspace", "/path/to/workspace"]

Hermes Agent

~/.hermes/config.yaml に追加してください。

mcp_servers:
  docgraph:
    command: docgraph
    args:
      - serve
      - --workspace
      - /path/to/workspace

OpenCode

OpenCode の MCP 設定に追加してください。

{
  "mcpServers": {
    "docgraph": {
      "command": "docgraph",
      "args": ["serve", "--workspace", "/path/to/workspace"]
    }
  }
}

任意の MCP クライアント

DocGraph は stdio トランスポートを使用します。次のように起動してください。

docgraph serve --workspace /path/to/workspace
# or single project:
docgraph serve --path /path/to/project

サーバーは stdin から JSON-RPC を読み取り、stdout に書き込みます。

アーキテクチャ

scan .md / .docx / .html / .pdf  (docformat registry: extensions + per-format size limits)
  -> dispatch:
       .md          → goldmark + inlined YAML frontmatter parser
       .docx        → stdlib archive/zip + encoding/xml
       .html / .htm → golang.org/x/net HTML tokenizer
       .pdf         → Detective-XH/gopdf (ledongthuc/pdf fork; text layer + CJK CMaps; writes to temp file)
       code docs    → optional code_doc pack for comments/tests/examples
  -> extract nodes, edges, links, metadata tuples, and section chunks
  -> store in SQLite (modernc.org/sqlite, pure Go)
  -> resolve cross-document references
  -> compute topic similarity (TF-IDF + graph Jaccard)
  -> serve over MCP stdio (mark3labs/mcp-go)

FTS5 は、CJK とラテン文字が混在する全文検索にトリグラムトークナイザーを使用します。

依存関係

依存関係	役割
modernc.org/sqlite	FTS5 を備えた Pure-Go SQLite ドライバー（CGo 不要）
goldmark	Markdown パーサー
yaml.v3	YAML フロントマターの解析
mcp-go	MCP プロトコル（stdio トランスポート）
fsnotify	クロスプラットフォームのファイル監視ツール
golang.org/x/net	.html／.htm の抽出に使用する HTML トークナイザー
Detective-XH/gopdf	PDF テキストレイヤーの抽出（CJK CMap デコーダーを追加した ledongthuc/pdf のフォーク）
stdlib	.gitignore と .docgraphignore の照合、および .docx 用の archive/zip と encoding/xml

サプライチェーン

CI では go mod verify によるモジュールチェックサムの検証と govulncheck の実行を行い、cyclonedx-gomod を使用して docgraph-sbom という名前の CycloneDX JSON SBOM アーティファクトを生成します。SBOM は GitHub Actions の実行時に go.mod から生成されます。生成された SBOM ファイルはリポジトリにチェックインされません。

CodeGraph との相互運用性

DocGraph と CodeGraph は相互に補完し合うものです。DocGraph はドキュメントのコンテキスト、ガバナンス／調査メタデータ、引用パス、ドキュメント参照、コンテキストパック、ドリフト監査、浅いコードドキュメントサーフェスを担当します。CodeGraph はシンボル、呼び出し元／呼び出し先、呼び出しトレース、ルートハンドラー、コードへの影響など、ソースコードのインテリジェンスを担当します。

CodeGraph との相互運用性は、現在、MCP サーバーの指示に含まれるアドバイザリー形式の引き継ぎレイヤーとして提供されています。DocGraph は CodeGraph を呼び出したり、.codegraph/ を読み取ったり、CodeGraph のシンボルアンカーをインポートしたりしません。予約済みの codegraph_anchor メタデータフィールドは、CodeGraph が安定したエクスポート／API の仕様を公開するまで空のままです。

ドキュメントとコードに関する作業では、DocGraph の code_doc パックを有効にしてください。これは DocGraph と CodeGraph の間のインターフェイスレイヤーです。DocGraph はドキュメントサーフェス（ファイルヘッダー、エクスポートされたドキュメントコメント、テスト名、例の名前）をインデックス化し、CodeGraph はコード構造（シンボル、呼び出し元／呼び出し先、呼び出しグラフ、型解決）をインデックス化します。両者を組み合わせることで全体像を把握できます。code_doc を有効にした format=drift_audit は、code.missing_symbol、code.undocumented_export、code.unanchored_feature の検出結果を提示し、エージェント環境で利用可能な場合は、シンボルレベルの質問を codegraph_* ツールに引き継げます。

着想元

DocGraph は、tree-sitter と SQLite を使用してソースコードのシンボルからナレッジグラフを構築する CodeGraph に着想を得ています。DocGraph は同じ基本設計を採用しています。

• スキーマ：nodes + edges + files + unresolved_refs + FTS5 + section_chunks + section_chunks_fts + document_metadata + governance_metadata + research_metadata + domain_packs + domain_pack_fields + entities + entity_mentions — セクションのスナップショット、セクション単位の検索、正規化されたガバナンスメタデータ、研究の来歴、ドメインスキーマパックの登録、エンティティ／ソースグラフの基本要素を追加して拡張したグラフモデルです。スキーマは、開くたびに冪等な CREATE TABLE/INDEX/TRIGGER IF NOT EXISTS によって初期化されます。スキーマの形状を変更する必要がある場合は、.docgraph/ を削除して再インデックスしてください。
• パイプライン：スキャン → 解析 → 保存 → 解決 — AST 抽出に tree-sitter の代わりに goldmark を使用する、同じ 4 フェーズのインデックス作成パイプラインです。
• 2 フェーズの解決：解析中に生のリンクを抽出し、すべてのファイルのインデックス作成後に、別の処理で解決します。これは CodeGraph の UnresolvedReference → ReferenceResolver パターンと同じです。
• MCP ツールの構成：コンテキスト、検索、ノード、類似項目、ファイル、ステータス、タグ向けの CodeGraph 互換の命名を採用したデフォルトの 8 ツールに、グラフ探索（docgraph_graph）を加えています。追加の LLM 呼び出しツール 2 つ（docgraph_embeddings、docgraph_enrichment）は、対応する --enable-* フラグが設定されている場合にのみ登録されます。グラフ探索、埋め込み、エンリッチメントはファサードツールであり、単一のディスパッチパラメーターの背後に細かな操作をまとめることで、エージェント向けの指示を簡潔に保ちます。

異なる点として、DocGraph は Go で記述されているため（単一バイナリで、Node.js ランタイムは不要）、CJK 対応にトライグラムトークナイザーを使用し、複数プロジェクトに対するファンアウトクエリ向けのワークスペースモードを追加しています。これらの機能は、コードナビゲーションではなく、ドキュメントのユースケースを反映しています。また、DocGraph はハイブリッドなトピック類似度（TF-IDF + グラフの Jaccard 係数 + タグ）も追加しており、明示的なリンクやコード構造では捉えられない概念的な関係を発見できます。

リリース v0.3.4 — SHA-256 チェックサム

EDB0808F3F248B66F53837B4888293C4BA30EEF6（Xavier）による署名です。

docgraph-darwin-arm64.tar.gz

c4dc880d8ed6796f28718c76c99e410c110366fd6c47bd991b518b023b5c28c3

docgraph-darwin-amd64.tar.gz

31dbfa7f8d6748f7147863f1f0b9549f82ca83f0e9847bc45002520c7039a1e6

docgraph-linux-amd64.tar.gz

a8ae2cf4843b47316853ee5177c89599c9893eb6d256731db432ec4565846f71

docgraph-linux-arm64.tar.gz

a9223d01473554063b0bbb584b1e7c205271c6340db3d2826a50fdefff52c3cc

docgraph-windows-amd64.zip

b1cacd26d9d69cc7169f7a6fe73cce565868d7be6131cc1a925a16545ad1a88a

検証：

gpg --verify SHA256SUMS.asc SHA256SUMS
shasum -a 256 -c SHA256SUMS

ライセンス

MIT