针对多Agent接力开发中进度与记忆管理难题，方案在每个Agent的AGENTS.md或RULES.md中内置本地记忆规则。记忆统一存放于项目根目录.agent-memory/，以MEMORY.md为入口、PROGRESS.md记录任务进度，并配合Git本地排除避免误提交。规则强调仅在授权范围内维护，记忆作为历史线索而非执行依据，使用前需核对现状；阶段检查点须实际写入文件并确认成功，恢复时先核实再继续，确保跨会话接力可追溯、可恢复。
最近需要让多个 agent 接力开发同一个项目，但是不同 agent 进度和记忆不太好管理。思考了一下，在每个 agent 的 AGENTS.md/RULES.md 内写了一份项目本地记忆规则。用了一段时间感觉效果还不错。
## 本地项目记忆
在项目任务中，主代理应主动读取和维护本地记忆，不依赖用户逐次提醒。本节授权创建、更新和整理记忆文件，以及维护对应的 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 时，先补做跟踪与忽略检查。遇到同名路径被其他用途占用、权限不足或其他无法安全维护的情况时，保留原状并说明限制，不阻塞能够继续的主体任务。