Claude Code 记忆设计解析

Claude Code 是 Anthropic 官方的 AI 编程助手 CLI。本文解析其记忆系统的设计理念和实现方式。

一、设计理念：分层记忆模型

Claude Code 采用「分层记忆」架构，不同层次的记忆有不同的生命周期和用途：

层次	存储位置	生命周期	用途
短期	内存 messages[]	单次会话	实时对话
中期	.transcripts/ + 摘要	跨压缩周期	上下文延续
长期	CLAUDE.md	项目级别	项目知识
任务	.tasks/	目标完成前	目标追踪

二、短期记忆：上下文管理

2.1 问题：上下文窗口有限

读一个 1000 行文件 ≈ 4000 token
读 30 个文件、跑 20 条命令 → 轻松突破 100k token
不压缩，Agent 无法在大项目里干活

2.2 三层压缩策略

Layer 1: micro_compact（静默压缩）

每次 LLM 调用前，将旧的 tool result 替换为占位符：

1 2	原始: [1000行代码的tool_result] 压缩后: [Previous: used read_file]

Layer 2: auto_compact（自动压缩）

token 超过阈值时触发：

保存完整对话到 .transcripts/transcript_xxx.jsonl
LLM 生成摘要
替换 messages[] 为摘要

Layer 3: compact tool（手动压缩）

用户或模型主动调用 /compact 命令。

2.3 信息不丢失

完整历史保存在磁盘上的 transcript 文件中，可以随时恢复。

三、长期记忆：CLAUDE.md

3.1 什么是 CLAUDE.md

CLAUDE.md 是项目根目录下的 Markdown 文件，存储项目的持久化知识：

my-project/
├── CLAUDE.md          # 项目记忆
├── src/
├── tests/
└── package.json

3.2 CLAUDE.md 存什么

内容类型	示例
项目概述	这是什么项目、技术栈
开发规范	代码风格、commit 规范
架构决策	为什么这样设计、权衡
已知问题	踩过的坑、待解决的问题
常用命令	构建、测试、部署命令
注意事项	模型需要记住的特殊规则

3.3 特点

项目级持久化：跟随项目存在，不随会话消失
版本控制友好：可以提交到 Git，团队共享
按需加载：模型在需要时读取，不占默认上下文
人工维护：由开发者主动编写和更新

四、任务记忆：持久化任务图

4.1 问题：内存清单不够用

内存中的 TodoManager：

没有顺序、没有依赖
状态只有做完/没做完
上下文压缩后就没了

4.2 解决方案：文件持久化的任务图

.tasks/
  task_1.json  {"id":1, "status":"completed"}
  task_2.json  {"id":2, "blockedBy":[1], "status":"pending"}
  task_3.json  {"id":3, "blockedBy":[1], "status":"pending"}
  task_4.json  {"id":4, "blockedBy":[2,3], "status":"pending"}

4.3 任务图回答三个问题

问题	判断条件
什么可以做？	`status=pending` 且 `blockedBy=[]`
什么被卡住？	`blockedBy` 非空
什么做完了？	`status=completed`

4.4 依赖自动解除

完成任务时，自动将其 ID 从其他任务的 blockedBy 中移除，解锁后续任务。

五、记忆系统架构图

  graph TB
    subgraph 短期记忆
        A[messages数组]
    end

    subgraph 中期记忆
        B[transcripts文件]
        C[LLM摘要]
    end

    subgraph 长期记忆
        D[CLAUDE.md]
    end

    subgraph 任务记忆
        E[.tasks目录]
        F[任务图JSON]
    end

    A -->|压缩| C
    A -->|保存| B
    D -->|读取| A
    F -->|状态更新| A

六、设计哲学

6.1 核心原则

“压缩不丢失，持久化到磁盘”

信息只在上下文中被压缩，原始数据保存在磁盘
长期记忆由人工维护，模型被动读取
任务记忆由模型维护，持久化到文件系统

6.2 权衡取舍

设计选择	优点	缺点
不做向量检索	简单、无依赖	无法语义搜索历史
文件持久化	可靠、可版本控制	需要主动管理
LLM 摘要压缩	保留语义	摘要可能丢失细节

七、与 OpenClaw 的差异

维度	Claude Code	OpenClaw
长期记忆	CLAUDE.md（人工维护）	MEMORY.md + 向量检索
会话记忆	压缩摘要	自动索引到 SQLite
检索方式	无自动检索	向量 + FTS 双模式
目标	编程助手	个人 AI 助手
记忆主动性	被动读取	主动检索

八、参考资料

Claude Code 的记忆设计体现了「简单有效」的理念：用文件系统持久化，用 LLM 摘要压缩，用 CLAUDE.md 存储长期知识。没有向量数据库，没有复杂的检索系统，但足以支撑编程场景的需求。