Claude Code 架构——记忆系统与会话管理（01）：从 JSONL 历史到长期记忆

        Claude Code 的记忆机制需要分成三个层次理解：当前上下文、持久化会话记录、跨会话长期记忆。

当前上下文决定模型这一轮能看到什么；会话记录保存过去发生过什么；长期记忆则保存以后仍然值得使用的信息。三者相互配合，但保存范围、加载方式和生命周期不同。

一、先区分三个层次

层次	保存什么	存在什么地方	如何参与后续工作
当前上下文	本轮使用的指令、消息、文件内容、工具结果与摘要	运行时组装的模型请求中	直接参与本轮推理
会话记录	消息、工具调用、工具结果和会话元数据	本地 JSONL 及附属文件	用于恢复、回看和派生会话
长期记忆	持久规则、用户偏好、协作反馈和长期有效的信息	CLAUDE.md、Auto Memory、Agent Memory 等文件	自动加载入口，按需读取细节

用JSONL把会话持久化，把会话记录存到磁盘，不代表模型每轮都能看到完整历史。

例如，一次工具调用输出了大量日志。日志可以保存在会话记录中，但随着上下文增长，运行时可能清理较早的工具输出，或将对话压缩成摘要。磁盘记录与当前模型输入因此会出现差异。官方运行机制

二、会话记录：保存完整的工作过程

1. 默认目录结构

本地会话的典型布局如下：

~/.claude/
├── history.jsonl
└── projects/
    └── <project>/
        ├── <session-id>.jsonl
        ├── <session-id>/
        │   ├── tool-results/
        │   └── subagents/
        └── memory/
            ├── MEMORY.md
            └── <topic>.md

其中：

• <session-id>.jsonl：主会话记录，包含消息、工具调用、工具结果和元数据。

• <session-id>/tool-results/：单独保存较大的工具输出等内容。

• <session-id>/subagents/：保存子代理的会话记录。

• memory/：长期 Auto Memory，与单次会话目录分开。

JSONL 的含义是“每行一个 JSON 对象”，适合持续追加记录。它的实际格式属于产品实现细节，不宜假定每行都只是普通聊天消息。官方目录说明

默认情况下，会话目录中的 <project> 根据工作目录路径生成。Auto Memory 的项目归属则通常根据 Git 仓库确定。因此，同一仓库的不同工作树可以拥有独立会话，同时共享 Auto Memory。会话存储规则、记忆存储规则

在 Windows 中，~/.claude 默认对应 %USERPROFILE%\.claude。设置 CLAUDE_CONFIG_DIR 后，相关路径会迁移到指定配置目录。官方目录说明

2. history.jsonl 与会话 JSONL 的区别

~/.claude/history.jsonl 主要保存输入提示词及其时间、项目路径，用于历史输入检索。

它不能替代会话记录：仅有用户输入，无法还原模型回复、工具调用和执行结果。需要回看完整工作过程时，应使用会话记录或 /export。输入历史说明、会话导出说明

3. 持久化不等于永久保留

常规本地会话数据受 cleanupPeriodDays 控制，默认保留期为 30 天；Desktop、Cowork 等环境有各自的保留规则。Auto Memory 文件不参与普通会话历史的清理，通常持续保留，直到被编辑或删除。数据保留规则

因此，值得长期保存的结论，应进入长期记忆或正式项目文档，而不能仅依赖旧会话仍然存在。

三、会话管理：继续、分叉、清空与压缩

这些操作解决不同问题：

操作	用途
claude --continue	继续当前目录最近的适用会话
claude --resume	打开会话选择器
claude --resume <session-id>	恢复指定会话
/resume	在交互界面切换到已有会话
claude --resume <session-id> --fork-session	基于原历史创建新的会话 ID
/clear	开始新的空对话上下文，旧会话仍可恢复
/compact [instructions]	用摘要替换较长的对话历史
/context	查看当前上下文的占用
/rename <name>	给会话命名，便于后续查找
/export	导出可阅读的会话内容

恢复会话会继续使用原会话 ID；分叉会话则创建新 ID，并保留原会话。分叉的是对话历史，项目文件仍位于实际工作目录中，需要独立文件环境时，应另外使用 Git worktree。会话管理文档、CLI 参数说明

使用时可以遵循一个简单原则：继续同一项工作用恢复；基于已有讨论尝试另一种方案用分叉；切换无关任务用清空；同一任务的上下文过长用压缩。

压缩之后，模型保留什么？

Compaction 是上下文压缩：将较长的历史整理成摘要，为后续工作腾出空间。它会保留关键进展，但不能保证所有细节都无损保留。

压缩后，项目根目录的 CLAUDE.md、无路径限制的规则和 Auto Memory 等内容会重新注入；子目录指令与路径相关规则，则在再次读取相应文件时加载。上下文与压缩说明

可以通过指令明确摘要重点：

/compact 保留当前任务目标、修改过的文件、已经验证的结果，以及尚未解决的问题

会话摘要服务于当前任务的连续性；长期记忆服务于未来会话的复用。 两者即使都保存为文本，也不能混为一谈。

四、Auto Memory：Claude 自己维护的长期记忆

1. 存储方式

Auto Memory 默认位于：

~/.claude/projects/<project>/memory/

典型内容如下：

memory/
├── MEMORY.md
├── user_preferences.md
├── feedback_testing.md
└── project_decisions.md

MEMORY.md 是入口索引，主题文件保存具体内容。同一 Git 仓库中的工作树和子目录共享这份 Auto Memory；默认情况下，它是机器本地数据，不会自动同步到其他机器。官方 Auto Memory 说明

2. 加载方式

每次新会话启动时，Claude Code 加载 MEMORY.md 的前 200 行或 25 KB，以先到者为准。

主题文件不会在启动时全部加载。Claude 根据索引判断需要哪些内容，再通过文件工具读取。因此，索引应该短小，具体信息应该进入主题文件。

一个索引条目可以写成：

- [测试反馈](feedback_testing.md)：用户对回归测试范围和验证方式的要求。

这种“索引常驻、细节按需读取”的结构，控制了启动时的上下文成本，也便于单独修改或删除一条记忆。

3. 什么值得保存？

官方文档将 Auto Memory 分为四类：user、feedback、project、reference，分别对应用户背景与偏好、协作纠正、项目外部上下文、外部信息入口。

它侧重保存未来仍有用、又无法直接从代码或 Git 历史中推导的信息，也不会保证每次会话都生成记忆。记忆内容说明

例如：

涉及线上数据库结构变更时，先提供迁移和回滚方案。

这是一项可跨会话复用的协作要求。相比之下，“刚才测试失败了一次”只是临时过程信息，需要进一步提炼后才可能成为有价值的记忆。

4. 管理与开关

使用 /memory 可以浏览和编辑记忆，并切换 Auto Memory。普通本地会话默认开启；其他运行环境可能不同。

也可以通过设置关闭：

{
  "autoMemoryEnabled": false
}

或在 PowerShell 中为随后启动的进程关闭：

$env:CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1"
claude

关闭功能后，历史会话与已经存在的记忆文件仍是不同的数据对象，不能把“关闭自动记忆”理解成“删除所有历史”。开关说明

五、用户维护的持久指令：CLAUDE.md 与 AGENTS.md

Auto Memory 保存协作中沉淀的信息；用户指令文件保存明确制定的规则。

常见位置包括：

文件	适用范围
~/.claude/CLAUDE.md	当前用户的跨项目偏好
项目根目录 CLAUDE.md 或 .claude/CLAUDE.md	项目共享规则
CLAUDE.local.md	当前项目的个人规则，应加入 .gitignore
子目录 CLAUDE.md	对应模块的局部规则
.claude/rules/*.md	拆分后的主题规则，可按文件路径生效

父级和当前目录的指令会在启动时加载；子目录指令通常在读取该目录中的文件时加载。指令文件说明

AGENTS.md 的版本边界

文件名应为 AGENTS.md。当前官方文档说明，从 v2.1.277 起支持直接读取它；默认情况下，工作目录及其上级没有项目 CLAUDE.md 或 CLAUDE.local.md 时，才采用 AGENTS.md。

需要兼容不支持直接读取的环境，可以在 CLAUDE.md 中导入：

@AGENTS.md

同一个项目同时存在两类文件时，应检查实际加载规则，避免误以为它们一定都会生效。AGENTS.md 支持说明

指令文件应该保持精简

适合常驻的内容包括测试命令、模块边界、编码约定，以及反复出现的易错点。多步骤操作流程可以放进 Skill；只针对某类文件的规则可以使用路径限定规则，减少每次会话的无关输入。扩展机制说明、官方使用建议

这些 Markdown 文件提供行为指导。必须严格执行的限制，应由权限配置、Hook 或其他程序机制落实。

六、Subagent 专属长期记忆

Subagent 是执行专门任务的子代理，通常拥有独立上下文。它的会话记录与长期记忆也需要分别理解：

• subagents/ 中的记录：某次执行发生了什么。

• Agent Memory：这个角色以后仍然需要知道什么。

1. 显式启用持久记忆

在自定义子代理定义中添加 memory：

---
name: api-reviewer
description: 检查 API 兼容性与异常处理
memory: project
---

审查接口变更前，读取已有记忆。
完成审查后，保存已确认、可复用的项目约定，并更新索引。

三个作用域对应不同目录：

memory 值	默认目录	适用场景
user	~/.claude/agent-memory/<agent-name>/	跨项目使用的角色经验
project	.claude/agent-memory/<agent-name>/	项目专属、可通过 Git 共享的知识
local	.claude/agent-memory-local/<agent-name>/	项目专属、无需提交的本地知识

每个目录都有自己的 MEMORY.md 和主题文件。Agent Memory 按角色与作用域组织，不仅绑定某一次调用。子代理持久记忆说明

2. 启动时如何接入？

启用后，子代理的 system prompt 会加入记忆目录说明和受限长度的索引内容，同时自动获得 Read、Write、Edit 工具，以完成读取、创建和更新记忆的闭环。

普通、非 fork 子代理不会自动加载主会话的 Auto Memory。fork 类型可以继承父会话及其 system prompt，但这与配置独立的 Agent Memory 仍是两种机制。

关闭 Auto Memory 总开关时，子代理的 memory 字段也不生效。子代理记忆与上下文边界

七、实践中如何分配信息

可以按信息的用途决定保存位置：

信息	建议位置
当前问题的日志、尝试过程和临时结果	会话记录
当前任务进展、未完成事项	会话上下文与摘要
每次工作都要遵守的项目规则	CLAUDE.md / AGENTS.md
用户偏好、反复纠正的协作方式	Auto Memory
专门角色积累的项目经验	Agent Memory
长期维护的设计、接口与操作说明	正式项目文档

记忆文件需要定期维护：修改过时结论、合并重复条目、给重要信息保留来源。避免把猜测、一次性的失败和未经验证的结论写成永久事实，也不要保存密钥或密码。

如果需要撤销文件修改，应使用 checkpoint 或 Git。Checkpoint 负责恢复受跟踪的文件编辑与对话状态，无法回滚数据库、部署等外部操作；它的职责与长期记忆不同。Checkpoint 说明

Claude Code 的连续性来自这些机制的配合：会话记录提供可恢复的历史，上下文管理让长任务继续推进，持久指令与长期记忆则让新会话获得经过筛选的规则和知识。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/2503_90728032/article/details/167038546