agent-memory

Agent Memory Skill

将持久化的项目记忆作为可审阅的 Markdown 保存在代码仓库中。任何能读取文件的 Agent 都可以跨会话读取和更新相同的 .agent-memory/ 文件。

设计原则

原则	实践
开放文件	将记忆保存为带 YAML frontmatter 的 Markdown 文件，可使用任意编辑器或能读取文件的 Agent 读取和编辑。
共享入口	将 AGENTS.md 作为权威指令文件；客户端专用文件只保留简短的指引。
与原生记忆共存	将供应商自动记忆视为机器本地临时内容，将 .agent-memory/ 视为有意维护、可跨 Agent 共享且可审阅的信息源；不要覆盖或重复保存原生存储内容。
生命周期管理	使用分类目录、expires 元数据、maintain 和 sync，让记忆保持最新，而不是不断堆积无用信息。
不含机密	保存项目知识和决策，不保存凭据、私钥、令牌或敏感个人数据。

---

命令

关键字	操作	描述
init	初始化	搭建 .agent-memory/、README、索引和 AGENTS.md，并仅为已在使用的 Agent 创建指针文件
migrate	迁移	检测并将旧结构（CURSOR.md、扁平文件、INDEX.yaml）迁移为记忆格式 v2.1
build	构建	扫描项目，并根据现有文档自动生成初始记忆文件
save	保存	将当前会话中获得的经验记录到记忆中
maintain	维护	精简内容、移除过时信息、修复索引、清理旧会话日志
sync	同步	协调当前工作区中已有的记忆文件，并保存当前会话内容
status	状态	只读健康检查——文件数量、过时情况、同步状态

根据明确的请求推断操作；不要求用户使用字面命令关键字。例如，“记住我们选择 SQLite 的原因”对应 Save；“协调这些记忆文件并记录我们的决定”对应 Sync。仅当预期操作或必需输入仍不明确时，才提出一个聚焦的问题。保留只读请求的性质：引导入门或审阅现有记忆，并不意味着可以重建或保存记忆。

进行开发者交接时，阅读索引和相关条目，总结当前决策与未决问题，并注明对应文件。将提案保留为提案。仅凭时间戳较新不能解决相互冲突的决策；应检查其依据和审核状态，若已接受的方向仍不明确，则提出询问。只有在已确认替代关系时才记录 supersedes。

跨代码仓库工作时，使用可访问的参考资料，并在相关时注明修订版本，以了解所属项目的决策。只总结本地所需的背景；指出无法访问的信息来源，不要臆造其内容。针对一个代码仓库的请求，并不授权修改另一个代码仓库。

直接在对话中展示记忆文件，而不是在外部编辑器中打开：Markdown 正文不含 YAML frontmatter；YAML、JSON 和纯文本则放在带围栏的代码块中。

评估清单

使用以下问题选择操作，然后继续执行，不要收集不必要的信息：

1. .agent-memory/ 是否已存在？它使用什么结构或版本？
2. 哪项操作符合请求：init、migrate、build、save、sync、maintain 还是 status？
3. 已有哪些指令文件或指针文件？它们是否指向 AGENTS.md？哪些供应商原生记忆存储必须保持不变？参见 references/agent-pointers.md。
4. 哪些项目文档可用于生成记忆，而无需逐字复制？
5. 这些记忆是本地/私有的，还是旨在通过 git 共享？

操作：初始化

从头搭建 .agent-memory/ 系统。

覆盖保护： 创建或更改 AGENTS.md、.agent-memory/index.yaml、.agent-memory/README.md 或 references/agent-pointers.md 中列出的任何指针文件之前，先检查是否已存在文件并保留其内容。如果目标文件已存在且不是兼容的精简指针文件，请暂存拟议的替换内容并在覆盖前征求同意。报告每个保留、创建或更改的文件。

记忆格式 v2.1 — 入口文件

project/
├── AGENTS.md          # Canonical shared instructions
└── .agent-memory/     # Reviewable project memory

关键点： AGENTS.md 是共享的事实来源。仅为项目已在使用的 Agent 添加精简指针文件；具体方案见 references/agent-pointers.md。切勿将共享指令放入仅供某个供应商使用的目录。以只读方式检测原生记忆／规则位置并报告；不得擅自迁移或覆盖。

步骤

1. 创建目录： 在 .agent-memory/ 下创建 user/、feedback/、project/、decisions/、context/、conventions/、references/、sessions/。
2. 创建文件： 创建 .agent-memory/README.md（系统规范）、.agent-memory/index.yaml（按 索引格式创建空的 [] 注册表）以及 AGENTS.md（规范的共享指令）。仅为已在使用的 Agent 创建指针文件，并遵循 references/agent-pointers.md。保留现有兼容的索引格式及其中的条目；不要将其重置为 []。
3. 完善 AGENTS.md： 将每个占位符替换为项目的实际结构和规则。加入会话开始时的加载指令，使下一个 Agent 能读取索引及相关条目。遵循覆盖保护，保留现有的实质性指令；未经批准，不要直接替换它们，而应提出新增方案。完成标准：不再含有 TODO 或占位符标记，并且已加入加载指令，或已报告待审批事项。
4. 检查注册表并报告创建或保留的内容。保存条目或请求执行单独的 Build 操作之前，空的 [] 索引就是正确状态；初始化时不要编造项目记忆。完成标准：新注册表可解析为空列表，或现有注册表保留原有条目；并且已配置下一会话的发现机制，或已明确报告其待审批状态。

---

操作：迁移

检测并将旧版结构迁移至 memory format v2.1。

旧结构	新结构	操作
根目录下的 CURSOR.md	AGENTS.md + 精简的 .cursor/rules/index.mdc 指针文件	将共享内容合并到 AGENTS.md；根据 agent-pointers.md 创建指针文件；将旧文件保留为 CURSOR.md.migrated
INDEX.yaml（大写）	index.yaml（小写）	重命名
扁平的 {type}--{topic}.md	{type}/{topic}.md	移入目录
summary: frontmatter	description: frontmatter	重命名字段
包含完整指令的 CLAUDE.md（没有 AGENTS.md）	AGENTS.md + 精简的指针文件	提升为 AGENTS.md；指针文件的编写方法见 agent-pointers.md

**步骤：**扫描上述每种旧结构 → 保留现有内容 → 仅执行已确认的迁移 → 将共享指令移入 AGENTS.md，然后根据 references/agent-pointers.md 将剩余客户端文件改写为精简指针文件 → 使 index.yaml 与文件系统保持一致 → 报告变更内容。完成条件：每项已确认的迁移都有备份或 .migrated 文件，共享指令仅保留在 AGENTS.md 中，且索引与文件系统之间没有差异。

**迁移保护：**重命名、移动和改写指针文件都具有破坏性。重命名 CURSOR.md、INDEX.yaml 或替换指令文件之前，应先展示计划中的源路径和目标路径并征求确认，除非文件为空或已是完全一致的自动生成指针文件。移动内容时始终保留备份或 .migrated 文件。

---

操作：构建

扫描项目，并根据现有文档自动生成初始记忆文件。

1. 扫描文档：*.md、package.json、pyproject.toml、Cargo.toml、CLAUDE.md、AGENTS.md、*.yaml 配置文件、.env.example
2. 提炼每个来源：概览 → project/overview.md，架构 → project/architecture.md，决策 → decisions/{topic}.md，约定 → conventions/{topic}.md，用户偏好/协作风格 → 仅在用户明确确认时写入 user/preferences.md
3. **规则：**总结而非复制。每个文件只写一个主题。注明来源文档。使用标准 frontmatter。
4. 如果发现旧格式（扁平文件、旧版 frontmatter 字段），则进行迁移
5. 更新 index.yaml — 为每个新文件添加条目，并使索引与文件系统保持一致
6. 使用汇总表进行报告。完成条件：每个新文件都有标准 frontmatter 和索引条目，索引与文件系统之间没有差异，且报告列出每个创建路径及其来源文档。

---

操作：保存

将当前对话中的经验记录到记忆中。

1. 回顾对话，查找：决策、反馈、约定、状态变更、重要上下文
2. **针对每项内容：**更新现有记忆文件，或在相应的 {type}/ 目录中创建新文件。对于重要会话，在 sessions/ 中创建会话日志。
3. **来源标识符：**将写入时使用的运行环境记录为 slug（codex、claude-code、cursor、grok、openclaw、vscode、craft-agent 或 other）
4. 使用标准 frontmatter 格式编写文件（参见 references/templates.md）
5. 更新 index.yaml 并报告已保存/更新的内容。完成条件：报告列出每个已创建或更新路径及其 id，且每个路径都有对应的索引条目。

---

操作：同步

协调当前检出中已存在的记忆文件，然后保存会话。同步不会获取、拉取、合并、提交、推送或同步其他仓库或供应商原生记忆存储。Git 操作需要单独的任务授权和仓库工作流。

阶段 1 — 导入： 扫描 .agent-memory/ 中未编入索引的文件（添加到索引）→ 扫描索引中的孤立条目（移除）→ 阅读更新后的文件以了解情况。

阶段 2 — 保存： 执行完整的保存操作（审查、更新/创建、会话日志、索引）。

阶段 3 — 报告： 输出一份合并报告（格式见 references/templates.md）。

完成条件：索引与文件系统之间没有差异，并且本次会话保存的每条事实都对应一个带标准前置元数据的索引文件。

---

操作：维护

全面维护：精简、清理过时内容、修正索引、清理旧会话日志。

1. 健康检查： 按类型统计文件数量，检查索引同步情况，找出过时/已过期的条目。
2. 过时检查 — 以必需元数据为准：
   • 主要信号： expires 字段。如果 expires 早于今天 → 标记为已过期，并询问是更新、归档还是移除。
   • 备用方法（没有 expires 时）： 使用 updated 日期（如果从未更新过，则使用 created 日期）+ 按类型设定的阈值：context/ >30 天，sessions/ >60 天。
   • 已归档条目： status: archived 且 updated 日期距今超过 90 天 → 建议删除。
   • supersedes 链： 如果文件 A 的 supersedes: B，且 B 仍存在并且 status: active，则标记 B 以供归档。
3. 精简： 找出内容重叠之处，建议合并，将会话日志中的模式提升至 conventions/ 或 decisions/。
4. 会话清理： 对于 type: session 且 updated 日期距今超过 60 天的条目，如有需要，将有价值的信息提取到其他位置，列出待删除项，并在删除前征求确认。
5. 报告健康状况摘要（格式见 references/templates.md）。完成条件：每个标记项都有用户决定或列为待处理项，并且未经确认没有任何内容被删除或归档。

---

操作：状态

快速只读健康检查。按类型统计文件数量，检查索引与文件系统是否同步，并报告过时/已过期的条目。如果 .agent-memory/ 不存在，则建议运行 init。如果发现问题，则建议运行 maintain。

---

文件格式规则

1. 提炼，不要照录。 记录摘要和决策，而不是对话全文。
2. 每个文件只写一个主题。 如果一条记忆涵盖无关主题，则拆分。
3. 原地更新。 事实变化时，编辑文件，不要无限追加。
4. 保持索引同步。 每个文件都应在索引中，每个索引条目都应指向一个文件。
5. 对上下文使用 expires。 上下文会过时。设置复查日期。
6. 引用，不要复制。 指向源文档，而不是重复内容。
7. 不要保存机密。 记忆文件中不得包含凭据、个人身份信息或敏感数据。
8. 使用绝对日期。 根据任务提供的日期和时区解析相对日期；否则使用当前日期和时区。计算并核实日历日期，然后将其保存为 YYYY-MM-DD。绝不要复制模板中的日期。只有在预期的参考日期或相对表述存在歧义时才询问。

有关前置元数据架构、记忆类型和模板，请参阅 references/templates.md。

---

参考文件

文件	内容
references/templates.md	会话日志模板、同步/健康报告模板、前置元数据架构、记忆类型表
references/agent-pointers.md	安装器技能根目录、轻量指针文件，以及原生记忆的范围和保留边界
references/troubleshooting.md	按项目类型（个人、多 Agent、团队、单体仓库）分类的常见问题、故障排查问答

---

相邻模式

模式	何时足够	何时 agent-memory 更合适
单个客户端指令文件	只有一个工具且项目规模较小	多个工具需要共享的、已建立索引的记忆库
供应商自动记忆	在单个客户端中进行本地临时记录和自动回忆	知识必须可移植、可审查、可通过 git 共享，或在不同检出版本间保持一致
会话交接说明	在聊天之间进行一次性信息传递	持久化决策、约定和项目上下文需要生命周期管理
Memory MCP/服务	已批准使用可搜索的集中式服务	更倾向于使用纯文本文件、git 审查和零运行时依赖

行为评估

仅供作者/审阅者使用： 仅在明确评估此技能时使用场景目录。正常执行任务时请跳过。将每个用例放在全新的临时目录中，向执行 Agent 隐藏断言，并对生成的产物和操作进行评分。目录定义了预期行为；它不能证明评估已通过。合成的浏览器和服务输入仅用于测试决策，不代表真实集成。