agent-memory

Agent 记忆

用于存储知识的持久记忆空间，可跨对话保留。

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

主动使用

发现值得保留的信息时保存记忆：

• 需要花费精力才能发现的研究结果
• 代码库中不明显的模式或注意事项
• 棘手问题的解决方案
• 架构决策及其理由
• 之后可能会继续处理的进行中工作

开始相关工作时查看记忆：

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

必要时整理记忆：

• 整合同一主题下零散的记忆
• 删除过时或已被取代的信息
• 工作完成、受阻或放弃时更新状态字段

文件夹结构

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

指南：

• 文件夹和文件名使用 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: "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]
---

搜索工作流

优先查看摘要，以高效查找相关记忆：

# 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. 保持信息最新： 更新或删除过时信息
4. 注重实用： 保存真正有用的信息，而非事无巨细地记录

内容参考

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

• 背景： 目标、背景信息、限制条件
• 状态： 已完成、进行中或受阻的事项
• 详情： 关键文件、命令、代码片段
• 后续步骤： 接下来要做什么、待解决的问题

并非每条记忆都需要包含所有章节，可按需取用。