拆解 Claude Code 记忆系统：渐进式加载 + 双向链接构成的 Markdown 知识图谱

阅读提示：这篇对Claude记忆机制的拆解主要是基于一段时间以来对 Claude Code 运行时记忆文件的直接检视和自身实操体会的整理，实操环节也通过某些提示词技巧套取“Claude code一些上下文信息”，并不是对Claude code源码的分析，毕竟除了之前的泄露版本我们是看不到Harness 源代码的。本文姑且算是一篇笔记和有兴趣的读者分享,如果大家也有新的观察视角欢迎留言区讨论。

先说可信度——这篇文章里，哪些是确定的，哪些是我合理推测的

在写这篇文章时，尽量对结论标了可信度。可以通过颜色判断：

标记	什么意思
✅	有文件结构和运行说明佐证，可以放心引用
🔶	基于证据的合理推测，但没找到直接文档确认
❓	属于外层运行时（harness）内部实现，完全看不到

一个观察：Claude记忆系统里，"判断该不该记"这件事大概率是模型自己决定的，而"存在哪、怎么读、加时间戳"这些基础设施应该是 harness 管的。两件事分开看，才不会晕。

一、核心思路：把记忆当代码仓库管

Claude Code 的记忆不是藏在一个 SQLite 里的神秘 blob。它就是一叠 Markdown 文件，放在你硬盘上，拿文本编辑器就能打开看。

它遵循几条很简单的原则：

• 一个文件只记一件事。每条记忆独立一个 .md，删改互不影响。
• 索引和正文分开。MEMORY.md 每行指向一条记忆的正文文件，会话开始时只加载索引，不加载正文。用到才去读。
• 每条记忆都要说清"是什么、为什么、怎么用"，而不是单纯记流水账。
• 召回时带时间戳警告。系统会告诉你"这是 N 天前的快照，用之前自己核实"。
• 不同项目的记忆互不干扰。靠工作目录路径来隔离。

二、文件都放在哪

✅ 确定的：

<你的用户目录>\.claude\projects\<项目键>\memory\

里面只有两类文件：

• MEMORY.md —— 索引，每行一条记忆。每次新会话，这个文件会被全文塞进上下文。
• 其余每个 .md —— 一条记忆的正文。用到的时候才加载。

.claude/projects/
├── 【项目 A】/
│   └── memory/
│       ├── MEMORY.md          ← 索引，常驻
│       ├── user-profile.md
│       ├── feedback-code-style.md
│       └── ...
└── 【项目 B】/
    └── memory/
        └── ...

三、怎么隔离不同项目

✅ 确定的：按工作目录的绝对路径隔离。路径字符串做一遍字符净化（sanitize），非字母数字字符统一替换成 -，得到的字符串就是"项目键"。

举个例子（虚构路径）：

工作目录：  C:\Dev\Sample_App\core_lib
              │  │        │      │
              ▼  ▼        ▼      ▼
项目键：    C--Dev-Sample-App-core-lib

🔶 这个替换规则是从真实文件反推出来的，: \ _ 这几个确认会变成 -。其他特殊字符是不是一样处理？没逐一验证。

❓ 有没有跨项目的"全局记忆"层？我没观测到任何证据。

四、记忆分四种类型

✅ 每条记忆必须归属到下面四类之一：

type	记什么	额外要求
user	你是谁：角色、专长、偏好	—
feedback	你给的工作指导（纠正、确认的做法）	必须写 Why 和 How to apply
project	进行中的目标、约束（且必须是从代码或 git 里看不出来的）	相对日期要转成绝对日期
reference	外部资源链接：URL、看板、工单号	—

✅ 明确不该往记忆里塞的东西：

• 代码结构、修 bug 的历史、git 日志、CLAUDE.md 里已经写过的；
• 只在当前对话里用得上、跨会话没价值的信息。
• 如果你让模型记上面这类内容，它会反问："这里面不显而易见的点是什么？"——然后只记那个。

五、一条记忆的文件长什么样

一条典型的 feedback 类记忆（根据实际文件抽象出来的）：

---
name: feedback-code-style
description: "Prefer composition over inheritance here; run the linter before commit"
metadata:
  node_type: memory
  type: feedback
  originSessionId: <会话 UUID>
  modified: <iso-8601 时间戳>
---

正文内容……
**Why:** 降低耦合，方便单独测试。
**How to apply:** 每次提交前跑 lint 和单测。
参见 [[user-profile]]

几个字段的来源要区分清楚：

• name、description、type、正文、[[链接]] —— ✅ 模型自己写的。
• node_type、originSessionId、modified —— 🔶 看起来是 harness 在保存时自动补上的，包括精确时间戳和会话 UUID。精简版说明文档里并没要求模型手写这些字段。

一个有趣的点：实际文件里的 metadata 字段比精简说明文档列出来的要多。精简说明只提了 type，而真实文件里还稳定出现 node_type、originSessionId、modified。这说明"模型写的语义字段"和"系统维护的基础设施字段"是两层。

索引文件里每行的格式 ✅：

- [标题](文件名.md) — 一句话钩子

六、什么时候写记忆

这一点目前的判断是：没有设定所谓自动触发器。 写不写、什么时候写，是模型在对话中自己判断的，应该不是事件驱动、也不是后台守护进程。

合理推断流程是这样：

1. 对话里出现一条信息
2. 模型判断：跨会话还有用吗？→ 没用的直接跳过
3. 有用的话：代码/git/CLAUDE.md 里已经有了吗？→ 有了也跳过
4. 没有的话：已经有记忆覆盖了吗？→ 有就更新，没有就新建
5. 无论新建还是更新，最后都要在 MEMORY.md 里同步索引行

实操验证点是：想让模型一定记住某件事，直接说"记住……"最稳。否则记不记完全取决于模型觉得值不值得。如果它想记下某些事，直接拒绝也能阻止记忆的的写入。

七、记忆怎么被召回

✅ 两层机制：

第一层：会话启动时——总是发生

MEMORY.md 索引被全文注入上下文。这意味着每次新对话，模型都知道"有哪些记忆可以翻"。

第二层：对话运行中——按需召回

harness 应该是根据 description 字段判断某条记忆是否和当前话题相关。相关的就把正文塞进 system-reminder，同时附带一句时效警告："这是 N 天前的快照，涉及 file:line，用之前先核实。"

模型也可以主动去 Read 或 Grep 记忆目录，不依赖 harness 自动推送。

内容	什么时候加载	备注
MEMORY.md 索引	每次会话开始，一定加载	全文进上下文
单条记忆正文	按需，只在相关时注入	会话开头不加载正文

❓ 召回的具体算法（语义相似度？关键词打分？）分析下来应该是 harness 内部实现，看不到。

八、怎么维护

整个生命周期大致是这样：

1. 写入前去重 —— 先检查有没有同名文件，有就更新，不新建重复的。
2. 发现错误就删 —— 记忆里有错，直接删文件。

   常见的模式：正文里出现类似 "CORRECTED … supersedes my earlier belief" 的段落——模型在后续会话里自我纠错，把旧认知推翻重写。

3. 双向链接 —— 用 [[name]] 把记忆串成知识图谱，这一点是真的秒。
4. 时效护栏 —— 每次召回都带"N 天前/时间点快照/先核实"的警告。
5. consolidate-memory 技能 —— 一个手动触发的整理工具，扫描整个记忆库，合并重复、修正过时内容、精简索引。

九、工具层面：没有专用 API

✅ 操作记忆用的全是通用文件工具，没有"记忆专用接口"：

操作	用什么工具	备注
新建	Write	写 .md，再更新 MEMORY.md 索引
查找	Read / Glob / Grep	读或搜记忆目录
修改	Edit（局部改）/ Write（整体重写）	优先更新已有文件
删除	Shell（Remove-Item / rm）	只在确认记忆确实错了时才删

memory\ 目录是已经存在的，不需要手动 mkdir。

十、这套设计好在哪

设计决策	带来的实际好处
文件化，纯 Markdown	能 git 管理，能 diff，人直接打开就能看懂
一条记忆一个文件	改、删、链接互不影响
索引常驻 + 正文按需	省 token，不用把整个知识库每回都塞进去
用 description 驱动召回	摘要比全文做匹配更准
时效护栏	从机制上防止把过期信息当事实用
类型化 + Why/How	记的是能直接执行的东西，不是流水账
双向链接	记忆之间能串成图，不是孤岛
项目隔离	多个项目互不污染
自我纠错	后来的证据可以推翻之前的认知

十一、坦白说，这些我还不能确定

• ❓ 召回算法的内部实现完全看不到。
• 🔶 node_type / originSessionId / modified 是 harness 自动写的，这个推断没被直接确认。
• 🔶 路径净化规则是从样例反推的，没覆盖所有特殊字符。
• ❓ 是否存在全局（跨项目）记忆层，没找到证据。
• ✅ 写入没有自动触发——全靠模型判断，所以可能漏记或多记。"直接说'记住'"最可靠。

附录：基于项目实际MEMEORY文件泛化的样例

以下为演示用的虚构数据，不是任何真实项目。

索引 MEMORY.md：

# Memory Index
- [User profile](user-profile.md) — 用户角色与偏好
- [Code style guidance](feedback-code-style.md) — 编码约定与提交前检查

记忆 user-profile.md（type: user）：

---
name: user-profile
description: 用户是一名后端工程师，偏好显式错误处理与充分的单元测试
metadata:
  node_type: memory
  type: user
  originSessionId: <会话 UUID>
  modified: <iso-8601 时间戳>
---
用户是一名后端工程师，负责服务端模块……

记忆 feedback-code-style.md（type: feedback）：

---
name: feedback-code-style
description: "本项目偏好组合而非继承；提交前必须先跑 lint 与测试"
metadata:
  node_type: memory
  type: feedback
  originSessionId: <会话 UUID>
  modified: <iso-8601 时间戳>
---
在本项目中优先使用组合而非继承……
**Why:** 降低耦合、便于测试。
**How to apply:** 每次提交前运行 lint 与单元测试。参见 [[user-profile]]

JOTO 企业落地观察

• 这类基于文件系统的记忆架构，对企业部署意味着无需引入复杂向量数据库或专用知识图谱引擎，可直接复用现有 DevOps 工具链（Git、CI/CD、IDE 插件）进行版本控制与协作，大幅降低 RAG 知识工程的运维门槛。
• 记忆按项目路径隔离的设计，凸显了“上下文即环境”的理念。这对企业智能体工程提出明确要求：团队需将业务上下文（如微服务边界、领域术语）显式编码为路径结构，而非依赖隐式提示词，否则跨项目知识复用将失效。
• 双向链接（[[name]]）与“Why/How”结构强制要求知识沉淀具备可执行性。这对 AI 安全治理构成天然约束——所有记忆必须附带时效警告与验证指引，避免模型将过期知识当作权威事实输出，降低了幻觉风险。
• 记忆写入完全由模型自主判断，且无自动触发机制。这要求企业在 FDE 驻场共创中，必须将“何时该记”这一元认知能力，作为提示词工程与人工反馈闭环的核心训练目标，而非寄望于系统自动完成。