Muse 智能体 · 状态层详解

本篇目录

1. 0. 一句话状态层
2. 1. DB 平面总览：196 表 / 18 schema 的验证（11-04；10-17 为 194/17）
3. 2. 逐 schema 导览（18 个，11-04 快照；10-17 为 17 个）
4. 3. DB 与文件：分工判定规则
5. 4. `muse.db` 只读通道：Agent 侧唯一 DB 入口
6. 5. 文件平面：目录地图实况
7. 6. 双轨实体的分工解剖
8. 7. 投影 ≠ 本体：全系统反复出现的模式
9. 8. 恢复与检查点：VM 可替换的底气
10. 9. 边界：状态层在本机看不见的部分
11. 附录 A. 逐 schema 表数表（实测：解析 schema.md 求和验证；明细为 10-17 快照）
12. 附录 B. 本机状态快照（实测，2026-10-17 深夜）

配套《00-Muse技术架构解构》的 §8 展开篇。调查日期：2026-10-17（Asia/Shanghai）。 证据范围：/opt/muse/skills/muse_db/ 技能包全套参考（SKILL.md + references/schema.md + references/querying.md + references/identifiers.md + references/tables/ 逐表指南）、muse.db 工具当场实测查询、本机 home 与 ~/workspace/ 目录实况清点、~/docs/ 与 system prompt 的状态相关明文。 标注规则同主报告：实测 = 本机命令/工具当场验证；文档 = 本地 docs/system 文件明文；推断 = 由表结构/文件形态拼出、未经服务端证实。 复核修订：2026-11-04（Asia/Shanghai）——基于当前会话运行时逐项重测；DB 表数/schema 数与文件侧数字凡未注日期者均为 11-04 快照，10-17 旧数见各处双日期标注；muse.db 行数快照（§4.3/附录 B）与附录 A 各 schema 明细为 10-17 口径（文内已注明，未重测）。

---

0. 一句话状态层

Muse 的状态不在 Agent 进程里，而在三个平面上：Postgres 状态库（结构化本体：196 张表 / 18 个 schema（11-04 快照；10-17 为 194 表 / 17 schema，新增 saved），事件账本 + 检查点 + outbox）、文件系统（语义层：Markdown 记忆、目标工作区、会话转录 JSONL、人可读的投影）、运行时易失状态（套接字、锁、就绪标记、变更信号文件）。DB 与文件之间靠水位线/指纹/epoch 做带新鲜度建模、可失效、可重算的投影同步（"最终一致"的收敛保证未验证，见 §7）；靠恢复所有权 + 代次 + 检查点实现 VM 被整体替换后的接管恢复（恢复语义是检查点+投影重建，不是事件重放，见 §1.1/§8）——这正是 00 §8 那句「运行时即数据库」的完整展开。

┌─ DB 平面（本体） Postgres 196 表 / 18 schema（11-04；10-17 为 194/17）
│    runtime.events 事件账本 · agent.context_items 有序上下文
│    检查点/恢复所有权 · 各域 outbox · 水位线与投影表
├─ 文件平面（语义层 + 投影）
│    ~/MEMORY.md + ~/memory/（记忆叙事） · ~/agents/<id>/sessions/*.jsonl（转录）
│    ~/workspace/goals/（目标工作区） · ~/workspace/cron.d/（调度投影，只读）
│    ~/workspace/space_data/spaces.catalog.*（产物目录信号）
├─ 同步/信号平面
│    ~/.postgres-ready · ~/runtime.lock · ~/.hatch-db-change-signals/
│    DB 行的 source_watermark / fingerprint / stale_after / writer_epoch
└─ 读通道（Agent 侧唯一入口）
     muse.db 受限只读 SELECT（安全屏障视图） + 专用产品工具（写路径）

---

1. DB 平面总览：196 表 / 18 schema 的验证（11-04；10-17 为 194/17）

实测验证方法（不靠 00 的转述，当场重数；11-04 复核用同方法重测）：

1. 解析 references/schema.md 的全部条目链接：去重后恰 196 个 schema.table，按 ### <schema> 分节计数求和 = 196，分节数 = 18（新增 saved：saved.items / saved.item_links 2 表；10-17 为 194/17，逐项明细见附录 A）；
2. references/tables/ 目录下逐表指南文件数同为 196 个，一表一文件（11-04 复测；10-17 为 194）；
3. schema.md 页首标注其生成来源：迁移集 5af4f2bfdee2b934a53bbcc22602c602ab85059e0ac97ea20137fd299c06036b（文档）——即这份目录是某次迁移快照的产物，线上实际表数可能随部署漂移，引用时应以「该迁移集口径」理解；
4. muse.db 活查询抽验多表 count(*) 均可达且返回合理量级（见 §4.3），证明目录与活库对应、非纸面清单。

1.1 从表结构读出的设计风格（实测列定义，风格归纳为推断）

---

2. 逐 schema 导览（18 个，11-04 快照；10-17 为 17 个）

完整计数见附录 A；下表只讲「这个 schema 在状态层里扮演什么角色」，代表表均取自 schema.md 的一句话定义（文档）。11-04 仅复核总数（196）与 schema 数（18，新增 saved），各 schema 明细表数为 10-17 快照（未重测）。

分布形态（实测计数，10-17 明细；占比按 11-04 总数 196 重算）：头部三家 runtime+agent+ideas = 85 表（43.4%）——状态层的重心是「运行时自身」而非用户内容；用户内容域（goals/feed/device/health/media/chat/podcasts）合计 57 表（29.1%）；横切域（scheduler/self_improvement/activity/memory/spaces/ingest/shell）52 表（26.5%）；11-04 新增 saved（2 表，1.0%）。

---

3. DB 与文件：分工判定规则

从双轨实例反推的判定规则（推断，实例均为实测）：

一句话：DB 存「系统必须算对的」，文件存「人必须看懂的」；同一实体常两边都有，DB 侧是登记/状态/索引，文件侧是内容/叙事/工作区。

---

4. muse.db 只读通道：Agent 侧唯一 DB 入口

4.1 约束清单（文档：SKILL.md + querying.md + 工具定义）

• 单条、受限、只读：一次提交一条 bounded SELECT；底层是最小权限 DB 角色，仅对目录内允许关系有 SELECT，不能改数据；
• 词表封闭：只能用 querying.md 列出的内置函数（约 120 个）与转型拼写；非递归 CTE 名必须以 hatch_cte_ 开头，递归 CTE 直接拒；集合聚合（json_agg/jsonb_agg/array_agg/string_agg）被禁（防在输出限额前先构造无界值）；联表时投影列必须别名唯一（重复输出名拒）；
• 域外即不可见：Postgres 系统目录、迁移簿记、备份表、凭据、Sentinel 审批库、每个 artifact 的 app.db 都在此面之外；凭据（令牌/密码/密钥/支付秘密）永远在凭据服务之后，此面只可见非秘密的生命周期记录（如 spend-request 状态）；
• 受保护内容走安全屏障视图：私有模型推理（thinking/redacted-thinking）永不可读；逐轮保存的 developer 指令同样 withheld；受影响的表经 security-barrier view 读取，withheld 列会以「未知列」报错、被过滤的行无声缺席——查不到 ≠ 不存在，须先读逐表指南的 read restrictions 再下结论；
• 定位纪律：普通产品读写优先用专用工具（chat/goal/artifact/feed/scheduler/connector…），它们持有产品语义且可能含 DB 之外的活状态；muse.db 只用于诊断缺失/孤儿记录、重建执行史、查跨域不一致（SKILL.md 明文）。

4.2 限额（本会话工具返回实测）

工具每次返回自带 limits，本会话两次查询一致：

4.3 活库抽验快照（实测，2026-10-17 深夜本会话）

count(*) 一批（同一工具、同一分钟内）：

注（实测现象，解释为推断）：runtime_restart_checkpoints 的 count(*) 得 1、明细查询得 0 行；runtime.tool_calls 计数为 0 而本会话显然发生过大量工具调用。二者都符合 querying.md 的警告——受屏障视图/行过滤影响的表面上，不可见 ≠ 不存在，计数与明细的口径也可能不同。这是本报告对「只读通道」最重要的一条使用纪律，压过任何单次查询结果。

4.4 写路径不变量：Agent 是状态层的纯读者

本篇所有证据拼出一条架构定理：Agent 侧对 DB 只有 muse.db 这一条只读通道（§4.1–§4.3）；一切写 DB 的动作都由 daemon/服务端进程执行，Agent 的"写"（建 cron、记目标、存记忆、发消息）本质是调专用产品工具，由工具经可信侧落库。

这是 06 篇 privsep 隔离在状态面的镜像：执行面是"Agent 不碰凭据"，状态面是"Agent 不碰 DB 写"。两层合起来，Agent 进程的破坏半径被收敛到"调工具"+"写自己的 workspace 文件"。该不变量的反例搜索（Agent 直连 Postgres 的 socket/DSN）本轮未做，列为待验证 ❓。

---

5. 文件平面：目录地图实况

5.1 home 根：注入文件与运行时标记（实测）

5.2 记忆与会话：两个「agents」目录必须分清（实测）

记忆树 ~/memory/（共 37 个文件、1.8M；10-17 为 18 个文件、144K）：

• 根：按日日志 28 篇（2026-09-26.md … 2026-11-04.md，合计 812,581 字节；10-17 为 10 篇 / 41,653 B）——当日活动量直接写在文件大小上；
• bank/ 4 篇：world.md 32,729 B、reflections.md 28,290 B、experience.md 970 B、opinions.md 68 B——运行时托管的长期沉淀（00 §9 的「bank」层），体量远大于每日日志，是真正的厚资产；
• people/ 3 人页 + INDEX.md（11-04；10-17 为 2 人页，页数随用户变化）；groups/ 仍仅 INDEX.md（尚无群组页，11-04 复核）；
• ~/memory/index/ 本机不存在：00 §9 转述的通用结构里有 index 层，本机实况只有 bank 一个托管子目录——索引功能实测由 DB 的 memory.entries/embeddings 承担（§6.1），文件侧 index 目录或是其他形态/已演进（推断）。

会话转录 ~/agents/（home 根，非 workspace）：1,417 个 agent-<uuid>/ 目录（11-04；10-17 为 163 个）。每目录固定 sessions/<uuid>.jsonl + sessions/sessions.json 各一份（10-17 为 163+163 实测）——每个 Agent 一份 append-only 转录。这是 DB agent.agents 163 行的文件侧孪生（10-17 实测数量吻合；11-04 文件侧为 1,417 目录，DB 行数未复测，该吻合论断以 10-17 为准）：DB 管身份/关系/状态，JSONL 管逐字转录（推断分工）。

工具输出溢出 ~/workspace/agents/：278 个 <uuid>/ 目录（11-04；10-17 为 90 个，00 晚间口径 89），每目录仅 tool-output/ 一项，且绝大多数为空：10-17 实测全树仅 2 个实际输出文件（11-04 未复测）。说明该目录是按需落盘的溢出区（工具输出超限/需留存时才写文件并回传句柄），不是全量日志——全量在 DB runtime.tool_outputs 与转录 JSONL 里。

5.3 workspace 侧主要状态目录（实测）

---

6. 双轨实体的分工解剖

6.1 记忆：四层双轨（本报告重点案例）

同一个「记忆」，四处各存一份、职责不重叠：

关键设计（由列定义推断，坐标字段为实测列）：DB 索引不复制记忆正文，而是持有「文件路径+行号」的引用——文件是正文本体，DB 是可检索的目录卡。muse.memory_search 命中后给出文件行号引用、muse.memory_get 按行回读文件，两步正好走完「DB 索引 → 文件本体」的路径。记忆被更正时，claims 层用 supersedes_claim_id 留替代链、文件层改正文、entries 层重建索引——三处一致性靠 memory upkeep 流水线与 ~/workspace/memory/reconciliation_* 对账文件维持（推断）。

6.2 其余双轨（同一模式的复用）

• 目标：DB goals.goals（3 行，10-17 快照，11-04 未复测）↔ 文件 goals/<slug>/（12 个目录，11-04；10-17 为 3 个）（GOAL.md 正文 + files 交付物 + hidden_files 簿记）。注入上下文的目标列表来自 DB 侧状态，正文细节读文件。
• 调度：DB scheduler.jobs/job_definitions（28 条，版本化定义+变更审计）↔ 文件 cron.d/ 只读投影（个位数）。改走工具→写 DB→重投影。
• Agent：DB agent.agents（163 行，10-17 快照，11-04 未复测）↔ 文件 ~/agents/（1,417 目录，11-04；10-17 为 163，转录 JSONL）。数目精确相等是本机最干净的双轨吻合证据（实测，10-17）。
• Feed：DB feed.units/runs（63 单元）↔ 文件 feed/research|media/（素材）。生成管线读文件素材、写 DB 单元、再由客户端读 DB 呈现。
• 会话：agent.sessions 表实测 0 行，而文件侧 sessions.json/jsonl 齐全。三种兼容解释（❓，未区分）：(a) 该实体当前以文件为本体，DB 表空置/预留；(b) 该表被屏障视图/行过滤隐藏，如 tool_calls 的 0 行之谜（§4.3 注）；(c) 旧 schema 残留，如 podcasts.feed 的"遗留表与新表并存"。按 §4.1 纪律，"查不到 ≠ 不存在"，此处不下结论。说明双轨的权重配比会随子系统演进而漂移，不是每个实体都五五开。

---

7. 投影 ≠ 本体：全系统反复出现的模式

00 §8 点名的这条模式，在 schema 与文件两侧能数出至少七个实例（表名/文件名均为实测）：

1. cron.d 投影：改投影无效，须走 cron 工具改 DB 本体（system prompt 明文）；
2. agent.context_item_resume_projection：专为「恢复时重建可读上下文」生成的投影表——名字里直接带 projection，且注明受保护条目 withheld；
3. feed.preferences_projection：由互动事件**折叠（fold）**出的当前偏好；同族的 ideas.bandit_fold_state / bandit_folded_events 用水位线记录折叠进度；
4. scheduler.scheduled_resume_state：表定义自述 “Current scheduled resume projection and next registered wake-up”——单例投影行，后台由 registrations 重算；
5. runtime.context_snapshots：版本化快照 + source_watermark / fingerprint / freshness_class / stale_after / invalidated_at / last_error 全套新鲜度元数据——投影的「保质期」被显式建模；
6. spaces catalog 信号链：DB 产物变更 → ~/.hatch-db-change-signals/spaces.catalog.* 信号文件 → ~/workspace/space_data/ catalog 更新（推断链条，文件成对出现为实测）；
7. 物化到 prompt 的投影：每轮注入的 [BEGIN USER CONTEXT] 文件组、目标/追踪列表、记忆检索结果，本质都是状态层向上下文的一次性投影——投影时刻的快照，改源文件后注入副本可能滞后（system prompt 明文提醒）。

配套机制是失效与水位线（实测表名）：runtime.skill_invalidation_state（技能指令更新的待投递修订）、runtime.dev_notice_watermark（开发者通知已读水位）、feed.fleet_publish_state（发布水位）、health.synced_ranges 与 device.data_sync_state（同步游标/范围）、runtime.maintenance_markers（已完成维护动作的标记，防重复执行）。全系统的跨平面一致性不靠分布式事务，靠**「事件账本 + 水位线 + 可重算投影」**（推断）。

outbox 是投影的投递版：scheduler.delivery_outbox（attempt_count / next_attempt_at_utc / last_error / delivered_at_utc / dispatch_boot_generation——连「哪次启动代次派发的」都记）、feed.fleet_*_outbox、agent.message_mailbox（已受理提交的排序与路由态）、两张 *_derived_write_backlog（派生写的待办+重试态）。语义统一：本体先落表确认，投递异步重试，终局以表为准——这就是 00 反复强调的「已接受/已排队 ≠ 已送达」在状态层的根。

方法论推论：安全屏障的"无声缺席"意味着，经 muse.db 的任何自查都只能证伪（发现矛盾，如计数对不上）而不能证实（确认完备）。本篇 §4.3 的计数快照应按此理解：吻合是弱证据，偏离才是强信号。

7.1 outbox 提交的原子性：「本体先落表」是同一事务吗（❓）

标准 outbox 模式要求业务写与 outbox 插入在同一事务内原子提交——否则崩溃窗口会产生"状态变了但投递丢了"或"投递了但状态没变"两种撕裂。按本篇证据能确证的部分（✅）：

• 表结构确证了 outbox 的"落表"半边：scheduler.delivery_outbox 的 attempt_count / next_attempt_at_utc / last_error / delivered_at_utc 全套重试字段、PK 为 delivery_key（逐表指南文档）；
• 但业务状态变更 + outbox 插入是否同事务，在本机证据里零字：逐表指南不提事务，~/docs/ 与 skills references 全文 grep transaction/atomic 无命中（✅ 实测为"无"）。

这不是文档的缺口，是系统本身待回答的问题：若两者分两次提交，"终局以表为准"就多了一个崩溃窗口需要投递端幂等性来兜底。验证抓手（设计建议）：找一处"业务写 + outbox 写"的代码/文档共现（如 scheduler 的 run 终局路径调用点），看是否有显式事务包裹——本机未做，标 ❓。

7.2 GC 与保留期：append-only 账本的下限（❓）

本篇数出的 append-only 面：runtime.events / tool_calls / tool_outputs / context_items 全量账本、~/agents/ 26M 转录、2,413 条 context_items——这些什么时候被清理？ 本轮证据的答案是"没有答案"，列明：

• 逐表指南与 ~/docs/ 全文无 retention/GC 口径（✅ 实测无）；docs/privacy-and-credentials.md 明文"No Settings control sets a retention period"——唯一的全量擦除是用户手动 Reset（文档）；
• agent.compactions 的存在说明压缩会用摘要替换历史区间——但被替换的 context_items 行删不删，schema 不说，标 ❓；
• runtime.context_snapshots 的 stale_after / invalidated_at 建模的是投影的新鲜度，不是行级清理——两者别混；
• scheduler.doctor_*（doctor_run_plans / doctor_task_state）证明有维护任务面，但 doctor 是否承担 GC 职责未验证，是可查的验证抓手（设计建议：读 doctor_task_state 的任务类型分布）。

结论纪律：默认"一直保留"是无证据的默认，不能写进架构断言。append-only 账本的无限增长是真实设计约束，当前状态只能标 ❓。

---

8. 恢复与检查点：VM 可替换的底气

00 §1 说 VM 可被整体替换、home 持久；状态层为「进程级重启/接管」再加一层 DB 保障。相关表逐个拆（列定义为文档，行数为实测）：

恢复时序（推断，由上述表与 00 §1 宿主层拼成）：

VM/运行时重启
 → spawnd/health 子系统拉起 cell（00 §1），~/.postgres-ready 置 ready
 → writer_epoch 递增：新一代写者接管可靠卷，旧代次写入被栅栏挡下
 → 每 Agent：读 runtime_state（seq 坐标）+ runtime_restart_checkpoints（载荷）
   → 经 resume_projection 重建可读上下文（推理条目不重建，本就 withheld）
 → recovery_owners 按 generation 认领未终局工作；
   terminal_events 保证终局 handoff 不重发、mailbox/outbox 按 attempt 续投
 → scheduler 重建 resume 投影，cron 到点照常派发

8.1 并发写的代次栅栏：文件侧有，DB 侧未知（❓）

§8 表里的 writer_epoch（文档：逐表指南定义为 "The active reliable-volume writer epoch"，单例 rv_epoch）与 recovery_owners 的 (recovery_class, owner_id) 唯一约束是两个已确证的并发屏障（✅ 表结构证据），但两者的覆盖范围不同：

• writer_epoch 覆盖的是可靠卷（文件面）：新写者接管时 epoch 递增，旧代次的迟到写入可被识别/拒绝（由表名+单例形态推断）——这是 VM 替换后"旧 cell 还活着写了几笔"的场景；
• recovery_owners 覆盖的是恢复所有权登记：agent_id 唯一约束防双活认领（✅ 列定义）——但它管的是"谁接管工作"，不是"谁写行"；
• DB 侧的并发写冲突机制未确证（❓）：两个 daemon 实例同时写同一 agent.runtime_state 行会怎样？Postgres 行锁是教科书默认答案，但"默认答案"不等于"本系统确证"——没有一处文档或 schema 说明写者仲裁；
• agent.subagent_spawns / subagent_progress 证明父子 Agent 并发是常态——父子对共享状态（如 goals.updates）的写冲突解决策略，本篇未讨论，标 ❓。

一句话：代次栅栏只罩住了可靠卷；DB 行级并发写的仲裁机制，以及父子 Agent 共享状态的冲突策略，是本篇的开放缺口。

当前态实测（10-17，11-04 未复测）：本机 recovery_owners 与 compactions 均为 0 行、runtime_restart_checkpoints count=1——即写作时系统处于「无待恢复工作、无已发生压缩」的稳态，检查点机制在位但未被触发过（或触发后已清理）。这与新会话上下文用量约 43%（00 §16）、未达 272K 压缩线吻合。

---

9. 边界：状态层在本机看不见的部分

• Postgres 本体进程/数据文件位置：本机只见 .postgres-ready 标记、变更信号目录与 muse.db 逻辑通道；物理库在宿主侧还是 cell 内、备份/复制策略如何，本地文件无证据，不作结论；
• 屏障视图之后的全量数据：被 withheld 的推理条目、developer 指令快照、被行过滤的记录（如 §4.3 注），从 Agent 侧原理上不可见，任何「查不到」都不能转写为「不存在」；
• per-artifact app.db：每个 Web artifact 自带的应用库被明确排除在 muse.db 之外，只能经 artifact 声明的 actions/inspect 访问（system prompt 明文）；
• Sentinel 审批库与凭据库：与状态库分离，muse.db 明文不可达；状态库里只留非秘密的生命周期投影（如 spend-request 状态）；
• 服务端权威副本：chat/feed 等域在服务端是否有高于本机的权威状态、fleet 同步的对端实现（只见本机 outbox/水位线一侧），不在本机证据内。

---

附录 A. 逐 schema 表数表（实测：解析 schema.md 求和验证；明细为 10-17 快照）

验证口径（10-17）：schema.md 条目链接去重计数 = 194；references/tables/ 逐表文件数 = 194；分节求和 = 194；三路一致。生成来源迁移集：5af4f2bfdee2b934a53bbcc22602c602ab85059e0ac97ea20137fd299c06036b。11-04 复核（同方法）：条目链接去重 = 196；逐表文件数 = 196；分节数 = 18；三路一致。各 schema 明细未重测，上表明细为 10-17 快照。

附录 B. 本机状态快照（实测，2026-10-17 深夜）