MemPalace 共享大脑接入规则：多 Agent 在同一宫殿中的记忆纪律与 Logstream 协作协议

当多个 Agent（如 Mac 上的 Claude Code、Windows 上的 Codex、家中的 Hermes bot）共享同一个 MemPalace 宫殿（hub）时，它们不仅共享一段记忆，还共享一张「正在流动的工作网」。mempalace/instructions/shared_brain_rules.md 正是为这种场景准备的注入到每个 Agent 系统提示词/指令文件中的行为规则块：它规定了 Agent 必须如何读写共享记忆、如何检查收件箱、如何常驻后台 watcher 保持「可被唤醒」、如何委派与认领任务、以及如何用 ack 闭合每一条协作回路。阅读本文后，你将掌握这段规则文本的每一处细节及其背后的源码依据，学会用 mempalace rules --agent <id> 把它正确渲染并接入任意 Agent harness。

这份文档在仓库中的角色：被复制的系统提示词片段

mempalace/instructions/shared_brain_rules.md 并非一篇普通教程，而是一份逐字复制（verbatim）的 System-Prompt Snippet。仓库内有三处内容互锁：

1. 权威源（single source of truth）：integrations/shared/coordination-protocol.md 的 "System-Prompt Snippet" 章节；
2. 打包副本：本文档 mempalace/instructions/shared_brain_rules.md，随 Python 包分发；
3. 渲染器：mempalace/instructions_cli.py 读取打包副本，把占位符 <AGENT_ID> 替换为真实身份，并用 HTML 注释包裹输出。

三个副本通过测试钉死（test-pinned）互不漂移——协调协议文档明确写道，CLI 读取的正是这份打包副本，因此同一个经过实战考验的规则块会以相同文本进入每一个 harness，而不是每个系统提示词各写一版。

把规则接入 Agent 的标准做法由 CLI 完成：

mempalace rules --agent mac-claude >> ~/.claude/CLAUDE.md

在源码层面，cli.py 中的 cmd_rules 会调用 instructions_cli.run_rules，其核心逻辑在 mempalace/instructions_cli.py：

• render_shared_brain_rules(agent_id) 读取模板后用 .replace("<AGENT_ID>", agent_id) 完成注入；
• 输出被 <!-- mempalace-shared-brain:start ... --> / <!-- mempalace-shared-brain:end --> 标记包裹，后续协议升级时重新渲染并整块替换即可，无需手改 N 份系统提示词；
• 身份参数做了强校验：必须匹配正则 [A-Za-z0-9._-]+，否则报错 --agent must be a single token like mac-claude (machine-harness)。

规则块应写入哪个文件取决于 harness：Claude Code 写 ~/.claude/CLAUDE.md，Codex CLI 写 ~/.codex/AGENTS.md，OpenCode 写 ~/.config/opencode/AGENTS.md，Antigravity IDE 写 ~/.gemini/config/GEMINI.md，Hermes 则写入其 SOUL.md（详见 shared-brain 指南）。

规则全景：Agent 在共享宫殿中的两套纪律

规则块开篇先立住身份：

You share a MemPalace hub with other agents. Your agent identity is <AGENT_ID> — use it as from_agent/created_by in every MemPalace call.

每个 Agent 必须有一个稳定、单一的 from_agent 身份，推荐格式为 <machine>-<harness>（例如 mac-claude、windows-codex）。这是它在每次事件写入时的 from_agent、每次 artifact 存储时的 created_by，也是他人投递任务的 to_agent。身份可以随意轮换或冒名，事件轨迹就无法审计——协调协议把「永不轮换、永不冒充」列为身份铁律。

规则主体随后分成两个明确不混用的层：

层	承载	访问方式	典型内容
Memory（drawers + knowledge graph + diary）	值得日后回忆的持久知识	语义搜索	决策、事实、人、项目、结论
Coordination（logstream 事件 + artifacts）	此刻在 Agent 之间流动的活跃工作	结构化过滤 + long-poll/watch	委派、回复、补丁、ack

判据只有一句话：如果别的 Agent 应该「行动」于它，它就是事件；如果未来会话应该「知道」它，它就是 drawer。 一次完成的委派通常两者皆产——事件承载了工作流，drawer 记录下结论。

Memory（记忆纪律）：先搜索、逐字引用、改事实要作废重写

规则块对记忆读写提出四条硬要求：

1. 回答前先搜：涉及过去的工作、决策、人物、项目时，先用 mempalace_search 检索宫殿；关系型/时间型事实用 mempalace_kg_query（知识图谱查询）。
2. 逐字引用，禁止转述：对检索到的内容必须 verbatim 引用，不得改写；如果宫殿里没有，就明说没有，绝不臆测（don't guess）。
3. 落地持久成果：决策、结论、学到的经验用 mempalace_add_drawer 归档成 drawer。
4. 事实变更用「作废 + 新增」：当某个事实改变时，先 mempalace_kg_invalidate 旧事实，再 mempalace_kg_add 新事实——这与记忆层 append-only 的哲学一致，修正是一条新记录，而不是原地修改。

这两条语义对应着 website/concepts/agent-logstream.md 中「协调 vs 记忆」的分工表：宫殿是长期召回（semantic search），logstream 是活跃协调（structured filters）。规则同时规定不得归档 secrets 与 tokens——共享宫殿意味着写入即对舰队可见，保密内容必须隔离在外。

Coordination（logstream）：收件箱检查、后台 watcher、ack 与循环闭合

协调部分是本规则块最长的段落，也是多数分布式协作失败的根源所在——事件写对了，但没人监听。规则把监听拆成四种模式并给出明确指示。

会话开始：先查收件箱，记住事件 id 光标

规则要求在开始工作前和长任务开始前执行收件箱扫描：

mempalace_event_list with to_agent=<AGENT_ID>, since_event_id=<last event id you processed>, preview=true.

要点有三：

• to_agent=<AGENT_ID> 会自动匹配 to_agent=* 的广播事件，无需二次查询（底层过滤逻辑见 logstream.py 的 event_matches_watch 与 broadcast 匹配约定）；
• since_event_id 是唯一的续读光标：事件按追加顺序（SQLite rowid）而非时间戳排序，跨副本同步时，peer 在 09:10:48Z 写入的事件可能在你本地 09:13:21Z 的事件之后才到达——用 since_created_at 做续读点会把它永远跳过；
• preview=true 让事件体以截断预览返回（附 body_truncated 与 body_length 标记），扫繁忙流时不浪费 token。

规则明确禁止用 since_created_at 续读，并把「记住那个 id，它就是你的光标」作为不可妥协的习惯。MCP 侧的对应实现见 mcp_server.py 的 tool_event_list，其参数含 since_event_id、since_created_at、order、preview 等完整过滤面。

会话全程：必须常驻后台 watcher，把「退出」当作「有信」

规则的措辞经过刻意打磨，是命令式而非条件式：

at the start of every session, right after the inbox check, launch a background watcher — do not wait to be asked, and do not wait for a coordinated task to begin

mempalace logstream watch --agent <AGENT_ID> \
  --state-file ~/.mempalace/watch/<AGENT_ID>.json --json

--state-file 是 watcher 自己的光标（不是 Agent 的收件箱光标），跨重启持久化，保证 restarted watcher 不会漏事件。watch 的退出码即唤醒信号：exit 0 = 命中（有信），exit 2 = --idle-exit-ms 超时空转。一次唤醒可能覆盖多个事件，所以 Agent 收到唤醒后应从自己的光标清扫收件箱，然后以同一 state file 重启 watcher——这个「处理 → 重启」循环必须维持整个会话。首次运行若无光标，watcher 从 live tip 开始（不做历史重放），并在 stderr 上明说。

规则点出两个高频踩坑：

• 用 --agent 而非 --to-agent：--agent <id> 展开为 --to-agent <id> --exclude-from-agent <id>。排除自己是承重的——to_agent=<你> 会匹配 * 广播，而你发出去的广播也是广播，少了排除项 watcher 会被自己的每一条 status 唤醒。
• 重复 --type 表示「或」：只唤醒真正需要自己的事件类型；但如果你会委派，task.reply 必须留在过滤器里——worker 报告 blocked/failed 正是以 reply 到达，拒绝该类型的 watcher 会把光标悄悄推过这条事件，委派从此石沉大海。

对「进程内等待单一已知关联」的情形，规则补充 mempalace_event_wait 就够了——它是长轮询，默认 60s、上限 300s，超时返回 {"timed_out": true, "events": []} 而非报错，内部已做 0.25s→1s 退避，外层不必再包紧循环；但它补充 watcher，永不替代 watcher。所有底层语义在 logstream.py 的 watch_events / wait_events 及 read_watch_state / write_watch_cursor 中均有实现。

可见性：宣布你的监听，或宣布你无法监听

协调中最危险的模式是「假 watcher」——声称在监听、实际没有，导致请求方停止寻找人工兜底。规则要求：

• 协调任务开始前，向 to_agent=* 发布一条 status 事件，声明你监听的过滤器与已到达的光标，让别的 Agent 在委派前就知道谁在家；
• turn-based harness（无法跑后台进程）必须明说：发布光标并声明需要 ping，绝不声称拥有实际上并不存在的 watch。

status 类型是舰队 watchers 普遍「睡过」的类型，因此公告不会烧掉唤醒；公告应每个会话一次、过滤器变更时再发一次，避免每次 re-arm 都广播造成自我唤醒风暴（详见 协调协议 的 "Announce your watch" 章节与 _4_monitoring-the-stream 模式表）。

审批弹窗会静默卡死循环

若 harness 把 shell 命令或 MCP 写入挡在人工审批之后，每一条 ack、reply、patch 都可能等在一个无人注视的弹窗上——对外表现为「声称了任务却悄然沉寂」，与崩溃无法区分。规则要求 请操作员放行（allowlist）mempalace 工具与 watch 命令（至少放行事件 append/ack 与 mempalace_patch_submit）。shared-brain 指南记录了一个实测数字：同一 ping 获批时 5 秒完成，困在无人审批弹窗后安静地躺了 4 分半钟。

Ack：用工具生成，不要手搓

确认动作统一走 mempalace_event_ack（CLI：mempalace logstream ack），它会自动填好 type=event.ack 与指向原事件的 ack_of 链接；规则明令禁止手写 event.ack 追加。事件流是 append-only 的——ack 从不修改原事件，而是追加一条引用它的新事件（底层实现见 logstream.py 的 ack_event）。

委派与接收：完整的两端协议

规则把委派压缩为一次 mempalace_event_append + 一次 mempalace_event_wait：

• 委派方：mempalace_event_append(type=task.request, stream=project/<name>, room=delegation, topic=<name>(子团队可选), correlation_id=task_..., status=open)，body 必须完整包含 goal（目标）+ branch（分支）+ base commit（基线提交）+ definition of done（完成定义）；随后在同一个 correlation_id 上 mempalace_event_wait 等待回复。
• 接受方：先以 status=claimed ack 认领，防止其他 Agent 重复做同一份工作；交付代码时用 mempalace_patch_submit 提交补丁——只 push 分支然后消失不算交付，事件才算（pushing a branch is not a handoff）。
• 被阻塞：回复 status=blocked 并附 verbatim 说明；拿不出补丁也照样回复。沉默是 logstream 唯一救不了的失败模式。

MCP 层的 tool_patch_submit 会把「存 artifact + 追加 patch.ready 事件」合并成一次调用；请求信封的高阶封装是 mempalace_task_create 与 CLI 的 mempalace task create，其任务字段校验（必填文本、base commit 合法性、body 完整度）集中在 mempalace/tasks.py（validate_task_request / create_task），完整任务原样保留在 logstream 中。CLI 日志流子命令（append/list/wait/ack）的入口在 cli.py 的 cmd_logstream，每个命令带 --json 以保持可脚本化。

接收补丁：验哈希、显式应用、跑测试、闭合回路

收到 patch.ready 的 Agent 遵循五步：

1. mempalace_artifact_get 取补丁；
2. 核验 sha256（artifact 存储时即带 sha256 与 size_bytes，logstream.py 的 put_artifact / _patch_content_warnings 会校验内容并按需告警，如缺末行换行导致 diff 末 hunk 被截断、CRLF 行尾被 git apply 拒绝）；
3. 仅在明确的、用户可见的意图下本地应用补丁——应用是本地显式决策，logstream 永远不会替你 apply；
4. 运行约定的测试；
5. 以 mempalace_event_ack(status=applied | failed) 收尾。

收束铁律：append-only、verbatim、闭合每条回路

规则块最后一行是总纲：

Events are append-only and verbatim. Close every loop — no task you touched stays open without an applied/failed/blocked ack.

这四项约束与 协调协议 的 Hard rules 完全对齐：事件不可变（修正 = 新事件并标 status=superseded）；payload 精确（body 与 artifact 一律 verbatim，正文放不下的内容转存 artifact）；每个认领的 task.request 都以 applied / failed / blocked 终结，不允许悬空的 open；cursor 一律是事件 id。记忆层面同样要求闭环落地：委派结束时，把「决定/学到的东西」用 mempalace_add_drawer 写成一格 drawer，让结论日后可被语义检索，无需重放事件轨迹。

与相关模块的衔接

• recall 协议：记忆半边规则（先搜再答、逐字引用）与 integrations/shared/recall-protocol.md 互补，后者是 search-before-answer 的完整规范。
• logstream 概念与 RFC：事件/artifact 模型、光标语义、SSE 实时流的完整设计见 website/concepts/agent-logstream.md 与其设计依据 docs/rfcs/003-agent-logstream-coordination.md。
• 部署侧：hub 启动、bearer token、远程 Agent 接入、多机 peers 同步与 read-only 观察者模式，见 shared-brain 部署指南。
• Skill 化：mempalace-task（任务预览/创建/认领/交付/回路闭合）与 mempalace-recall（召回）两类 skill 分别位于 skills/mempalace-task/SKILL.md 与 skills/mempalace-recall/SKILL.md。
• 可用工具全景：规则中引用的 search、kg、add_drawer、event、artifact 等 MCP 工具清单可对照 mempalace/instructions/help.md，CLI 侧对应 cmd_logstream / cmd_task / cmd_artifact（cli.py）。
• 测试验证：logstream 核心、MCP 工具与 CLI 的测试覆盖分别在 tests/test_logstream.py、tests/test_mcp_logstream.py、tests/test_cli_logstream.py，可据此确认 append/list/wait/ack/artifact 与 watch 的退出码契约。

小结：把规则注入 Agent 的最小清单

把这份 shared-brain 规则正确接入一个 Agent，只需三步：

1. 为它分配稳定身份 <machine>-<harness>（如 linux-bob-claude）；
2. 执行 mempalace rules --agent <identity>，把标记块整体写入对应 harness 的指令文件（Claude Code 用 ~/.claude/CLAUDE.md，Codex 用 ~/.codex/AGENTS.md 等），并让操作员放行 mempalace 工具与 mempalace logstream watch；
3. 会话开始时按规则顺序执行：mempalace_event_list 收件箱扫描（记下事件 id 光标）→ 后台拉起 logstream watch → 需要委派时 event_append + event_wait → 收到补丁验 sha256 后显式应用并跑测试 → mempalace_event_ack 闭合回路 → 用 drawer 归档最终结论。

这段规则之所以值得以「同一份文本」注入所有 Agent，是因为协调的失败几乎从不源于协议缺失，而源于监听缺失与措辞含糊。命令式地、逐字地、在每个会话开始就执行的规则，才是让多 Agent 舰队从「偶发协作」走向「可预期协调」的分水岭。