memory-protocol by jwilger/agent-skills
npx skills add https://github.com/jwilger/agent-skills --skill memory-protocol价值: 反馈——积累的知识在多个会话中创造复合反馈循环。你今天学到的应该加速明天的工作。
教导智能体如何使用 Memento MCP 知识图谱,在多个会话间系统地存储和回忆项目知识。
你的长期记忆(训练数据)和短期记忆(上下文窗口)非常出色,但对于当前上下文之外的项目特定知识的中期记忆却很薄弱。Memento 通过在会话和项目间持久化一个知识图谱来解决这个差距。
解决的问题:会话间的上下文丢失、已知问题的重复调试、已确立规范的重新发现、对相同错误的重复用户纠正。
在继续之前,请确认 Memento MCP 工具可用(mcp__memento__semantic_search、mcp__memento__create_entities 等)。
如果 Memento MCP 工具不可用,停止并告知用户:
"memory-protocol 技能需要 Memento MCP,但我无法访问 mcp__memento__* 工具。要启用记忆持久化,请安装并配置 Memento MCP 服务器 (https://github.com/gannonh/memento-mcp)。没有它,此技能无法工作,我将继续工作但不使用跨会话记忆。"
然后继续工作,但不遵循记忆协议实践——不要尝试基于文件的变通方案。
当此技能处于活动状态且 Memento MCP 工具可用时,不要使用任何基于文件的记忆系统来存储跨会话知识。这包括内置的 memory/ 目录、MEMORY.md 索引、自动记忆功能或任何其他基于文件的持久化机制。所有跨会话的记忆存储通过 Memento MCP 工具进行。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
基于文件的记忆系统和 Memento 服务于相同的目的——跨会话持久化知识。同时使用两者会造成脑裂:存储在文件中的知识对 Memento 搜索不可见,而 Memento 中的知识对文件读取不可见。选择一个。当此技能加载时,选择的是 Memento。
注意:这不禁止 WORKING_STATE.md(它是崩溃恢复基础设施,不是跨会话记忆)或项目文档文件(它们是交付物,不是记忆)。
在开始任何非平凡任务之前,回忆相关的过去知识。此步骤是强制性的。不要因为"这看起来很简单"或因为你相信你记得之前会话的内容而跳过它——你在会话之间不保留记忆。
回忆触发点:
关于错误触发的回忆,请参见下面的专门章节。
对每个回忆事件应用多维搜索(下一节)。
如何回忆——以下三个步骤都是必需的:
mcp__memento__semantic_search —— 描述当前工作的查询,限制 10 条。这仅返回摘要——不是全貌。mcp__memento__open_nodes —— 对于搜索返回的每一个相关实体,调用 open_nodes 来检索完整的实体:所有观察、所有关系、完整上下文。不要跳过此步骤。语义搜索返回的是部分数据;完整的实体通常包含搜索摘要遗漏的关键细节(注意事项、纠正、相关警告)。跳过 open_nodes 意味着你在基于不完整的信息行动。relations 来发现关联知识。对每个相关实体调用 open_nodes。继续遍历,直到结果不再相关。像 depends_on、contradicts、supersedes 和 part_of 这样的关系经常指向会改变你行动方式的信息——一个依赖于变通方案的修复、一个后来被纠正的规范、一个被取代的决定。跳过步骤 2 或 3 就违背了知识图谱的目的。一个扁平的关键词搜索可以单独完成步骤 1——图谱的价值在于知识之间的连接。如果你只搜索而从不打开或遍历,你将错过那些本可以防止错误的反驳信息、纠正和依赖关系。
重要: 不要使用 mcp__memento__read_graph —— 记忆跨越所有项目,图谱太大而无用。
每个回忆事件需要至少两次搜索——不仅仅是一次。原因:智能体通常会搜索技术主题,但会错过那些可以防止重复错误的过程和工作流学习。之前会话的日志显示,相同的用户纠正模式反复出现(团队成员使用、ADR 过程、TDD 工作流、构建命令、审批过程),因为智能体只搜索了功能名称,从未搜索关于正在进行的_工作类型_的过程学习。
必需的搜索维度:
| 即将... | 同时搜索... |
|---|---|
| 进行 TDD 工作 | "TDD 过程错误", "ping-pong 结对经验教训" |
| 生成智能体/子智能体 | "团队成员使用", "智能体协调问题" |
| 调试错误 | "调试工作流错误", 先前错误发生情况 |
| 创建 ADR | "ADR 过程", "ADR 错误" |
| 提交/PR/合并 | "提交规范", "审批过程" |
| 任何过程步骤 | "[过程] 纠正", "[过程] 经验教训" |
此表格并非详尽无遗。原则是:除了"关于_这个特定事物_我知道什么?"之外,总是问"关于做_这类事情_我学到了什么?"
这与一般的回忆触发点分开,因为错误触发的回忆是智能体最常忘记搜索记忆的地方。模式是:发生错误,智能体立即从头开始调试,尝试多次修复,直到很久以后(如果有的话)才想到检查这个问题之前是否已经解决过。这浪费了时间并重复了过去的工作。
在以下情况触发:
规则: 在尝试修复之前搜索记忆。不是在三次失败尝试之后。不是在花费 10 分钟调试之后。是在之前。
应用多维搜索:
如果你被用户纠正过: 搜索这个纠正(或类似的纠正)是否已经存储在记忆中。如果是,说明你回忆失败——承认这一点,并用更新的上下文强化记忆。
在解决了一个不明显的问题、学习了一个规范或做出一个决定之后,立即存储它——不要等待,你会丢失上下文。
存储什么:
不存储什么:
在创建之前总是先搜索——先进行 mcp__memento__semantic_search。如果存在相关实体,使用 mcp__memento__add_observations 扩展它,而不是创建重复项。
实体命名: <描述性名称> <项目> <YYYY-MM> (例如,"Cargo 测试超时修复 TaskFlow 2026-01")
观察格式:
"项目: <名称> | 路径: <路径> | 范围: PROJECT_SPECIFIC | 日期: YYYY-MM-DD | <见解>""范围: GENERAL | 日期: YYYY-MM-DD | <见解>"关系——在创建或更新实体后,总是创建至少一个。使用 mcp__memento__create_relations 链接到相关实体。主动语态的关系类型:implements、extends、depends_on、discovered_during、contradicts、supersedes、validates、part_of、related_to、derived_from。
有关实体类型表、观察格式指南、关系表、遍历策略和示例,请参见 references/memento-protocol.md。
此协议适用于主智能体和任何被委派工作的子智能体。在指示子智能体时,明确包含记忆协议要求。
子智能体必须:
在管道或工厂工作流内部运行时,管道将操作学习存储在 .factory/memory/ 中以优化未来的运行。
跟踪的学习类型:
独立用户可以忽略工厂记忆;上述标准记忆实践保持不变。
当你遇到不再准确的记忆时(API 已更改、规范已废弃、上游错误已修复),更新或删除它。错误的记忆比没有记忆更糟糕。
修剪触发点:
在上下文压缩之前或在自然停止点,主动存储任何未保存的发现,以免知识因截断而丢失。这是在知识消失之前的最后机会。
对于持续超过单个任务的会话(管道运行、多切片 TDD、团队协调),维护一个 WORKING_STATE.md 文件作为防止上下文压缩和崩溃的保险。
.factory/WORKING_STATE.md (管道模式)或项目根目录有关完整格式和示例,请参见 references/working-state.md。
有关整合的自我提醒协议(频率、组合重读列表和压缩后规则),请参见模板目录中的 CONSTRAINT-RESOLUTION.md。
在所有模式下均为建议性。回忆和存储纪律是自我执行的。对 read_graph 的限制是门控性的:该工具将返回无用的结果,起到自然的威慑作用。
硬性约束:
[RP] —— 如果 Memento 不可用,记录此差距,继续工作但不使用记忆,告知用户。在完成由本技能指导的工作后,验证:
create_relations 链接此技能需要 Memento MCP。对于增强的工作流,它与以下集成:
缺少依赖项?使用以下命令安装:
npx skills add jwilger/agent-skills --skill debugging-protocol
每周安装次数
130
仓库
GitHub 星标数
2
首次出现
2026年2月12日
安全审计
安装于
codex117
cursor115
kimi-cli114
opencode114
gemini-cli113
amp113
Value: Feedback -- accumulated knowledge creates compound feedback loops across sessions. What you learn today should accelerate tomorrow's work.
Teaches the agent to systematically store and recall project knowledge across sessions using the Memento MCP knowledge graph.
Your long-term memory (training data) and short-term memory (context window) are excellent, but mid-term memory for project-specific knowledge outside the current context is poor. Memento addresses this gap by persisting a knowledge graph across sessions and projects.
Solves: context loss between sessions, repeated debugging of known issues, rediscovery of established conventions, repeated user corrections for the same mistakes.
Before proceeding, confirm that Memento MCP tools are available (mcp__memento__semantic_search, mcp__memento__create_entities, etc.).
If Memento MCP tools are NOT available, stop and inform the user:
"The memory-protocol skill requires Memento MCP, but I don't have access to mcp__memento__* tools. To enable memory persistence, install and configure the Memento MCP server (https://github.com/gannonh/memento-mcp). Without it, this skill cannot function and I will proceed without cross-session memory."
Then continue working without memory protocol practices — do not attempt a file-based workaround.
When this skill is active and Memento MCP tools are available, do NOT use any file-based memory system for cross-session knowledge storage. This includes the built-in memory/ directory, MEMORY.md index, auto-memory features, or any other file-based persistence mechanism. All cross-session memory storage goes through Memento MCP tools exclusively.
File-based memory systems and Memento serve the same purpose — persisting knowledge across sessions. Using both creates split-brain: knowledge stored in files is invisible to Memento searches, and knowledge in Memento is invisible to file reads. Pick one. When this skill is loaded, Memento is the one.
Note: this does NOT prohibit WORKING_STATE.md (which is crash-recovery infrastructure, not cross-session memory) or project documentation files (which are deliverables, not memory).
Before starting any non-trivial task, recall relevant past knowledge. This step is mandatory. Do not skip it because "this seems simple" or because you believe you remember from a prior session — you do not retain memory between sessions.
Recall triggers:
For error-triggered recall, see the dedicated section below.
Apply Multi-Dimensional Search (next section) to every recall event.
How to recall — all three steps are required:
Search: mcp__memento__semantic_search — query describing the current work, limit 10. This returns summaries only — not the full picture.
Open: mcp__memento__open_nodes — for EVERY relevant entity returned by search, call open_nodes to retrieve the complete entity: all observations, all relations, full context. Do NOT skip this step. Semantic search returns partial data; the full entity often contains critical details (caveats, corrections, related warnings) that the search summary omits. Skipping open_nodes means you are acting on incomplete information.
Traverse: Follow relations on opened entities to discover connected knowledge. Call open_nodes on each related entity. Continue traversing until results are no longer relevant. Relations like depends_on, contradicts, , and frequently point to information that changes how you should act — a fix that depends on a workaround, a convention that was later corrected, a decision that was superseded.
Skipping steps 2 or 3 defeats the purpose of a knowledge graph. A flat keyword search could do step 1 alone — the graph's value is in the connections between knowledge. If you only search and never open or traverse, you will miss counter-information, corrections, and dependencies that would have prevented mistakes.
IMPORTANT: Do NOT use mcp__memento__read_graph — memories span all projects and the graph is too large to be useful.
Every recall event requires at least two searches — not just one. The reason: agents consistently search for the technical topic but miss process and workflow learnings that would prevent repeated mistakes. Prior session logs show patterns of the same user corrections recurring (team member usage, ADR process, TDD workflow, build commands, approval process) because agents only searched for the feature name and never for process learnings about the type of work being done.
Required search dimensions:
| About to... | Also search for... |
|---|---|
| Do TDD work | "TDD process mistakes", "ping-pong pairing lessons" |
| Spawn agents/subagents | "team member usage", "agent coordination issues" |
| Debug an error | "debugging workflow mistakes", prior error occurrences |
| Create an ADR | "ADR process", "ADR mistakes" |
| Commit/PR/merge | "commit conventions", "approval process" |
| Any process step | "[process] corrections", "[process] lessons learned" |
This table is non-exhaustive. The principle: always ask "what have I learned about doing this kind of thing?" in addition to "what do I know about this specific thing?"
This is separated from the general recall triggers because error-triggered recall is where agents most consistently fail to search memory. The pattern: an error occurs, the agent immediately starts debugging from scratch, burns through multiple fix attempts, and only much later (if ever) thinks to check whether this problem was solved before. This wastes time and repeats past work.
Fires on:
The rule: Search memory BEFORE attempting a fix. Not after three failed attempts. Not after spending 10 minutes debugging. Before.
Apply multi-dimensional search:
If you've been corrected by the user: search for whether this correction (or a similar one) was already stored in memory. If it was, you failed to recall — acknowledge this and reinforce the memory with updated context.
After solving a non-obvious problem, learning a convention, or making a decision, store it immediately — do not wait, you will lose context.
What to store:
What not to store:
Always search before creating — mcp__memento__semantic_search first. If a related entity exists, extend it with mcp__memento__add_observations rather than creating a duplicate.
Entity naming: <Descriptive Name> <Project> <YYYY-MM> (e.g., "Cargo Test Timeout Fix TaskFlow 2026-01")
Observation format:
"Project: <name> | Path: <path> | Scope: PROJECT_SPECIFIC | Date: YYYY-MM-DD | <insight>""Scope: GENERAL | Date: YYYY-MM-DD | <insight>"Relationships — ALWAYS create at least one after creating or updating an entity. Use mcp__memento__create_relations to link to related entities. Active-voice relation types: implements, extends, depends_on, discovered_during, contradicts, supersedes, validates, part_of, related_to, derived_from.
See references/memento-protocol.md for entity type table, observation format guide, relationship table, traversal strategy, and examples.
This protocol applies to both the main agent AND any subagents to which work is delegated. When instructing a subagent, include the memory protocol requirement explicitly.
Subagents must:
When running inside a pipeline or factory workflow, the pipeline stores operational learnings in .factory/memory/ to optimize future runs.
Types of learnings tracked:
Standalone users can ignore factory memory; the standard memory practices above remain unchanged.
When you encounter a memory that is no longer accurate (API changed, convention abandoned, bug fixed upstream), update or delete it. Wrong memories are worse than no memories.
Pruning triggers:
Before context compaction or at natural stopping points, proactively store any unsaved discoveries before knowledge is lost to truncation. This is your last chance before the knowledge evaporates.
For sessions lasting beyond a single task (pipeline runs, multi-slice TDD, team coordination), maintain a WORKING_STATE.md file as insurance against context compaction and crashes.
.factory/WORKING_STATE.md (pipeline mode) or project rootSee references/working-state.md for the full format and examples.
See CONSTRAINT-RESOLUTION.md in the template directory for the consolidated self-reminder protocol (frequency, combined re-read list, and post-compaction rules).
Advisory in all modes. Recall and storage discipline are self-enforced. The constraint against read_graph is gating: the tool will return unhelpful results, acting as a natural deterrent.
Hard constraints:
[RP] -- if Memento is unavailable, document the gap, continue without memory, inform user.After completing work guided by this skill, verify:
create_relationsThis skill requires Memento MCP. For enhanced workflows, it integrates with:
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill debugging-protocol
Weekly Installs
130
Repository
GitHub Stars
2
First Seen
Feb 12, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex117
cursor115
kimi-cli114
opencode114
gemini-cli113
amp113
AI Elements:基于shadcn/ui的AI原生应用组件库,快速构建对话界面
66,200 周安装
主动任务系统:AI助手自主任务管理,从被动响应到主动协作
95 周安装
Spec设计调研技能:AI驱动需求分析,系统化提取未知项并生成研究任务
95 周安装
Playwright 高质量应用截图生成工具 - 一键创建营销级 HiDPI 截图
95 周安装
arch-tsdown-cli:TypeScript CLI项目启动模板,支持ESM、d.ts自动生成与npm可信发布
95 周安装
Confluence 专家指南:空间管理、文档架构、模板与协作知识库搭建
96 周安装
构建完整AI聊天应用指南:Next.js + Neon + AI SDK实现持久化聊天与自动命名
96 周安装
supersedespart_of