Back to Details

memory-protocol

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Memory Protocol

记忆协议

Value: Feedback -- accumulated knowledge creates compound feedback loops across sessions. What you learn today should accelerate tomorrow's work.
价值： 反馈——积累的知识会在不同会话间形成复合反馈循环。你今天学到的内容应该能加速明天的工作。

Purpose

目的

Teaches the agent to systematically store and recall project knowledge using file-based persistent memory. Solves the problem of context loss between sessions, repeated debugging of known issues, and rediscovery of established conventions.
教导Agent使用基于文件的持久化记忆来系统性地存储和调用项目知识。解决会话间上下文丢失、重复调试已知问题以及重新发现既定约定的问题。

Practices

实践规范

Recall Before Acting

行动前先调用记忆

Before starting any non-trivial task, search memory for relevant past work. Before debugging any error, search for that error message. Before making design decisions, search for past decisions on the same topic.
Search triggers:
  • Starting a new task
  • Encountering an error or unexpected behavior
  • Making architectural or design decisions
  • Unsure about a project convention
  • Before asking the user a question (it may already be answered)
How to search:
bash
grep -r -i "search terms" ~/.claude/projects/<project-path>/memory/ --include="*.md"
If relevant memory is found, use it to inform your work. If not found, proceed and store what you learn (next practice).
Do not:
  • Skip search because "this seems simple"
  • Assume you remember from a previous session (you do not)
在启动任何重要任务前，搜索记忆中相关的过往工作内容。在调试任何错误前，搜索该错误信息。在做设计决策前，搜索同一主题的过往决策记录。
搜索触发场景：
  • 启动新任务
  • 遇到错误或意外行为
  • 制定架构或设计决策
  • 对项目约定不确定时
  • 向用户提问前（答案可能已存在于记忆中）
搜索方法：
bash
grep -r -i "search terms" ~/.claude/projects/<project-path>/memory/ --include="*.md"
如果找到相关记忆，利用其指导工作。如果未找到，继续推进工作并存储你学到的内容（见下一实践规范）。
禁止：
  • 因“这看起来很简单”而跳过搜索步骤
  • 假设你能记住上一会话的内容（实际无法记住）

Store After Discovery

发现内容后立即存储

After solving a non-obvious problem, learning a convention, or making a decision, store it immediately. Do not wait until later -- you will forget or lose context.
What to store:
  • Solutions to non-obvious problems (with the error message as keyword)
  • Project conventions discovered while working
  • Architectural decisions and their rationale
  • User preferences for workflow or style
  • Tool quirks and workarounds
What not to store:
  • Obvious or well-documented information
  • Temporary values or session-specific facts
  • Verbose narratives (keep entries concise and searchable)
Storage format:
markdown
undefined
解决非显而易见的问题、了解到项目约定或做出决策后，立即存储相关内容。不要等到之后——你会忘记或丢失上下文信息。
需要存储的内容：
  • 非显而易见问题的解决方案（以错误信息为关键词）
  • 工作中发现的项目约定
  • 架构决策及其理由
  • 用户对工作流或风格的偏好
  • 工具的特殊特性及解决方法
无需存储的内容：
  • 显而易见或已有完善文档的信息
  • 临时值或会话专属事实
  • 冗长的叙述（保持条目简洁且便于搜索）
存储格式：
markdown
undefined

Brief Title with Keywords

含关键词的简短标题

Context: One sentence on when this applies.
Discovery: The key insight or solution, concise.
Related: Links to related memory files if any.

Write to the appropriate subdirectory:
~/.claude/projects/<project-path>/memory/ MEMORY.md # Quick reference (always loaded, keep under 200 lines) debugging/ # Error solutions architecture/ # Design decisions conventions/ # Project patterns tools/ # Tool quirks and workarounds patterns/ # Reusable approaches
undefined
适用场景： 一句话说明该内容的适用情况。
发现内容： 核心见解或解决方案，简洁明了。
相关链接： 如有相关记忆文件，可添加链接。

写入对应的子目录：
~/.claude/projects/<project-path>/memory/ MEMORY.md # 快速参考（会话启动时自动加载，内容保持在200行以内） debugging/ # 错误解决方案 architecture/ # 设计决策 conventions/ # 项目模式 tools/ # 工具特性及解决方法 patterns/ # 可复用方法
undefined

Keep MEMORY.md as the Index

维护MEMORY.md作为索引

MEMORY.md
is loaded into context at session start. Use it as a concise index of the most important facts -- project overview, critical conventions, known gotchas. Link to detailed files in subdirectories for depth.
Keep MEMORY.md under 200 lines. When it grows beyond that, move details into topic files and replace with a one-line summary and link.
MEMORY.md
会在会话启动时加载到上下文中。将其用作最重要信息的简洁索引——项目概述、关键约定、已知陷阱。如需详细内容，可链接到子目录中的对应文件。
保持MEMORY.md内容在200行以内。当内容超过此限制时，将细节内容移至主题文件中，并在MEMORY.md中替换为一行摘要及链接。

Factory Memory

工厂记忆

When running inside a pipeline or factory workflow, the pipeline stores operational learnings in 
.factory/memory/
to optimize future runs.
Types of learnings tracked:
  • CI patterns: Which types of changes cause CI failures (e.g., "adding new dependencies often breaks the build step")
  • Rework patterns: Common rework causes by gate (e.g., "mutation survivors most often in error-handling paths")
  • Pair effectiveness: Which engineer pairs are most effective in which domain areas (used for pair selection optimization at full autonomy)
  • Domain hotspots: Files and modules that frequently trigger review findings or rework
How memory optimizes the pipeline:
  • Pair selection (full autonomy level)
  • Slice ordering (prioritize slices in domains with fewer rework patterns)
  • Proactive warnings (flag known CI-failure-prone change patterns before push)
Memory files in 
.factory/memory/
are append-only during a session and summarized during retrospective. The human can review and edit factory memory during Phase 3 (human review).
Standalone users can ignore factory memory; the standard memory practices above remain unchanged.
在流水线或工厂工作流中运行时，流水线会将操作经验存储在
.factory/memory/
目录中，以优化未来的运行流程。
追踪的经验类型：
  • CI模式： 哪些类型的变更会导致CI失败（例如：“添加新依赖通常会破坏构建步骤”）
  • 返工模式： 各环节中常见的返工原因（例如：“未被测试覆盖的代码大多出现在错误处理路径中”）
  • 配对效率： 哪些工程师配对在哪些领域效率最高（用于完全自主模式下的配对选择优化）
  • 热点领域： 经常引发评审意见或返工的文件和模块
记忆如何优化流水线：
  • 配对选择（完全自主级别）
  • 切片排序（优先处理返工模式较少领域的任务切片）
  • 主动预警（在推送前标记已知易导致CI失败的变更模式）
.factory/memory/
目录中的记忆文件在会话期间为追加模式，并在回顾阶段进行汇总。人类可在第三阶段（人工评审）中查看和编辑工厂记忆。
独立用户可忽略工厂记忆，上述标准记忆实践规范保持不变。

Prune Stale Knowledge

清理过期知识

Knowledge goes stale. 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:
  • Memory contradicts current observed behavior
  • Referenced files or APIs no longer exist
  • Convention has clearly changed
知识会过期。当你发现记忆内容不再准确（API变更、约定废弃、上游已修复bug）时，更新或删除该内容。错误的记忆比没有记忆更糟糕。
清理触发场景：
  • 记忆内容与当前观察到的行为矛盾
  • 引用的文件或API已不存在
  • 约定已明确变更

Store Before Context Loss

上下文丢失前存储内容

Before context compaction or at natural stopping points (task complete, switching tasks), store any undocumented insights from the current session. This is your last chance before the knowledge evaporates.
在上下文压缩或自然停止点（任务完成、切换任务）前，存储当前会话中所有未记录的见解。这是你在知识消失前的最后存储机会。

Enforcement Note

实施说明

This skill provides advisory guidance. It cannot force the agent to search memory before acting or to store discoveries. On harnesses with persistent memory directories (Claude Code auto memory), storage is straightforward. On harnesses without persistent filesystems, adapt the pattern to whatever persistence mechanism is available (project files, comments, or external tools). The recall-before-act and store-after-discovery patterns are universal even if the storage mechanism varies.
本技能提供指导性建议，无法强制Agent在行动前搜索记忆或存储发现的内容。在具备持久化记忆目录的环境中（如Claude Code自动记忆），存储操作非常简单。在无持久化文件系统的环境中，可根据现有持久化机制（项目文件、注释或外部工具）调整该模式。无论存储机制如何，“行动前调用记忆”和“发现后立即存储”的模式都是通用的。

Verification

验证

After completing work guided by this skill, verify:
  • Searched memory before starting the task
  • Searched for error messages before debugging from scratch
  • Stored solutions to any non-obvious problems encountered
  • Stored any newly discovered conventions
  • MEMORY.md remains under 200 lines
  • No stale or contradicted memories left uncorrected
在遵循本技能完成工作后，验证以下内容：
  • 启动任务前已搜索记忆
  • 调试前已搜索错误信息，而非从头开始
  • 存储了遇到的所有非显而易见问题的解决方案
  • 存储了所有新发现的项目约定
  • MEMORY.md内容仍保持在200行以内
  • 未遗留任何过期或矛盾的记忆内容

Dependencies

依赖项

This skill works standalone. For enhanced workflows, it integrates with:
  • debugging-protocol: Search memory before starting the 4-phase investigation
  • user-input-protocol: Store user answers to avoid re-asking the same questions
  • tdd: Store test patterns and domain modeling insights between sessions
Missing a dependency? Install with:
npx skills add jwilger/agent-skills --skill debugging-protocol
本技能可独立运行。如需增强工作流，可与以下技能集成：
  • debugging-protocol： 启动四阶段调查前先搜索记忆
  • user-input-protocol： 存储用户的回答，避免重复提问
  • tdd： 跨会话存储测试模式和领域建模见解
缺少依赖项？通过以下命令安装：
npx skills add jwilger/agent-skills --skill debugging-protocol