understanding-graph

理解图谱：用于递归式理解的持久媒介

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

Understanding Graph 是一个为 AI Agent 提供结构化持久记忆的 MCP 服务。它不同于存储事实的知识库，存储的是对外有用的理解更新——矛盾、意外、决策、证据，以及信念随时间如何演变。它不需要私有思维链。多个 Agent 可以通过图谱本身协同：每个 Agent 读取其他 Agent 写下的内容，在此基础上继续推进，并为下一个 Agent 留下可检查的痕迹——迹象式协作。

为什么选择 Understanding Graph？

传统记忆	Understanding Graph
存储事实	存储撰写好的理解更新
“用户偏好深色模式”	“用户因眼睛疲劳切换到深色模式——审美与舒适之间的矛盾最终取舍为舒适”
扁平检索	带类型、可修订的解读
丢失解读过程	保留记录在案的理由和修订
单个 Agent	通过共享图谱实现多 Agent 协同

核心见解： AI Agent 不仅需要记住事实——还需要可用的先前状态、推动转变的证据、更新后的结论以及仍存的不确定性。这样，后续工作就能检验或修订结论，而无需重建隐藏的思考过程。

---

快速开始

需要 Node.js 22 或更高版本。

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

在你希望图谱支持的工作所在目录中运行初始化程序：

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

它会为 Codex 和 Claude Code 创建项目级 MCP 配置，在 AGENTS.md 和 CLAUDE.md 中安装相同的流动式理解约定，为两个客户端安装项目级 reading-mode 技能，并将本地 projects/ 路径添加到忽略规则中，但不会安装任何入门图谱。打开任一客户端，使用常规 ChatGPT 或 Claude 订阅登录，然后提出实际的研究、写作、编码或决策任务。开始实际工作时，Agent 会创建一个描述性命名的图谱。你不需要说“使用图谱”。模型在订阅客户端中运行；Understanding Graph 本身不会调用任何模型 API。

如需按时间顺序全新阅读，请向 Agent 提供文件路径，并要求它开启阅读器模式。它会暂存源文件，不返回或抽取其正文，然后仅通过 source_read 逐段读取接下来的有序内容，并可在继续之前附上基于该段内容的一般理解。Codex 还提供 $reading-mode；Claude Code 提供 /reading-mode。直接粘贴到聊天中的文本已经被读到，因此若确实需要全新阅读，请使用文件路径。

符合条件的 ChatGPT 方案可使用 Codex，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/ 条目 —— 将图谱数据保留在本地；不会创建起始项目

在此目录中打开的每个会话都会共用同一个项目根目录。选定命名图谱后，在此工作的 Agent 也会共用该图谱。只有在工作确实存在相互独立的部分时，才使用其他 Agent。

原始 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

为每个进程指定独立的端口和项目存储根目录，以运行彼此独立的 sidecar。各根目录可以是同一卷上的同级目录：

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

在部署中使用绝对路径。共享已安装的包及其只读前端是安全的；不要让彼此独立的 sidecar 指向同一个 PROJECT_DIR。

默认情况下，服务器绑定到 loopback。若要在另一台主机上运行 worker，请明确设置 HOST 和私有 worker 令牌；两者缺一时，非 loopback 启动会安全失败：

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。这只会改变本次抽取；可选的创造力工具仍可直接使用。

检索有两个正交维度：workflow 用于识别领域及其原生证据，而 stance 用于加权认知压力——例如深化、抵抗、关联、扰动、回顾或测试。这两个维度都不会限制模型可以采取的行动。

原子提交

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 读取该节点，或仅凭 ID 通过 graph_global_lookup 查找它。这是 entangled-alignment 时间顺序标注流水线所用的 分层理解图 的基础，该流水线会在不同历史时期和文档之间建立交叉引用。

---

核心概念

节点（理解单元）

每个认知节点都记录一次撰写者的理解更新，并以一个触发类型标明创建它的原因：

触发类型是认知行为，而非类别——它们记录的是 Agent 为什么在此刻创建该节点，而不是该节点属于哪一类事物。你最常使用的七种类型如下：

触发类型	使用场景
foundation	核心概念、公理、起点
surprise	意外发现、与先前信念相矛盾
tension	思想之间存在冲突，尚未解决
consequence	后续影响
question	有待探索的开放问题
decision	在多个选项中做出的选择，并附有理由
prediction	可在之后验证的前瞻性信念

较少使用但同样可用的类型包括：hypothesis、model、evaluation、analysis、experiment、serendipity、repetition、randomness、reference、library。这些普通认知节点可以保留丰富的、暂定的、尚未解决的记录，而不只是已确定的结论，以便未来的 Agent 重新进入这项工作。thinking 触发类型则不同：它专供独立的合成 Reader/CMP 合成器使用，用于从底层图中重建按时间顺序排列的训练区块。普通阅读、写作、编码和通用工作流无法访问或修改这些保留区块；只有 TOOL_MODE=synthetic_reader 可以访问。完整且经过审慎选择的 18 种触发类型已记录在理解图论文（第 3.1 节）中；这是一项不断演进的设计，并非声称的形式化最小集合。

边（连接）

边类型	含义
supersedes	新的理解取代旧的理解；通过专用的 graph_supersede 生命周期操作创建
contradicts	思想之间存在冲突
refines	让已有理解更加精确
learned_from	说明洞见的来源
answers / questions	解答或提出问题
contains	父子层级关系
next	顺序排列

文档

结构化文本、源材料和图原生代码共享同一棵可寻址文档树。叶节点可以是段落、函数、类、类型或测试，并记录其用途、来源提交、修订记录，以及指向塑造它的问题、决策、证据或张力的类型化链接。这样，后续的 Reader 可以通过调用 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 事务封装：如果任何操作失败，整个批次都会回滚。commit_message 会保留为节点的起源故事——未来读取这些节点的 Agent 不仅能看到内容，还能看到创建这些节点的意图。

概念与节点管理（除所选模式列出的操作外，均为批处理操作）

工具	用途
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 个 token）
graph_context	完整的图 XML，可选择聚焦于一个节点；超过 50 个节点时自动精简
graph_context_region	获取由 context、skeleton 或 search 返回的某个编号区域的完整详情
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 和公理强制——灵感源自 异星的本体论。此处将其中的随机线索、临时公理和另类物理学设想改编为面向 Agent 的可选工具；其输出在经过审视之前仍属推测。

工具	用途
graph_bisociate	通过扩散激活和信息增益，呈现候选跨上下文配对
graph_discover_grounded	对图中相距较远的内容进行默认的有界比较；任何连接都不视为有效
graph_discover_grounded_chaos	在确实存在有依据的桥接后进行可选的词典扰动；需要宿主安装词表
graph_discover	对图中内容进行明确标注为推测性的盲 ANI
graph_random	生成具体的随机设想，包括可选的、经过审视的物理学假设强制
graph_serendipity	仅限批处理：记录一项综合，并附上来源边
graph_validate	仅限批处理：记录针对经过审视的意外发现的人工验证判断
graph_chaos	将机器本地词典或图节点中的词语注入文本
graph_decide	仅限批处理：记录针对各选项的类型化决策
graph_evaluate_variations	使用实验性的新颖度评分对备选方案排序

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

工具	用途
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	跨所有项目搜索

多 Agent 协作（Solver）

Solver 工具可在 research、collaborative_coding 和 full 工具模式下使用。

工具	用途
solver_spawn	注册专用 Solver Agent
solver_delegate	向 Solver 队列提交任务
solver_claim_task	领取待处理任务（工作者模式）
solver_complete_task	提交任务结果
solver_list	列出已注册的 Solver
solver_queue_status	查看任务队列统计信息

---

使用 Claude Code Agent Teams 进行多 Agent 协作

Understanding Graph 被设计为 Claude Code Agent Teams 的共享持久化媒介。运行 npx -y [email protected] init 后，主 Agent 会创建或选择一个命名图；在该项目根目录下工作的每位队友都可以共享该图——实现无需捆绑数据的群体协作。

工作原理

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 为每位队友安装相同的流体协议 -- 每个 Agent 都将图谱视为规范媒介，可以直接工作，也可以在自然的选择点调用 graph_suggest_next 获取具体选项。
2. 提交消息是协调层 -- 每次 graph_batch 都需要提供 commit_message。当 Security 队友写下“Security Agent：发现 JWT 存储在 localStorage 中——便利性与 XSS 风险之间存在冲突”时，Backend 队友会通过 graph_history() 看到这条消息并采取行动。
3. 触发器用于对贡献分类 -- 队友为自己的节点添加标签（tension、question、decision、surprise），从而轻松找到重要内容：“显示所有未解决的冲突”或“还有哪些未解答的问题？”
4. 无需强制直接消息的持久交接 -- 队友可以通过图谱本身协调。研究人员留下 question 节点；Backend Agent 通过 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.

长期运行的协调（求解器系统）

对于跨越多个会话或需要在单个团队之外异步交接的任务：

工具	用途
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 -- Agent 集成
• 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/管理请求所需的 Bearer 密钥
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 为 Agent 提供共享的情景记忆——记录决策背后的解释过程。 Sema 为它们提供共享的语义记忆——一种内容寻址的认知模式词汇表。两者可以组合使用：

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

两者都安装后，Agent 可以：

1. 在节点的 understanding 或 why 文本中引用 sema 模式 URI（例如 sema://StateLock#7859），以固定某个协调原语的含义。
2. 使用 graph_semantic_search 查找当前项目中引用某个模式的节点。若搜索涉及多个图谱，请显式切换项目，或使用跨项目引用工具。
3. 调用 sema_handshake，在两个 Agent 基于彼此在图谱中的思考继续构建之前，确认它们对某个模式的定义完全一致——失败时关闭的握手机制可防止语义悄然漂移。

完整指南：将 Understanding Graph 与 sema 配合使用

在图谱中编写代码

代码存放在图谱文档根节点及其有序子节点中。使用 doc_generate 或 doc_generate_all 生成可运行文件，运行真实的构建和测试，然后修订或重新排列源节点并重新生成——绝不要直接修补生成的投影。

完整工作流请参阅 coding-inside-the-graph。

---

引用

@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