Understanding Graph を理解する：持続的な理解のための再帰的メディア

持続的で検証可能な理解のための再帰的メディア。

Understanding Graph は、AI エージェントに構造化された持続的なメモリを提供する MCP サーバーです。事実を保存するナレッジベースとは異なり、外部から利用可能な理解の更新、すなわち緊張、驚き、決定、証拠、そして信念が時間とともにどのように進化したかを保存します。プライベートな思考連鎖（chain-of-thought）は必要ありません。複数のエージェントはグラフ自体を通じて協調できます。各エージェントは他のエージェントが書いたものを読み、それを基に構築し、次のエージェントのために検証可能な痕跡を残します——これはスティグマジー（stigmergy）です。

なぜ Understanding Graph なのか？

核となる洞察： AI エージェントは事実を覚えるだけでなく、利用可能な以前の状態、方向転換の証拠、更新された結論、そして残存する不確実性を必要とします。これにより、後の作業は隠れた熟考を再構築することなく、結論を検証または修正できます。

Related MCP server: agent-memory-mcp

クイックスタート

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

グラフを利用した作業を置きたいディレクトリでイニシャライザを実行します：

cd your-project
npx -y understanding-graph@0.1.30 init

これにより、Codex と Claude Code の両方に対してプロジェクトスコープの MCP 設定が作成され、AGENTS.md と CLAUDE.md に同じ流動的理解（fluid-understanding）契約がインストールされ、両クライアントにプロジェクトスコープの 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 サーバーと以下のスキルが得られます：

生の 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 understanding-graph@0.1.30 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", "understanding-graph@0.1.30", "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", "understanding-graph@0.1.30", "mcp"],
      "env": {
        "PROJECT_DIR": "/path/to/your/projects"
      }
    }
  }
}

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

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

PROJECT_DIR=/path/to/your/projects npx -y understanding-graph@0.1.30 start
# open http://localhost:3000

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

PORT=3101 PROJECT_DIR=/srv/undergraph/worker-1 npx -y understanding-graph@0.1.30 start
PORT=3102 PROJECT_DIR=/srv/undergraph/worker-2 npx -y understanding-graph@0.1.30 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 understanding-graph@0.1.30 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 understanding-graph@0.1.30 @huggingface/transformers@4.2.0
npx understanding-graph@0.1.30 init

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

これがない場合、グラフの他の部分は正常に動作します。graph_understand と graph_semantic_search は、埋め込みが利用できない場合に決定論的な語彙検索を使用します。セマンティック専用の分析ツールは、オプションモデルが必要な場合に説明します。

仕組み

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

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 はオンデマンドで引き続き利用できます。

アトミックコミット

graph_batch は、概念とエッジの変更、およびアトミックな多段階ドキュメント変更のエントリポイントです。1つのバッチ内で graph_add_concept、graph_connect、graph_question、graph_supersede、doc_create などを連鎖させることができます。事前検証チェックは graph_connect のID参照とタイトル参照の両方を受け入れ、推移的な到達可能性を計算します（そのため、A → B → existing というチェーンは、Aがexistingに直接触れていなくても有効です）。バッチ途中で失敗した場合、トランザクション全体がロールバックされ、中途半端な状態は残りません。

クロスプロジェクト参照

あるプロジェクトのグラフノードは、graph_add_reference({ refProject, refNodeId }) を介して別のプロジェクトのノードを参照できます。他のプロジェクトは、graph_lookup_external で切り替えずに読み取ったり、graph_global_lookup でIDだけで見つけたりできます。これは、entangled-alignment の時系列注釈パイプラインで使用される 階層的理解グラフ の基盤であり、時代やドキュメントが相互参照を描きます。

コアコンセプト

ノード（理解単位）

各認知ノードは、作成された理由を示すトリガーとともに、著者の理解更新を記録します。

トリガーは認知行為であり、カテゴリではありません。エージェントがこの正確な瞬間にノードを作成した理由を捉え、それが何の種類のものであるかではありません。最も頻繁に使用する7つ：

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

エッジ（接続）

ドキュメント

構造化された散文、ソース資料、グラフネイティブコードは、同じアドレス可能なドキュメントツリーを共有します。リーフは、パッセージ、関数、クラス、型、またはテストであり、それぞれ独自の記録された目的、起源コミット、リビジョン、およびそれを形作った質問、決定、証拠、緊張への型付きリンクを持ちます。これにより、後のリーダーは、doc_read({ nodeId, showProvenance: true, showRevisions: true }) を呼び出すことで、ファイルが存在する理由だけでなく、正確に1つのユニットが存在する理由を尋ねることができます。

implements は抽象的なコミットメントからその具体的なユニットを指します。expresses と inspired_by はアーティファクトユニットから、それがレンダリングするもの、またはその著者が影響を受けたと報告するものを指します。learned_from は認知更新から、それを引き起こしたソースまたはアーティファクトとの遭遇を指します。これらは検証可能な原因ではなく、検査可能な著者の主張です。コードルートは実行可能なファイルを生成します。ユニットは再生成前に分割、結合、移動、並べ替えが可能です。

プロジェクト

異なるコンテキストのための分離されたグラフ。各プロジェクトは独自のSQLiteデータベースを持ちます。

ツール概要

バッチ操作

概念・ノード管理（選択されたモードでリストされない限りバッチ操作）

接続管理（選択されたモードでリストされない限りバッチ操作）

読み取りと分析

合成と探索

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

ソースの読み取り

プロジェクト管理

プロジェクト横断

マルチエージェント連携 (Solver)

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

Understanding Graph は、Claude Code Agent Teams のための共有永続メディアとして設計されています。npx -y understanding-graph@0.1.30 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 Agent: found JWT stored in localStorage -- tension between convenience and XSS risk」と書くと、バックエンド担当のチームメイトは graph_history() でそれを確認し、対応します。

3. トリガーが貢献を分類します -- チームメイトはノードにタグを付け（tension、question、decision、surprise）、重要なものを見つけやすくします。「未解決の緊張をすべて表示」や「まだ開いている質問は？」などです。

4. 必須のダイレクトメッセージなしで永続的な引き継ぎ -- チームメイトはグラフ自体を通じて調整できます。リサーチャーは question ノードを残し、バックエンドエージェントは graph_find_by_trigger でそれらを見つけ、answers エッジを作成します。

スウォーム（群れ）での開始

cd your-project
npx -y understanding-graph@0.1.30 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.

長期実行の調整 (solver システム)

複数のセッションにまたがるタスクや、単一チームを超えた非同期ハンドオフが必要な場合:

solver システムは SQLite データベースに永続化されるため、タスクはセッションをまたいで存続します。あるチームが委任した作業を、将来のチームが引き継ぐことができます。

アーキテクチャ

packages/
  core/          # Graph logic, SQLite storage, embeddings
  mcp-server/    # MCP server (41 default / 69 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

環境変数

動作原則

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 understanding-graph@0.1.30 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 つのエージェントがパターンの同じ定義を共有していることを検証します。フェイルクローズのハンドシェイクにより、サイレントなセマンティックドリフトを防ぎます。

完全なウォークスルー: Understanding Graph と sema の併用

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

コードはグラフのドキュメントルートとその順序付けられた子ノードに存在します。 doc_generate または doc_generate_all で実行可能ファイルを生成し、実際のビルドと テストを実行してから、ソースノードを修正または再配置して再生成します。生成されたプロジェクションを 直接パッチしないでください。

完全なワークフローについては coding-inside-the-graph を参照してください。

引用

@misc{westerberg2026understanding,
  title        = {Understanding Graph: A Recursive Medium for Persistent 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 Protocol: modelcontextprotocol.io