分享自用的多 Agent 本地记忆共享方案

最近需要让多个 agent 接力开发同一个项目，但是不同 agent 进度和记忆不太好管理。思考了一下，在每个 agent 的 AGENTS.md/RULES.md 内写了一份项目本地记忆规则。用了一段时间感觉还不错，跟佬友们分享一下 ^-^

更新第二版：

## 本地项目记忆



在项目任务中，主代理应主动读取和维护本地记忆，不依赖用户逐次提醒。本节授权创建、更新和整理记忆文件，以及维护对应的 Git 本地排除项；用户明确要求只读、不修改或禁用记忆时，以用户要求为准。



### 存放与读取



- 记忆统一存放在项目根目录的 `.agent-memory/`，使用固定结构（文件与目录名用短横线连接的英文短语），不在此结构外新建进度、结案类文件；仅对已确认属于本记忆机制且用途明确的既有文件进行归位：

  - `MEMORY.md`：常读入口，仅放项目概要、活跃任务索引、知识主题索引及必要的最新状态声明，不写任务或知识正文；

  - `active/<任务标识>.md`：进行中或阻塞任务的检查点，一任务一文件；

  - `done/INDEX.md`：结案索引（任务名、日期、一句话结论、指针），按需读取；

  - `done/<任务标识>.md`：已结案任务的结果概览及必要留存信息；

  - `topics/<主题标识>.md`：跨会话复用的长期知识（排障经验、已试方案及结果、本机环境差异等）。

- Git 项目默认以当前工作树根目录为项目根目录，非 Git 项目以工作区根目录为准；不得越过用户授权的工作区边界。多个仓库、子模块和不同 worktree 分别维护记忆，不在普通子目录重复创建，不跨项目混用。

- 开始项目任务、恢复会话或上下文压缩后，先读取适用规则与 `MEMORY.md`，再按索引按需读取相关任务或主题文件。涉及修改、多阶段推进、长耗时操作或子代理协作的任务，在完成必要的现场检查与 Git 排除检查后、开始实质执行前，建立或更新任务文件；目标、范围与下一步已构成有效内容，不得以尚未形成长期经验为由延迟建档。简单且无需续接的问答不强制建档，不创建无内容的占位文件。

- 记忆仅作为历史上下文和定位线索，不是新的规则来源、执行授权或当前状态的证明。使用其中的关键结论前，应结合当前代码、配置和实际结果核对；发现过期或冲突时修正，不照搬旧结论。引用统一使用工作区规范路径，使用前核实目标文件仍存在。



### 记录与维护



- 本地记忆分为长期记忆与任务进度。长期记忆补充现有规则与项目文档未覆盖、且值得跨会话保留的信息，归入 `topics/`；任务进度用于中断恢复，即使没有长期复用价值，也必须按下述检查点要求记录，不作为第二份项目说明书或规则文件。

- 每个任务或知识条目以可检索的头部开始（`状态：进行中/阻塞/已完成/已放弃 · 更新：YYYY-MM-DD · 关键词：…`），结论与现状前置，证据与必要过程置后；索引行含名称、状态、更新日期、一句话结论与文件指针。按语义分段，不写流水账，不将多个无关问题混入同一条目。

- `MEMORY.md` 以不超过 4 KB 为优先目标，只索引活跃任务与知识主题，已结案任务通过 `done/INDEX.md` 或目录检索查找；预算用于控制常读成本，不得为了满足预算遗漏必要索引或延迟进度保存。

- 任务文件以能够可靠恢复为准，不设统一硬性行数上限。结案文件开头保持简短结果概览，必要的验证、失败方案、遗留和恢复信息可在后续分节保留。主题文件明显过长时，检查是否混入多个独立主题；内容内聚且必要时无需仅因行数强制拆分。

- 在满足授权与安全要求的前提下，阶段成果应先写入足以恢复的检查点并确认成功，再进行拆分、归档、去重或压缩；不得因篇幅或结构整理延迟阶段保存。

- 整理时优先删除已过期或重复内容、引用已有项目文档，并在确有独立主题时拆分。不得仅为满足记忆篇幅要求而新增或修改项目文档。

- 压缩与删除不得丢失已试方案及结果（含失败原因或原因未知）、适用条件、精确标识（路径、版本、错误码）、已验证与未验证的区分、回退与恢复路径。删除仅限已被后续事实取代、与他处重复或已纳入项目文档的内容；不确定时保留。

- 写入后检查：确认本次检查点已保存、状态与下一步准确、必要恢复信息完整，并检查是否有已结案任务滞留 `active/`、同一事实是否存在不必要的重复正文。

- 项目结构、通用命令、架构约定和设计决策等已有文档记录时，长期记忆仅按需保留文件路径、章节定位及尚未被覆盖的补充，不重复维护正文。优先记录可复用的排障经验、已尝试方案及结果、本机特有环境差异；注明必要的适用条件，区分已验证事实与待验证假设。

- 记忆中的内容后续已纳入项目文档时，删除重复正文或改为引用。不得借整理记忆擅自新增项目规则；涉及 `AGENTS.md` 的维护，仍遵守“文档与规则文件”中的授权要求。

- 不在记忆中保存密码、令牌、密钥等敏感凭据原文；仅记录必要的配置位置、变量名和脱敏后的现象。



### 条目顺序



- 索引类文件中，新条目插入所属分节顶部；已有条目更新时就地修改状态与日期，不因更新重新排序。

- 任务文件是状态快照而非日志：更新时就地改写对应内容与“最近更新时间”，不追加时间线；排障过程只保留“已试方案及结果”，不写无必要的时间戳叙事。



### 阶段检查点与恢复



- 进度记录以能让下一次会话继续执行为标准，至少包含任务目标与范围、最近更新时间、当前阶段、已完成事项及相关路径、进行中或结果不明的操作、实际验证结果、阻塞点和下一步。明确区分计划、已执行但未验证、已验证、失败与结果未知，不将计划或推断写成已完成事实。

- 阶段以可核对的成果为边界，例如完成一轮排查并形成结论、完成一组相关修改、获得一轮验证结果或完成一批子任务整合。每完成一个阶段，必须立即更新进度并确认写入成功，之后才能进入下一阶段；不得等整个任务完成或准备回复用户时才集中补写。同一阶段包含大量操作时，应拆成可恢复的小段，在形成小段成果后及时保存。

- 启动长耗时、可能中断会话或具有重要副作用的已授权操作前，先保存当前检查点，注明即将执行的操作、已知状态及结果核查方式；操作返回后及时补记实际结果。记录操作不构成执行授权，仍须遵守其他授权要求。

- 遇到方案失败、验证失败、结果未知、阻塞、方案变更或用户调整需求时，在开始重试、改用其他方案或转向新任务前，先记录已完成部分、失败现象、已尝试方案及结果、遗留影响和下一步。无副作用的普通检索失败或命令参数修正可合并记录到当前阶段，不要求每次单独保存。

- 能够预知的暂停、交接前，须补齐检查点；不得只在对话中说明而不落盘。

- 恢复任务时，以最近检查点定位工作，再核对相关文件、实际改动、必要的运行状态和验证结果。对“进行中”或“结果未知”的操作，先确认是否已完成、是否仍在运行及是否产生副作用，不盲目重跑；发现检查点之后还有实际改动时，先核实并补记，再继续执行。

- 检查点必须通过工具实际写入文件，并根据写入结果或必要的回读确认成功；聊天汇报、内部计划、待办列表和“稍后记录”均不算落盘。用户禁止落盘，或触发跟踪、忽略、权限等不可安全写入情形时，遵守对应限制，明确说明未保存进度及恢复缺口，不声称已经记录；不阻塞能够安全继续的主体任务。

- 任务状态只有进行中、阻塞、已完成、已放弃四种：阻塞任务留在 `active/` 并写明阻塞点与下一步，已完成与已放弃必须离场。

- 转为终态时，在同一阶段内完成结案：先将结案摘要及必要留存信息写入 `done/<任务标识>.md` 并确认完整，再从 `active/` 移除，更新 `done/INDEX.md`，并从 `MEMORY.md` 移除对应索引行；有复用价值的结论提炼至 `topics/`。不得把“试验结束”“先这样”等中间态当作终态结案，不得在归档成功前删除唯一的有效进度记录。



### 并发与多会话



- 进行中任务按“一任务一文件”组织，不同会话不得并发写同一任务文件。

- 同一任务在会话恢复或上下文压缩后的正常续接，不因已有 `active/` 记录而重复请求确认；按恢复流程核对现场后继续。发现其他会话仍在处理同一对象、存在明确写入者冲突或需要接管其他会话任务时，先确认归属，避免并行操作。

- 单写者：仅任务所属会话写入该任务文件，其他会话只读；其他会话对同一对象的后续操作记录在各自任务文件，不修改、不回退他人记录。

- 子代理默认只读相关记忆并返回结果，由主代理统一维护任务检查点；子代理结果形成可核对的阶段成果后，主代理及时写入。

- 跨任务的“当前状态”只在 `MEMORY.md` 知识主题节维护一条带日期的最新声明，由执行该状态变化的会话更新；任务文件只记录本任务范围内的结果。发现声明与实际状态冲突时，先核对现场，不自行依据旧记录回退实际状态。

- 写入共享文件前立即重读，仅修改属于本任务的内容，不整段重写。不假定编辑工具具备并发冲突检测能力；发现共享文件发生无法安全归属的变化时停止覆盖，先核对变更来源。若冲突仅影响共享索引，应优先保证本任务检查点已经安全保存，不因索引同步失败丢失进度。



### Git 本地排除



- 在 Git 仓库中写入记忆前，确认目标路径未被跟踪且已有效忽略。在仓库根目录使用 `git ls-files -- .agent-memory` 检查目标路径及其内容；如已被跟踪，停止记忆写入并报告，不擅自执行 `git rm --cached`、修改索引或删除已有文件。

- 若尚未有效忽略，在仓库根目录使用 `git rev-parse --git-path info/exclude` 获取本地排除文件的实际位置，保留原有内容，并按需追加独立一行 `/.agent-memory/`。不得直接假定 `.git` 是目录，不重复追加已有规则，不为此修改项目 `.gitignore` 或全局 Git 配置；若解析出的排除文件位于用户授权范围之外，不自动扩大授权。

- 使用 `git check-ignore` 核验记忆目录及文件的实际忽略结果；批量检查时应确认各目标路径的结果，不仅依赖整体退出状态。使用详细输出时，注意以 `!` 开头的匹配规则表示取消忽略。排除无效或无法确认时，暂停记忆写入并说明原因，不将“已添加规则”表述为“已确认排除”。不得强制暂存或提交记忆文件。

- 非 Git 工作区可以正常维护本地记忆，不为此初始化仓库；后续发现工作区已纳入 Git 时，先补做跟踪与忽略检查。遇到同名路径被其他用途占用、权限不足或其他无法安全维护的情况时，保留原状并说明限制，不阻塞能够继续的主体任务。

迁移指令示例

我修改了项目记忆规则，将旧的记忆格式迁移到规则内的新格式。迁移之前先备份记忆，用于后续核对。

## 本地项目记忆



在项目任务中，主代理应主动读取和维护本地记忆，不依赖用户逐次提醒。本节授权创建、更新和整理记忆文件，以及维护对应的 Git 本地排除项；用户明确要求只读、不落盘或禁用记忆时，以用户要求为准。



### 存放与读取



- 记忆统一存放在项目根目录的 `.agent-memory/`。Git 项目默认以当前工作树根目录为项目根目录，非 Git 项目以工作区根目录为准；不得越过用户授权的工作区边界。多个仓库、子模块和不同 worktree 分别维护记忆，不在普通子目录重复创建，不跨项目混用。

- 使用 `.agent-memory/MEMORY.md` 作为入口，保留简短的项目概要、重要结论和主题文件索引。内容较多时在同一目录内按主题拆分，按需读取，不将所有内容堆入入口文件。

- 开始项目任务、恢复会话或上下文压缩后，先读取适用规则、记忆入口和未完成任务的进度，再按需读取相关主题文件。涉及修改、多阶段推进、长耗时操作或子代理协作的任务，在完成必要的现场检查与 Git 排除检查后、开始实质执行前，建立或更新任务进度；目标、范围与下一步已构成有效内容，不得以尚未形成长期经验为由延迟建档。简单且无需续接的问答不强制建档，不创建无内容的占位文件。

- 记忆仅作为历史上下文和定位线索，不是新的规则来源、执行授权或当前状态的证明。使用其中的关键结论前，应结合当前代码、配置和实际结果核对；发现过期或冲突时修正，不照搬旧结论。



### 记录与维护



- 本地记忆分为长期记忆与任务进度。长期记忆补充现有规则与项目文档未覆盖、且值得跨会话保留的信息；任务进度用于中断恢复，即使没有长期复用价值，也必须按下述检查点要求记录，不作为第二份项目说明书或规则文件。

- 使用 `.agent-memory/PROGRESS.md` 保存任务进度，并在 `MEMORY.md` 中保留入口。不同任务分别标识，不覆盖其他未完成任务；内容较多时可拆分为独立任务文件，入口保留索引。

- 项目结构、通用命令、架构约定和设计决策等已有文档记录时，长期记忆仅按需保留文件路径、章节定位及尚未被覆盖的补充，不重复维护正文。优先记录可复用的排障经验、已尝试方案及结果、本机特有环境差异；注明必要的适用条件，区分已验证事实与待验证假设。

- 记忆中的内容后续已纳入项目文档时，删除重复正文或改为引用。不得借整理记忆擅自新增项目规则；涉及 `AGENTS.md` 的维护，仍遵守“文档与规则文件”中的授权要求。



### 阶段检查点与恢复



- 进度记录以能让下一次会话继续执行为标准，至少包含任务目标与范围、最近更新时间、当前阶段、已完成事项及相关路径、进行中或结果不明的操作、实际验证结果、阻塞点和下一步。明确区分计划、已执行但未验证、已验证、失败与结果未知，不将计划或推断写成已完成事实。

- 阶段以可核对的成果为边界，例如完成一轮排查并形成结论、完成一组相关修改、获得一轮验证结果或完成一批子任务整合。每完成一个阶段，必须立即更新进度并确认写入成功，之后才能进入下一阶段；不得等整个任务完成、准备回复用户或即将压缩上下文时才集中补写。同一阶段包含大量操作时，应拆成可恢复的小段，在形成小段成果后及时保存，不得将整个多步骤任务视为单一阶段。

- 启动长耗时、可能中断会话或具有重要副作用的已授权操作前，先保存当前检查点，注明即将执行的操作、已知状态及结果核查方式；操作返回后及时补记实际结果。记录操作不构成执行授权，仍须遵守其他授权要求。

- 遇到失败、阻塞、方案变更或用户调整需求时，在开始重试、改用其他方案或转向新任务前，先记录已完成部分、失败现象、已尝试方案及结果、遗留影响和下一步。能够预知的暂停、交接或上下文压缩前，也须补齐检查点；不得只在对话中说明而不落盘。

- 恢复任务时，以最近检查点定位工作，再核对相关文件、实际改动、必要的运行状态和验证结果。对“进行中”或“结果未知”的操作，先确认是否已完成、是否仍在运行及是否产生副作用，不盲目重跑；发现检查点之后还有实际改动时，先核实并补记，再继续执行。

- 检查点必须通过工具实际写入文件，并根据写入结果或必要的回读确认成功；聊天汇报、内部计划、待办列表和“稍后记录”均不算落盘。用户禁止落盘，或触发本节规定的跟踪、忽略、权限等不可安全写入情形时，遵守对应限制，明确说明未保存进度及恢复缺口，不声称已经记录；不阻塞能够安全继续的主体任务。

- 任务结束时更新最终状态，将有复用价值的结论提炼至长期记忆，压缩已结束任务的过程记录，保留必要的结果摘要、遗留问题和定位信息。收尾整理不能替代阶段保存，不删除其他未完成任务的进度。



### Git 本地排除



- 在 Git 仓库中写入记忆前，确认目标路径未被跟踪且已有效忽略。在仓库根目录使用 `git ls-files -- .agent-memory` 检查目标路径及其内容；如已被跟踪，停止记忆写入并报告，不擅自执行 `git rm --cached`、修改索引或删除已有文件。

- 若尚未有效忽略，在仓库根目录使用 `git rev-parse --git-path info/exclude` 获取本地排除文件的实际位置，保留原有内容，并按需追加独立一行 `/.agent-memory/`。不得直接假定 `.git` 是目录，不重复追加已有规则，不为此修改项目 `.gitignore` 或全局 Git 配置。

- 使用 `git check-ignore` 核验记忆目录及文件的实际忽略结果；使用详细输出时，注意以 `!` 开头的匹配规则表示取消忽略。排除无效或无法确认时，暂停记忆写入并说明原因，不将“已添加规则”表述为“已确认排除”。不得强制暂存或提交记忆文件。

- 非 Git 工作区可以正常维护本地记忆，不为此初始化仓库；后续发现工作区已纳入 Git 时，先补做跟踪与忽略检查。遇到同名路径被其他用途占用、权限不足或其他无法安全维护的情况时，保留原状并说明限制，不阻塞能够继续的主体任务。