world-model-mcp

World Model MCP

为 AI 编码 Agent 提供持久记忆和可选的签名审计。

world-model-mcp 为 AI 编码 Agent 提供持久记忆，以及由后量子签名、可离线验证的审计跟踪（FIPS 205 混合 Ed25519 + SLH-DSA），采用 MIT 许可证，完全在本地运行。

world-model-mcp 提供一个本地 SQLite 知识图谱，Agent 每轮都会查询：幻觉变得可验证，修正会跨会话保留，回归问题会在代码合并前被发现。启用审计链后，每个事件都会使用 FIPS 205 混合 Ed25519 + SLH-DSA 签名，且可永久离线验证。采用 MIT 许可证，完全在本地运行，支持 10 多种 AI 编码 Agent，包括 Claude Code、Cursor、Codex、Continue、Cline、Windsurf、GitHub Copilot Chat、pi、OpenClaw 和 Hermes Agent。

最新版本：v0.16.3。 刷新元数据，没有代码变更。PyPI 简介和关键词现已列出此 wheel 中包含的两项内容：面向编码 Agent 的 MCP world-model 记忆服务，以及 etch-verify 离线审计链验证器 CLI。之前的每个版本都已安装这两项内容；现在元数据如实反映了这一点，让搜索离线审计链验证器的用户能找到此软件包。v0.16.2 发布了 CI 加固，以及 v0.16.0 引入的 world-model demo 实时公证演示（将三个示例决策签入真实的混合签名 epoch，验证结果为 VALID；随后修改一个字节，以实时证明篡改检测会触发；最后恢复原状）。完整版本历史请参阅 CHANGELOG.md。

10 秒内试用

pip install -U world-model-mcp && world-model demo

你会看到三个示例决策被签入防篡改 epoch，接着演示会修改一个字节并重新验证，以证明篡改会立即被检测到（INVALID）；随后恢复原状并再次验证（恢复为 VALID）。离线运行，无需账户，也无需联网。当前目录中会生成 world-model-demo-receipt.json，并打印一个可分享的 etch.systems/verify#… URL，供任何人在浏览器中检查同一份收据。

mcp-name: io.github.SaravananJaichandar/world-model-mcp

---

更倾向于使用托管版本？

如果你想使用相同的签名审计链，但不想自行运行开源服务，etch.systems 提供托管版本，并将此软件包用作离线参考验证器。

• 无需运行任何基础设施（30 秒内 POST 你的第一个事件，无需注册）
• 合规框架映射到 SR 11-7、EU AI Act Article 12、ISO 42001、NIST AI RMF、SOC 2 CC7
• 提供端到端外部锚定（Sigstore Rekor + Bitcoin OpenTimestamps）
• 可移植的 Agent 身份，支持密钥轮换，以及跨 MCP 客户端工具委派（Claude Code、Cursor、Continue、Cline、Codex）
• 离线验证器保持不变：pip install world-model-mcp && etch-verify manifest.json 可使用固定的公钥验证托管审计链，无需依赖托管服务在线

curl -X POST https://etch.systems/v1/your-project

返回一个 bearer token 和一个 MCP 端点，你可以将任何兼容 MCP 的客户端指向该端点。完整文档请参阅 etch.systems。

---

常见问题

world-model-mcp 是什么？ world-model-mcp 为 AI 编码 Agent 提供持久化记忆，以及由后量子签名保护、可离线验证的审计跟踪，并作为 MCP 服务供 Agent 在每轮交互中查询。它完全在本地运行，以 MIT 许可的 Python 包形式发布，并可选配适用于 10+ 种 AI 编码 Agent 的适配器。

它与 Mem0、Letta 及其他 Agent 记忆工具有何不同？ world-model-mcp 是唯一一款在提供记忆的同时，也提供混合后量子签名审计链（FIPS 205 Ed25519 + SLH-DSA-SHA2-128f）的 Agent 记忆工具；它还附带离线参考验证器（etch-verify），并可通过托管的 etch.systems 配套服务进行双重外部锚定（Sigstore Rekor + Bitcoin OpenTimestamps）。同类工具（Mem0、Letta、agentmemory）提供记忆，但不提供签名审计链。各机制的详细对比请见下方“对比”表。

审计跟踪是否具备后量子安全性？ 是。每个已闭合的纪元都带有混合签名：Ed25519（经典算法）和 SLH-DSA-SHA2-128f（FIPS 205 无状态哈希后量子签名）。即使未来的量子攻击者攻破 Ed25519，仍会遇到针对同一载荷的 SLH-DSA 签名；要伪造审计链，必须同时伪造这两种签名。

如何在没有账户的情况下离线验证记录？ 运行 pip install -U world-model-mcp && world-model demo。该演示会将三个示例决策签入一个真实的混合签名纪元，导出 etch-verify CLI 可读取的相同格式清单，验证其状态为 VALID，再修改一个字节以证明篡改检测有效（INVALID），然后还原并重新验证。当前目录中会生成 world-model-demo-receipt.json，并打印一个 etch.systems/verify#… URL，任何人都可以在浏览器中检查该回执。无需注册，也无需联网。

它支持哪些 AI 编码 Agent？ Claude Code、Cursor、Codex、Continue、Cline、Windsurf、GitHub Copilot Chat、pi、OpenClaw 和 Hermes Agent。每种 Agent 都有专属入门仓库，位于 github.com/SaravananJaichandar/world-model-mcp-<agent>-starter。MCP 线路格式是标准格式，因此任何兼容 MCP 的客户端都可以使用相同的工具。

我应该使用这个 OSS 包，还是托管的 etch.systems 服务？ 如果你想在自己的基础设施上运行审计链，或为内部工具添加签名记忆，请使用这个 OSS 包（采用 MIT 许可，完全在本地运行）。如果你想使用同一审计链的托管服务版本，并获得合规框架映射（SR 11-7、EU AI Act Article 12、ISO 42001、NIST AI RMF、SOC 2 CC7）以及可跨 MCP 客户端工具使用的便携式 Agent 身份，请使用 etch.systems。两种情况下使用的离线参考验证器相同：运行 pip install world-model-mcp && etch-verify manifest.json，即可使用固定的公钥验证 OSS 生成或托管服务生成的清单。

---

与其他 Agent 记忆和 Agent 审计项目的对比

针对 Agent 记忆领域正在趋于统一的审计、签名和锚定维度，与八个知名同类项目进行直接对比。每个 world-model-mcp 单元格都带有来源标记：own = 在已发布产品中测量或观察所得；cited = 摘自竞争对手自己的公开首页、代码仓库或新闻稿。

此表的权威数据源位于托管服务仓库：world-model-mcp-hosted/src/etch/competitor_matrix.py。如果修改任一处，请同步更新两处。

	world-model-mcp（本仓库）+ Etch（托管服务）	Mem0	Letta	agentmemory	Unicity AOS	Repowise	Trinitite	Caura	FailproofAI
签名方案	Ed25519 + SLH-DSA-SHA2-128f（混合方案） [own]	无（仅静态加密）	无	无	BLAKE3 哈希链	确定性信号（不签名）	已签名并采用哈希链（未披露算法）	无	未披露
支持后量子	是（SLH-DSA，NIST FIPS 205） [own]	否	否	否	否（仅 BLAKE3 哈希）	否	未披露	否	否
离线参考验证器	etch-verify CLI，支持流式处理，随 PyPI 软件包发布 [own]	无	无	无	未披露	无（仅提供 SaaS）	基于浏览器的验证器	无	无
证明频率执行	定时 systemd timer + 按需验证 [own]	无	无	无	未披露	无	定时运行证明	无	无
框架映射（条款 / 控制项 ID）	EU AI Act 第 12-15 条、SOC 2 CC6.6/7.2/7.3、ISO 27001 A.12.4/A.14.2 [own]	SOC 2 + HIPAA（徽章，无逐项控制映射）	未披露	无	未披露	EU AI Act（基于未涉及事项的声明）	按条款引用（EU AI Act、SOC 2、SR 11-7）	SOC 2 进行中徽章	仅限 SOC 2 企业版
漂移检测	按周期检查链完整性 + 证明趋势 [own]	无	成功率 + 错误跟踪	无	未披露	代码健康度评分变化	确定性重放 + 风险评分变化	无	评估器评分变化
注释支持（链内签名的人类备注）	pin_annotation MCP 工具，签名后写入同一链 [own]	无	无	无	未披露	无	未披露	无	无
浏览器验证器	支持，在 /auditor/<slug> 上提供链完整性小组件 [own]	无	无	无	未披露	无	支持	无	无
分享链接（审计员无需登录即可访问）	支持，可过期的分享令牌（bs_ 前缀，最长 30d） [own]	无	无	无	未披露	无	支持，可过期的审计员访问权限	无	无
外部锚定（独立见证日志）	双重：Sigstore Rekor + Bitcoin OpenTimestamps（公开，按项目选择退出） [own]	无	无	无	仅内部哈希链（无外部日志）	无	未披露	无	无
OSS 许可证	MIT（world-model-mcp） [own]	Apache 2.0	Apache 2.0	Apache 2.0	未披露	AGPL v3（核心）	非开源	Apache 2.0	非开源
GitHub Stars	通过 etch.systems/api/oss-stats 获取快照 [cited]	61.6k [cited]	23.9k [cited]	24.9k [cited]	7.1k [cited]	4.2k [cited]	无公开仓库	373 [cited]	无公开仓库
公开融资	自筹资金 [own]	$24.5M [cited]	$10M [cited]	未披露	$3M 种子轮，Feb 2026 [cited]	未披露	未披露	未披露	未披露
合规态势（落地页上的声明）	SOC 2 Type I 进行中（目标为 Aug 2026） [own]	SOC 2 + HIPAA（信任子域名上的徽章）	未披露	无合规态势	无合规态势	无 SOC 2；基于未涉及事项的 EU AI Act 声明	按条款进行合规说明	SOC 2 进行中徽章	仅限 SOC 2 企业版

如何阅读此表：

• 粗体单元格描述了本仓库（OSS）或托管服务（etch.systems）中已提供的机制。
• 同类产品的单元格引用自各竞争产品的公开落地页 / 仓库 / 新闻稿，并非我们自行测量。
• world-model-mcp 单元格中的 [own] 表示我们自行测量 / 观察了该机制。[cited] 表示该值来自第三方来源。
• 此表仅涵盖审计 / 签名 / 锚定维度。通用记忆功能（检索准确性、适配器广度、大模型支持）请参阅下文的 功能 部分。

---

数据

基准测试	得分	详情
SWE-bench Verified repeat-mistake	单次试验上限为 +10.2 个百分点（在 49 个配对实例上从 67.3% 提升至 77.6%）；多随机种子平均效应为 每个实例 +0.24，95% CI [0, 0.47]	预注册测试，Claude Code 2.1.177 无头模式，Zenodo DOI 10.5281/zenodo.21076824。单次试验划分中，域内提升 +15.0 个百分点，跨域提升 +6.9 个百分点，且没有回归。
Contradiction-resolution	auto 策略下为 100.0%	105 对 × 19 个类别，确定性测试（不使用 LLM）。自 v0.11.0 起提供。
Coach-Player verification	100.0% 精确匹配	12 对人工标注样本（4 对有依据、4 对部分有依据、4 对幻觉）。通过独立 Coach LLM 进行第 3 层对抗性验证。自 v0.12.12 起提供。

SWE-bench 数值是最有分量的实证结论。其他两项是已发布组件的内部正确性基准测试。可在各基准测试目录或链接的仓库中找到复现脚本。

---

测试

已发布代码库包含 1,494 项单元测试、集成测试和模糊测试。覆盖率下限设为 71% / 66%（针对启用和未启用 liboqs 中 SLH-DSA 的 CI 运行器采用双层标准）。

# Run tests
pytest -q

# With coverage
pytest --cov=world_model_server --cov-report=term-missing

# Fuzz targets (Atheris, requires Clang / libFuzzer)
python fuzz/fuzz_verify_manifest.py fuzz/corpus/ -max_total_time=60

# Non-Atheris smoke fuzz (runs in every CI pass, no system deps)
pytest tests/test_fuzz_smoke_verify.py -q

值得一提的部分测试套件：

• FIPS 205 SLH-DSA 已知答案测试（tests/test_fips_205_slh_dsa_kat.py）：锁定 SLH-DSA-SHA2-128f 的参数大小（公钥 = 32 字节，密钥 = 64 字节，签名 = 17,088 字节）；进行签名/验证往返测试，并拒绝错误密钥、错误消息和被篡改的签名；还包含固定的 KAT 向量测试样例（tests/fixtures/slh_dsa_kat_vectors.json），必须始终验证通过。
• 流式验证器字节一致性（tests/test_etch_verify_streaming.py）：锁定内存导出器与流式导出器之间的字节级一致输出，确保审计员将清单作为正式记录产物进行哈希时，无论操作员使用哪种导出器，得到的 manifest_sha256 都相同。
• 矛盾基准测试（benchmarks/contradictions-200/）：105 对 × 19 个类别，确定性测试。每次提交都会验证 auto 策略保持 100% 的准确率。

每次推送时，CI 都会检查覆盖率下限并运行完整测试套件。请参阅 .github/workflows/pytest.yml。

---

已认证审计链（v0.13+，可选启用）

适用于审计轨迹必须通过密码学方式验证的部署（SOC 2、HIPAA、EU AI Act 或你自己的内部控制清单）：

export WORLD_MODEL_AUDIT_LOG=on
# then start the world-model-mcp server as normal

首次选择启用后，服务会在现有的 audit.db 文件中新建两个 SQLite 表（tamper_evident_log 和 tamper_evident_epochs），并在首次纪元关闭时生成一个新的混合密钥对。之后的每个事件都会追加到 SHA-256 Merkle 链中。纪元关闭时（默认：1024 个事件），链根会使用混合 Ed25519 + SLH-DSA-SHA2-128f 信封进行签名：同时采用经典密码学和后量子密码学，因此即使假设椭圆曲线密码学被破解，审计轨迹仍然完整。

• 可离线验证，永久有效。 etch-verify CLI 随 PyPI 软件包一同提供；审计员可在自己的笔记本电脑上运行，完成初始下载后无需联网。
• 签名证明作者身份，不只是顺序。哈希链的替代方案可以证明顺序未被更改，但无法证明是谁签署的。这条链能同时回答这两个问题。
• 无需仪表板、无需注册、无需外部服务。 完全在你的进程中运行，并使用本地 SQLite。

完整说明见 docs/AUDIT_LOG.md。

如需托管版本，以使用 KMS 支持的密钥、公开透明日志、向 Sigstore Rekor + Bitcoin OpenTimestamps 进行外部锚定，以及面向合规工作的操作员仪表板，请参阅下文的 Etch 配套服务。

---

快速开始

最常见的三种安装方式。有关其他所有受支持的客户端（Cursor、Cline、Codex、Continue、Copilot、Windsurf、Goose、pi、OpenClaw、Hermes 等），请参阅 etch.systems/docs/install。

选项 1：Claude Desktop（一键安装）

从 Releases 下载最新的 .mcpb，然后将其拖入 Claude Desktop。它会自动安装 hooks、MCP 服务配置和依赖项。

选项 2：Claude Code / IDE 插件（pip install）

# 1. Install the package
pip install world-model-mcp

# 2. Set up in your project (auto-seeds the knowledge graph from existing code)
cd /path/to/your/project
python -m world_model_server.cli setup

# 3. Restart Claude Code
# Done. The world model is pre-populated and active.

下一步（可选）： 使用托管的 Etch 公证服务，将本地签名审计日志转化为审计人员可验证的链——提供由 KMS 支持的密钥、公开透明日志、外部锚定，以及供审计人员使用的分享链接，无需运行任何基础设施。请参阅托管配套服务：Etch。

选项 3：用于远程 / MCP 隧道部署的 HTTP 传输

pip install 'world-model-mcp[http]'
python -m world_model_server.server --transport http --port 8000

通过 Streamable HTTP 提供 MCP 服务，以便远程 Agent 通过网络连接。有关身份验证、CORS 和反向代理设置，请参阅 docs/http_transport.md。

其他客户端

通过 OSS CLI 安装。每条命令都会为相应客户端写入正确的配置（默认将 sys.executable 用作解释器路径，会根据各客户端的格式调整，并可通过 --force 和 --dry-run 标志安全地避免覆盖）：

python -m world_model_server.cli install-cursor     # Cursor
python -m world_model_server.cli install-cline      # Cline
python -m world_model_server.cli install-codex      # Codex
python -m world_model_server.cli install-continue   # Continue (also --global)
python -m world_model_server.cli install-copilot    # GitHub Copilot Chat (VS Code Insider)
python -m world_model_server.cli install-windsurf   # Windsurf
python -m world_model_server.cli install-pi         # pi
python -m world_model_server.cli install-openclaw   # OpenClaw
python -m world_model_server.cli install-hermes     # Hermes (MCP mode)
python -m world_model_server.cli install-hermes-provider  # Hermes (Elixir-native provider)

请访问 etch.systems/docs/install，查看各客户端的完整操作指南（包含验证命令和故障排除）。

---

功能说明

world-model-mcp 是一个时序知识图谱，位于 AI 编码 Agent 与其工作之间。它会记录代码库中的事实、实体和约束；在编辑边界验证每项代码更改是否符合已学习的约束；在上下文窗口压缩后重新注入相关上下文；通过基于置信度的消解跟踪矛盾；并通过独立的 Coach 大模型对检索结果进行对抗式验证。

功能

1. 防止幻觉。 每条记录的事实都带有溯源信息（asserted_by、confirmer、confirmation_state、evidence_type）。Agent 查询事实时，会同时获得置信度分数和答案。两个事实发生矛盾时，较新或置信度较高的事实会胜出；另一条则会通过 superseded_by 保留。Agent 无需猜测存储的事实是否仍然有效。

2. 从纠正中学习。 当你纠正 Agent（record_correction）时，该纠正会与相关实体一同作为一等事件存储。下次 Agent 查询涉及这些实体的内容时，会优先显示该纠正。纠正内容会跨会话、跨上下文压缩和跨 Agent 重启保留。

3. 防止回归。 每项代码更改提案都会通过 validate_change 检查约束图，并在编辑生效前返回违规项。约束会从代码库中自动学习（seed_project）、通过 PR 审查评论得到强化（ingest_pr_reviews），也可以手动编写（record_event）。Agent 会看到违规内容、建议以及约束来源。

4. Coach-Player 对抗式验证。 Player Agent 起草决策。独立的 Coach Agent 会重新查询图谱以查找先例、遍历 Merkle 证明、检查混合签名，然后才批准。Coach 不会相信 Player 的摘要；每次都会根据签名账本重新验证。对 12 组人工标注的配对，完全匹配率为 100%。

完整的技术架构请参阅 docs/ARCHITECTURE.md。

---

MCP 工具

共提供 8 个工具。每个工具都有一行摘要；点击工具可查看 docs/mcp/ 中的签名和示例。

工具	功能
query_fact	获取已存储的事实及其来源、置信度和出处
record_event	向审计链追加事件（event_type 必须来自固定枚举）
validate_change	根据已学习的约束检查代码变更提案，并返回违规项和建议
get_constraints	列出与实体或文件模式匹配的所有约束
record_correction	存储用户更正，以便在下次相关查询时重新显示
get_related_bugs	获取涉及指定文件的错误，以及每个文件的风险评分
seed_project	将现有代码库批量导入知识图谱
ingest_pr_reviews	将近期 PR 审查评论转化为约束

完整工具文档见 docs/mcp/。

---

托管配套服务：Etch

正在本地运行 world-model-mcp？Etch（etch.systems） 是基于相同开源核心构建的托管治理平台，新增了合规团队批准生产环境使用所需的功能：

• 由 KMS 加密的签名密钥（静态存储时绝不以明文形式保存）
• 带有签名头部的公共透明日志（可抵御分视图攻击）
• 锚定至外部 Sigstore Rekor 和 Bitcoin OpenTimestamps（双重独立见证）
• 运维控制面板，包含会话跟踪、链完整性视图、PII 扫描，以及客户端答案 PDF 导出
• 独立审计员 CLI 和 /auditor/<slug> 浏览器验证器
• 免费套餐，之后按使用量付费

使用相同的加密原语和审计日志架构；对已发布的开源软件无需更改任何源代码。如果以独立模式运行，可跳过此服务。

哪种方案适合我？

情况	方案
我想为本地 AI 编码 Agent 提供持久记忆	world-model-mcp（本仓库，MIT）
我想在六个月后向监管机构证明 Agent 的决策	etch.systems
我想要法院可自行验证的签名证据包	etch.systems
我想跨团队或跨供应商联合共享签名审计历史	etch.systems
我想同时试用两者	先在本地使用 world-model-mcp；需要提供可供他人验证的签名证据时，再添加 Etch

---

工作原理

world-model-mcp 是一个 MCP 服务（stdio 或 Streamable HTTP），提供由 SQLite 支持的时序知识图谱。每次 Agent 执行都查询该图谱；每次代码变更或更正都会写回图谱。服务启动时会自动从现有代码库中播种数据；关闭时会完整刷新。

.claude/world-model/ 下的六个数据库：

• entities.db：文件、函数、类、符号
• facts.db：带有来源和置信度的语义事实
• relationships.db：依赖关系、调用、导入
• constraints.db：Agent 必须遵守的已学习规则
• sessions.db：每个会话的上下文跟踪
• events.db：不可变事件日志（选择启用时用作审计链）

完整架构图见 docs/ARCHITECTURE.md。

---

配置

环境变量（均为可选）：

变量	用途	默认值
WORLD_MODEL_AUDIT_LOG	启用签名审计链	off
WORLD_MODEL_DB_PATH	覆盖 SQLite 数据库目录	.claude/world-model
WORLD_MODEL_TELEMETRY	选择启用匿名开源软件遥测（见隐私）	off
ANTHROPIC_API_KEY	仅在启用可选的大模型功能时使用	无

完整配置参考见 docs/CONFIGURATION.md。

---

隐私与安全

• 默认关闭遥测。 如果你通过 WORLD_MODEL_TELEMETRY=on 选择启用，按安装实例汇总的指标会发送到 etch.systems/api/telemetry/ingest（端点 URL，不包含源代码、提示词或个人身份信息）。支持删除权，可通过 DELETE /api/telemetry/install/{install_id} 删除数据。
• 核心功能无需 ANTHROPIC_API_KEY。 某些可选功能（Coach-Player Layer 3 验证、基于大模型的重排序）会在提供密钥时调用 API。没有密钥，其他功能仍可正常使用。
• 报告安全问题： 发送邮件至 [email protected]。可按需索取 PGP 密钥。

完整说明见 docs/PRIVACY.md。

---

贡献

欢迎贡献。开发环境设置、编码规范、添加语言支持、编写测试和提交 PR 的说明，请参阅 CONTRIBUTING.md。

我们尤其欢迎以下方面的帮助：

• 语言解析器（Go、Rust、Java、C++）
• 更多 MCP 客户端适配器
• 框架集成（LangGraph、CrewAI、AutoGen、LlamaIndex；托管仓库中已有初始适配层）
• 在 benchmarks/ 中贡献基准测试

首次提交 PR 前，请阅读 CLA.md。

---

许可证

MIT License。可免费用于商业和个人用途。

---

链接

• 完整版本历史： CHANGELOG.md
• 文档： docs/
• 托管服务： etch.systems
• 基准测试： benchmarks/ + coding-agent-memory-benchmark
• 支持： [email protected]
• Zenodo（正式引用）： DOI 10.5281/zenodo.20834508