Back to Details

memory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Memory

记忆

Memory is not storage. Memory is the foundation for evolution.
记忆不是存储。记忆是进化的基础。

Philosophy

核心理念

Why Memory?

为什么需要记忆？

Without memory, every session starts from zero.
Session 1: Makes mistake A
Session 2: Makes mistake A again
Session 3: Makes mistake A again
...forever
With memory, patterns emerge:
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
Memory isn't for the current session—memory is a gift to future sessions.
没有记忆，每个会话都要从零开始。
会话1：犯了错误A
会话2：再次犯错误A
会话3：再次犯错误A
……循环往复
有了记忆，就能形成模式：
会话1：犯了错误A，记录下来
会话2：读取记录，避免错误A，发现问题B
会话3：读取两条记录，避免错误A和B，找到更优路径
……持续进步
记忆不是为当前会话服务的——记忆是给未来会话的礼物。

The Deeper Purpose

深层意义

Memory transforms isolated events into accumulated wisdom.
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"
This is how learning works. Not through rules handed down, but through patterns that emerge from recorded experience.
记忆能将孤立事件转化为积累的智慧。
单条记录：“我们尝试了X，因Y失败”
5条记录后形成模式：“类似X的方法在Y场景下容易失败”
20条记录后形成智慧：“在尝试类X解决方案前，先检查是否存在Y情况”
这就是学习的运作方式。不是通过自上而下的规则，而是从记录的经验中浮现出模式。

What to Remember

该记录什么

Not everything deserves memory. Record what would hurt if forgotten:
RememberDon't Remember
Decisions and their rationaleImplementation details (use code)
Mistakes and lessonsObvious facts (use docs)
Context that explains "why"Temporary debugging notes
Patterns that emergedThings Git already tracks
The test: "Would a future agent benefit from knowing this?"
并非所有内容都值得记录。只记录遗忘后会造成麻烦的内容：
值得记录无需记录
决策及其依据实现细节（用代码留存）
错误与经验教训显而易见的事实（用文档留存）
解释“为什么”的上下文临时调试笔记
浮现出的模式Git已追踪的内容
判断标准：“未来的Agent会因知晓此事而受益吗？”

Structure

结构

.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)
.memory/
├── context.md      → 当前状态、待关注事项（优先读取）
├── notes/          → 学习心得、观察发现
├── decisions/      → ADRs：决策内容及原因
├── todos/          → 跨会话任务
└── sessions/       → 会话总结（用于交接给下一个会话）

context.md

context.md

The handoff document. When a new session starts, this tells them:
  • What's currently in progress
  • What concerns are active
  • What needs attention
Keep it current. A stale context.md is worse than none.
会话交接文档。新会话启动时，它会告知：
  • 当前正在推进的工作
  • 待关注的事项
  • 需要处理的内容
保持内容更新。过时的context.md还不如没有。

Naming Convention

命名规范

YYYY-MM-DD-kebab-slug.md
Natural sort order. Grep-friendly. Self-documenting.
YYYY-MM-DD-kebab-slug.md
自然排序，支持Grep检索，自文档化。

Core Operations

核心操作

IntentAction
"Remember this"Create note in 
.memory/notes/
"We decided X because Y"Create ADR in 
.memory/decisions/
"What did we learn about Z?"Search 
.memory/
, summarize with citations
"Session ending"Create session summary, update context.md
意图操作
“记住这个”在
.memory/notes/
中创建笔记
“我们决定X，原因是Y”在
.memory/decisions/
中创建ADR
“我们关于Z有哪些学习心得？”搜索
.memory/
，附带引用进行总结
“会话结束”创建会话总结，更新context.md

Record Format

记录格式

markdown
---
type: note | decision | todo | session
status: active | completed | archived
tags: [relevant, keywords]
created: YYYY-MM-DD
---
markdown
---
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.
undefined
内容要让未来的Agent感激你。
undefined

Integration

集成

Memory provides context to other skills:
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
记忆系统为其他技能提供上下文：
memory
  │
  ├─► orientation在会话启动时读取context.md
  ├─► dive借助过往笔记指导调查
  ├─► engineering在提出新方案前查阅决策记录
  └─► refining在PR描述中纳入相关历史

Understanding, Not Rules

理解优先，而非规则

TensionResolution
Completeness vs NoiseRecord signal, not noise. Ask: "Would this help a future agent?"
Structure vs FlexibilityUse consistent format, but content matters more than form
Writing vs DoingRecording takes seconds; re-learning takes hours
矛盾点解决方案
完整性 vs 冗余性记录有效信息，而非噪音。自问：“这对未来的Agent有帮助吗？”
结构化 vs 灵活性使用统一格式，但内容比形式更重要
记录 vs 执行记录只需几秒，重新学习却要数小时

The Anti-Pattern

反模式

The worst failure isn't forgetting to record—it's recording without understanding.
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."
The second takes 30 seconds longer. It saves the next agent hours.
最糟糕的失败不是忘记记录——而是不加理解地记录。
错误示例：“修复了认证模块的bug”
正确示例：“当请求过程中令牌过期时，认证会静默失败。
       根本原因：异步竞态条件。
       修复方案：在敏感操作前添加令牌刷新逻辑。
       经验教训：任何认证代码都应处理操作过程中的令牌过期问题。”
后者多花30秒，但能为下一个Agent节省数小时时间。

Reference

参考资料

See 
reference/
for:
  • templates/ - Record templates
  • remote-sync.md - GitHub/GitLab Issues sync
  • setup.md - Initialization options
查看
reference/
获取：
  • templates/ - 记录模板
  • remote-sync.md - GitHub/GitLab Issues 同步
  • setup.md - 初始化选项