# 记忆系统（智能体用户视角）

英文版：[English](./memory-system.md)

Dominds 的“记忆系统”本质上是一套**上下文工程（context engineering）**：把不同稳定性、不同共享范围、不同执行语义的信息放到合适的载体里，让智能体在长程任务中既能保持速度，也能保持正确率与对人类的透明度。

TL;DR：

- **让对话历史可丢弃**（噪音可以随时清掉）。
- **让关键产物可存活**（清理头脑后仍能继续推进）。
- **让技能成为一等上下文资产**：memory 记住“事实/索引/共识”，skills 固化“何时做、怎么做、边界是什么”的可复用操作能力。
- **实时公开宣告、公开交流（并可追溯）工作进展，达成及时强制协调**：差遣牒 / 团队记忆 / 环境提示，才是跨智能体、多主线并行推进时真正的效率来源。

关键约定：**差遣牒是任务实时协调公告板**。关键决策/当前状态/下一步必须写回 `progress`；硬约束必须写回 `constraints`；不要只留在对话或提醒项里。

相关术语：[dominds-terminology.md](./dominds-terminology.md)

## 目录

- [分层与分类（空间维度）](#分层与分类空间维度)
  - [权限与分工（社会化分工的要义）](#权限与分工社会化分工的要义)
- [分层与分类（时间维度）](#分层与分类时间维度)
  - [A) 长期记忆：把“分工与治理”固定下来](#a-长期记忆把分工与治理固定下来)
  - [B) 中期（任务）记忆：差遣牒是单一真源](#b-中期任务记忆差遣牒是单一真源)
  - [C) 短期记忆：对话历史是工作缓冲，提醒项是工作集](#c-短期记忆对话历史是工作缓冲提醒项是工作集)
- [日常工作流（职场健康）](#日常工作流职场健康)
  - [写到哪里（快速规则）](#写到哪里快速规则)
  - [Memory vs Skills：选型原则](#memory-vs-skills选型原则)

---

## 分层与分类（空间维度）

同一份信息可以按“谁需要看见/共同维护”来分。这个维度与“长期/中期/短期”等时间维度正交，用来避免把团队共识写进个人工作日志，或把个人工作集误当成团队公告板。

- **个体记忆（个人/对话局部）**：
  - `persona` / `knowhow` / `pitfalls`（按成员分配的角色定义）
  - 个人记忆（`personal_memory`）
  - 个人 skills（`.minds/skills/individual/<member-id>/...`）
  - 对话历史（含工具调用与反馈）
  - 提醒项（工作集/工作日志）
- **集体记忆（团队/任务共享）**：
  - rtws 级“环境提示”（`.minds/env*.md`）：用于写清楚“这个工作区的基本事实/运行约束/注意事项”
  - 团队记忆（`team_memory`）
  - 团队共享 skills（`.minds/skills/team_shared/...`；`linkable` 池作为团队管理维护的可复用来源）
  - 差遣牒：同一个差遣牒正常预期会被多个主线对话（不同主理人）共同推进，因此它应被视为“集体记忆”的单一真源

skills 与 memory 同属长期上下文资产，但不是同一种东西：**memory 是事实/索引/共识的存储层；skills 是可复用提示技能与操作规程的执行指导层**。系统会在启动时列出可见 skill 的摘要，模型按需通过 `read_skill` 读取正文；`allowed-tools` 这类上游元数据只作迁移提示，不会自动授予 Dominds 工具权限。团队协作 SOP 一般优先落 skill：它应描述角色协作方式、输入输出、升级条件、同步节奏和验收口径，而不是把当前工作区的具体路径写进主体。

### 权限与分工（社会化分工的要义）

上述“集体记忆”并不意味着“任何智能体都能随意改”。Dominds 的一个核心原则就是**社会化分工**：连“团队治理/团队管理”本身也应被视为一种职能。

- `team_memory` 的维护工具（`add_team_memory` / `replace_team_memory` / `drop_team_memory` / `clear_team_memory`）通常只会配备给**少部分智能体**（团队治理角色）。
- `rtws/.minds/` 目录内容（包括 env 提示等）通常只有配备了 **team_mgmt 工具集**的智能体才有权限更改。
- 当你没有相应权限时，正确动作是：**起草修改提案（内容 + 理由 + 影响面）→ 诉请具备权限的职能智能体合并落地**，而不是把关键约定留在对话里或私有提醒项里。

---

## 分层与分类（时间维度）

按时间尺度记忆可以分三层：长期 / 中期（任务）/ 短期（对话历史）。它与“个体/集体”等空间维度正交：同一条信息既属于某个时间层，也属于某个共享范围。

- **A) 长期记忆（稳定、跨对话生效）**
  - **组织结构分配（静态定义）**：`persona` / `knowhow` / `pitfalls`
  - **动态治理维护（团队共享）**：团队记忆（team memory）
  - **个体智能体自主维护**：个人记忆（individual memory）
  - **可复用技能资产**：个人 / 团队共享 skills（prompt guidance），以及 MCP resource skills
- **B) 中期（任务）记忆（跨对话 course 生效）**
  - **差遣牒固定三样（自动注入）**：`goals` / `constraints` / `progress`
  - **差遣牒附加章节（按需召回）**：固化的 `bearinmind/`（`contracts` / `acceptance` / `grants` / `runbook` / `decisions` / `risks`）；其他章节按需扩展（详见 [encapsulated-taskdoc.zh.md](./encapsulated-taskdoc.zh.md)）
- **C) 短期（对话历史）记忆（高噪音、可丢弃）**
  - **智能体拉取**：传统对话历史、工具调用及反馈
  - **环境推送**：后台进程状态、MCP 租用等提醒项
  - **智能体自主增删改**：部分提醒项（工作集/工作日志）
  - **智能体自主头脑清理**：`clear_mind`

### A) 长期记忆：把“分工与治理”固定下来

长期记忆的关键词是：**稳定**、**可复用**、**跨对话**。它们要么定义“我是谁/我负责什么”，要么定义“我们团队怎么做事”。

#### 1) persona / knowhow / pitfalls：组织结构分配（静态定义）

这三类文档用于把一个智能体“定位”成团队里的某个角色：

- `persona`：身份与风格（口吻、工作方式、职责边界、偏好约束）
- `knowhow`：偏正向的稳定知识与经验沉淀（你擅长什么、哪些方法已验证有效、你的工具观与安全观）
- `pitfalls`：偏负向的历史教训与避坑规则（哪些坑不要再踩、哪些信号意味着风险、哪些路径更稳）

它们的作用不是记录任务进度，而是让分工结构长期有效：减少反复解释、减少误解、减少“临时拼人格”的随机性。

#### 2) 团队记忆（team memory）：动态治理维护（团队共享）

团队记忆只写**真正稳定且值得共享**的东西，例如：

- 仓库约定（命名口径、目录契约）
- 架构决策与不变量（为什么这么做、哪些不能做）
- “我们在这里如何跑测试/如何上线”的可复用步骤
- 跨智能体协作契约（例如：哪些信息必须写进差遣牒，哪些必须写进团队记忆）

工具：

- `add_team_memory` / `replace_team_memory` / `drop_team_memory` / `clear_team_memory`

#### 3) 个人记忆（individual memory）：个体智能体自主维护

个人记忆是“我如何高效工作”的长期资产，尤其是一个**职责域 rtws 索引**：

- 你负责的关键文档/代码的**精确路径**
- 对应的最小关键事实（入口点、关键符号、局部契约）

这样你在职责范围内可以尽量做到“0 次 ripgrep 就能开工”。同时有一个硬约束：**必须保持准确**——一旦你改了相关文件或发现记忆过期/冲突，立刻用 `replace_personal_memory` 更新。

工具：

- `add_personal_memory` / `replace_personal_memory` / `drop_personal_memory` / `clear_personal_memory`

关键提示：

- 不要用通用文件工具去读/写/列目录 `.minds/memory/**`（会被硬拒绝）；个人记忆应通过上述个人记忆工具管理。
- 个人记忆会自动隔离到 `.minds/memory/individual/<member-id>/...`，因此 `path` 不应包含你的成员 id（不要写 `<member-id>/...`）。
- 若你当前没有任何个人记忆条目，直接 `add_personal_memory` 即可：目录会由系统自动创建。

#### 4) Skills：可复用操作能力（提示技能资产）

skills 的关键词是：**程序化思路**、**可复用操作路径**、**触发条件与边界**。它回答的是“遇到某类任务时，应该怎样做”，而不是“这个工作区当前有哪些事实”。

常见形态：

- 个人 skill：`.minds/skills/individual/<member-id>/<skill-id>/`
- 团队共享 skill：`.minds/skills/team_shared/<skill-id>/`
- MCP resource skill：由 MCP resource 暴露的虚拟 skill

建议写入 skill 的内容：

- 跨工作区可复用的调试/审查/设计/验收套路
- 团队协作 SOP、职责切分、交接/升级/同步流程、验收与回退口径
- 某类任务的执行步骤、检查清单、失败恢复策略
- 何时适用、何时不适用、需要哪些权限/工具/输入的边界说明

不建议写入 skill 的内容：

- 当前 rtws 的精确路径、文件索引、架构事实、临时状态：这类内容更适合 `personal_memory` / `team_memory` / `.minds/env*.md` / Taskdoc
- 需要准实时同步的任务状态、下一步、阻塞：进入 Taskdoc `progress`
- 需要脚本、专有工具、MCP、外部二进制或稳定执行能力的内容：应升级为 Dominds app / toolset / teammates contract，而不是只停留在 Markdown skill

一个实用拆分法：**工作区关联强的事实进 memory；独立于工作区内容的操作方法进 skill**。如果一个经验同时包含二者，就拆开：把通用步骤写成 skill，把当前仓库的路径、命令入口、局部契约写进 memory 或 env notes，并在 skill 中说明需要先读取相应 memory/env 信息。若某个 SOP 看起来“写满了路径”，先尝试把它抽象成可泛指的协作概念；路径只保留为绑定信息，不要让它吞掉 SOP 主体。

### B) 中期（任务）记忆：差遣牒是单一真源

差遣牒的关键词是：**任务契约**、**团队共享**、**可持续推进**。它回答三个问题：我们要达成什么、不能做什么、目前进展到哪。

#### 固定三样（自动注入）

- `goals`：完成时必须为真的内容
- `constraints`：硬规则（安全/风格/流程/合规）
- `progress`：精炼进展（关键决策、当前状态、下一步）

#### 章节语义约定

- `progress` 是全队共享的里程碑公告牌：记录关键决策、当前状态与下一步；不是流水账，不是个人工作记录。
- `goals` / `constraints` 是较稳定的任务契约：每次更新都要保留仍然有效的他人条目，不要把共享约定误改成个人笔记。

#### 使用要点（只保留最重要的约束）

- 把 `goals / constraints / progress` 当作**团队共享公告板**，不是个人草稿本。
- `progress` 只写“足以让下一程继续推进”的精炼状态；每次更新都应保持“当前全貌快照”完整可扫读；高频细节放到提醒项（工作集）。
- 不要把长工具输出塞进差遣牒：要么提炼成结论/证据，要么放到提醒项里做精炼摘录。

差遣牒附加章节（非自动注入）与 `*.tsk/` 封装语义，详见：[encapsulated-taskdoc.zh.md](./encapsulated-taskdoc.zh.md)

### C) 短期记忆：对话历史是工作缓冲，提醒项是工作集

短期记忆的关键词是：**高噪音**、**短生命周期**、**随时可清**。它服务于“现在这一小段推进”，而不是长期可复用。

#### 1) 智能体拉取：对话历史、工具调用与反馈

这些内容用于当下决策，但天然会膨胀、混杂噪音、并迅速过时。正确做法是：

- 只把“结论 + 下一步”提炼进差遣牒 `progress`
- 把确实值得花 token 保留的细节，提炼进少量提醒项

永远不要把“我之前看过/跑过”当作可持久依赖的事实。

#### 2) 环境推送：系统提醒项（后台进程 / MCP 租用等）

有一类提醒项来自运行时环境（例如后台进程状态、MCP 租用/到期等）。它们更像信号灯：

- 你应该阅读并据此调整行为
- 若它没有实质改变当前判断/计划/风险，就禁止做任何用户可见回应（禁止写“静默吸收”“已收到”等占位语句）
- 若它确实改变了当前判断/计划/风险，也无需单独回一条“收到”；只需在下一条有实质内容的回复中体现
- 但它们的生命周期通常由系统管理（自动更新/自动清理），不要把它们当成个人工作日志
- 在消息语义上，这类提醒应视为**系统提示**：通常落在 `role=user` 侧，并带显眼头标（如 `【系统提示】`），避免与个人工作提醒混淆

#### 3) 智能体自主增删改：工作提醒项（工作集/工作日志）

提醒项是你为自己维护的“超小工作集”：它会在每次生成时注入上下文，并能跨 `clear_mind` 保留。

在消息语义上，默认提醒项包装注入上下文时仍应视为**运行时系统提示**：Dominds 内置和 fallback 包装落在 `role=user` 侧，带 `【系统提示】` 头标，并使用第二人称口吻（例如“你设置了提醒项，让运行时系统提醒你：……”）。理想情况下它们应是 `role=environment`，但当前 LLM API 普遍不支持，所以默认运行时包装用 `role=user` 承载；自定义 reminder owner 仍按自身契约决定输出 role。提醒项投影应插入在真实对话消息之前，并使用成对 header/footer；footer 只说明该 header/footer 之间的提醒项是系统提醒、并非用户指令，避免误伤对话历史中的真实用户指令。

建议：

- 总量保持 1–3 条；能原地更新就不要新建
- 每条都要能证明 token 成本：不再影响决策就删除

工具：

- `add_reminder` / `update_reminder` / `delete_reminder`（部分系统提醒项由特定工具托管，需用托管工具更新）

推荐结构（单条工作提醒项）：

- 最后更新：时间戳
- 当前在做什么：1–3 条
- 冻结的关键决策：1–5 条
- 下一步：3–8 条可操作步骤
- 不要忘记：1–3 条高风险点

#### 4) `clear_mind`：自主头脑清理（启动新一程）

当对话/工具输出噪音开始**影响你的注意力与判断力**（造成误判或低质量决策）时，正确动作不是“硬扛”，而是：

1. 提炼（差遣牒 + 提醒项）
2. `clear_mind`

`clear_mind` 的设计目标就是让清理变得廉价：对话历史可以清掉，但关键产物（差遣牒、记忆、提醒项等）可以存活，下一程还能继续跑。

---

## 日常工作流（职场健康）

> 饭要一口一口吃，路要一步一步走

智能体日常工作的目标不是“多写文档”，而是建立一个低成本、可复用的节拍：**推进一小步 → 实时宣告进展 → 清噪 → 继续推进**。

### 默认节拍（每个小步闭环）

1. **推进一小步**：用工具完成一个可验证的最小进展（必要时再拉历史/跑命令/读文件）。
2. **公开宣告进展（集体记忆）**：
   - 把关键决策、当前状态、下一步写进差遣牒 `progress`
   - 新出现的硬约束写进 `constraints`（不要只写在提醒项/对话里）
   - 稳定约定沉淀到团队记忆；rtws 的基本事实/运行约束写进 `.minds/env*.md`
3. **维护个人工作集（个体记忆）**：把仍在高频影响决策的细节压缩到少量提醒项（1–3 条，优先原地更新）。
4. **清噪（必要时）**：当噪音开始影响注意力与判断力（造成误判/低质量决策），先提炼再 `clear_mind`，开启新一程。

> 权限提示：如果你没有 `team_memory` 或 team_mgmt 权限，不要“跳过公开宣告”。请把建议写成可合并的补丁内容，然后诉请具备权限的治理/团队管理职能智能体更新 `team_memory` 或 `.minds/**`。

### 写到哪里（快速规则）

- **差遣牒 `progress`**：关键决策、当前状态、下一步（团队协作的“公告板”）
- **差遣牒 `constraints`**：硬规则/安全/合规/风格（必须被所有主线及时看到）
- **团队记忆 `team_memory`**：稳定的团队约定与不变量（值得长期复用）
- **环境提示 `.minds/env*.md`**：rtws 的基本事实、运行约束、注意事项（让人类与所有智能体对齐同一环境）
- **个人记忆 `personal_memory`**：个人偏好 + 职责域 rtws 索引（保持准确）
- **skills**：可复用操作指引、检查清单、触发条件与边界（portable procedure，不是事实仓库）
- **提醒项**：短期高频细节（工作集/工作日志，随时可删）
- **对话历史/工具输出**：默认可丢弃；需要留的只留“精炼摘录”，不要长期背着原始转储

### Memory vs Skills：选型原则

优先问四个问题：

1. **它是否强依赖当前工作区内容？** 精确路径、符号、接口事实、仓库约定、当前 rtws 运行约束，优先 memory/env；跨工作区可复用的方法，优先 skill。
2. **它是事实还是做法？** “X 文件负责 Y”是 memory；“做 X 类评审时按 A/B/C 检查”是 skill。
3. **它需要团队共享还是个人携带？** 多人都应遵守的稳定事实进 `team_memory`；团队协作 SOP 与团队级操作规程通常进团队共享 skill。只服务某成员的入口地图进 `personal_memory`，只服务某成员的操作偏好进个人 skill。
4. **它是否需要真正的执行能力？** 如果需要脚本、权限、MCP、外部二进制、稳定 UI/API 能力，就不要只写 skill；应设计 app/toolset/teammates contract，并在 skill 里只保留调用与判断规程。

设计上的额外考量：

- **上下文预算**：memory 应短小、精确、常更新；skill 可以较长，但摘要要能帮助模型决定是否 `read_skill`。
- **过期成本**：容易随仓库变化而过期的事实不要塞进 skill；否则 skill 会成为隐蔽的陈旧知识源。
- **可审计性**：团队共享 skill 和 team memory 都是团队资产，应由具备治理权限的角色维护；个人资产也要在发现过期时立即更新。
- **语言与语义**：涉及用户可见语义时，遵守项目 i18n 规则；中文语义仍是基准。

### 吃紧/告急：一旦发作就先止血

当上下文健康进入**吃紧/告急**（见 [context-health.zh.md](./context-health.zh.md)）时，不要继续“堆输入”：

1. 停止扩展新分支与新输入
2. 把必须共享的进展写回差遣牒/团队记忆/环境提示
3. 把个人仍需要的细节压缩进提醒项
4. `clear_mind` 开新一程
