agent-memory

Agent 记忆

一个持久化的记忆空间，用于存储能够跨对话保留的知识。

位置： .claude/skills/agent-memory/memories/

主动使用

当你发现值得保留的内容时，保存记忆：

• 花费了较多精力才查明的研究发现
• 代码库中不明显的模式或陷阱
• 棘手问题的解决方案
• 架构决策及其理由
• 可能之后恢复的进行中工作

在开始相关工作时检查记忆：

• 在调查某个问题领域之前
• 在处理你之前接触过的功能时
• 在对话中断后恢复工作时

需要时整理记忆：

• 合并同一主题下分散的记忆
• 删除过时或已被取代的信息
• 当工作完成、受阻或被放弃时，更新 status 字段

文件夹结构

在可能的情况下，将记忆整理到分类文件夹中。没有预定义的结构，请根据内容创建合理的分类。

指导原则：

• 文件夹和文件名使用 kebab-case
• 随着知识库的演进进行合并或重组

示例：

memories/
├── file-processing/
│   └── large-file-memory-issue.md
├── dependencies/
│   └── iconv-esm-problem.md
└── project-context/
    └── december-2025-work.md

这只是一个示例。请根据实际内容自由组织结构。

Frontmatter

所有记忆都必须包含带有 summary 字段的 frontmatter。summary 应足够简洁，以便判断是否需要阅读完整内容。

Summary 是决策点：Agent 通过 rg "^summary:" 扫描 summary，以决定读取哪些记忆的完整内容。请编写包含足够上下文的 summary，说明记忆的主题、关键问题或话题，以及它为何重要。

必填：

---
summary: "1-2 line description of what this memory contains"
created: 2025-01-15  # YYYY-MM-DD format
---

可选：

---
summary: "Worker thread memory leak during large file processing - cause and solution"
created: 2025-01-15
updated: 2025-01-20
status: in-progress  # in-progress | resolved | blocked | abandoned
tags: [performance, worker, memory-leak]
related: [src/core/file/fileProcessor.ts]
---

搜索流程

使用 summary 优先的方法高效查找相关记忆：

# 1. List categories
ls .claude/skills/agent-memory/memories/

# 2. View all summaries
rg "^summary:" .claude/skills/agent-memory/memories/ --no-ignore --hidden

# 3. Search summaries for keyword
rg "^summary:.*keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i

# 4. Search by tag
rg "^tags:.*keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i

# 5. Full-text search (when summary search isn't enough)
rg "keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i

# 6. Read specific memory file if relevant

注意： 记忆文件已被 gitignore 忽略，因此使用 ripgrep 时需要添加 --no-ignore 和 --hidden 参数。

操作

保存

1. 为内容确定合适的分类
2. 检查现有分类是否合适，或创建新分类
3. 编写包含必填 frontmatter 的文件（使用 date +%Y-%m-%d 获取当前日期）

mkdir -p .claude/skills/agent-memory/memories/category-name/
# Note: Check if file exists before writing to avoid accidental overwrites
cat > .claude/skills/agent-memory/memories/category-name/filename.md << 'EOF'
---
summary: "Brief description of this memory"
created: 2025-01-15
---

# Title

Content here...
EOF

维护

• 更新：当信息发生变化时，更新内容并在 frontmatter 中添加 updated 字段
• 删除：删除不再相关的记忆

  trash .claude/skills/agent-memory/memories/category-name/filename.md
  # Remove empty category folders
  rmdir .claude/skills/agent-memory/memories/category-name/ 2>/dev/null || true
  

• 合并：当相关记忆增多时，将它们合并
• 重组：随着知识库的演进，将记忆移动到更合适的分类中

指导原则

1. 为恢复工作而写：记忆的存在是为了以后恢复工作。记录继续工作所需的所有关键要点，包括已做出的决策、原因、当前状态和后续步骤，避免丢失上下文。
2. 编写自包含的笔记：包含完整上下文，使读者无需任何前置知识即可理解并处理内容
3. 让 summary 具有决定性：阅读 summary 就应能判断是否需要查看详细内容
4. 保持时效：更新或删除过时的信息
5. 注重实用：保存真正有用的内容，而不是所有内容

内容参考

在编写详细记忆时，可以考虑包含：

• 上下文：目标、背景、约束
• 状态：已完成、进行中或受阻的内容
• 细节：关键文件、命令、代码片段
• 后续步骤：接下来要做什么、未解决的问题

并非所有记忆都需要所有部分，请使用与之相关的内容即可。