memory

记忆

记忆不是存储。记忆是进化的基础。

理念

为什么需要记忆？

没有记忆，每次会话都从零开始。

Session 1: Makes mistake A
Session 2: Makes mistake A again
Session 3: Makes mistake A again
...forever

有了记忆，规律便会浮现：

Session 1: Makes mistake A, records it
Session 2: Reads record, avoids A, discovers B
Session 3: Reads both, avoids A and B, finds better path
...progress

记忆不是为了当前会话——记忆是送给未来会话的礼物。

更深层的目的

记忆能将孤立事件转化为累积的智慧。

Individual record: "We tried X, it failed because Y"
Pattern after 5 records: "Approaches like X tend to fail when Y"
Wisdom after 20 records: "Before attempting X-like solutions, check for Y"

这就是学习的方式。学习不是靠传授规则，而是靠从记录下来的经验中浮现的规律。

记住什么

并非所有事情都值得记忆。记录那些忘掉会让人感到痛苦的内容：

记住	不要记住
决策及其依据	实现细节（使用代码）
错误和经验教训	显而易见的事实（使用文档）
能解释“为什么”的背景	临时调试笔记
浮现出的规律	Git 已经跟踪的内容

判断标准：“未来的 Agent 是否会从中受益？”

结构

.memory/
├── context.md      → Current state, active concerns (read first)
├── notes/          → Learnings, observations
├── decisions/      → ADRs: what was decided and why
├── todos/          → Tasks that span sessions
└── sessions/       → Session summaries (handoff to next)

context.md

交接文档。新会话开始时，它会告知：

• 当前正在进行的工作
• 当前关注的问题
• 需要处理的事项

保持内容最新。过时的 context.md 比没有还糟。

命名约定

YYYY-MM-DD-kebab-slug.md

自然排序。便于 grep 搜索。文件名本身就能说明内容。

核心操作

意图	操作
“记住这件事”	在 .memory/notes/ 中创建笔记
“我们决定 X 是因为 Y”	在 .memory/decisions/ 中创建 ADR
“我们对 Z 有什么认识？”	搜索 .memory/，并附上引用进行总结
“会话即将结束”	创建会话摘要，更新 context.md

记录格式

---
type: note | decision | todo | session
status: active | completed | archived
tags: [relevant, keywords]
created: YYYY-MM-DD
---

# Title

Content that future agents will thank you for.

集成

记忆为其他技能提供背景信息：

memory
  │
  ├─► orientation reads context.md at session start
  ├─► dive uses past notes to inform investigation
  ├─► engineering reads decisions before proposing new ones
  └─► refining includes relevant history in PR descriptions

理解，而非规则

矛盾	解决方式
完整性与噪声	记录有用信息，而非噪声。请问：“这能帮助未来的 Agent 吗？”
结构与灵活性	使用一致的格式，但内容比形式更重要
写作与行动	记录只需几秒；重新学习却要花上几小时

反模式

最糟糕的失败不是忘记记录，而是记录了却没有理解。

Bad: "Fixed bug in auth"
Good: "Auth was failing silently when token expired mid-request.
       Root cause: async race condition.
       Fix: Added token refresh before sensitive operations.
       Lesson: Any auth code should handle mid-operation expiry."

第二种做法只多花 30 秒，却能为下一个 Agent 节省数小时。

参考

参见 reference/：

• templates/ - 记录模板
• remote-sync.md - GitHub/GitLab Issue 同步
• setup.md - 初始化选项