理解图：一种用于持久理解的递归媒介

一种用于持久、可检查理解的递归媒介。

理解图（Understanding Graph）是一个 MCP 服务器，为 AI 智能体提供结构化、持久的记忆。与存储事实的知识库不同，它存储对外部有用的理解更新——张力、意外、决策、证据，以及信念如何随时间演变。它不需要私有的思维链。多个智能体可以通过图本身进行协调：每个智能体读取其他智能体所写的内容，在此基础上构建，并为下一个留下可检查的痕迹——即 stigmergy（间接协作）。

为什么选择理解图？

核心洞察： AI 智能体不仅需要记住事实——它们还需要可用的先前状态、转折性证据、更新后的结论和剩余的不确定性。这使得后续工作能够测试或修订结论，而无需重建隐藏的推理过程。

Related MCP server: Loxo

快速开始

推荐：使用你的 Codex 或 Claude 订阅

在你希望进行基于图的工作的目录中运行初始化器：

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

它为 Codex 和 Claude Code 创建项目范围的 MCP 配置，在 AGENTS.md 和 CLAUDE.md 中安装相同的流体理解契约，为两个客户端安装项目范围的 reading-mode 技能，并将本地 projects/ 路径添加到忽略规则中，而不安装任何起始图。打开任一客户端，使用你正常的 ChatGPT 或 Claude 订阅登录，并请求实际的研究、写作、编码或决策任务。当实际工作开始时，智能体会创建一个描述性命名的图。你不需要说“使用图”。模型在订阅客户端中运行；理解图本身不进行任何模型 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

通过为每个进程分配自己的端口和项目存储根来运行独立的 sidecar。这些根可以是同一卷上的兄弟目录：

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

在部署中使用绝对路径。共享已安装的包及其只读前端是安全的；不要将独立的 sidecar 指向相同的 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）。它是一个可选的 peer 依赖，因此默认安装保持小巧。对于基于 npx 的项目，请本地安装两个包，以便 Node 从同一依赖树中解析 peer：

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 之类的工作流工具管理自己的原子更新。普通工作会修订、归档或取代节点，同时保留其历史；不可逆的清除是单独的、明确选择的管理操作。提交流成为可检查的更新日志——每个节点的提交消息成为其起源故事。

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

可选的 chooser 是用于浮现可能加深或多样化理解、恢复被忽视的材料、测试当前视图或暴露有用连接的图特定指针的辅助工具。建议在服务器端从图和工作流加权的压力中采样，尽可能包含具体节点或区域，并临时降低最近建议的动作类型的权重。模型仍然负责任务适配，并且可以始终直接工作、做其他事情或停止，而不是制造工作。将 UG_GUIDANCE_MODE 设置为 direct 以移除环境建议提示；graph_suggest_next 仍可按需使用。

原子提交

graph_batch 是概念和边变更以及原子性多步骤文档变更的入口点。在一个批次内，你可以链式调用 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 时间顺序标注流水线所使用的 层次理解图 的基础，其中时代和文档会建立交叉引用。

核心概念

节点（理解单元）

每个认知节点都捕获一次作者的理解更新，并带有一个 触发器 标记 创建原因：

触发器是 认知行为，而非类别——它们捕获的是代理在此确切时刻创建节点的 原因，而不是它是什么类型的事物。你最常使用的七个触发器：

较少见但可用：hypothesis、model、evaluation、analysis、experiment、serendipity、repetition、randomness、reference、library。这些普通认知节点可以保留丰富、临时、未解决的证词——而不仅仅是已定论的结论——当它有助于未来的代理重新进入工作时。thinking 触发器则不同：它保留给独立的合成 Reader/CMP 合成器，该合成器从底层图重建时间顺序的训练块。保留块对普通阅读、写作、编码和一般工作流是隐藏且不可变的；只有 TOOL_MODE=synthetic_reader 才能访问它们。完整、精心选择的 18 种触发器类型记录在 understanding-graph 论文（第 3.1 节）中；这是一个不断演进的设计，而非声称的形式化最小值。

边（连接）

文档

结构化散文、源材料和图原生代码共享同一棵可寻址的文档树。叶子节点可以是段落、函数、类、类型或测试，并带有其自身的记录目的、来源提交、修订版本，以及指向塑造它的问题、决策、证据或张力的类型化链接。这使得后来的 Reader 可以通过调用 doc_read({ nodeId, showProvenance: true, showRevisions: true }) 来询问为什么存在某个确切的单元——而不仅仅是为什么存在该文件。

implements 从抽象承诺指向其具体单元；expresses 和 inspired_by 从工件单元指向它所呈现的内容或其作者报告为有影响力的内容；learned_from 从认知更新指向引发它的来源或工件遭遇。这些是可检查的作者声明，而非已验证的因果关系。代码根生成可运行的文件；单元可以在重新生成之前被拆分、合并、移动和重新排序。

项目

用于不同上下文的隔离图。每个项目都有自己的 SQLite 数据库。

工具概览

批次操作

概念与节点管理（批次操作，除非所选模式另有列出）

连接管理（批次操作，除非所选模式另有列出）

读取与分析

综合与探索

文档操作（可用性因工作流模式而异）

源文本阅读

项目管理

跨项目

多代理协调（Solver）

与 Claude Code Agent Teams 的多代理协作

Understanding Graph 被设计为 Claude Code Agent Teams 的共享持久化媒介。运行 npx -y understanding-graph@0.1.30 init 后，主导者创建或选择一个命名图；在该项目根目录下工作的每个队友都可以共享它——无需捆绑数据的 stigmergy。

工作原理

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。当安全队友写下"安全代理：发现 JWT 存储在 localStorage 中——便利性与 XSS 风险之间存在张力"时，后端队友通过 graph_history() 看到它并据此行动。

3. 触发器对贡献进行分类 —— 队友为他们的节点打标签（tension、question、decision、surprise），从而轻松找到重要内容："显示所有未解决的张力"或"还有哪些问题未解决？"

4. 无需强制直接消息的持久化交接 —— 队友可以通过图本身进行协调。研究者留下 question 节点；后端代理通过 graph_find_by_trigger 找到它们并创建 answers 边。

开始使用 swarm

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. 将图作为媒介 —— 当理解模式激活时， 保留对工作重要的可传达理解和可寻址工件单元， 而不仅仅是最终答案。

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 来验证两个代理在图的构建中之前共享模式的相同定义——故障关闭式握手可防止静默语义漂移。

完整教程：将 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 会据此渲染"Cite this repository"按钮）。

许可证

MIT —— LICENSE

GitHub： emergent-wisdom/understanding-graph npm： understanding-graph MCP Protocol： modelcontextprotocol.io