乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > Claude源码分析 · Claude 是如何＂记住＂你的项目的

Claude源码分析 · Claude 是如何＂记住＂你的项目的

当前时间： 2026-04-11 19:11:05 更新时间： 2026-04-11 分类：软件教程 评论(0)

Claude源码分析 · Claude 是如何＂记住＂你的项目的

上篇文章基于Claude源码分析了Claude控制会话中上下文的机制，今天继续来聊一聊Claude Code的长期记忆。

一、两套系统，各司其职

Claude Code 有两套长期记忆系统，互补协同：

CLAUDE.md — 主要由你手动编写的指令和规则

项目关键信息的索引地图，你来写，Claude 来读

Auto Memory — Claude 自动记录的笔记

基于你的纠正和偏好，自动沉淀的使用习惯与隐性知识备忘录，默认开启

每次在项目目录下启动 Claude 会话，它都会读取这两样东西加载到上下文中——这就是 Claude 记住你项目的关键。

维度
CLAUDE.md
Auto Memory
谁写
你（手动编写）
Claude（自动记录）
内容
指令和规则
学习到的模式和偏好
作用域
项目/用户/组织级
项目级（同 git repo 共享）
加载时机
每次会话
每次会话（200行/25KB）
适用场景
编码规范、工作流、项目架构
调试洞察、发现的偏好

二、CLAUDE.md：四层优先级

Layer 1 · 组织级 — IT/DevOps 管理，所有用户强制生效路径：/Library/Application Support/ClaudeCode/CLAUDE.md（macOS）

Layer 2 · 用户全局 — 个人偏好，跨所有项目生效路径：~/.claude/CLAUDE.md

Layer 3 · 项目级 ⭐ 最常用 — 团队共享，版本控制分发路径：./CLAUDE.md 或 ./.claude/CLAUDE.md

Layer 4 · 本地私有 — 仅自己可见，建议加入 .gitignore路径：./CLAUDE.local.md

加载规则：从当前目录向上遍历，越靠近当前目录的文件优先级越高，后加载的覆盖前面的。

💡 Claude.md 如何写，之前的文章和视频聊了很多了，这里就不展开了

三、Auto Memory：Claude 的自动记忆

Auto Memory 默认开启，核心机制是：Claude 在 System Prompt 中注入约 60 行行为指令，告诉它”你有一个持久化的文件记忆系统”，”如何保存、何时保存、保存什么”。

当触发条件满足时，Claude 主动写入 .md 文件并更新 MEMORY.md 索引。下次会话启动时自动加载。

比如你说”记住我喜欢简洁的回答，不需要总结”，它就会自动记录。

核心设计原则（源码 memoryTypes.ts）：

“Memories are constrained to four types capturing context NOT derivable from the current project state.”

只记录无法从当前项目状态推导的隐性知识，严格分为四种类型。

四、四种记忆类型详解

Type 1: user — 用户画像

存什么：你的角色、目标、职责、知识水平作用域：始终 private何时保存：当了解到你的角色/偏好/知识细节时

🗣 你说：”我是数据科学家，正在调查日志系统”✅ Claude 保存：用户角色-数据科学家，当前目标-调查日志系统

用途：让 Claude 针对你的背景定制回答方式和解释策略。

Type 2: feedback — 行为反馈 ⭐⭐⭐ 最重要

存什么：你对工作方式的指导（该做/不该做）作用域：默认 private；项目级规范用 team何时保存：两种情况——① 你纠正（”不要用XX”）② 你确认非显而易见的方案（”对，就这样”）

🚫 纠正：”不要 mock 数据库，上次因此出了生产事故”✅ Claude 保存：integration tests 必须用真实数据库，原因：mock/prod divergence 曾掩盖坏迁移

✅ 确认：”对，单个 bundled PR 是对的，拆分只会增加噪音”✅ Claude 保存：重构此区域时用户偏好单 PR——确认后的有效判断，非纠正

关键设计哲学：不仅要记录失败，还要记录成功。如果只保存纠正，你会避免过去的错误，但会逐渐偏离你已验证过的方法，变得越来越保守。

Type 3: project — 项目上下文

存什么：进行中的工作、目标、bug（代码/git 中无法推导的）作用域：private 或 team（强烈偏向 team）何时保存：当了解到谁在做什么、为什么、何时完成时

🗣 你说：”重构 auth 中间件是因为法务标记了 session token 存储方式不符合新合规要求”✅ Claude 保存：auth middleware rewrite driven by legal/compliance（非技术债清理）

⚠️ 特殊要求：相对日期必须转为绝对日期！”下周四”❌ → “2026-03-05″✅

Type 4: reference — 外部系统指针

存什么：外部系统中信息的位置（Jira、Linear、Grafana、Slack 等）作用域：通常 team何时保存：当了解到外部资源及其用途时

🗣 你说：”bug 都记在 Linear 的 INGEST 项目里”✅ Claude 保存：pipeline bugs tracked in Linear project “INGEST”

五、什么不该存？

❌ 不存的原因
示例
可从代码推导
代码模式、架构结构
可 grep 得到
函数签名、文件位置
可 git log 看到
提交历史、变更时间线
临时性信息
当前编辑的文件、本次会话 bug 编号

核心原则：只存无法从当前项目状态推导的隐性知识。

常见滥用与纠正

滥用场景
问题
正确做法
把函数签名写入 memory
可从代码直接获取
不存，让 Claude 自己 grep
把对话摘要存为一条 memory
太长太泛，无法精准召回
只存关键决策和理由
用 project 类型存代码结构
可从目录树推导
存架构决策的 why，而非 what
用 feedback 存一次性纠正
只是本次偏好
只存反复出现的跨会话偏好

六、CLAUDE.md 与 Auto Memory 怎么分工？

信息类型
归属
理由
编码规范（团队强制）
CLAUDE.md
需版本控制、团队共享、人工审核
个人偏好（”我喜欢简洁回复”）
Auto Memory
私有、自动、无需维护
项目架构说明
CLAUDE.md
需要精确措辞
外部系统链接
Auto Memory
参考类信息，按需召回

简单判断：需要精确措辞、团队共享、人工审核 → CLAUDE.md；隐性知识、个人偏好、自动沉淀 → Auto Memory。

七、MEMORY.md 索引与加载机制

所有记忆文件存储在 ~/.claude/projects/<sanitized-git-root>/memory/ 目录下。其中 MEMORY.md 是索引文件，每次会话都完整加载，最多 200 行或 25KB，超出会被截断。

为什么用索引而不是全量加载？

  • 全量加载会消耗大量 token
  • 包含大量不相关信息
  • 违反”只加载相关记忆”的设计原则

加载流程：

  1. 扫描所有 .md 的 frontmatter（获取 name / description / type / mtime）
  2. 格式化成文本清单
  3. 用轻量模型（Sonnet）选择 Top-5 最相关的
  4. 返回路径列表 → 主模型决定是否读取内容
用户提问: "帮我重构认证模块"↓findRelevantMemories(query, memoryDir)↓① scanMemoryFiles() → 扫描所有 .md 的 frontmatter→ 获取 name / description / type / mtime (最多200个文件)↓② formatMemoryManifest() → 格式化为文本清单:[project] auth-rewrite.md (2026-03-05): Legal/compliance driven rewrite[feedback] no-mock-tests.md (2026-02-28): Must use real DB[reference] linear-ingest.md (2026-01-15): Pipeline bugs tracker↓③ Sonnet 模型选择 Top-5 最相关的(轻量模型 sideQuery，成本低；Top-5 为硬编码常量)↓④ 返回路径列表 → 主模型决定是否读取内容

💡 findRelevantMemories.ts

八、autoDream：后台记忆整合

autoDream 是后台记忆整合服务，把分散在多个会话中的短期记忆合并、去重、修正，整理成结构化的长期记忆。默认不开启，需要在 ~/.claude/settings.json 中设置 "autoDreamEnabled": true。

触发需要通过四道 Gate，全部通过才执行：

Gate 1

功能开关 ✅

Gate 2

时间 ≥ 24h

Gate 3

会话 ≥ 5 个

Gate 4

分布式锁 ✅

核心能力：跨会话聚合、记忆合并、去伪存真、索引维护、日期规范化。

九、扩展记忆系统

Agent Memory — 子代理独立记忆

每个 Agent 类型有自己独立的记忆空间，与主对话互不干扰。子代理能积累自己领域的经验，也不会污染主对话的记忆。

以上，就是Claude长期记忆管理的关键机制。

附录：源码索引

功能模块
关键文件
核心函数/类
Auto Memory 加载 memdir.ts
loadMemoryPrompt(), buildMemoryLines()
记忆类型定义 memoryTypes.ts
TYPES_SECTION_INDIVIDUAL, MEMORY_TYPES
RAG 召回 findRelevantMemories.ts
findRelevantMemories(), selectRelevantMemories()
记忆扫描 memoryScan.ts
scanMemoryFiles(), formatMemoryManifest()
路径管理 paths.ts
isAutoMemoryEnabled(), getAutoMemPath()
CLAUDE.md 解析 claudemd.ts
getMemoryFiles(), getClaudeMds()
autoDream 整合 autoDream.ts
initAutoDream(), executeAutoDream()
整合 Prompt consolidationPrompt.ts
buildConsolidationPrompt()
分布式锁 consolidationLock.ts
tryAcquireConsolidationLock()
Agent Memory agentMemory.ts
loadAgentMemoryPrompt(), getAgentMemoryDir()
Team Memory teamMemPaths.ts
isTeamMemoryEnabled(), getTeamMemPath()
Stop Hooks stopHooks.ts
handleStopHooks()

参考文档：Claude Code Official – Memory

源码位置：src/memdir/（持久化记忆）、src/utils/claudemd.ts（CLAUDE.md 解析）