Procheiron

Procheiron

未经审核的记忆绝不会传到你的 Agent 手中。
这条记忆是谁写的，谁检查过？此后有人动过它吗？

Procheiron 是一个小巧、无依赖的 AI Agent 记忆信任层。记忆工具擅长存储和召回；信任却无人负责。让多个 Agent 共享一份记忆，任何一个都能写入一条“事实”，其他 Agent 也会欣然据此行事——没人审核，没人批准；等发现它错了，也没有简便的方法追溯或撤销它。

Procheiron 为此增添规范，并通过验证器强制执行，而非仅凭约定。它不提供自己的记忆引擎——没有嵌入、排序或召回功能。你可以使用现有的任何记忆方案——向量数据库、知识图谱或 Markdown 文件夹。它管理记录；你的引擎继续负责记忆。

当场抓获

部署验证通过后，有人凭借写入权限悄悄改写了历史——一项过去的晋升记录突然声称是另一个人执行的：

$ procheiron validate ./team-memory
Procheiron validation (full tier): PASS

$ # edit team-memory/memory/index/audit.jsonl:  "actor": "vera_curator" → "rogue_agent"

$ procheiron validate ./team-memory
Procheiron validation (full tier): FAIL
  ERROR: audit chain: audit event 0: entry_hash mismatch — content was altered
         after it was written
  ERROR: memories.jsonl:1: active record has no corroborating promotion audit
         event — forged/hand-flipped record

_{真实输出（ID 已缩短）。接下来的两个部分会演示如何在自己的机器上复现这次抓获——无需克隆仓库。}

安装

pip install procheiron             # or: pipx install procheiron — see the note below
pip install "procheiron[crypto]"   # optional: ed25519 signing (the chain itself needs nothing)

_{pipx 用户：pipx 会将 procheiron 命令加入 PATH，但不会让系统的 python3 能够导入该包。脚手架生成的辅助脚本（memory_propose.py、memory_promote.py、validate_minimal.py）需要此包，因此请使用 procheiron init 完成时打印出的解释器运行它们，而不要直接使用 python3。以下内容均假设你已在激活的环境中使用普通的 pip install 安装。}

在使用编码 Agent？给它一条指令，它就会安装 Procheiron、通过 MCP 完成接入，并端到端运行篡改检查：

获取并遵循以下说明： https://raw.githubusercontent.com/logotheusneuro-cpu/procheiron-core/master/INSTALL_FOR_AGENTS.md

或者，无需安装，从未加工的检出目录验证规范：python3 conformance/run_conformance.py。

亲自试着破坏它（60 秒）

在自己的机器上运行上面的演示：搭建一个公共库，写入一条受治理的记忆，然后改写历史，看看链条如何断裂。

procheiron init ./commons && cd commons

# 1. propose a memory as alice
python3 memory_propose.py --created-by alice --type decision --scope project \
    --subject "retry policy" --statement "Retries use exponential backoff." \
    --source-path docs/decisions.md --confidence 0.9

# 2. promote it — reviewed by someone who is NOT alice (self-review is refused)
python3 memory_promote.py --memory-id <id printed by step 1> --new-status active \
    --reviewer bob --authorized-by casey --reason "verified against the source" \
    --allow-unverified-reviewer

procheiron validate .        # PASS

# 3. rewrite history — swap the reviewer on the promotion event
sed -i.bak 's/bob/rogue/g' memory/index/audit.jsonl

procheiron validate .        # FAIL: entry_hash mismatch — content was altered
mv memory/index/audit.jsonl.bak memory/index/audit.jsonl    # put history back → PASS again

适用于你的 Agent

Procheiron 提供 MCP 服务，因此任何支持 MCP 的 Agent——Claude Code、Claude Desktop、Cursor、 Codex 等——都能按照人类所遵循的同一套规则，读取和写入共享记忆库。共有四个 工具：memory.search、memory.get、memory.propose、memory.promote。

Claude Code：

claude mcp add procheiron -- procheiron mcp --root ./commons

任何带有 mcpServers 配置的客户端（Cursor、Claude Desktop 等）——请合并，而不要替换：

{ "mcpServers": { "procheiron": { "command": "procheiron", "args": ["mcp", "--root", "./commons"] } } }

写入操作默认是 dry-run，除非你传入 --allow-writes。通过 MCP 进行升级也会受到与其他场景相同的限制：写入某条记忆的 Agent 无法批准它。

该服务兼容两个时代：既支持当前的 2026-07-28 修订版（无状态、每个请求都带 _meta、server/discover），也支持旧版 initialize 握手，因此无论你的客户端是否已迁移，都能正常工作。这不仅关乎兼容范围——如果没有握手作为依据，现代请求过去会按旧版规则处理；而当记忆工具的真实含义是“我不支持你的协议”时，却回复“未找到内容”，这是你无法与真实结果区分的一种答复。

工作原理

1. 每条记忆都会经历一个生命周期：draft → candidate → validated → active → superseded。

2. 只有经未参与写入的人审核后，记忆才会变为 active——即受信任状态。 系统会拒绝自我审核，而不只是劝阻：

   $ python3 memory_promote.py --memory-id mem_20260709_retry_policy… --new-status active \
         --reviewer alice --reason "looks right to me"
   memory_promote: REFUSED — self-review: 'alice' created this record (invalid transition §8.7)
   

3. 每个步骤都会写入一份只追加的审计日志，日志条目通过哈希链关联（BLAKE2b，纯标准库实现）。编辑或重新排序任何历史事件都会破坏链条。删除末尾内容（截断尾部）是哈希链本身无法发现的唯一修改——使用 --expect-head 在外部固定链首，也能检测到这种情况（见下文）。

4. 想要可通过加密方式验证作者身份？安装加密扩展，并使用 ed25519 为条目签名。无法执行的签名检查会直接报错，绝不会悄然放行。

对比

若要确保 Agent 记忆可信，你通常会采用以下做法：

	强制独立审核	防篡改历史	适用于任何存储	设置
约定文档（“Agent 应当……”）	否——依赖自觉	否	—	无
记忆文件的 Git 历史	否	是——除非重写历史本身	仅适用于这些文件，不适用于你的存储	无
记忆引擎的元数据	否——由自身声明	否	仅适用于该引擎	无
完整溯源方案（W3C PROV + 签名基础设施）	可实现	是	是	自行搭建
Procheiron	是——验证器会拒绝 †	是——另有哈希链；完整重写需要外部锚点	是——可管理你选择的任意存储中的记录	pip install；若要获得最强保障，还需管理锚点和密钥

_{† 可防止自我审核以及编辑／重新排序篡改。拥有文件系统写入权限的内部人员仍可追加伪造的升级记录——要堵住这一漏洞，需要使用可选的签名扩展，并将密钥保存在他们无法触及的地方。CLAIMS.md 详细说明了防篡改证据与经过身份验证的溯源之间的明确界限。}

基于相同假设，Git 已经能提供防篡改能力——无人重写锚点。两者的区别在于，Procheiron 有强制审核关卡和 Git 并不具备的记录级结构。记忆引擎并非竞争对手：Procheiron 管理这些引擎所持有的记录，而且永远不会自行实现检索功能。

命令

命令	功能
procheiron init ./my-commons	搭建一个受治理的记忆共享库。
procheiron validate <root>	验证部署。添加 --expect-head <hex> 和 --expect-lint <fp>，可根据外部锚点固定链头和强制执行配置；--json 会报告这两个当前值。
procheiron scorecard <root>	信任循环指标：记录数、独立晋升数、拦截的问题数。
procheiron keygen --actor <id>	为签名作者身份生成一对 ed25519 密钥（需要 procheiron[crypto]）。私钥 → 0600 文件；公钥 → stdout，供 known_actor_keys 使用。
procheiron mcp --root <root>	通过 MCP（stdio JSON-RPC）向 Agent 提供共享库服务。
procheiron conformance	运行一致性测试套件（需要检出仓库）。
procheiron version	输出版本信息。

审计日志能做什么、不能做什么

在依赖它之前，先坦诚说明一点。

哈希链让日志具备篡改可见性：任何人若悄悄修改历史记录，都会破坏哈希链。但哈希链只能证明日志内部一致——拥有文件写入权限的人可以从头重建整个日志，而且重建后的日志仍能通过验证。解决方法是将最新条目的哈希锚定到此人无法触及的位置（git 提交就可以），并在检查时传入：procheiron validate --expect-head <hex>。这样，彻底重写也会被发现。

强制执行配置也有同样的问题——它与其管辖的一切都存放在同一目录中，因此可以从内部降级。用同样的方法通过 --expect-lint <fingerprint> 锚定它。两个锚点都会无条件检查，删除锚定的内容会导致检查失败，而不是跳过检查；procheiron validate --json 会输出当前的 audit_head 和 lint_fingerprint，供你固定锚点。

完整威胁模型——签名、密钥与蓄意的内部人员

签名能进一步提高门槛。启用加密扩展并配置密钥注册表（known_actor_keys）后，注册的每个作者身份发出的事件都必须带有该身份的有效签名。移除签名会导致验证失败，不会蒙混过关。

还需如实说明剩余风险：如果同一个 OS 用户同时拥有日志、密钥和密钥注册表，蓄意的内部人员仍可以重写并重新签署所有内容。在单台共享机器上，你得到的是篡改可见性（可通过外部锚点检测），而非篡改防护。若要彻底阻止这类内部人员，就必须将链头锚定在外部，并让密钥脱离写入者的控制范围——例如交由单独的用户、HSM 管理，或使用无密钥签名。

还有一条重要界限：这些都关乎来源证明，而非正确性。关卡能证明是谁撰写和审核了记录，以及历史记录无人重写——但无法让内容变成事实。审核者可能会批准错误信息，使其获得信任；此时你能得到的是一条清晰的追踪路径，以及一条用于替换旧记录的路径，而不是预防错误。

我们会在 CLAIMS.md 中持续记录哪些内容已有证明、哪些仅是声明，并为每项声明引用证据。如果本 README 中的任何内容与该文件不一致，以该文件为准。

仓库内容

路径	内容
spec/	v0.1 规范：治理、记忆共享库、控制平面、规范性一致性 MUST 列表，以及 Core/Profile 边界。
conformance/	基准测试套件。generic-vault/ 是完整的虚构部署（“Meridian Atelier”）；minimal-vault/ 是最精简的采用者；此外还有必须测试失败的负面测试夹具。
src/procheiron/data/adopter/	采用者模板——procheiron init 写入新共享库的精确字节内容，也是运行一致性测试时使用的模板。仅有一份，不设镜像副本。
init/	用于将 Procheiron 移植到现有项目的 PORTING_GUIDE.md（procheiron init 是脚手架工具）。

设计选择

• 零运行时依赖。 实际部署时运行的所有内容都是 Python 标准库。 唯一的可选额外项是用于 ed25519 签名的 procheiron[crypto]；哈希链本身不需要任何依赖。（jsonschema 和 opa 仅用于开发／CI 交叉检查。）
• 默认可检测篡改，按需签名。 请参阅 chain.py 和 signing.py。
• 核心可移植，配置文件具体化。 规范保持通用；部署专属绑定（身份、路径、权限层级）放在配置文件中。请参阅 spec/boundary.md。
• 绝不负责回忆。 嵌入和检索是记忆引擎的工作。Procheiron 不会开发与之竞争的功能。

路线图

1. 通过一致性测试的第二个独立真实部署——届时，“作者自己能用”才真正变成“可用”。
2. 参考适配器，展示 Procheiron 如何端到端地管理一款热门第三方记忆引擎。
3. 生产环境密钥托管指南——涵盖独立用户、HSM 和无密钥签名模式，确保即使在单台机器上也能可靠签名。

截至目前已发布：v0.1 带来了规范、一致性测试套件、CLI 和脚手架；v0.2 带来了可检测篡改的链和可选签名。

正在某处运行 Procheiron？请提交一份 部署报告 ——独立部署确实是路线图上的第一项。

常见问题

这是记忆引擎吗？ 不是。没有嵌入、排序、回忆基准测试，以后也不会有。memory.search／memory.get 工具是对记录的治理筛选器（按状态和范围筛选，默认仅返回已审核的记录），而非内容检索。它管理的是你的引擎所持有的记录。

它能阻止恶意内部人员吗？ 能检测；要预防则必须做到两件事：将链头锚定在内部人员无法触及的地方，并确保签名密钥不在其写入权限范围内。上文明确说明了边界所在。

为什么零依赖？ 信任层不应要求你信任一整棵依赖树。实际部署时运行的所有内容都是 Python 标准库；甚至哈希链也只用标准库。

我怎么知道它是否适合我的配置？ 两个问题即可判断。你的写入者是否由彼此独立的主体控制——例如不同的人员、团队或进程——还是由一名操作员运行所有 Agent？你能否在写入者无法触及的范围之外管理外部链头锚点和密钥托管？两个答案都是“是”，保障措施就能完全生效。两个答案都是“否”，对你而言，审核关卡就更接近约定而非强制执行——你仍能获得可检测篡改的审计轨迹和严格的反自审检查，但更深层的承诺并不适用于你的架构。

它已可用于生产环境吗？ 按照我们自己的规则，还不行。一致性测试已在测试样例层面通过，但只有当第二个真实部署由我们之外的人运行并通过测试套件后，我们才会宣称“可在生产环境复现”。这是路线图上的第一项。目前它已适用于单个团队的共享记忆库，可提供可检测篡改的审计轨迹和强制独立审核——这正是上文 60 秒演示所展示的内容。

如果我停止使用它呢？ 执行 pipx uninstall procheiron，所有内容仍可保留：共享库采用纯 JSONL 和 Markdown 格式，每条记录和每个审计事件都能用 cat 查看。无需导出，也不会被锁定。

这个名字是什么意思？ Procheiron（πρόχειρον）在希腊语中意为“随手可用”——历史上指简短实用的法律手册。对于一套随手可查的小规则来说，这是个贴切的名字。

许可证

MIT——请参阅 LICENSE。