Sema：当哈希即词汇时

用于多智能体协作的内容寻址语义。

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 服务器以及一个教导智能体搜索/解析/铸造/握手工作流的技能：

# 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

Related MCP server: giskard-memory

快速入门

与 AI 智能体一起使用 (MCP)

已通过上述 JSON 配置或 pip install 路径涵盖。针对此仓库进行开发：

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

您的智能体现在可以访问 sema_search、sema_lookup、sema_handshake 以及其他 9 个工具。任何兼容 MCP 的客户端都可以工作——Sema 公开了一个标准的 stdio 服务器。

验证它是否有效 — 询问您的智能体：“在 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

# Start local API + web frontend (binds to 127.0.0.1 by default)
sema serve

自带词汇表

从零开始构建私有注册表——无需 PR 或维护者介入：

sema init ./mylib.db
export SEMA_DB_PATH=$(pwd)/mylib.db
sema apply --add path/to/MyPattern.json
sema search "..."

后续的 sema 命令（包括 sema mcp）将从您的私有注册表中读取。请参阅 CONTRIBUTING.md 获取规范的贡献路径，并参阅 docs/specification/versioning.md 获取改进和替代策略。

在 Python 中使用

from sema.core.actions import sema_handshake
import json

# Look up the canonical hash
result = json.loads(sema_handshake("StateLock"))
print(result["canonical_stub"])  # b91b

# Verify alignment
result = json.loads(sema_handshake("StateLock#5602"))
print(result["verdict"])  # PROCEED

尝试协议（无需 API 密钥）

python experiments/demos/local_handshake.py

查看握手过程：匹配的哈希继续，不匹配的哈希停止，未知的模式停止。耗时 2 秒。

工作原理

word = hash(canonical(definition))

获取任何概念（协作协议、推理模式、信任机制），以规范形式表达它，然后进行哈希处理。该哈希就是词汇。定义中更改一个字节，就会得到一个不同的词汇。

Agent A: "Let's use StateLock#5602"
Agent B: sema_handshake("StateLock#5602")
         -> PROCEED (hashes match) or HALT (drift detected)

这是反波斯特定律 (Anti-Postel principle)：字节相同 = 继续，字节不同 = 停止。没有歧义，没有静默失败。

词汇表

跨 4 个层的 427 个默认模式（具有更高风险面的额外模式保存在单独的数据库中——请参阅 安全性）：

• 物理 (Physics) — 不可变基质（锁、熵、因果关系）

• 思维 (Mind) — 混合认知（推理、推断、策略）

• 社会 (Society) — 多智能体协作（经济、治理、协议）

• 基础设施 (Infrastructure) — 操作约束（数据结构、验证）

每个模式都是一个可执行规范，包含机器可验证的契约、不变量、故障模式和类型化依赖项。

MCP 工具

当作为 MCP 服务器 (sema mcp) 运行时，可以使用以下工具：

Web 前端

pip install "semahash[api]"
sema serve
# Open http://localhost:3000

交互式 3D 图形可视化、模式浏览器和搜索。使用 React + Three.js 构建。

实验

experiments/ 目录包含一个受控的多智能体设计挑战，比较了三种条件：

使用 Sema 模式的智能体产生了经得起对抗性审查的物理基础设计。没有使用 Sema 的智能体产生了未能通过安全审查的浅层设计。

重现方法：

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

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

关键属性

• 零语义冲突：覆盖整个词汇表

• 16.9 倍平均 token 压缩：通过内容寻址存根实现

• 故障关闭架构：不匹配即停止，绝不静默失败

• 平均嵌入相似度 0.21：高度的结构独特性

与 understanding-graph 一起使用

Sema 为您的智能体提供共享的语义记忆——一个具有内容寻址身份的认知模式词汇表。Understanding Graph 为它们提供共享的情景记忆——决策背后的实际思维轨迹。它们可以组合使用：

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

两者都安装后，智能体可以：

1. 将 understanding-graph 决策节点锚定在 sema 模式哈希（例如 StateLock#5602）中，这样原语的含义永远不会漂移。

2. 使用 graph_semantic_search 查找所有引用给定 sema 模式的过去图节点——哈希稳定的历史，而非关键词匹配。

3. 在编写依赖于共享概念的决策之前调用 sema_handshake；如果返回 HALT，智能体将改为写入一个 tension 节点并停止，从而防止静默分歧。

完整指南：docs/guides/understanding-graph.md

仓库结构

sema/
├── src/sema/              Core library (hashing, validation, MCP server, API)
├── data/                  Vocabulary (427 default + 26 higher-risk 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)
│   ├── 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.19548971},
  url          = {https://doi.org/10.5281/zenodo.19548971}
}

请参阅 CITATION.cff 获取机器可读版本（GitHub 会从中渲染一个“引用此仓库”按钮）。

安全性

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

预期用途：推理和参考。 模式是思维工具——智能体可以搜索、解析并进行握手的命名概念，以推理协作、风险和程序。请参阅 docs/manuals/vocabulary-design.md 了解每个模式背后的意图和设计选择。

将模式作为可执行配方运行尚未经过测试。 许多模式描述了智能体可以逐步执行的程序。该路径仍处于研究阶段——机制文本尚未经过端到端验证，我们不对模式在被执行而非引用时的安全性做出任何声明。如果您选择此路径，请在沙盒环境中运行智能体的执行步骤。具有已知风险的模式在其元数据中带有 caution 字段；缺少该标志意味着该模式尚未被归类为有风险，并不意味着它已被认证为安全。

长期目标是对智能体间通信实施加密强制的安全约束——这是一个积极的研究方向。

许可证

Sema 采用双重许可：

• 代码（src/、web/、experiments/、scripts/ 中的所有内容以及包配置）— MIT。您可以自行托管、分叉并在其上构建商业产品。

• 内容（data/ 中的模式词汇表、docs/ 中的文档、paper/ 中的学术论文以及显示在 semahash.org 上的散文）— CC BY 4.0。只要您注明 Henrik Westerberg，就可以在任何地方、出于任何目的（包括商业目的）重复使用这些模式和散文。

有关学术引用，请参阅 CITATION.cff。GitHub 会在项目页面上将其渲染为“引用此仓库”按钮，该按钮会自动生成 APA 和 BibTeX 格式。