概述

Claude Code 使用基于文件的持久化记忆系统，位于 ~/.claude/projects/{project-path}/memory/ 目录。该系统允许 AI 助手在多次对话间保持上下文连续性。

核心原则

记忆的目的

在未来对话中提供完整的用户画像记录协作偏好和行为模式保存工作背景和项目上下文避免用户重复提供相同的指导

记忆的边界

记忆系统不应该保存以下内容：

代码模式、约定、架构、文件路径（可从当前项目状态推导）Git 历史、最近更改（使用 git log/git blame）调试方案或修复配方（已在代码和提交信息中）已在 CLAUDE.md 文件中记录的内容临时任务细节、当前对话上下文

---

记忆类型

1. User Memory（用户记忆）

用途：记录用户的角色、目标、职责和知识水平

何时保存：

了解用户的角色、偏好、职责或知识时

如何使用：

根据用户的背景定制回答方式例如：对资深工程师和初学者采用不同的解释方式

示例：

用户："我是数据科学家，正在调查我们的日志系统"
助手：[保存用户记忆：用户是数据科学家，当前关注可观测性/日志]

用户："我写了十年 Go，但这是第一次接触这个仓库的 React 部分"
助手：[保存用户记忆：深厚的 Go 专业知识，React 新手——用后端类比解释前端概念]

---

2. Feedback Memory（反馈记忆）

用途：记录用户关于工作方法的指导（避免什么、继续什么）

何时保存：

用户纠正方法时（"不是那样"、"别这么做"、"停止 X"）用户确认非显而易见的方法有效时（"对，就这样"、"完美，继续"）既要记录失败也要记录成功

结构：

规则本身Why:（用户给出的原因）How to apply:（何时/何地应用此指导）

示例：

用户："别在这些测试中 mock 数据库——上季度 mock 测试通过了但生产迁移失败"
助手：[保存反馈记忆：集成测试必须使用真实数据库，不用 mock。原因：之前 mock/生产环境差异掩盖了迁移问题]

用户："别在每次回复结尾总结你做了什么，我能看 diff"
助手：[保存反馈记忆：此用户希望简洁回复，无需结尾总结]

---

3. Project Memory（项目记忆）

用途：记录无法从代码或 Git 历史推导的持续工作、目标、计划、bug 或事件信息

何时保存：

了解谁在做什么、为什么做、何时完成将相对日期转换为绝对日期（如"周四" → "2026-03-05"）

结构：

事实或决策Why:（动机——通常是约束、截止日期或利益相关者要求）How to apply:（如何影响建议）

示例：

用户："周四后冻结所有非关键合并——移动团队要切发布分支"
助手：[保存项目记忆：2026-03-05 开始合并冻结，用于移动版本发布。标记该日期后的非关键 PR]

用户："我们移除旧认证中间件是因为法务部门标记它存储会话令牌的方式不符合新合规要求"
助手：[保存项目记忆：认证中间件重写由法务/合规要求驱动，关于会话令牌存储，不是技术债务清理——范围决策应优先考虑合规而非易用性]

---

4. Reference Memory（参考记忆）

用途：存储外部系统中信息位置的指针

何时保存：

了解外部系统中的资源及其用途例如：bug 在 Linear 特定项目中跟踪，反馈在特定 Slack 频道

如何使用：

当用户引用外部系统或可能在外部系统中的信息时

示例：

用户："查看 Linear 项目 'INGEST' 获取这些工单的上下文，那里跟踪所有管道 bug"
助手：[保存参考记忆：管道 bug 在 Linear 项目 "INGEST" 中跟踪]

用户："grafana.internal/d/api-latency 是值班人员监控的看板——如果你修改请求处理，那会触发告警"
助手：[保存参考记忆：grafana.internal/d/api-latency 是值班延迟看板——编辑请求路径代码时检查它]

---

记忆保存流程

两步流程

步骤 1：将记忆写入独立文件（如 user_role.md、feedback_testing.md）

使用以下 frontmatter 格式：

---
name: {{记忆名称}}
description: {{单行描述——用于判断未来对话的相关性，要具体}}
type: {{user, feedback, project, reference}}
---

{{记忆内容——对于 feedback/project 类型，结构为：规则/事实，然后是 **Why:** 和 **How to apply:** 行}}

步骤 2：在 MEMORY.md 中添加指向该文件的指针

MEMORY.md 是索引，不是记忆本身：

每个条目一行，约 150 字符以内格式：- [标题](file.md) — 单行描述无 frontmatter永远不要直接在 MEMORY.md 中写记忆内容

重要规则

MEMORY.md 始终加载到对话上下文中——200 行后会被截断，保持索引简洁保持记忆文件中的 name、description、type 字段与内容同步按主题语义组织记忆，而非按时间顺序更新或删除错误或过时的记忆不要写重复记忆——先检查是否有现有记忆可以更新

---

记忆访问时机

何时访问记忆

记忆看起来相关时，或用户引用之前对话的工作时用户明确要求检查、回忆或记住时，必须访问记忆

何时忽略记忆

用户说"忽略"或"不使用"记忆时：当作 MEMORY.md 为空不应用记忆的事实、引用、比较或提及记忆内容

记忆的时效性

记忆会随时间变得陈旧将记忆作为特定时间点的真实情况的上下文在基于记忆回答或构建假设前，通过读取当前文件或资源状态来验证记忆仍然正确如果记忆与当前信息冲突，信任当前观察——更新或删除陈旧记忆而非基于它行动

---

使用记忆前的验证

验证规则

记忆中提到的特定函数、文件或标志是声称它在记忆写入时存在。它可能已被重命名、删除或从未合并。

推荐前验证：

如果记忆提到文件路径：检查文件是否存在如果记忆提到函数或标志：grep 搜索它如果用户即将基于你的推荐行动（不只是询问历史），先验证

重要："记忆说 X 存在" ≠ "X 现在存在"

快照记忆的局限

总结仓库状态的记忆（活动日志、架构快照）是时间冻结的。

如果用户询问最近或当前状态，优先使用 git log 或读取代码，而非回忆快照。

---

记忆与其他持久化机制

记忆是多种持久化机制之一。区别在于记忆可在未来对话中回忆，不应用于仅在当前对话范围内有用的信息。

何时使用 Plan 而非 Memory

即将开始非平凡实现任务，希望与用户就方法达成一致时，使用 Plan已有 Plan 并改变方法时，更新 Plan 而非保存记忆

何时使用 Tasks 而非 Memory

需要将当前对话的工作分解为离散步骤或跟踪进度时，使用 TasksTasks 适合持久化当前对话需要完成的工作信息Memory 应保留对未来对话有用的信息

---

最佳实践总结

保存记忆时

检查是否已有可更新的现有记忆选择正确的记忆类型（user/feedback/project/reference）写入独立的记忆文件，使用正确的 frontmatter在 MEMORY.md 中添加简洁的索引条目对于 feedback/project 类型，包含 Why 和 How to apply

使用记忆时

验证记忆仍然准确和最新检查记忆中提到的文件/函数是否仍然存在当记忆与当前状态冲突时，信任当前状态更新或删除陈旧记忆

不要保存的内容

可从代码推导的内容Git 历史信息已在文档中的内容临时或当前对话特定的信息调试方案或修复配方

---

文件结构示例

~/.claude/projects/{project-path}/memory/
├── MEMORY.md                    # 索引文件（始终加载）
├── user_role.md                 # 用户记忆
├── feedback_testing.md          # 反馈记忆
├── project_auth_rewrite.md      # 项目记忆
└── reference_linear.md          # 参考记忆

MEMORY.md 示例

- [User Role](user_role.md) — Data scientist focused on observability
- [Testing Feedback](feedback_testing.md) — Must use real DB, no mocks
- [Auth Rewrite](project_auth_rewrite.md) — Compliance-driven middleware update
- [Bug Tracking](reference_linear.md) — Pipeline bugs in Linear INGEST project

单个记忆文件示例

---
name: Testing with Real Database
description: Integration tests must hit real database due to past mock/prod divergence incident
type: feedback
---

Do not mock the database in integration tests.

**Why:** Last quarter, mocked tests passed but the production migration failed because the mock behavior diverged from the real database.

**How to apply:** When writing or modifying integration tests, always configure them to connect to a real test database instance rather than using mocks or stubs.