project-memory

目的和工作流

记录项目中特定的解决方案，尤其是那些经过多次失败尝试，或花费大量搜索、时间或 token 才找到的方案，让下一个 Agent 不必重复这些工作。

1. 开始处理项目时——在阅读代码或进行更改之前运行 load，无需等待他人提醒。在处理某个领域之前，先搜索相关键。
2. 有所收获或完成工作时——检查下方的记录条件，并对符合条件的经验运行 add。报告已保存的条目；如果没有符合条件的内容，无需说明。

脚本

所有读取和写入操作都通过此技能自身目录中的 scripts/memory.py 完成。不要用 echo 手动构造 JSON——包含引号或反斜杠的经验会悄无声息地破坏文件。

需要 python3（仅使用标准库，无需安装软件包）。如果缺少该程序，请说明，而不是改用 shell 拼接字符串。

_MEM="<this skill's directory>/scripts/memory.py"
python3 "$_MEM" --help

命令	功能
load	按键去重，并分层打印此项目的记忆
load --all	同上，但展开所有条目
load --json	同上，以 JSON 数组形式输出
add	添加一条经验，可选择将旧条目合并到其中
search QUERY	按子字符串筛选经验
stats	按类型统计数量，并计算平均置信度
path	打印此项目的存储路径

---

加载（首先执行）

python3 "$_MEM" load

输出按知识存在于其他位置的情况分层。pitfall、pattern 和 preference 会完整打印，因为项目中没有其他地方记录它们。architecture 和 tool 只会打印键列表，因为 AGENTS.md 和代码中已经记录了这些内容，而且 Agent 接下来就会阅读它们：

## Only recorded here (pitfall, pattern, preference)
- **n-plus-one-products** (9/10) — Product.includes(:variants) needed in catalog controller

## Index — 42 more, run `search <key>` for the full text
- **architecture**: no-orm-raw-sql, events-are-append-only
- **tool**: rg-over-grep

无论存储内容有多少，每个键都会列出。折叠细节没有问题，但不能隐藏条目的存在——看不到的键就永远不会被搜索到。当某个键看起来与接下来要做的工作相关时，在处理该领域之前运行 search <key>：

python3 "$_MEM" search n-plus-one-products

输出已去重：键相同时保留最新条目。NO_LEARNINGS 表示这是一个全新的项目；继续工作即可。损坏的行会被跳过并报告，不会导致操作中止。

需要阅读整个存储内容时，使用 --all 展开所有条目。

load 末尾会附上记录提醒；--json 和 --all 则不会。

---

添加

根据实际发生的情况起草字段，并直接写入符合条件的条目，无需要求用户提供或批准每个字段。报告已保存的内容。

1. 类型——pitfall 用于实际出错的情况，pattern 用于经实践验证有效的工作方式，preference 用于用户希望采用的做法。这三种类型会完整加载。architecture 和 tool 用于描述项目的构成，只会加载键，因为仓库中的文件已经记录了这些信息。根据条目所属类型选择，而不是根据其重要程度或显示方式选择。
2. 键——采用 kebab-case，并准确描述经验。大多数条目在 load 中只显示键，因此 lesson-001 实际上无法辨认，而 n-plus-one-products 则便于查找。脚本会拒绝通用键和编号键。
3. 经验——简洁且可复用的经验：适用条件、应避免的失败做法、经验证的解决方案及其证据或位置。根因已确认时，应一并说明；仍不确定的内容应标明。
4. 置信度——1-10

python3 "$_MEM" add \
  --type pitfall \
  --key n-plus-one-products \
  --insight 'Product.includes(:variants) needed in catalog controller — N+1 caused 3s load' \
  --confidence 9 \
  --files 'app/controllers/catalog_controller.rb'

脚本会自动填写时间戳、分支和 slug。--source 默认为 user-stated；其他技能应传入各自的名称。

再次添加已有键即可更新该条目。load 只显示最新条目。更正旧经验之前，请参阅旧经验不再适用时。

---

合并根因相同的条目之前，请阅读合并条目，了解相应命令、保留规则以及如何恢复被吸收的键。

值得记录的内容

• 只记录置信度达到 7 或以上的内容。
• 只记录项目特有的经验。通用编程知识不应记录在这里。
• 这条内容适合写进 AGENTS.md 吗？如果适合，就写在那里。这里存放的 是只有在实际工作中才会发现的内容：哪里出了问题、最终找到的修复方法， 以及用户希望下次如何以不同方式处理。
• 对于技术经验，记录反复尝试失败后经验证有效的解决方案，或经过大量搜索、 时间投入或 token 消耗才找到的实用方法。记录内容必须有助于避免在类似情况下 重复付出这些成本。
• 保留值得避免的失败路径、成功的方法、适用条件和证据。不要编造重试次数、 token 总量或用时；即使没有测量成本，也能判断某项调查耗费很大。
• 不要保存常规的成功经验、通用建议、工作日志或推测性的修复方案。 明确的用户偏好在满足相同项目特有规则时仍可记录。
• 不记录任务清单或未解决的 bug——这些应放在项目的问题跟踪器 或 AGENTS.md 中。

---

旧经验失效时

1. 阅读现有条目，并将其中的假设与当前版本、环境、输入和用法进行比较。 根据源代码证据或有针对性的复现调查失效原因；单次失败不足以证明条目无效。
2. 区分暂时性问题或超出条目适用条件的用法，以及在这些条件下已不再奏效的方法。 如果原因尚未查明，应如实说明不确定性，不要把旧经验改写成已被证伪。
3. 确认失效后，使用相同的 key 执行 add，替换当前经验，无需征求批准。 记录证据、受影响的条件以及经验证的替代方法。如果尚无替代方法，应说明这一限制， 而不是继续推荐失效的方法。保留旧方法仍然有效的适用条件，并保留适用的吸收关系。
4. 回读条目，核实修正结果。保留只追加的历史记录； 不要手动编辑或删除存储中的行。

其他技能和 Agent 如何记录经验

对于委派的工作，主 Agent 会在每位工作者的提示词中提供相关的已存经验。 工作者应将耗费成本的反复试错发现和证据（包括疑似过时的条目）返回给主 Agent， 而不是自行写入存储。主 Agent 会验证、去重并记录符合条件的经验或已确认的修正， 无需征求批准。

一次调用，无需重复格式：

python3 <project-memory>/scripts/memory.py add \
  --type pitfall --key '<key>' --insight '<concise reusable lesson>' \
  --confidence 8 --source '<skill-or-agent-name>' --files '<file>'

规则相同：置信度达到 7 或以上、项目特有、实际遇到。

---

存储和导出

共享存储位于 ~/.mystack/projects/<slug>/learnings.jsonl。 要定位它或了解其格式，请阅读 存储格式和项目标识。

如果有人要求为交接或项目文档导出记忆，请阅读 导出。不要自动将其追加到项目文档中。