semahash

Sema：当哈希即为词语

面向多 Agent 协作的内容寻址语义。

Sema 是一个用于推理和通信的内容寻址引用系统。参与者按照约定的表示方式对信息进行编码并生成哈希，然后将内容地址用作可验证的引用，也可以配合易读的名称。匹配完整引用即可确认所解析哈希内容的身份；语义等价性、正确性和执行仍是彼此独立的问题。

网站： semahash.org · Discord： 加入

安装

MCP 服务（推荐）

添加到任意 MCP 客户端（Claude Code、Cursor、VS Code、Windsurf、Claude Desktop）：

{
  "mcpServers": {
    "sema": {
      "command": "uvx",
      "args": ["--from", "semahash[mcp]", "sema", "mcp"]
    }
  }
}

也可以通过 Claude Code CLI：

claude mcp add sema -- uvx --from "semahash[mcp]" sema mcp

首次调用时，这会使用 uv 在隔离环境中下载、安装并运行 sema，之后会缓存以供后续调用。

Claude Code 插件（MCP 服务 + 技能）

Sema 也以 Claude Code 插件的形式提供——MCP 服务加上一项技能，用于教会 Agent 搜索／解析／铸造／握手工作流：

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

# Install the plugin
claude plugin install sema

这样你既可以使用 MCP 服务，也可以使用 sema-usage 技能（自动加载），它会教你何时搜索而非铸造、如何在文本中嵌入名称，以及如何在边界处验证含义。该技能是 Claude Code 的便利功能——MCP 服务可与任意客户端配合使用。

本地开发：

claude --plugin-dir /path/to/sema

永久安装（pip）

pip install "semahash[mcp]"

仅用于 CLI（不含 MCP 服务）：

pip install semahash

快速开始

与 AI Agent 搭配使用（MCP）

上文已介绍通过 JSON 配置或 pip install 方式使用。针对本仓库进行开发时：

git clone https://github.com/emergent-wisdom/sema.git
pip install -e "./sema[mcp]"

现在，你的 Agent 可以使用 sema_search、sema_lookup、sema_handshake 以及其他 9 个工具。任意兼容 MCP 的客户端均可使用——Sema 提供标准的 stdio 服务。

验证是否正常运行——询问你的 Agent：“搜索 sema 中的协作模式，并对 StateLock 执行握手。”

Sema 提供标准的 MCP stdio 服务——任意兼容 MCP 的客户端均可使用，包括 OpenClaw（openclaw mcp set sema '{"command":"uvx","args":["--from","semahash[mcp]","sema","mcp"]}'）。

通过 CLI 使用

# Search the vocabulary
sema search "coordination"

# Look up a specific pattern
sema resolve StateLock

# Print a pattern's full definition
sema show StateLock

# Browse the graph structure
sema skeleton

# Watch the active vocabulary in the local view (binds to 127.0.0.1 by default)
sema serve --open

自定义词汇

从头构建私有注册表——无需提交 PR，也无需维护者介入：

sema init ./mylib.db
sema use ./mylib.db
sema apply --add path/to/MyPattern.json
sema search "..."

后续的 sema 命令（包括 sema mcp）都会从你的私有注册表读取。（如果设置了 SEMA_DB_PATH，它的优先级高于 sema use。）有关规范的贡献流程，请参阅 CONTRIBUTING.md；有关精炼与取代政策，请参阅 docs/specification/versioning.md。

将项目数据库打包为经过验证的独立库版本：

sema package ./mylib.db \
  --name mylib \
  --version 1.0.0 \
  --output-dir dist/mylib-1.0.0 \
  --github-repo acme/sema-mylib

将生成的 library.json 和带版本号的 ZIP 作为资源发布到对应的已发布 GitHub Release 中。使用者应安装指向 library.json 的 Release 资源 URL，而非仓库 URL 或分支：

sema install https://github.com/acme/sema-mylib/releases/latest/download/library.json
sema use mylib
sema list
sema root

每次安装的是一个经过验证的快照，而不是合并词汇；捆绑的词汇仍是离线默认内容。使用 sema update mylib 跟随已安装库记录的版本发布指针。完整的 DeFi 编写、依赖闭包、打包、GitHub Release 和更新工作流，请参阅发布和安装词汇库。

在 semahash.org 上发布的库可以按名称查找和安装，无需账户：

sema registry search defi
sema install mylib

要在那里列出一个版本发布，让其他人和 Agent 能找到它，请登录一次，然后从命令行发布：

sema login        # approve the short code in your browser, once
sema registry import https://github.com/acme/sema-mylib/releases/latest/download/library.json

Agent 也可以使用你在 semahash.org 个人资料页面创建的密钥登录：将密钥传给 sema login --key -，或调用 sema_library_login MCP 工具。

登录采用 OAuth 2.0 设备授权流程，因此也适用于没有浏览器的 Agent 或机器。要使用其他部署，请运行 sema login --registry https://registry.example。登录成功后，该注册表会被记住，供后续命令使用。--registry 和 SEMA_REGISTRY_URL 会覆盖记住的选项；首次使用时默认采用 https://semahash.org。

在 Python 中使用

from sema.core.registry import RegistryManager

registry = RegistryManager()
pattern = registry.get_pattern("StateLock")

# Look up the canonical reference
print(pattern["sema_ref"])  # StateLock#c9c2

# Verify an inline reference before relying on it
assert pattern["sema_ref"] == "StateLock#c9c2"

试用协议（无需 API 密钥）

python experiments/demos/local_handshake.py

查看握手过程：哈希匹配则 PROCEED，哈希不匹配则 HALT，未知模式则 HALT。协作模式接受短前缀以检测偏移；严格模式要求完整哈希。耗时 2 秒。

工作原理

word = hash(canonical(definition))

任取一个概念（协调协议、推理模式或信任机制），将其表示为规范形式并计算哈希。该哈希就是这个词。定义中只要有一个字节发生变化，得到的词就会不同。

Cooperative: sema_handshake("StateLock#c9c2")
             -> PROCEED with assurance="prefix", or HALT

Strict:      sema_handshake("StateLock", "<full 64-char hash>", strict=true)
             -> PROCEED with assurance="full_hash", or HALT

这就是反 Postel 原则：严格模式只有在完整哈希完全一致时才会继续；协作模式使用简短前缀作为非对抗性的偏移信号。两种模式下，遇到不匹配都会安全失败。

词汇

捆绑的词汇涵盖 4 个层：

• 物理 — 不可变基底（锁、熵、因果关系）
• 心智 — 混合认知（推理、推断、策略）
• 社会 — 多 Agent 协调（经济、治理、协议）
• 基础设施 — 操作约束（数据结构、验证）

每个模式都是一个内容寻址的行为定义。具体卡片可以添加机器可验证的契约、不变量、故障模式、参数和类型化依赖项；这些字段可能决定其身份。

MCP 工具

作为 MCP 服务运行时（sema mcp），可使用以下工具：

工具	描述
sema_search	按名称、描述或含义搜索模式
sema_lookup	根据引用获取模式（例如，StateLock#c9c2）
sema_resolve	获取依赖项已展开的模式
sema_handshake	在 Agent 之间进行失败即关闭的语义验证
sema_mint	创建新模式（验证、哈希并添加到词汇表）
sema_propose_context	为多 Agent 定义集计算上下文摘要（漂移检测）
sema_verify_context	验证来自另一个 Agent 的上下文提案
sema_tree	按层和类别浏览词汇表
sema_validate	验证模式 JSON 是否正确
sema_stats	词汇表统计信息
sema_graph_skeleton	超精简图概览（约 150 个词元）
sema_reset_session	清除会话缓存，让搜索重新返回完整结果
sema_library_search	查找发布在 semahash.org 上的库
sema_library_install	按名称或 library.json URL 验证并安装库
sema_library_login	保存用户提供给 Agent 的 semahash.org 密钥
sema_library_publish	在用户同意后，于 semahash.org 上发布 GitHub 版本

本地视图

pip install "semahash[api]"
sema serve --open
# Opens http://localhost:3000

本地视图显示通过 sema use 选定的词汇表，也是已连接 Agent 写入的词汇表。它会跟随后续切换；Agent 创建模式时，其 3D 图会不断扩展：新模式会亮起并显示在实时列表中。模式浏览器提供卡片、列表和 JSON 视图。开发过程始终在你的计算机上进行；semahash.org 托管已完成的库，可写词汇表的页面会列出将其发布到该网站的可选步骤。

实验

experiments/ 目录包含对 Sema 主张和实现边界的可复现实验评估。

Delta 重建

公开的 v0.3.0 到 v0.4.0 重建实验用于检查当前图和哈希级联算法能否根据较早版本重建目标词汇表。它会比较聚合根、语义模式内容、逻辑依赖图、未哈希元数据以及完整的规范化读模型，而不是将根相等视为版本完全相同。它还演示了安全的重建路径：将 delta 集成到完整的暂存卡片快照中，编译新的数据库，验证结果，然后才激活它。

.venv/bin/python experiments/delta_reconstruction/reproduce.py

实验及其预期结果记录在 experiments/delta_reconstruction/README.md 中。 常规测试套件会运行该实验中添加、移除、重命名、级联、元数据和失败用例的小型合成版本。

多 Agent 设计挑战

受控的多 Agent 设计挑战对比了三种条件：

条件	Sema	轮次	结果
A：仅自然语言	否	4	设计被否决
B：Sema 词汇表	是	11	SAD Engine 获批
C：Sema + 协议	是	25	SAD Engine 通过全面审查

使用 Sema 模式的 Agent 产出了以物理学为基础、经受住对抗性审查的设计。未使用 Sema 的 Agent 产出了浅薄的设计，未能通过安全审查。

要复现：

cd experiments/sema_design_challenge
export GOOGLE_API_KEY=your_key
./reproduce.sh

详情请参阅 experiments/sema_design_challenge/README.md。

关键特性

• 整个词汇表中零语义冲突
• 通过内容寻址存根实现平均 16.9 倍的词元压缩
• 失败即关闭架构——出现不匹配时会停止，绝不会静默失败
• 平均嵌入相似度为 0.21——结构差异显著

形式化验证试点

Sema 的握手决策内核和规范化类型标签配有一套小型 Lean 4 证明集。握手支持用于常规漂移检测的协作式前缀匹配，也支持用于证明级身份验证的严格全哈希验证；证明分别陈述了各项保证。编码证明确立了哈希前域分离，而 Python 一致性测试则将模型与生产实现关联起来。有关已证明的定理、可信计算基假设和声明的明确限制，请参阅 verification/README.md。

与 understanding-graph 搭配使用

Sema 为你的 Agent 提供共享的语义记忆——包含认知模式的词汇表，并以内容寻址方式标识。Understanding Graph 为它们提供共享的情景记忆——决策背后的实际思考轨迹。两者可以组合使用：

claude mcp add sema -- uvx --from "semahash[mcp]" sema mcp
claude mcp add ug   -- npx -y understanding-graph mcp

两者都安装后，Agent 可以：

1. 将 understanding-graph 决策节点锚定到一个 sema 模式哈希（例如 StateLock#c9c2），这样基础构造的含义就永远不会漂移。
2. 使用 graph_semantic_search 查找所有引用指定 sema 模式的过往图节点——历史记录由哈希保持稳定，而非依赖关键词匹配。
3. 在写入依赖共享概念的决策之前调用 sema_handshake；如果返回 HALT，Agent 会改为写入一个 tension 节点并停止，从而避免无声分歧。

完整演练：docs/guides/understanding-graph.md

仓库结构

sema/
├── src/sema/              Core library (hashing, validation, MCP server, API)
├── data/                  Vocabulary pattern cards + taxonomy databases
├── docs/                  Documentation (philosophy, schema spec, CLI reference)
├── paper/                 Academic paper (sema.tex)
├── web/                   Web frontend (React + Three.js graph visualization)
├── experiments/
│   ├── orchestrator/      Multi-agent engine (bundled for experiment reproduction)
│   ├── delta_reconstruction/  Historical release reconstruction validation
│   ├── sema_design_challenge/  Main experiment (3 conditions, 5 runs, full traces)
│   └── demos/             Standalone demos (local handshake, Babel Test)
└── pyproject.toml         Package config (extras: [mcp], [api], [full])

贡献

想要添加模式、改进现有模式，或在本地托管前端？请参阅 CONTRIBUTING.md。

引用

@misc{westerberg2026sema,
  title        = {Sema: When the Hash Is the Word},
  author       = {Westerberg, Henrik},
  year         = {2026},
  month        = apr,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19462702},
  url          = {https://doi.org/10.5281/zenodo.19462702}
}

机器可读版本请参阅 CITATION.cff（GitHub 会根据该文件显示“引用此仓库”按钮）。

安全

Sema 不附带可执行代码——它是一个模式定义库（句柄、机制、不变量、依赖图）。MCP 服务会将模式作为数据交给客户端；它不会执行这些模式所描述的行为。

预期用途：推理和参考。 模式是思考工具——Agent 可以搜索、解析并通过握手确认的命名概念，用于推理协调、风险和流程。每种模式的设计意图和设计选择，请参阅 docs/manuals/vocabulary-design.md。

将模式作为可执行方案运行尚未经测试。 许多模式描述了 Agent 可以逐步执行的流程；Dynamics 类别中的模式则不属于此类，因为它们描述的是系统如何运行，应用方式是用于解读案例，而非执行。执行流程仍处于研究阶段——机制文本尚未经过端到端验证；对于执行模式而非仅将其作为参考时的安全性，我们不作任何声明。如果选择这条路，请在沙盒环境中运行 Agent 的执行步骤。已知存在风险的模式会在其元数据中带有 caution 字段；没有此标记表示该模式尚未被归类为有风险，并不代表它已通过安全认证。

长期目标是通过密码学手段强制实施 Agent 间通信的安全约束——这是一个正在开展的研究方向。

许可证

Sema 采用双重许可：

• 代码（src/、web/、experiments/、scripts/ 中的所有内容，以及软件包配置）——MIT。可自行托管、分叉，并基于它构建商业产品。

• 内容（data/ 中的模式词汇、docs/ 中的文档、paper/ 中的学术论文，以及 semahash.org 上展示的文字）—— CC BY 4.0。可在任何地方、出于任何目的（包括商业用途）复用这些模式和文字。分享词汇时，建议注明：

  Vocabulary from Sema, licensed under CC BY 4.0.

学术引用方式请参阅 CITATION.cff。GitHub 会在项目页面上将其显示为“引用此仓库”按钮，并自动生成 APA 和 BibTeX 格式的引用。