Claude Code 的「记忆」（官方称 auto-memory）是一套基于本地文件的持久化记忆机制。它不依赖向量数据库，也不依赖云端存储，就是普通 Markdown 文件 + 一套读写约定。本文从存储位置、文件格式、索引机制、召回逻辑、写入规则几个层面拆解它的实现原理。

一、先厘清「记忆」的概念边界

在 Claude Code 里，至少有四种东西会被笼统地称为「记忆」，但它们的实现机制完全不同：

概念	作用域	是否持久	实现
auto-memory（自动记忆）	跨会话、跨项目	✅ 持久	本地 Markdown 文件系统
CLAUDE.md	项目/全局	✅ 持久	静态指令文件，人为维护
上下文窗口（conversation）	单次会话	❌ 会话结束即失	对话上下文注入
prompt caching	单次/相邻会话	❌ 有时效	token 缓存降低开销

本文讨论的是第一种——auto-memory，这也是真正意义上「Claude 跨会话记住你」的那套机制。其余三者的详细说明见本文最后一节。

二、存储位置

每个项目拥有一个独立的记忆目录，路径形如：

~/.claude/projects/-Users-nc-rain-raincode-Knowledge/memory/

目录名由「项目工作目录的绝对路径」哈希而来，路径中的 / 被替换为 -。因此不同项目互不干扰，Claude 在 A 项目里记住的东西不会污染 B 项目的上下文。

目录内部结构：

memory/
├── MEMORY.md              # 索引文件（每次会话都加载）
├── user_profile.md        # 单条记忆
├── feedback_no_coauthor.md
└── ...

三、文件结构：一条记忆一个文件

每条记忆是一个独立的 Markdown 文件，开头是 YAML frontmatter：

---
name: user_profile
description: ZhenYu 的基本信息：国籍、语言偏好
metadata:
  type: user
---

<记忆正文>

三个字段各有分工：

• name：唯一标识（slug），供关联引用
• description：一句话摘要，召回时用它判断相关性
• metadata.type：记忆类型，见下文

四、索引机制：MEMORY.md

MEMORY.md 是整套机制的核心，它在每次会话启动时被完整加载进上下文，内容只是一行一条的指针：

# Memory Index

- [user_profile.md](./user_profile.md) — 用户的基本信息
- [feedback_no_coauthor.md](./feedback_no_coauthor.md) — git commit 不要附加 Co-Authored-By

关键设计在于「索引常驻、正文按需」：

• 常驻上下文的只有这一份极简索引，让 Claude 「知道自己记得什么」而不占太多 token
• 记忆正文不会全量注入，只有当某条记忆与当前任务相关时，才会被读取进上下文

这是 auto-memory 区别于「把一堆文件全部塞进 prompt」的关键——既保留记忆能力，又控制了上下文开销。

五、记忆的四种类型

metadata.type 决定了这条记忆的用途和写入方式：

type	内容	示例
user	用户是谁（角色、技术栈、偏好）	语言偏好、所在行业
feedback	用户给的工作方式反馈	提交信息不要带签名行
project	项目背景、目标、约束	某个长期项目的架构决策
reference	外部资源指针	文档 URL、看板、工单链接

其中 feedback 类型在正文里会额外带上两个字段，说明「为什么」和「怎么用」：

**Why:** 这是用户明确的纠正，违反会让提交历史不干净。

**How to apply:** 写 commit message 时不要附加 Co-Authored-By 行。

六、召回与关联

召回靠 description 匹配

每条记忆的 description 是召回时的「门牌号」。Claude 在会话中判断当前任务是否与某条记忆相关时，主要依据这份一行摘要，而不是把整条记忆读出来比对。

关联靠 [[链接]]

记忆正文之间用 wiki 风格的 [[name]] 互相链接，形成关联网络：

这是某条记忆的正文，提到了 [[user_profile]] 和 [[feedback_no_coauthor]]。

[[name]] 指向的是另一条记忆的 name 字段。即使链接对象还不存在，也没关系——它标记了一个「将来值得补记」的主题。

七、写入规则

auto-memory 遵循一套克制原则，避免记忆膨胀：

1. 只记代码仓库本身记录不了的：用户偏好、工作约束、项目背景。代码结构、历史修复、CLAUDE.md 已有的内容不重复记。
2. 先查重再写：写入前先检查是否已有覆盖它的文件，有则更新、无则新建；确认错误的记忆直接删除。
3. 相对日期转绝对：记忆里不写「上周」「前天」，统一转成具体日期。
4. 写完更新索引：每新增一条，在 MEMORY.md 里加一行指针，正文不进索引。

八、与其他「记忆」的区分

1. CLAUDE.md —— 静态指令 vs 动态记忆

CLAUDE.md 是人写的、静态的规则文件；auto-memory 是 Claude 自己积累的、动态的事实档案。前者的边界由你明确划定，后者会随对话自发生长。详见 claude-md.md。

2. 上下文窗口 —— 会话级工作记忆

当前对话里的所有内容（含被总结后压缩的部分）是「工作记忆」，会话结束即消失。auto-memory 是从这些对话里沉淀出来、写入磁盘的那极小一部分。

3. prompt caching —— 性能优化而非记忆

prompt caching 缓存的是 token，用来降低重复请求的开销，和「记住内容」无关。它可能让 CLAUDE.md 等重复出现的输入加载更快，但不产生任何跨会话的「认知」。

小结

一句话概括 auto-memory 的实现：

MEMORY.md 是常驻的目录索引，每个 .md 文件是一条带类型标签的事实；靠 frontmatter 的 description 做相关性筛选，靠 [[name]] 做相互关联，正文按需加载。

理解了这套机制，就可以：

• 主动去 ~/.claude/projects/*/memory/ 看看 Claude 记住了什么
• 把值得长期保留的用户偏好、项目约束写成规范格式
• 清理那些已过时或错误的记忆文件

贡献者: Ra1n

上一页CLAUDE.md 配置

下一页Skills 技能系统