SGJki.
← blog AI Agent · 2026-04-12

cc-memory-incident-lessons

通过一次实际事故，深入学习CC memory系统的设计原理与实现机制。

11 min read
#AI#Memory System

Claude Code 记忆系统深度解析：四层架构打造持久化智能

一、引言

当你使用 Claude Code 进行跨日开发时，是否好奇过为什么 AI 能记住上周讨论的技术方案？为什么它能理解你的代码风格偏好？这一切的背后，是 Claude Code 精心设计的四层记忆系统。本文将深入剖析这套系统的工作原理，帮助你更好地利用它提升开发效率。

二、四层记忆架构总览

Claude Code 的记忆系统并非单一组件，而是由四个层次构成的复杂架构。每个层次承担不同的职责，共同实现从瞬时到持久、从项目级到全局级的信息保留。

层次名称生命周期存储位置典型内容
L1会话内容记忆当前会话运行时内存消息历史、工具调用结果
L2跨会话记忆持久化~/.claude/projects/{path}/memory/项目目标、团队规范、技术债务
L3跨项目记忆持久化~/.claude/rules/通用规则、语言规范
L4用户画像持久化~/.claude/projects/{path}/memory/user_*.md技术背景、工作偏好

L1 会话内容记忆（Session Context）

这是最”短暂”的一层，但也是最核心的一层。在每个 Claude Code 会话中，所有对话内容都实时存储在运行时内存中。

工作特性：

生命周期：仅在当前会话有效
存储位置：Claude Code 运行时内存
上下文管理：当上下文窗口接近满额时，系统会自动进行上下文压缩

会话内容记忆的核心价值在于维持对话的连贯性。当你讨论一个复杂的技术方案时，中间产生的所有结论、代码片段、工具调用结果都会被临时记录，确保 AI 能在后续对话中准确引用这些信息。

上下文压缩机制是一个关键技术点。当上下文窗口即将满额时，Claude Code 会智能地压缩早期对话内容，保留最相关的信息，确保新产生的讨论内容不会因为空间不足而丢失。

L2 跨会话记忆（Per-Project Memory）

这是实现”跨日开发”的关键层次。当你在项目中完成一天的编码工作后关闭会话，第二天重新打开时，Claude Code 会自动加载该项目之前保存的记忆。

存储结构：

~/.claude/projects/{project-path}/memory/
├── MEMORY.md           # 记忆索引文件
├── user_*.md          # 用户画像文件
├── feedback_*.md      # 反馈记录
├── project_*.md       # 项目相关记忆
└── reference_*.md     # 参考资料

MEMORY.md 索引文件格式：

---
name: 项目记忆索引
description: 存储项目的关键上下文信息
type: memory_index
---

# 项目记忆索引

## 最近更新
- 2026-04-11: 更新技术方案决策
- 2026-04-09: 记录团队编码规范

## 记忆文件列表
- `project_tech_decisions.md` - 技术方案选择
- `user_preferences.md` - 用户工作偏好

每个记忆文件都包含 frontmatter 元数据和正文内容。正文部分遵循统一的格式：

---
name: 文件名称
description: 简要描述记忆内容
type: [user|feedback|project|reference]
---

# 标题

## Why
为什么这条信息重要（解释其价值和用途）

## How to apply
如何在实际工作中应用这条信息（具体指导）

这种结构化的设计使得记忆内容既便于人类阅读，也便于 AI 解析和使用。

L3 跨项目记忆（Global Memory）

如果说 L2 是项目级的知识沉淀，那么 L3 就是个人级的知识积累。跨项目记忆存储在 ~/.claude/rules/ 目录下，内容对你的所有项目全局可见。

目录结构：

~/.claude/rules/
├── common/           # 通用规则（适用于所有项目）
│   ├── coding-style.md
│   ├── git-workflow.md
│   ├── testing.md
│   ├── security.md
│   └── ...
├── zh/              # 中文规则翻译
├── typescript/      # TypeScript 语言特定规则
├── python/          # Python 语言特定规则
├── golang/          # Go 语言特定规则
└── ...

这种分层设计的精妙之处在于规则优先级。语言特定的规则可以覆盖通用规则中的默认值。例如，Python 项目中关于测试覆盖率的要求可能与通用规则不同，此时 Python 特定规则优先。

启用方式： 在 ~/.claude/settings.json 中全局启用后，所有项目都会自动加载这些规则，为每个新会话提供一致的起始上下文。

L4 用户画像（User Profile）

这是最个性化的一层，专注于记录”你是谁”而非”项目是什么”。

典型内容：

---
name: 用户技术画像
description: 记录用户的技术背景和工作偏好
type: user
---

# 用户技术画像

## 技术背景
- 主力语言：Python, TypeScript
- 熟悉框架：FastAPI, LangGraph
- 偏好数据库：PostgreSQL + pgvector

## 工作风格
- 倾向于 TDD 开发流程
- 重视代码审查
- 使用中文进行技术文档撰写

## 反馈模式
- 喜欢直接指出问题
- 不喜欢过多铺垫
- 重视效率优先

用户画像使 Claude Code 能够针对个人习惯调整交互方式——了解你偏爱 TDD 的团队会主动建议先写测试；知道你习惯直接风格的 AI 会减少客套话。

三、记忆的写入时机

系统何时决定”记住”一条信息？这是一个关键的实现细节。

显式触发：

  • 用户直接要求：“请记住…”
  • 用户说：“下次遇到这种情况，用…”

自动推断： 这是更常见的方式。Claude Code 会从对话中自动识别值得记忆的信息：

场景识别：
- 用户纠正了 AI 的某个行为 → → 记忆用户的正确偏好
- 用户透露了自己的角色（"我是后端开发"） → → 更新用户画像
- 用户讨论了项目的技术选型 → → 记录项目技术决策
- 用户提到了项目的约束条件 → → 记录项目上下文

这种自动推断能力使记忆系统对用户几乎透明——不需要刻意记住什么，AI 会替你处理。

四、关于本地存储的澄清

一个常见的误解是将 Claude Code 的记忆系统与 Git 仓库混淆。

重要区分：

# Git 仓库（代码项目）
/path/to/your/project/
├── .git/
├── src/
├── tests/
└── MEMORY.md  # 如果存在，说明项目自己创建的

# Claude Code 记忆（完全独立的系统）
~/.claude/projects/{project-path}/memory/
├── MEMORY.md
└── user_*.md

关键点在于：~/.claude/projects/ 目录不在任何 Git 仓库中，且已被 .gitignore 忽略。这意味着：

  1. 记忆内容不会被提交到代码仓库
  2. 不会随项目共享给其他协作者
  3. 完全私有，保护个人偏好和项目敏感信息

与传统存储方案的对比

维度Claude Code 记忆系统传统方式（笔记/文档）纯量化的 KV 存储
检索方式AI 语义理解人工查找精确 key 查询
结构化程度半结构化（frontmatter + 正文）自由格式严格 schema
上下文感知自动关联项目场景需手动标注无
写入自动化可自动推断全手动全手动
隐私保护本地隔离取决于存放位置取决于存放位置

五、知识科普：四层记忆架构

趁热打铁，让我来介绍一下Claude Code的记忆系统。根据我的研究（和这次事故的教训），Claude Code的memory系统大致可以分为四层：

层级名称存储位置说明
1项目记忆~/.claude/projects/{project}/memory/MEMORY.md针对特定项目的持久化记忆
2全局记忆~/.claude/memory/跨项目的全局记忆
3会话记忆当前会话内存中只在当前会话有效
4Auto-Memory自动生成根据项目内容自动生成

**项目记忆（Project Memory）**是用户最常提到的MEMORY.md文件。它存储在用户家目录下的.claude目录中，与Git仓库是分离的。这就是为什么git status看不到它的原因——它压根不在Git的版本控制范围内。每个项目有自己独立的memory目录，路径类似~/.claude/projects/my-project/memory/MEMORY.md。

**全局记忆（Global Memory）**则是跨项目共享的记忆内容，适合存放通用的设置、知识或指令。比如你可以在这里存放一些通用的代码规范或者常用的技术栈信息，这些内容在所有项目中都可以被访问。

**会话记忆（Session Memory）**只存在于当前会话，一旦会话结束就会消失。这类似于传统意义上的”上下文窗口”，但会被计入Token使用量。在长时间对话中，如果上下文接近窗口上限，Claude Code可能会自动压缩或清理这部分内容。

Auto-Memory是Claude Code根据项目内容自动生成和维护的记忆内容，帮助AI更好地理解项目上下文。它会在项目目录结构、代码语言、技术栈等发生变化时自动更新。

四层记忆的优先级

当同一信息在多个层级中都存在时，Claude Code会按照以下优先级处理：

  1. 会话记忆 - 最高优先级，当前会话中明确提到的内容
  2. 项目记忆 - 次高优先级，项目特定的持久化记忆
  3. Auto-Memory - 中等优先级，自动生成的上下文理解
  4. 全局记忆 - 最低优先级，跨项目的通用设置

这个优先级意味着，如果你想在所有项目中都遵循某项规范，应该把它放在全局记忆中；如果你只想在特定项目中保持某些信息，就应该使用项目记忆。

六、实际使用场景

为了更好地理解memory系统的价值，让我举几个实际的使用场景：

场景一：新项目接入

当你接手一个新项目时，Claude Code可以通过memory系统快速了解项目背景。比如你可以在项目的MEMORY.md中记录：“这是一个使用FastAPI的后端项目，数据库使用PostgreSQL，主要API路径在/app/api/目录下”。下次会话开始时，AI就能迅速进入状态，而不需要重新解释项目结构。

场景二：编码规范统一

如果你的团队有特定的编码规范，可以将其存储在全局memory中。这样无论在哪个项目工作，Claude Code都会遵循统一的规范，比如变量命名风格、注释要求等。

场景三：上下文连续性

有时候一个复杂任务需要分多次会话完成。通过合理使用项目memory，可以确保每次新会话都能继承之前的工作进度和决策。比如你可以在MEMORY.md中记录：“第三阶段完成了用户认证模块，接下来要做权限管理模块”。

场景四：问题跟踪

在调试复杂问题时，可以利用memory记录已尝试的方法和结论。这样即使换到新会话，也能避免重复同样的尝试。

最佳实践建议

  1. 信任系统的自动记忆——不必刻意”记住什么”，当你的信息重要时，AI 会自动保存。

  2. 定期审查记忆文件——偶尔检查 memory/ 目录，删除过时信息，保持记忆的准确性。

  3. 善用规则目录——如果你有多语言项目，在 rules/python/ 和 rules/typescript/ 中分别定义项目规范，实现精确的项目级配置。

  4. 理解 .gitignore——确认你的记忆目录不会被意外提交到 Git 仓库。

七、总结

Claude Code 的四层记忆系统是一个精心设计的工程产物。会话内容记忆保证了对话的连贯性；跨会话记忆实现了项目上下文的持久化；跨项目记忆提供了个人知识库的复用；而用户画像则让 AI 能够真正”懂你”。

理解这套系统的工作原理，能帮助你更高效地与 AI 协作。下一篇文章中，我们将探讨如何结合记忆系统设计更优的 Agent 交互策略。

Appendix

会话中断恢复机制总结

  1. 多层记忆系统
graph TD
    M["MEMORY.md（项目记忆索引）<br/>- 记录所有 memory 文件的指针和描述<br/>- 会话间持久化，宕机不丢失"]
    P[".plan/ 目录（计划文档）<br/>- plan-brainstorming 输出的计划<br/>- 已提交的 commit 记录"]
    C["代码文件（实现）<br/>- 核心引擎已实现并提交<br/>- 未完成部分可通过计划追踪"]

    M --> P --> C
  1. 此次恢复过程
步骤机制作用
1MEMORY.md读取项目记忆索引，了解 Context Catch 项目
2.plan/plan_index.md追踪所有计划文件
3.plan/context-catch.md读取计划文档，对照完成状态
4git log确认已提交的实现
5代码审查确认核心引擎已完成，剩余 API + 集成
  1. 关键设计
  • 文件优先：所有代码、计划、记忆都以文件形式保存
  • 计划追踪：.plan/ 目录记录每次 planning 的输出
  • 分批提交：已完成的工作及时 commit，减少丢失
  • 会话摘要：记录任务状态，支持跨会话恢复
  1. 此次丢失的信息

仅有未提交的工作（如 API 端点、集成代码的草稿）可能丢失。但核心实现已完成并提交，所以能从计划追踪到完成状态。

Plan-Brainstorming 完整工作流程

1. 工作流程图

graph TD
    WP["writing-plans skill（规划阶段）<br/>- 分析需求，确定范围<br/>- 分解任务，粒度到 2-5 分钟的步骤<br/>- 保存到 docs/superpowers/plans/YYYY-MM-DD-[feature].md<br/>- self-review 检查"]
    CHOICE["用户选择执行方式"]
    EX["executing-plans skill（内联执行）<br/>- 分批执行<br/>- 检查点审查"]
    SDD["subagent-driven-development<br/>（子代理执行 - 推荐）<br/>- 每个任务启动新子代理<br/>- 任务间审查"]
    FIN["finishing-a-development-branch skill（收尾阶段）<br/>- 验证测试<br/>- 呈现选项 (merge/PR/保留/丢弃)<br/>- 执行选择"]
    DONE["完成"]

    WP --> CHOICE
    CHOICE --> EX
    CHOICE --> SDD
    EX --> FIN
    SDD --> FIN
    FIN --> DONE
  1. 文档追踪 | 阶段 | 文档位置 | 内容 | |------|---------|------| | 规划输出 | docs/superpowers/plans/YYYY-MM-DD-<feature>.md | 完整实现计划 | | 计划索引 | .plan/plan_index.md | 所有计划的目录索引 | | 项目记忆 | MEMORY.md | 记忆系统索引 |
  2. Context Catch 项目追踪
graph TD
    A["docs/superpowers/plans/2026-04-11-context-catch-implementation.md<br/>[规划文档]"]
    B[".plan/context-catch.md<br/>[核心计划]"]
    C[".plan/plan_index.md<br/>[计划索引更新]"]
    D["[执行] → [今日实现 + 提交]"]

    A --> B --> C --> D
  1. 关键 skill 链

writing-plans → executing-plans → finishing-a-development-branch ↓ subagent-driven-development (可选替代 executing-plans)

  1. 恢复机制

宕机后可通过：

  1. MEMORY.md → 了解项目状态
  2. .plan/plan_index.md → 找到所有计划
  3. docs/superpowers/plans/<feature>.md → 读取完整计划
  4. git log → 确认已提交的进度

本文基于 Claude Code 实际行为分析编写，细节可能因版本更新而略有差异。

Sources

No external sources for this entry.

Related

2026-04-13 · blog

CC Memory与 Claude-mem的设计哲学

通过一次讨论，深入分析CC memory系统和Claude-mem插件的设计哲学。AI Agent · 8 min read 2026-07-28 · blog

leader.skill

拆解卡兹克开源的 leader.skill：把模糊想法翻译成 agent 能独立跑完的目标任务书。从八条对 agent 本性的悲观公理反推它的所有硬规则——Harness 比 Goal 重要、法与情报分家、反向验证、执行型 vs 探索型分流。AI Agent · 10 min read 2026-06-15 · blog

Hermes Agent 核心功能与 Skill 自进化机制

剖析 MemTensor 的 Hermes Agent：一个 Python agent 外壳经 JSON-RPC 接入 MemOS Reflect2Evolve V7 记忆引擎，靠 crystallize→verify→lifecycle 闭环实现 skill 自进化，用 η 的…AI Agent · 10 min read