拆解 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 applyproject进行中的目标、约束且必须是从代码或 git 里看不出来的相对日期要转成绝对日期reference外部资源链接URL、看板、工单号—✅ 明确不该往记忆里塞的东西代码结构、修 bug 的历史、git 日志、CLAUDE.md里已经写过的只在当前对话里用得上、跨会话没价值的信息。如果你让模型记上面这类内容它会反问“这里面不显而易见的点是什么”——然后只记那个。五、一条记忆的文件长什么样一条典型的 feedback 类记忆根据实际文件抽象出来的---name: feedback-code-styledescription: Prefer composition over inheritance here; run the linter before commitmetadata: 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) — 一句话钩子六、什么时候写记忆这一点目前的判断是没有设定所谓自动触发器。写不写、什么时候写是模型在对话中自己判断的应该不是事件驱动、也不是后台守护进程。合理推断流程是这样对话里出现一条信息模型判断跨会话还有用吗→ 没用的直接跳过有用的话代码/git/CLAUDE.md 里已经有了吗→ 有了也跳过没有的话已经有记忆覆盖了吗→ 有就更新没有就新建无论新建还是更新最后都要在MEMORY.md里同步索引行实操验证点是想让模型一定记住某件事直接说记住……最稳。否则记不记完全取决于模型觉得值不值得。如果它想记下某些事直接拒绝也能阻止记忆的的写入。七、记忆怎么被召回✅ 两层机制第一层会话启动时——总是发生MEMORY.md索引被全文注入上下文。这意味着每次新对话模型都知道有哪些记忆可以翻。第二层对话运行中——按需召回harness 应该是根据description字段判断某条记忆是否和当前话题相关。相关的就把正文塞进 system-reminder同时附带一句时效警告“这是 N 天前的快照涉及 file:line用之前先核实。”模型也可以主动去Read或Grep记忆目录不依赖 harness 自动推送。内容什么时候加载备注MEMORY.md索引每次会话开始一定加载全文进上下文单条记忆正文按需只在相关时注入会话开头不加载正文❓ 召回的具体算法语义相似度关键词打分分析下来应该是 harness 内部实现看不到。八、怎么维护整个生命周期大致是这样写入前去重—— 先检查有没有同名文件有就更新不新建重复的。发现错误就删—— 记忆里有错直接删文件。常见的模式正文里出现类似“CORRECTED … supersedes my earlier belief”的段落——模型在后续会话里自我纠错把旧认知推翻重写。双向链接—— 用[[name]]把记忆串成知识图谱这一点是真的秒。时效护栏—— 每次召回都带N 天前/时间点快照/先核实的警告。consolidate-memory 技能—— 一个手动触发的整理工具扫描整个记忆库合并重复、修正过时内容、精简索引。九、工具层面没有专用 API✅ 操作记忆用的全是通用文件工具没有记忆专用接口操作用什么工具备注新建Write写.md再更新MEMORY.md索引查找Read/Glob/Grep读或搜记忆目录修改Edit局部改/Write整体重写优先更新已有文件删除ShellRemove-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.mdtype: user---name: user-profiledescription: 用户是一名后端工程师偏好显式错误处理与充分的单元测试metadata: node_type: memory type: user originSessionId: 会话 UUID modified: ISO-8601 时间戳---用户是一名后端工程师负责服务端模块……记忆feedback-code-style.mdtype: feedback---name: feedback-code-styledescription: 本项目偏好组合而非继承提交前必须先跑 lint 与测试metadata: node_type: memory type: feedback originSessionId: 会话 UUID modified: ISO-8601 时间戳---在本项目中优先使用组合而非继承……**Why:** 降低耦合、便于测试。**How to apply:** 每次提交前运行 lint 与单元测试。参见 [[user-profile]]学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】