understanding-graph

Understanding Graph：再帰的な理解のための永続的な媒体

再帰的で、検証可能な理解のための永続的な媒体です。

Understanding Graph は、AI エージェントに構造化された永続的なメモリを提供する MCP サーバーです。事実を保存するナレッジベースとは異なり、外部から役立つ理解の更新――緊張、意外な発見、決定、証拠、そして時間の経過に伴う信念の変化――を保存します。非公開の思考過程は必要ありません。複数のエージェントはグラフ自体を介して連携できます。それぞれがほかのエージェントの記述を読み、それを基に作業し、次のエージェントが確認できる痕跡を残します――スティグマジーです。

Understanding Graph を選ぶ理由

従来のメモリ	Understanding Graph
事実を保存	作成者による理解の更新を保存
「ユーザーはダークモードを好む」	「目の疲れを感じた後、ユーザーはダークモードに切り替えた――美しさと快適さの間の緊張は、快適さを優先する形で解消された」
フラットな検索	型付けされ、見直し可能な解釈
解釈に至る中間過程が失われる	記録された根拠と改訂を保持
単一のエージェント	共有グラフを介したマルチエージェント連携

核心となる洞察： AI エージェントが必要としているのは、事実を記憶することだけではありません。利用可能な変更前の状態、方向転換を促した証拠、更新された結論、そして残る不確実性も必要です。これにより、その後の作業で、隠れた熟考を再構築せずに結論を検証したり改訂したりできます。

---

クイックスタート

Node.js 22 以降が必要です。

推奨：Codex または Claude のサブスクリプションを使用する

グラフを使った作業を行うディレクトリで、初期化ツールを実行します。

cd your-project
npx -y [email protected] init

プロジェクト単位の MCP 設定を Codex と Claude Code の両方に作成し、同じ流動的な理解に関する契約を AGENTS.md と CLAUDE.md にインストールし、両方のクライアントにプロジェクト単位の reading-mode スキルをインストールします。また、スターターグラフはインストールせずに、ローカルの projects/ パスを無視ルールに追加します。どちらかのクライアントを開き、普段お使いの ChatGPT または Claude のサブスクリプションでサインインして、実際の調査、執筆、コーディング、または意思決定のタスクを依頼してください。実際の作業が始まると、エージェントが内容を表す名前のグラフを作成します。「グラフを使って」と伝える必要はありません。モデルはサブスクリプションクライアント上で動作し、Understanding Graph 自体はモデル API を呼び出しません。

新たに時系列順に読むには、エージェントにファイルパスを渡し、リーダーモードを有効にするよう依頼してください。ソースの本文を返したりサンプリングしたりせずに準備し、その後は source_read を通じて次の順序どおりの一節だけに触れながら、先へ進む前に通常の、該当箇所に基づく理解を付加できます。Codex では $reading-mode、Claude Code では /reading-mode も利用できます。チャットに直接貼り付けたテキストにはすでに触れているため、本当に新鮮な状態で読む必要がある場合はファイルパスを使用してください。

Codex は対象となる ChatGPT プランで利用できます。また、Claude Code は Claude Pro または Max で利用できます。通常のプラン上限は引き続き適用されます。

インストール可能なプラグイン（ワークフロースキル＋MCP サーバー）

パッケージには .codex-plugin と .claude-plugin のマニフェストが含まれています。 このプラグインは、MCP の機能と understanding-work スキルを組み合わせています。モードが有効な間、作業や今後の調査に役立つ、伝達可能な理解がグラフ上に展開されます。 グラフは、状態に応じて次に取り得る具体的な行動を少数提示します。モデルはユーザーのタスクを踏まえてそれぞれの重みを判断し、自由に選択、組み合わせ、変更、または却下します。上記の初期化ツールを使えば、プラグインディレクトリの一覧を待たずに同じ仕組みを利用できます。

Claude Code では、既存のマーケットプレイスの手順を利用できます。

# One-time: add the Emergent Wisdom marketplace
claude plugin marketplace add emergent-wisdom/marketplace

# Install the plugin
claude plugin install understanding-graph

ローカル開発の場合：

claude --plugin-dir /path/to/understanding-graph

これにより、MCP サーバーと次のスキルが利用できるようになります。

スキル	呼び出し方法	内容
understanding-work	(自動読み込み)	重み付けされた、モデルが選ぶきっかけを通じた、グラフを介した柔軟な理解
orient	/understanding-graph:orient	会話開始時にグラフの状態を読み取る
quality-check	/understanding-graph:quality-check	評価、分析、サーモスタット
reading-mode	/understanding-graph:reading-mode	source_read を使った原典の精読
serendipity	/understanding-graph:serendipity	根拠に基づく、または純粋なセレンディピティを通じて新規性をもたらす
web-ui	/understanding-graph:web-ui	:3030 で 3D 可視化を起動する
graph-workflow	(自動読み込み)	グラフの共通ルールと、タスクからワークフローへの振り分け
code-work	(自動読み込み)	グラフネイティブなコードノード、生成、実行可能な証拠
collaborative-code	(自動読み込み)	コードサブツリーの所有権、引き継ぎ、ロック、統合の証拠
creative-work	(自動読み込み)	書籍、散文、脚本、編集による改稿

生の MCP サーバーは互換性のある任意のクライアントで動作しますが、同梱のスキルまたは生成されたプロジェクト指示を使用することを推奨します。ツールスキーマだけでは、複数ステップからなる理解ワークフローは安定して有効になりません。

初期化ツールが作成するもの

次のものが作成されます。

• .codex/config.toml -- Codex の MCP 設定
• .mcp.json -- Claude Code のプロジェクト MCP 設定
• AGENTS.md と CLAUDE.md -- 同一の標準的な理解ワークフロー
• .agents/skills/reading-mode/SKILL.md -- Codex 用の明示的な読解ワークフロー
• .claude/skills/reading-mode/SKILL.md -- Claude Code 用の明示的な読解ワークフロー
• .gitignore の projects/ エントリ -- グラフデータをローカルに保持します。初期プロジェクトは作成されません。

このディレクトリで開いたすべてのセッションは、同じプロジェクトルートを共有します。名前付きグラフを選択すると、そのグラフ上で作業するエージェントも同じグラフを共有します。追加のエージェントを使うのは、作業に実際の独立した分担領域がある場合に限ってください。

生の MCP 設定（上級者向け）

クライアントでプラグインをインストールできない場合や、初期化ツールを実行できない場合は、MCP サーバーに直接接続してください。

claude mcp add ug -- npx -y [email protected] mcp

MCP の初期化では、簡潔なグラフ利用の契約も提供されますが、サーバー指示へのクライアントの対応状況はさまざまです。一貫した動作を得るには、同梱の understanding-work スキルまたは生成されたプロジェクト指示も提供してください。

クライアントごとのセットアップガイド：Claude Code · Claude Desktop · Cursor · mcporter

Claude Desktop

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects",
        "UG_SOURCE_ROOT": "/path/to/your/source-project"
      }
    }
  }
}

UG_SOURCE_ROOT は、ファイルベースのソース読み込みをそのディレクトリに制限します。プロジェクト初期化ツールは、自動的にプロジェクトルートを設定します。

Cursor / Windsurf

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

{
  "mcpServers": {
    "understanding-graph": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects"
      }
    }
  }
}

Web UI / 3D ビジュアライゼーション

ルートの npm パッケージにはビルド済みのフロントエンドが含まれており、Web サーバーに依存しているため、公開済みのパッケージから UI を直接起動できます。

PROJECT_DIR=/path/to/your/projects npx -y [email protected] start
# open http://localhost:3000

各プロセスに独自のポートとプロジェクトストアのルートを割り当てて、独立したサイドカーを実行します。ルートには、同じボリューム上の兄弟ディレクトリを指定できます。

PORT=3101 PROJECT_DIR=/srv/undergraph/worker-1 npx -y [email protected] start
PORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y [email protected] start

デプロイでは絶対パスを使用してください。インストール済みのパッケージと読み取り専用のフロントエンドを共有するのは安全ですが、独立したサイドカーで同じ PROJECT_DIR を指定しないでください。

デフォルトでは、サーバーはループバックにバインドします。別のホストでワーカーを実行するには、HOST とプライベートなワーカートークンを明示的に設定してください。どちらかが設定されていない場合、ループバック以外での起動はフェイルクローズします。

HOST=0.0.0.0 PORT=3101 \
UG_WORKER_TOKEN=replace-with-a-long-random-secret \
PROJECT_DIR=/srv/undergraph/worker-1 \
npx -y [email protected] start

信頼された呼び出し元は、すべての /api または /admin リクエストに Authorization: Bearer <UG_WORKER_TOKEN> を含める必要があります。リモートトラフィックは、TLS または認証済みのプライベートネットワーク経由にしてください。

代わりに、チェックアウトしたリポジトリから UI を開発するには、次のようにします。

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web
# open http://localhost:3000

オプション：埋め込みベースの検索を有効にする

graph_semantic_search、graph_similar、graph_semantic_gaps、graph_backfill_embeddings では、@huggingface/transformers（ローカル埋め込みモデル。コンパイル後のサイズは約 160 MB）を使用できます。これはオプションのピア依存関係であり、デフォルトのインストールを小さく保てます。npx ベースのプロジェクトでは、Node が同じ依存関係ツリーからピア依存関係を解決できるよう、両方のパッケージをローカルにインストールしてください。

npm install --save-dev [email protected] @huggingface/[email protected]
npx [email protected] init

別途グローバルにインストールした @huggingface/transformers では、分離された npx キャッシュ内のインストールを確実に満たせません。

これをインストールしなくても、グラフのほかの機能は通常どおり動作します。埋め込みを利用できない場合、graph_understand と graph_semantic_search は決定論的な語彙検索を使用します。セマンティック分析専用のツールは、オプションのモデルが必要な場合にその理由を説明します。

---

仕組み

概念とエッジへの直接的な変更は graph_batch を通じて行います。関連するワークフローモードでは、ドキュメント用のヘルパーもトップレベルに公開されています。関連するドキュメント、概念、エッジの変更をまとめて反映する場合は、バッチを使用してください。すべてのバッチには commit_message が必要で、SQLite トランザクション内で実行されます。いずれかの操作に失敗すると、実行されなかった場合と同じように、バッチ全体がロールバックされます。source_read などのワークフローツールは、独自のアトミックな更新を管理します。通常の作業では、ノードの履歴を保持しながら改訂、アーカイブ、または置き換えを行います。元に戻せない完全削除は、明示的に選択する別個の管理操作です。コミットストリームは、内容を確認できる更新ログになります。各ノードのコミットメッセージが、そのノードの由来の記録になります。

1. project_switch({ project: "my-project" })
2a. DIRECT: use graph_understand, graph_batch, or another graph tool immediately
2b. GUIDED: graph_suggest_next({ task, workflow: "coding" })
3. [if guided, judge, modify, reject, skip, or choose a sampled route]
4. graph_batch({ commit_message, agent_name, ... }) # preserve artifact + understanding

オプションのチューザーは、理解を深めたり広げたりする、見過ごされてきた資料を見つける、現在の見方を検証する、有用なつながりを明らかにするといった用途で、グラフ固有の手がかりを提示するための補助機能です。候補はグラフとワークフローに応じて重み付けされた圧力からサーバー側でサンプリングされ、可能な場合は具体的なノードや領域が含まれます。また、最近提案されたアクションの種類は一時的に重みが下げられます。タスクへの適合性は引き続きモデルが判断します。モデルはいつでも、直接作業する、別のことをする、作業を止めるといった選択ができ、無理に作業を作り出す必要はありません。周囲に候補を提示するプロンプトをなくすには、UG_GUIDANCE_MODE を direct に設定してください。graph_suggest_next は引き続き必要に応じて利用できます。

通常のガイダンスは必要だが、根拠のあるランダム比較、ビソシエーション、ANI、攪乱、一時的な強制は必要ない場合は、個別のロールに creativity: false を渡してください。この設定はそのロールにのみ適用されます。オプションの創造性ツールは、引き続き直接利用できます。

検索には、互いに独立した 2 つの軸があります。workflow はドメインとその固有の証拠を示し、stance は深化、抵抗、つながり、攪乱、再検討、検証などの認識論的な圧力の重み付けを指定します。どちらの軸も、モデルが実行できることを制限しません。

アトミックコミット

graph_batch は、概念やエッジの変更、および複数ステップにわたるドキュメントの変更をアトミックに行うためのエントリーポイントです。1 つのバッチ内で、graph_add_concept、graph_connect、graph_question、graph_supersede、doc_create などを連鎖させて実行できます。事前検証では、graph_connect の参照に ID と タイトル の両方を受け付け、推移的な到達可能性も計算します（つまり、A が既存のノードに直接つながっていなくても、A → B → existing という連鎖は有効です）。バッチの途中でエラーが発生すると、トランザクション全体がロールバックされ、中途半端な状態は残りません。

プロジェクトをまたぐ参照

あるプロジェクトのグラフノードは、graph_add_reference({ refProject, refNodeId }) を使って別のプロジェクトのノードを参照できます。他のプロジェクトからは、プロジェクトを切り替えずに graph_lookup_external で読み取ったり、ID だけで graph_global_lookup を使って検索したりできます。これは、時代やドキュメントが相互参照を行う、entangled-alignment の時系列アノテーションパイプラインで使われている 階層型理解グラフ の基盤です。

---

コアコンセプト

ノード（理解の単位）

各認知ノードは、作成された 理由 を示すトリガーを含む、記述された理解の更新を記録します。

トリガーはカテゴリではなく、認知的行為です。つまり、それがどのようなものかではなく、エージェントがそのノードをまさにその時点で作成した 理由 を示します。最もよく使う 7 つは次のとおりです。

トリガー	使用するタイミング
foundation	中核となる概念、公理、出発点
surprise	予想外の発見、以前の信念に反するもの
tension	アイデア間の対立、未解決の問題
consequence	下流への影響
question	探究すべき未解決の問い
decision	根拠を伴う、選択肢の中から下した決定
prediction	後で検証できる、将来に関する信念

あまり一般的ではありませんが、次のものも利用できます：hypothesis、model、evaluation、analysis、experiment、serendipity、repetition、randomness、reference、library。これらの通常の認知ノードは、将来のエージェントが作業に再び取り組む際に役立つ場合、確定した結論だけでなく、豊かで暫定的、未解決の証言も保持できます。thinking トリガーは異なり、基盤となるグラフから時系列のトレーニングブロックを再構成する、独立した合成 Reader/CMP シンセサイザー専用です。予約済みブロックは通常の読み取り、書き込み、コーディング、および一般的なワークフローから隠され、変更できません。アクセスできるのは TOOL_MODE=synthetic_reader のみです。慎重に選定された 18 種類のトリガーの全容は、understanding-graph の論文（セクション 3.1）に記載されています。これは進化し続ける設計であり、形式上の最小要件を主張するものではありません。

エッジ（接続）

エッジタイプ	意味
supersedes	新しい理解が古い理解に取って代わります。専用の graph_supersede ライフサイクル操作で作成されます
contradicts	アイデア同士が対立しています
refines	既存の理解に精度を加えます
learned_from	洞察の帰属先
answers / questions	問いを解決する、または提起する
contains	親子関係
next	順序

ドキュメント

構造化された文章、ソース資料、グラフネイティブなコードは、同じアドレス指定可能なドキュメントツリーを共有します。リーフには、文章、関数、クラス、型、テストなどがあり、それぞれに記録された目的、由来のコミット、改訂履歴、そしてそれを形作った質問、決定、証拠、緊張関係への型付きリンクが含まれます。これにより、後から読む人はファイルが存在する理由だけでなく、特定の単位が存在する理由も、doc_read({ nodeId, showProvenance: true, showRevisions: true }) を呼び出して尋ねられます。

implements は抽象的なコミットメントから具体的な単位へ向けられます。expresses と inspired_by は、成果物の単位から、それが表現するもの、または作者が影響を受けたと報告するものへ向けられます。learned_from は、認知的な更新から、そのきっかけとなった情報源や成果物との遭遇へ向けられます。これらは検証済みの因果関係ではなく、確認可能な、作者が記した主張です。コードルートは実行可能なファイルを生成します。再生成する前に、単位を分割、統合、移動、並べ替えできます。

プロジェクト

異なるコンテキスト用の分離されたグラフです。各プロジェクトには独自の SQLite データベースがあります。

---

ツール概要

デフォルトの general サーフェスに含まれる46個のツールから選んだツール、明示的な full モードの70個のツール、および graph_batch から呼び出せるバッチ専用操作（クリックして展開）

バッチ操作

ツール	目的
graph_batch	複数の操作を、必須の commit_message とともにアトミックなコミットとして実行します。SQLite トランザクションでラップされており、操作が1つでも失敗すると、バッチ全体がロールバックされます。commit_message はノードの由来の物語として保持されます。将来、これらのノードを読むエージェントは、内容だけでなく、それを作成した意図も確認できます。

概念とノードの管理（選択したモードに記載がない限り、バッチ操作）

ツール	目的
graph_add_concept	重複を検出しながら新しい概念を追加
graph_question	探索用の質問ノードを作成
graph_revise	概念の理解を更新
graph_supersede	古くなった概念を置き換え
graph_add_reference	外部またはプロジェクト間の参照を追加
graph_rename	ノードの名前を変更（ソフト参照を更新）
graph_archive	履歴を保持したままソフト削除
node_set_metadata	ノードに任意のメタデータを設定
node_get_metadata	ノードのメタデータを取得
node_set_trigger	ノードの分類を変更
node_get_revisions	理解の変遷履歴を取得

接続の管理（選択したモードに記載がない限り、バッチ操作）

ツール	目的
graph_connect	概念間のエッジを作成
graph_answer	質問ノードへの回答を記録
graph_disconnect	エッジを削除またはアーカイブ
edge_update	エッジの種類または説明を更新
edge_get_revisions	関係の履歴を取得

読み取りと分析

ツール	目的
graph_understand	事前知識、抵抗、証拠、型付き関係を含む、ワークフロー固有の再開用パケットを構成
graph_skeleton	構造の概要（約150トークン）
graph_context	グラフ全体の XML を取得。任意の1ノードに焦点を当てることも可能で、50ノードを超える場合は自動的に圧縮
graph_context_region	context、skeleton、または search が返した、番号付きの1つの領域の詳細を取得
graph_semantic_search	意味に基づいてノードを検索
graph_similar	概念的に類似したノードを検索
graph_find_by_trigger	種類でノードを検索
graph_analyze	構造上の欠落、循環、橋渡しとなるノード、未解決の質問、セレンディピティノードを検出
graph_semantic_gaps	接続されていない概念を検出
graph_score	時系列、改訂、解決状況、エッジの具体性、接続性を対象とした構造的な代理指標（意味的な品質ではありません）
graph_path	概念間の推論経路
graph_centrality	最も影響力のある概念
graph_thermostat	収束、継続、分岐に関する、エントロピー形式の助言的な状況指標
graph_history	コミット履歴と変更内容

### 統合と探索

ツールキットの中央値脱出ブランチ――特に ANI と Axiomatic Forcing――は、The Ontology of the Alien に着想を得ています。ランダムな手がかり、一時的な公理、代替物理学の思考実験を、出力が精査されるまでは推測にとどまる、エージェント向けの任意のツールとして応用しています。

ツール	目的
graph_bisociate	拡散活性化と情報利得を用いて、文脈をまたぐ候補ペアを提示します
graph_discover_grounded	グラフ内の離れた情報を比較するための、デフォルトの範囲制限付き手法です。有効なつながりがない場合もあります
graph_discover_grounded_chaos	実際に根拠のある橋渡しが見つかった後に、任意で辞書に揺らぎを加えます。ホストにインストールされた単語リストが必要です
graph_discover	グラフ内の情報に対して、明示的に推測を行うブラインド ANI です
graph_random	精査を前提とした任意の Physics What-If forcing を含む、具体的なランダムな発想のきっかけを提示します
graph_serendipity	バッチ専用：ソースエッジを用いて統合結果を記録します
graph_validate	バッチ専用：精査済みのセレンディピティに対する、作成者による検証判断を記録します
graph_chaos	マシンローカルの辞書またはグラフノードからテキストに単語を注入します
graph_decide	バッチ専用：選択肢に対する型付きの決定を記録します
graph_evaluate_variations	実験的な Novelty Score で代替案をランク付けします

ドキュメント操作（利用可否はワークフローモードによって異なります）

ツール	目的
doc_create	内容を含むドキュメントを作成します
doc_revise	ドキュメントのテキストを変更します
doc_insert_thinking	synthetic_reader のみ：再構成された Reader/CMP 事前学習ブロックを挿入します
doc_append_thinking	synthetic_reader のみ：再構成された Reader/CMP 事前学習ブロックを末尾に追加します

ソースの読み取り

ツール	目的
source_load	段階的に読むためのテキストを読み込みます
source_read	次の部分を読み取り、ノードを自動作成します
source_position	読み取りの進捗を取得します
source_list	読み込んだソースを一覧表示します
source_export	ソーステキストを正確に再構成します。synthetic_reader では、予約済みの Reader/CMP ブロックも追加でエクスポートできます

プロジェクト管理

ツール	目的
project_switch	アクティブなプロジェクトを切り替えます
project_list	利用可能なプロジェクトを一覧表示します

プロジェクト間（TOOL_MODE=full）

ツール	目的
graph_lookup_external	別のプロジェクト内のノードを検索します
graph_list_external	アクセス可能な外部プロジェクトを一覧表示します
graph_find_by_reference	概念を参照しているノードを検索します
graph_resolve_references	プロジェクト間の参照を検証します
graph_global_lookup	すべてのプロジェクトを横断して検索します

マルチエージェント連携（Solver）

Solver ツールは、research、collaborative_coding、full の各ツールモードで利用できます。

ツール	目的
solver_spawn	専門のソルバーエージェントを登録します
solver_delegate	ソルバーのキューにタスクを投稿します
solver_claim_task	保留中のタスクを取得します（ワーカーモード）
solver_complete_task	タスクの結果を提出します
solver_list	登録済みのソルバーを一覧表示します
solver_queue_status	タスクキューの統計情報を表示します

---

Claude Code Agent Teams によるマルチエージェント

Understanding Graph は、Claude Code Agent Teams 向けの共有永続メディアとして設計されています。npx -y [email protected] init の実行後、リードが名前付きグラフを作成または選択します。そのプロジェクトルートで作業するすべてのチームメイトがグラフを共有でき、データを同梱せずにスティグマジーを実現します。

動作の仕組み

You: "Create an agent team to research and implement auth for this app"

Claude (Team Lead):
  ├── Researcher teammate   ─── reads/writes shared graph ───┐
  ├── Backend teammate       ─── reads/writes shared graph ───┤  Same Understanding Graph
  ├── Security teammate      ─── reads/writes shared graph ───┤  (via MCP)
  └── synthesizes findings from graph_history()               ┘

1. init により、すべてのチームメンバーに同じ流動的なプロトコルが適用されます -- 各エージェントはグラフを標準的な媒体として扱い、直接作業することも、自然な選択ポイントで graph_suggest_next を使って具体的な可能性を尋ねることもできます。
2. コミットメッセージが調整レイヤーになります -- 各 graph_batch には commit_message が必要です。Security チームメンバーが「Security Agent: found JWT stored in localStorage -- tension between convenience and XSS risk」と記すと、Backend チームメンバーは graph_history() からそれを確認し、対応できます。
3. トリガーによって貢献が分類されます -- チームメンバーはノードにタグ（tension、question、decision、surprise）を付けるため、「未解決の緊張点をすべて表示して」や「未回答の質問は何？」といった検索が簡単になります。
4. 直接メッセージのやり取りを必須としない、継続的な引き継ぎ -- チームメンバーはグラフ自体を通じて調整できます。リサーチャーが question ノードを残し、バックエンドエージェントが graph_find_by_trigger でそれを見つけて、answers エッジを作成します。

スウォームを始める

cd your-project
npx -y [email protected] init     # one-time setup

次に、Claude Code で次を実行します：

Create an agent team with 3 teammates to [your task].
Each teammate should work through the shared Understanding Graph,
preserve material understanding as it emerges, and use graph_batch
with descriptive commit messages so the team can coordinate.

長期間にわたる調整（ソルバーシステム）

複数のセッションにまたがるタスクや、1つのチームだけでは完了しない非同期の引き継ぎが必要な場合：

ツール	目的
solver_spawn	専門家（例：「SecurityReviewer」、「ArchiveKeep」）を登録します
solver_delegate	タスクをキューに登録します
solver_claim_task	保留中の作業を引き受けます（ワーカーモード）
solver_complete_task	結果を提出します
solver_lock / solver_unlock	共有ノードでの競合を防ぎます

ソルバーシステムは SQLite データベースに状態を保持するため、タスクはセッションをまたいで維持されます。あるチームが委任した作業を、後のチームが引き受けることができます。

---

アーキテクチャ

packages/
  core/          # Graph logic, SQLite storage, embeddings
  mcp-server/    # MCP server (46 default / 70 full tools + batch operations)
  web-server/    # REST API + serves frontend
  frontend/      # 3D visualization (React + Three.js)

スタック：

• SQLite + better-sqlite3 -- 永続ストレージ
• Graphology -- インメモリーグラフ操作
• MCP Protocol -- エージェントとの統合
• Transformers.js -- セマンティック検索向けのローカル埋め込み

---

開発

git clone https://github.com/emergent-wisdom/understanding-graph.git
cd understanding-graph
npm install
npm run build
npm run start:web    # Web UI at http://localhost:3000

開発モード

# Terminal 1: Web server with hot reload
npm run dev:web

# Terminal 2: Frontend dev server
cd packages/frontend && npm run dev

---

環境変数

変数	デフォルト	説明
PROJECT_DIR	./projects	プロジェクトデータの保存先
UG_SOURCE_ROOT	現在の作業ディレクトリ	source_load.filePath が読み取れるディレクトリです。この範囲外にあるファイルには content を直接指定してください
PORT	3000	Web サーバーのポート
HOST	127.0.0.1	Web のバインドアドレスです。ループバック以外を指定する場合は UG_WORKER_TOKEN が必要です
UG_WORKER_TOKEN	--	リモートワーカー API／管理者リクエストに必要なベアラーシークレット
ANTHROPIC_API_KEY	--	リポジトリの自律型ワーカースクリプト用（任意）
ANTHROPIC_MODEL	--	任意の Anthropic 自律型ワーカーに使用する明示的なモデル ID
TOOL_MODE	general	適用するツール範囲：安全なクロスドメインの general、対象を絞った reading、research、coding、collaborative_coding、writing、明示的に広範囲な full、または予約済みの事前学習データ生成用 synthetic_reader
UG_GUIDANCE_MODE	guided	提案補助機能：guided は次のアクション候補を任意で提示します。direct は、必要に応じて呼び出せる graph_suggest_next を維持しつつ、常時表示されるプロンプトを抑制します
UG_ANI_DICTIONARY_PATH	システムの単語リスト	/usr/share/dict/words やその他の標準パスが利用できない場合に使用する、ホストにインストールされた改行区切りの単語リストへの絶対パスです。辞書は同梱されず、代替機能では単語数が減少します
DEFAULT_PROJECT	未設定	起動時に読み込む、または明示的に作成する任意のプロジェクト

作業原則

1. グラフを媒体として使う — Understanding モードが有効な間は、最終的な回答だけでなく、作業に重要な、伝達可能な理解と参照可能な成果物の単位を保持します。
2. 主体性をモデルに委ねる — 任意の補助機能が役立つ場合、graph_suggest_next は重み付けされた具体的な提案を提示します。モデルはユーザーのタスクに応じて、直接作業することも、提案を選択、組み合わせ、変更、拒否、置き換え、またはスキップすることもできます。
3. 作業を変えうるときに再確認する — 定期的なタイマーや形式的な儀式としてではなく、実際の選択が必要な場面、予想外の出来事、抵抗、不確実性が生じたときに、蓄積されたグラフを見直します。
4. 書き写すのではなく、統合する — 入力をコピーするのではなく、未解決の影響や緊張関係も含め、やり取りによって何が変わったかを保持します。自由な探索の後に安定化を確認する任意の手段として PURE を利用できますが、ノルマでも、新たな発想への門番でもありません。
5. 来歴を保持する — 内容がわかるコミット、専用の改訂および置き換え操作、実際の成果物から得られた証拠を使用し、共同作業で実際に必要な場合は、所有者や引き継ぎを明示します。

---

sema と併用する

Understanding Graph は、エージェントに共有のエピソード記憶、つまり判断に至るまでの解釈の記録を提供します。Sema は、コンテンツアドレス方式の認知パターンの語彙である共有の意味記憶を提供します。両者を組み合わせることで、次のことが可能になります。

# Add both to Claude Code
claude mcp add ug   -- npx -y [email protected] mcp
claude mcp add sema -- uvx --from semahash sema mcp

両方をインストールすると、エージェントは次のことができます。

1. ノードの understanding または why のテキスト内で sema パターンの URI（例：sema://StateLock#7859）を参照し、協調プリミティブの意味を明確にできます。
2. graph_semantic_search を使用して、現在のプロジェクト内でパターンを参照するノードを検索できます。複数のグラフにまたがって検索する場合は、プロジェクトを明示的に切り替えるか、プロジェクト横断の参照ツールを使用します。
3. sema_handshake を呼び出して、グラフ内で互いの考えを土台にする前に、2 つのエージェントがパターンの同じ定義を共有していることを確認できます。このフェイルクローズ方式のハンドシェイクにより、気づかないまま意味がずれていくことを防ぎます。

詳しい手順：sema と Understanding Graph を併用する

グラフ内でのコーディング

コードは、グラフのドキュメントルートと、その順序付けられた子ノードに格納されます。doc_generate または doc_generate_all で実行可能なファイルを生成し、実際のビルドとテストを実行してから、ソースノードを改訂または並べ替えて再生成します。生成された投影を直接修正してはいけません。

ワークフローの詳細については、グラフ内でのコーディングを参照してください。

---

引用

@misc{westerberg2026understanding,
  title        = {Understanding Graph: A Persistent Medium for Recursive Understanding},
  author       = {Westerberg, Henrik},
  year         = {2026},
  month        = aug,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19462658},
  url          = {https://doi.org/10.5281/zenodo.19462658}
}

機械可読形式については、CITATION.cffを参照してください（GitHub はこのファイルから「このリポジトリを引用」ボタンを表示します）。

ライセンス

MIT -- LICENSE

GitHub： emergent-wisdom/understanding-graph npm： understanding-graph MCP プロトコル： modelcontextprotocol.io