Claude Code Memory 记忆系统

一、概述

Claude Code 的 Memory 记忆系统是一种持久化记忆机制，它能够在不同的对话会话之间保留用户信息、项目上下文和学习经验。这意味着用户无需在每次新对话中重复说明自己的偏好、角色或项目背景——记忆系统会将这些信息自动带入后续的交互中，让使用体验更加流畅和个性化。

记忆系统的核心价值体现在三个方面：首先是减少重复说明，用户不需要反复告诉 Claude Code 自己的身份、语言偏好或工作方式，系统会自动记住这些信息并在后续对话中使用。其次是保持行为一致性，记忆系统会记录用户对特定回复方式的偏好、对某种输出格式的要求，以及用户纠正过的内容，从而确保 Claude Code 的行为风格始终符合用户的期望。最后是积累项目知识，随着对话的深入，系统会逐步积累对项目的理解，包括项目目标、技术约束、重要决策和外部资源位置，这些都是项目持续发展的重要资产。

在技术实现上，记忆系统采用的是文件化存储方式，以 Markdown 文件的形式保存在用户的本地文件系统中。这种设计既保证了记忆的持久性（不受会话生命周期影响），也使得用户可以方便地查看和手动管理记忆内容。每次对话开始时，记忆系统会自动加载相关的记忆信息，为 Claude Code 提供必要的上下文支持。

二、记忆的存储位置

Claude Code 的记忆文件存储在用户本地文件系统的特定路径下。对于项目级别的记忆，其存储路径为 ~/.claude/projects/<project-hash>/memory/ 目录，其中 project-hash 是根据项目路径自动生成的唯一标识符，确保不同项目的记忆彼此隔离。在 Windows 系统中，对应的路径为 C:\Users\<用户名>\.claude\projects\<project-hash>\memory\。

每个项目目录下的记忆文件夹中，最重要的文件是 MEMORY.md 文件。这个文件扮演着记忆的"索引目录"角色——它记录了当前项目所有记忆的摘要和元数据。每次新的对话开始时，Claude Code 会自动加载 MEMORY.md 文件中的内容，从而了解当前项目中已有哪些记忆可用。

记忆文件采用 Markdown 格式编写，使用 frontmatter 机制来定义记忆的元数据。每个记忆文件都包含三个关键 frontmatter 字段：name（记忆的名称，用于快速识别记忆的主题）、description（记忆的描述，简要说明记忆的内容和用途）、type（记忆的类型标签，标识记忆属于哪种分类）。以下是 MEMORY.md 文件的典型结构：

值得注意的是，MEMORY.md 文件的内容在加载时会受到200行截断限制。这是为了防止记忆文件过于庞大而影响对话性能。因此，用户应当定期维护记忆文件，清理过时或无用的记忆条目，确保核心记忆能够被有效加载和使用。

三、记忆类型

Claude Code 的记忆系统定义了四种不同的记忆类型，每种类型对应不同的使用场景和信息性质。理解这四种类型的区别，有助于用户更好地组织和利用记忆系统。下表对四种记忆类型进行了全面对比：

记忆类型	标签	用途	适用场景	示例
用户记忆	user	记录用户的角色、偏好、知识背景	用户身份定义、语言偏好、专业领域	"用户是一名中医学习者，偏好中文交流"
反馈记忆	feedback	记录用户的纠正和确认信息	行为纠正、格式偏好、风格调整	"用户喜欢 Markdown 格式输出和结构化内容"
项目记忆	project	记录项目目标、约束、重要决策	项目架构、技术栈、业务规则	"项目目标是构建中医学习笔记系统"
参考记忆	reference	记录外部资源位置指引	文档链接、API 参考、数据源路径	"参考文档位于 docs/api/readme.md"

3.1 用户记忆（user）

用户记忆是最基础也是最重要的记忆类型，它记录了用户的角色、偏好和知识背景信息。这类记忆帮助 Claude Code 理解"与谁在对话"，从而调整回复的语言风格、专业深度和信息呈现方式。例如，如果用户是一名中医学习者，Claude Code 就会在解释概念时更多地引用中医理论和术语；如果用户偏好简洁的回复，系统就会避免冗长的解释。

用户记忆的典型内容包括：用户的职业或学习领域（如"中医学习者"、"软件开发者"）、语言偏好（如"使用中文交流"）、专业水平（如"初学者"、"进阶用户"）、以及常用的工作方式（如"喜欢先看总结再看细节"）。这些信息通常在对话早期就会形成，并且相对稳定，不需要频繁更新。

3.2 反馈记忆（feedback）

反馈记忆记录了用户在对话过程中给出的纠正和确认信息。这类记忆的核心价值在于帮助 Claude Code 从错误中学习——当用户指出某个回复方式不理想、某个解释不够准确、或者某种输出格式需要调整时，这些信息就会被记录为反馈记忆，确保后续不会再犯同样的错误。

每条反馈记忆通常包含两个关键组成部分：Why（为什么需要调整）和 How to apply（如何应用到后续行为中）。例如，如果用户指出"不要使用过于学术化的语言"，反馈记忆不仅会记录"用户偏好通俗易懂的语言"这个事实，还会记录"在解释医学概念时应使用类比和日常语言"这个应用方法，从而使反馈能够在实践中真正发挥作用。

3.3 项目记忆（project）

项目记忆记录了与当前项目相关的全局性信息，包括项目目标、技术约束、架构决策和重要约定。这类记忆对于维护项目的长期一致性至关重要——它确保 Claude Code 始终清楚地理解项目的总体方向和技术选型，不会因为对话的推进而产生偏离。

项目记忆的典型内容包括：项目的核心目标（如"构建一个中医学习笔记网站"）、使用的技术栈（如"HTML、CSS、JavaScript"）、设计约束（如"使用响应式设计"、"内容结构化"）、重要的业务规则（如"版权声明统一"），以及已经做出的关键决策（如"文件命名使用时间戳格式"）。这些信息通常在项目早期就建立，并在项目演进过程中逐步丰富和完善。

3.4 参考记忆（reference）

参考记忆记录了与项目相关的外部资源位置指引，包括文档路径、API 地址、数据源位置等。这类记忆帮助 Claude Code 快速定位和使用项目所需的外部资源，无需用户每次都重新提供链接或路径。

参考记忆特别适合记录以下类型的信息：配置文件的存储路径（如"网站配置文件位于 /config/site.json"）、第三方服务的文档链接（如"字体图标使用的是 Font Awesome 5"）、参考资料的存放位置（如"学习笔记模板位于 /LearningNotes/template.html"），以及其他项目中需要频繁访问的外部资源。需要注意的是，参考记忆的记录应当避免包含敏感信息，如 API 密钥或密码。

四、记忆的创建与更新

记忆的创建和更新并非随意进行，而是遵循特定的触发条件和时机。理解哪些情况适合创建记忆、哪些情况不适合，是高效使用记忆系统的关键。以下是创建记忆的主要触发场景和注意事项。

4.1 适合保存为记忆的场景

当出现以下情况时，系统会自动触发记忆保存操作：首先是用户明确要求记住某事，例如用户说"请记住我喜欢用 Markdown 表格"或"请记下这个配置路径"，这类明确的记忆请求是最直接的触发条件。其次是发现用户角色或偏好信息，例如在对话中用户提到自己的职业、学习领域或交流偏好，系统会判断这些信息具有长期复用价值，适合保存为记忆。

另外，当用户纠正了行为方式时，系统也会自动创建反馈记忆。例如用户说"不要用那么多专业术语"或"请用列表而不是段落"，这些纠正在本质上是一种学习信号，记录下来可以避免后续再次犯错。最后，重要的项目决策或约束也是创建记忆的好时机，比如项目的技术选型、架构设计决策、命名规范约定等，这些信息对项目的长期维护具有重要意义。

4.2 不适合保存为记忆的场景

并非所有信息都适合保存为记忆。以下类型的内容应当避免存入记忆系统：首先是代码模式和实现细节，临时的代码片段、具体的函数实现、调试过程中的中间结果等，这些内容变化频繁且复用价值低，更适合放在对话上下文中而不是长期记忆。其次是Git 历史，提交记录、分支信息、版本变更等已有 Git 系统管理，无需额外存入记忆。

最后，临时任务状态也不适合保存为记忆。例如"当前正在完成第三个功能的开发"、"刚刚修复了 Bug #1234"这类临时性的进度信息，它们在当前对话中有意义，但在后续对话中很快就会过时。将这些临时信息存入记忆只会增加记忆文件的体积，降低系统加载效率。

4.3 记忆的更新机制

记忆并非一成不变——随着项目的演化和用户需求的变化，已有的记忆也需要定期更新。记忆更新的时机包括：用户角色或偏好发生变化时（例如从初学者进阶为中级用户）、项目目标或技术路线调整时、原有的参考资源链接失效或更换时。系统会在检测到这些变化时自动更新对应的记忆条目，但用户也可以手动编辑 MEMORY.md 文件来进行更精细的记忆管理。

五、记忆的访问和使用

记忆系统在对话中的工作方式是一个自动化的后台过程。当每次新对话开始时，Claude Code 会自动加载当前项目目录下的 MEMORY.md 文件，将该文件中索引的所有记忆条目纳入对话上下文。这个加载过程对用户是完全透明的——用户无需手动指定要加载哪些记忆，系统会自动识别并整合相关信息。

然而，为了保证对话性能和响应速度，记忆加载存在一个重要的限制：MEMORY.md 文件的内容最多只能加载 200 行。超过这个限制的内容将被截断，无法在对话中使用。这意味着如果记忆文件过于庞大（例如包含了大量过时的历史记忆），核心记忆可能反而因为被截断而无法生效。因此，定期维护记忆文件、清理冗余内容不仅是良好习惯，更是确保记忆系统正常工作的必要操作。

在对话过程中，记忆并非总是处于激活状态。系统会根据当前对话的主题和需求，智能地判断哪些记忆是相关的，并在需要时激活它们。这种"按需激活"的机制既避免了无关记忆对当前对话的干扰，也提高了系统资源的利用效率。例如，当用户询问项目架构相关问题时，系统会优先激活项目记忆和参考记忆；当用户给出新的偏好指示时，系统则会激活反馈记忆进行记录。

六、记忆管理

高效的记忆管理是充分发挥记忆系统价值的关键。Claude Code 的记忆系统提供了查看、更新、删除等基本管理操作，同时也需要用户注意避免记忆重复和维护记忆质量。以下从五个方面详细介绍记忆管理的方法和最佳实践。

6.1 查看已有记忆

查看当前项目的记忆非常直接——只需打开项目目录下的 MEMORY.md 文件即可。该文件列出了所有已保存的记忆条目及其元数据（名称、描述、类型）。用户可以使用文本编辑器直接查看文件内容，也可以通过系统命令快速定位记忆文件路径。对于拥有多个项目的用户，建议定期检查各项目的 MEMORY.md 文件，了解当前记忆的整体状况。

6.2 更新过时记忆

随着项目的发展和用户需求的变化，部分记忆可能会变得过时或不准确。例如，项目的技术栈从 Vue 切换到 React 后，原有的技术栈记忆就需要立即更新。更新记忆的操作很简单——直接编辑 MEMORY.md 文件中对应条目的 description 字段即可。更新时应注意同时调整可能受影响的关联记忆，确保记忆系统内部的逻辑一致性。

6.3 删除错误记忆

当发现某条记忆存在错误（例如记录了错误的配置文件路径、误解了用户的偏好）时，应当及时从 MEMORY.md 文件中删除该条目。删除操作需要谨慎——在删除前确认该记忆确实不再需要，而不是暂时未使用。对于不确定是否需要保留的记忆，可以考虑先将其标记为"待确认"状态，而不是立即删除。

6.4 避免记忆重复

记忆重复是一个常见问题——同一信息可能在不同的对话中被多次记录，形成多条内容相似的记忆条目。重复记忆不仅浪费了宝贵的 200 行加载空间，还可能导致系统行为的不一致。避免记忆重复的方法包括：在创建新记忆前先检查是否已有类似条目、使用精确的描述避免模糊匹配、定期合并内容相近的记忆条目。

6.5 记忆的版本控制

如果将记忆文件所在的 .claude 目录纳入 Git 版本管理，就可以实现记忆的版本控制。这样做的好处是：可以查看记忆的历史变更记录、在误删除或误修改后回滚到之前的版本、在团队协作中同步记忆配置。需要注意的是，.claude 目录通常位于用户主目录下，不同项目的记忆隔离存储，因此版本控制应当是基于项目目录进行的。

七、记忆 vs 其他持久化机制

Claude Code 提供了多种持久化机制来管理上下文信息，其中最重要的是 Memory 记忆系统和 CLAUDE.md 文件。这两种机制虽然都用于长期信息保存，但在定位、范围和管理方式上存在显著差异。理解这些差异对于选择合适的持久化方式至关重要。

对比维度	Memory 记忆系统	CLAUDE.md
存储位置	~/.claude/projects/<hash>/memory/（用户目录）	项目根目录（代码库内）
适用范围	个人记忆，仅当前用户可见	项目级，代码库内所有协作者可见
内容性质	用户偏好、个人反馈、项目记忆	项目标准、代码规范、开发流程
版本控制	可选（需手动配置）	是（作为代码库的一部分）
加载方式	自动加载 MEMORY.md 索引	自动加载至系统指令
修改权限	用户和 Claude Code 均可修改	用户手动编辑
内容限制	200行截断	无明确截断

7.1 何时使用记忆

记忆系统最适合保存个人化的信息，包括：用户的个人偏好和习惯（如语言偏好、输出格式偏好）、用户对系统行为的具体反馈和纠正（如"不要使用英文术语"）、以及用户个人的学习进度和知识背景（如"正在学习中医的神农本草经"）。这类信息与特定用户强相关，不适合放入代码库共享。

7.2 何时使用 CLAUDE.md

CLAUDE.md 最适合保存项目级的信息，包括：项目的架构设计和技术选型（如"本项目使用 React + TypeScript"）、团队约定的编码规范和开发流程（如"提交信息使用英文"）、项目特有的配置文件说明和构建命令（如"使用 npm run build 构建"）。这类信息与具体项目绑定，适合放入代码库供所有协作者共享。

7.3 两者的协同使用

在实际使用中，记忆系统和 CLAUDE.md 并不是二选一的关系，而是相辅相成的。推荐的做法是：将项目级的通用规范放入 CLAUDE.md，将个人化的偏好和反馈存为记忆。两者结合可以实现"项目规范统一 + 个人体验个性化"的最佳效果。例如，CLAUDE.md 定义了项目的整体文档结构，而用户的记忆则记录了个人的阅读顺序偏好和学习重点。

八、核心要点总结