memory-protocol

记忆协议

价值： 反馈——不断积累的知识会在不同会话间形成复合反馈循环。今天学到的知识应能加速明天的工作。

目的

教会 Agent 如何使用 Memento MCP 知识图谱，系统地存储和回忆跨会话的项目知识。

你的长期记忆（训练数据）和短期记忆（上下文窗口）都很出色，但对于当前上下文之外的项目特定知识，你的中期记忆能力较差。Memento 通过在不同会话和项目间持久化知识图谱，弥补这一不足。

解决的问题：会话间上下文丢失、对已知问题重复调试、重新发现既定约定，以及用户反复纠正同一类错误。

实践

确认 Memento MCP 是否可用

继续之前，请确认 Memento MCP 工具可用 （mcp__memento__semantic_search、mcp__memento__create_entities 等）。

如果 Memento MCP 工具不可用，请停止并告知用户：

“记忆协议技能需要 Memento MCP，但我无法访问 mcp__memento__* 工具。若要启用记忆持久化，请安装并 配置 Memento MCP 服务 （https://github.com/gannonh/memento-mcp）。没有它，此技能无法 正常运行，我会在不使用跨会话记忆的情况下继续。”

然后继续工作，但不使用记忆协议实践——不要尝试采用基于文件的替代方案。

反模式：Memento 可用时使用基于文件的记忆

当此技能已启用且 Memento MCP 工具可用时，不要使用任何基于文件的记忆系统来存储跨会话知识。这包括内置的 memory/ 目录、MEMORY.md 索引、自动记忆功能，或任何其他基于文件的持久化机制。所有跨会话记忆都必须专门通过 Memento MCP 工具存储。

基于文件的记忆系统与 Memento 用途相同——在不同会话间持久化知识。两者并用会造成信息割裂：存储在文件中的知识无法通过 Memento 搜索找到，而 Memento 中的知识也无法通过读取文件找到。只能选择一种。加载此技能后，应选择 Memento。

注意：这并不禁止使用 WORKING_STATE.md（这是崩溃恢复基础设施，不是跨会话记忆）或项目文档文件（它们是交付成果，不是记忆）。

行动前回忆 — 不容妥协

开始任何非简单任务前，都要回忆相关的过往知识。这一步是强制要求。不要因为“这看起来很简单”，或认为自己还记得之前会话中的内容而跳过——你无法保留不同会话之间的记忆。

回忆触发条件：

• 开始任何非简单任务
• 做出架构或设计决策
• 不确定项目惯例
• 向用户提问前（答案可能已经有了）

有关错误触发的回忆，请参阅下文的专门章节。

每次回忆都要应用多维搜索（下一节）。

如何回忆 — 以下三个步骤缺一不可：

1. 搜索： mcp__memento__semantic_search — 查询内容应描述当前工作，限制为 10 条。此操作只返回摘要，而非完整信息。

2. 打开： 对搜索返回的每个相关实体，都调用 mcp__memento__open_nodes，以获取完整实体：所有观察、所有关系和完整上下文。不要跳过这一步。语义搜索返回的数据并不完整；完整实体往往包含摘要中遗漏的重要细节（注意事项、更正、相关警告）。跳过 open_nodes 意味着你依据不完整的信息行事。

3. 遍历： 沿着已打开实体中的 relations 查找关联知识。对每个相关实体调用 open_nodes。持续遍历，直到结果不再相关。depends_on、contradicts、supersedes 和 part_of 等关系经常会指向改变行动方式的信息——例如依赖某种变通方案的修复、后来得到更正的惯例，或已被取代的决策。

跳过步骤 2 或 3，就违背了知识图谱的意义。普通关键词搜索只能完成步骤 1——知识图谱的价值在于知识之间的联系。如果你只搜索，却从不打开或遍历，就会错过可能避免错误的反向信息、更正和依赖关系。

重要： 不要使用 mcp__memento__read_graph——记忆涵盖所有项目，图谱过于庞大，不便使用。

多维搜索

每次回忆都必须至少进行两次搜索，不能只搜索一次。原因是：Agent 一贯只搜索技术主题，却漏掉了能避免重复犯错的流程和工作流经验。过往会话记录显示，同一用户的更正反复出现（团队成员使用方式、ADR 流程、TDD 工作流、构建命令、审批流程），这是因为 Agent 只搜索功能名称，却从未搜索与当前工作类型有关的流程经验。

必需的搜索维度：

1. 技术查询： 具体主题、错误、功能或领域概念
2. 流程查询： 关于此类工作类型的经验——错误、更正、工作流见解以及相关惯例

即将进行……	还要搜索……
开展 TDD 工作	“TDD 流程中的错误”、“结对协作经验”
启动 Agent/子 Agent	“团队成员使用方式”、“Agent 协调问题”
调试错误	“调试工作流中的错误”、过往错误记录
创建 ADR	“ADR 流程”、“ADR 错误”
提交/发起 PR/合并	“提交惯例”、“审批流程”
任何流程步骤	“[流程] 更正”、“[流程] 经验总结”

此表并非穷尽所有情况。原则是：除了问“我对这件具体事了解什么？”，还要始终问“我对如何完成这类事情有哪些经验？”

错误触发的回忆——不可妥协

此规则与常规回忆触发条件分开，因为错误触发的回忆是 Agent 最常忘记搜索记忆的情况。常见模式是：错误出现后，Agent 立即从头开始调试，尝试多个修复方案，耗费大量时间，直到很久以后（如果想起来的话）才检查之前是否解决过这个问题。这既浪费时间，也重复了过去的工作。

触发条件：

• 任何错误消息、堆栈跟踪或异常行为
• 任何测试失败
• 任何钩子失败（pre-commit、CI、linter）
• 用户对流程的任何纠正（“不，你应该改为做 X”）
• 任何无法通过立即显而易见的修复解决的问题

规则： 尝试修复前先搜索记忆。不要等到失败三次后，也不要等到调试了 10 分钟后。要在此之前搜索。

进行多维度搜索：

• 搜索具体的错误消息或症状
• 搜索关于此类情况的流程经验（例如，“调试 Node.js 模块错误”“此项目中的测试失败模式”）

如果用户纠正了你： 搜索记忆中是否已存储这项纠正（或类似内容）。如果已存储，说明你未能回忆起来——承认这一点，并根据更新后的上下文强化这条记忆。

发现后立即存储

解决了不明显的问题、发现了惯例或做出了决策后，立即存储——不要等待，否则你会丢失上下文。

应存储的内容：

• 不明显问题的解决方案（以错误消息作为搜索词）
• 工作中发现的项目惯例
• 架构决策及其理由
• 用户对工作流或风格的偏好
• 工具的特殊行为和变通方法
• 用户的纠正——尤其是流程纠正

不应存储的内容：

• 显而易见或文档完善的信息
• 临时值或特定会话的信息
• 冗长的叙述（保持条目简洁且便于搜索）

创建前务必先搜索——先使用 mcp__memento__semantic_search。如果存在相关实体，则使用 mcp__memento__add_observations 扩展该实体，而不是创建重复项。

实体命名： <描述性名称> <项目> <YYYY-MM> （例如，“Cargo Test Timeout Fix TaskFlow 2026-01”）

观察记录格式：

• 项目专属："Project: <name> | Path: <path> | Scope: PROJECT_SPECIFIC | Date: YYYY-MM-DD | <insight>"
• 通用："Scope: GENERAL | Date: YYYY-MM-DD | <insight>"
• 每条观察记录都必须是完整、独立的陈述

关系——创建或更新实体后，始终至少创建一条关系。 使用 mcp__memento__create_relations 链接相关实体。采用主动语态的关系类型：implements、extends、depends_on、discovered_during、contradicts、supersedes、validates、part_of、related_to、derived_from。

实体类型表、观察记录格式指南、关系表、遍历策略和示例，请参阅 references/memento-protocol.md。

子 Agent 职责

此协议适用于主 Agent 以及所有受委派工作的子 Agent。指示子 Agent 时，必须明确说明记忆协议要求。

子 Agent 必须：

• 开始受委派任务前搜索 Memento
• 进行多维度搜索（技术查询 + 流程查询）
• 存储工作中发现的任何新见解
• 适用时与现有实体建立关系

工厂记忆

在流水线或工厂工作流中运行时，流水线会将操作经验存储在 .factory/memory/ 中，以优化后续运行。

跟踪的经验类型：

• CI 模式： 哪些变更类型会导致 CI 失败
• 返工模式： 各关卡常见的返工原因
• 协作效果： 哪些工程师搭档在哪些领域效果最佳
• 领域热点： 哪些文件和模块经常触发问题

独立用户可以忽略工厂记忆；上述标准记忆实践保持不变。

清理过时知识

当你发现某条记忆已不再准确（API 已更改、约定已废弃、上游 bug 已修复）时，请更新或删除它。错误的记忆比没有记忆更糟。

清理触发条件：

• 记忆与当前观察到的行为相矛盾
• 引用的文件或 API 已不存在
• 约定显然已发生变化

在上下文丢失前保存

在上下文压缩前或自然停顿时，主动保存所有尚未记录的发现，以免知识因截断而丢失。这是知识消失前的最后机会。

长时间运行会话的 WORKING_STATE.md

对于持续时间超过单个任务的会话（流水线运行、多轮切片 TDD、团队协作），请维护一个 WORKING_STATE.md 文件，以防上下文压缩或崩溃。

• 位置：.factory/WORKING_STATE.md（流水线模式）或项目根目录
• **更新频率：**每次重要状态变更后
• **读取频率：**会话开始时、上下文压缩后、任何中断后

完整格式和示例请参阅 references/working-state.md。

自我提醒协议

请参阅模板目录中的 CONSTRAINT-RESOLUTION.md，了解整合后的自我提醒协议（频率、合并后的重新阅读清单和上下文压缩后的规则）。

执行说明

在所有模式下均为建议性要求。回忆和存储纪律由自身执行。 禁止使用 read_graph 是门控约束：该工具会返回无用结果，从而起到自然的威慑作用。

硬性约束：

• 对非简单任务，行动前先回忆：[RP]——如果 Memento 不可用，请记录这一缺失，在没有记忆的情况下继续，并告知用户。

约束

• “至少搜索两次，而不只是一次”：两次搜索是指使用两个语义不同的查询，探索问题的不同维度。搜索“auth middleware”和“authentication middleware”只是使用同义词进行了一次搜索，不算两次。其要点是：同时探索技术维度（使用什么技术／模式）和流程维度（存在哪些决策／约定）。
• “非简单任务”判定标准：如果任务结果取决于项目上下文——约定、过往决策、架构选择或领域知识，则该任务不是简单任务。如果任何称职的 Agent 无论项目历史如何都会产出相同结果，则该任务是简单任务。如有疑问，请先回忆。进行不必要搜索的代价是几秒钟；遗漏相关上下文的代价则是返工。

验证

完成受此技能指导的工作后，请确认：

• 开始任务前已搜索记忆（semantic_search）
• 已搜索流程／工作流方面的经验，而不只是技术主题（多维度搜索）
• 每次遇到非简单错误时，均已在尝试修复前搜索记忆
• 已将发现保存为带有结构化观察内容的 Memento 实体
• 已使用 create_relations 关联相关实体
• 已指示子 Agent 遵循记忆协议
• 没有留下未纠正的过时或矛盾记忆
• 对于长时间运行的会话，已维护 WORKING_STATE.md
• 已遵循自我提醒协议（每 5–10 条消息重新读取状态）

依赖项

此技能需要 Memento MCP。为增强工作流，它还集成了：

• **debugging-protocol：**在开始 4 阶段调查前搜索记忆
• **user-input-protocol：**保存用户的回答，避免重复提问
• **tdd：**在不同会话之间保存测试模式和领域建模方面的见解
• **pipeline：**流水线控制器使用 WORKING_STATE.md 和自我提醒，在长时间自主运行期间保持角色纪律
• **ensemble-team：**团队协调者使用自我提醒，防止多 Agent 会话期间角色偏移

缺少依赖项？请使用以下命令安装：

npx skills add jwilger/agent-skills --skill debugging-protocol