agent-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Memory

A persistent memory space for storing knowledge that survives across conversations.

Location:

.claude/skills/agent-memory/memories/

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

存储位置：

.claude/skills/agent-memory/memories/

Proactive Usage

主动使用场景

Save memories when you discover something worth preserving:

Research findings that took effort to uncover
Non-obvious patterns or gotchas in the codebase
Solutions to tricky problems
Architectural decisions and their rationale
In-progress work that may be resumed later

Check memories when starting related work:

Before investigating a problem area
When working on a feature you've touched before
When resuming work after a conversation break

Organize memories when needed:

Consolidate scattered memories on the same topic
Remove outdated or superseded information
Update status field when work completes, gets blocked, or is abandoned

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

花费精力调研得到的结论
代码库中不明显的模式或陷阱
棘手问题的解决方案
架构决策及其理由
后续可能继续推进的未完成工作

在开始相关工作前，查阅记忆：

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

必要时整理记忆：

合并同一主题的分散记忆
删除过时或已被取代的信息
当工作完成、受阻或中止时，更新状态字段

Folder Structure

文件夹结构

When possible, organize memories into category folders. No predefined structure - create categories that make sense for the content.

Guidelines:

Use kebab-case for folder and file names
Consolidate or reorganize as the knowledge base evolves

Example:

text

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

This is just an example. Structure freely based on actual content.

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

指南：

文件夹和文件名使用kebab-case格式
随着知识库的发展，合并或重新整理内容

示例：

text

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

这只是示例，请根据实际内容自由构建结构。

Frontmatter

All memories must include frontmatter with a

summary

field. The summary should be concise enough to determine whether to read the full content.

Summary is the decision point: Agents scan summaries via

rg "^summary:"

to decide which memories to read in full. Write summaries that contain enough context to make this decision - what the memory is about, the key problem or topic, and why it matters.

Required:

yaml

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

Optional:

yaml

---
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

字段的Frontmatter。摘要应简洁明了，足以让读者判断是否需要阅读完整内容。

摘要是决策依据：Agent会通过

rg "^summary:"

扫描摘要，决定是否需要完整阅读该记忆。撰写摘要时需包含足够上下文，说明记忆的主题、核心问题或内容，以及其重要性。

必填项：

yaml

---
summary: "1-2行描述此记忆的内容"
created: 2025-01-15  # 格式为YYYY-MM-DD
---

可选项：

yaml

---
summary: "大文件处理期间Worker线程内存泄漏的原因及解决方案"
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]
---

Search Workflow

搜索工作流

Use summary-first approach to efficiently find relevant memories:

bash

undefined

采用“先看摘要”的方法高效查找相关记忆：

bash

undefined

1. List categories

1. 列出分类

ls .claude/skills/agent-memory/memories/

2. View all summaries

2. 查看所有摘要

rg "^summary:" .claude/skills/agent-memory/memories/ --no-ignore --hidden

3. Search summaries for keyword

3. 按关键词搜索摘要

rg "^summary:.*keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i

4. Search by tag

4. 按标签搜索

rg "^tags:.*keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i

5. Full-text search (when summary search isn't enough)

5. 全文搜索（当摘要搜索不够时使用）

rg "keyword" .claude/skills/agent-memory/memories/ --no-ignore --hidden -i

6. Read specific memory file if relevant

6. 若相关则阅读具体记忆文件


**Note:** Memory files are gitignored, so use `--no-ignore` and `--hidden` flags with ripgrep.


**注意：** 记忆文件已被git忽略，因此使用ripgrep（rg）时需添加`--no-ignore`和`--hidden`参数。

Operations

操作指南

Save

保存

Determine appropriate category for the content
Check if existing category fits, or create new one
Write file with required frontmatter (use
```
date +%Y-%m-%d
```
for current date)

bash

mkdir -p .claude/skills/agent-memory/memories/category-name/

确定内容对应的合适分类
检查是否已有匹配的分类，或创建新分类
撰写包含必填Frontmatter的文件（使用
```
date +%Y-%m-%d
```
获取当前日期）

bash

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

cat > .claude/skills/agent-memory/memories/category-name/filename.md << 'EOF'

summary: "此记忆的简要描述" created: 2025-01-15

Title

标题

Content here... EOF

undefined

内容在此处... EOF

undefined

Maintain

维护

Update: When information changes, update the content and add
```
updated
```
field to frontmatter

Delete: Remove memories that are no longer relevant

bash

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

Consolidate: Merge related memories when they grow
Reorganize: Move memories to better-fitting categories as the knowledge base evolves

更新：当信息变更时，更新内容并在Frontmatter中添加
```
updated
```
字段

删除：移除不再相关的记忆

bash

trash .claude/skills/agent-memory/memories/category-name/filename.md
# 移除空分类文件夹
rmdir .claude/skills/agent-memory/memories/category-name/ 2>/dev/null || true

合并：当相关记忆增多时，合并它们
重新整理：随着知识库的发展，将记忆移动到更合适的分类中

Guidelines

撰写指南

Write for resumption: Memories exist to resume work later. Capture all key points needed to continue without losing context - decisions made, reasons why, current state, and next steps.
Write self-contained notes: Include full context so the reader needs no prior knowledge to understand and act on the content
Keep summaries decisive: Reading the summary should tell you if you need the details
Stay current: Update or delete outdated information
Be practical: Save what's actually useful, not everything

为恢复工作而写：记忆的存在是为了后续恢复工作。记录所有继续工作所需的关键点——已做出的决策、理由、当前状态和下一步计划。
撰写独立完整的笔记：包含完整上下文，让读者无需前置知识即可理解并采取行动。
摘要需具备决策性：阅读摘要应能让你判断是否需要查看详细内容。
保持内容时效性：更新或删除过时信息。
注重实用性：只保存真正有用的内容，而非所有内容。

Content Reference

内容参考

When writing detailed memories, consider including:

Context: Goal, background, constraints
State: What's done, in progress, or blocked
Details: Key files, commands, code snippets
Next steps: What to do next, open questions

Not all memories need all sections - use what's relevant.

撰写详细记忆时，可考虑包含以下部分：

上下文：目标、背景、约束条件
状态：已完成、进行中或受阻的内容
细节：关键文件、命令、代码片段
下一步计划：后续行动、待解决问题

并非所有记忆都需要包含所有部分，按需使用即可。