Claude Code 的会话历史与记忆系统

• 一、核心区别
• 二、会话历史
  • 2.1 存储结构
  • 2.2 JSONL Entry 类型
  • 2.3 /insights 命令详解
    • 数据采集
    • AI 洞察生成
    • HTML 报告
    • 实现架构
  • 2.4 /cost 命令详解
    • 输出示例
    • 数据来源
    • 与 /insights 的互补
  • 2.5 如何查询当前项目的会话
• 三、记忆（Memory）
  • 3.1 存储结构
  • 3.2 记忆类型
  • 3.3 记忆文件格式
  • 3.4 什么不该存为记忆
  • 3.5 记忆的检索
• 四、记忆是怎么被生成的
  • 路径一：主代理直接写入
  • 路径二：Archivist 后台提取代理
    • 触发条件
    • 执行流程
    • 权限隔离
    • 并发控制
    • 与主代理的缓存共享
• 五、记忆的整理：Dream
  • 5.1 触发条件
  • 5.2 整理流程（4 阶段）
  • 5.3 Dream 的权限
  • 5.4 Dream 与 Archivist 的关系
• 六、全链路：从对话到记忆到检索

Claude Code 有两套独立的数据持久化机制：会话历史（Session History） 和 记忆（Memory）。它们维度不同、用途不同、生命周期不同，但通过”提取”和”整理”两条管线连接在一起。

一、核心区别

关键点：会话历史是会话维度的——每个 JSONL 文件对应一次会话；记忆是项目维度的——同一个 git 仓库的所有会话共享同一份 memory 目录。路径中的 <cwd-hash> 是工作目录的哈希，而 memory 路径中的 <git-root> 是 git 仓库的规范路径（findCanonicalGitRoot），同一仓库的所有 worktree 共享一份记忆。

二、会话历史

2.1 存储结构

~/.claude/projects/
├── -Users-bytedance-code-myapp/     ← <cwd-hash>
│   ├── a1b2c3d4.jsonl              ← 会话 1
│   ├── e5f6g7h8.jsonl              ← 会话 2
│   └── e5f6g7h8/
│       └── subagents/
│           └── agent-x9y8.jsonl    ← 子代理记录
└── -Users-bytedance-code-other/
    └── ...

2.2 JSONL Entry 类型

每行是一个 JSON 对象，type 字段区分种类：

2.3 /insights 命令详解

/insights 是会话历史最强大的消费方式。它扫描所有会话 JSONL，提取结构化数据，调用 Opus 模型生成洞察，最终输出一个可交互的 HTML 报告。

数据采集

从每个会话的 JSONL 中提取以下维度（SessionMeta）：

AI 洞察生成

采集完成后，系统并行调用 Opus 模型生成 6-8 个洞察章节：

HTML 报告

所有洞察渲染为一个自包含的 HTML 文件，包含概览卡片、四象限快速摘要、按工作领域分类的会话统计、交互风格分析，以及每日活动热力图、语言分布、工具使用分布、每日 Token 消耗、一天中活跃时段等图表。

实现架构

/insights 触发
  │
  ├─ 1. 数据采集
  │     扫描 ~/.claude/projects/ 下所有 JSONL
  │     → 提取 SessionMeta（工具计数、语言、Token、代码行变更等）
  │     → 提取 SessionFacets（Opus 分析每个会话的目标/结果/满意度）
  │
  ├─ 2. 数据聚合
  │     aggregateData() → AggregatedData
  │     汇总所有会话的统计 + 检测 multi-clauding
  │
  ├─ 3. 并行洞察生成
  │     6-8 个 Opus 调用并行执行
  │     每个调用传入聚合数据 + 会话摘要列表
  │     → 返回结构化 JSON（project_areas / interaction_style / what_works / ...）
  │
  ├─ 4. HTML 渲染
  │     generateHtmlReport(data, insights)
  │     → 自包含 HTML（内联 CSS + 图表）
  │     → 保存到临时文件
  │
  └─ 5. 输出
        本地用户：file:// URL
        Ant 内部：上传 S3 → 返回 HTTPS URL

2.4 /cost 命令详解

/cost 显示当前会话的模型调用详情和费用。/insights 是跨会话的宏观分析，但缺少按模型拆分的调用细节；/cost 正好补上这个缺口。

输出示例

Total cost:            $1.2345
Total duration (API):  5m 30s
Total duration (wall): 12m 15s
Total code changes:    150 lines added, 30 lines removed
Usage by model:
        claude-sonnet-4:  50,000 input, 8,000 output, 30,000 cache read, 5,000 cache write ($0.45)
     claude-opus-4:  20,000 input, 3,000 output, 10,000 cache read, 2,000 cache write ($0.78)

数据来源

/cost 的数据来自内存中的实时累计（cost-tracker.ts），不是从 JSONL 重新解析。每次 API 调用返回后，addToTotalModelUsage() 即时更新计数器。因此 /cost 只反映当前会话，不含历史会话。

与 /insights 的互补

2.5 如何查询当前项目的会话

会话列表不需要完整解析 JSONL。系统采用轻量读取策略：先 stat() 获取 mtime 按时间排序，然后对候选文件只读头部 64KB + 尾部 64KB（readSessionLite），从中提取 customTitle、aiTitle、lastPrompt、summary、gitBranch、tag 等字段。

三、记忆（Memory）

3.1 存储结构

~/.claude/projects/<git-root>/memory/
├── MEMORY.md              ← 入口索引（≤200行/25KB，自动加载到 system prompt）
├── user_role.md           ← 用户记忆
├── feedback_testing.md    ← 反馈记忆
├── project_goals.md       ← 项目记忆
├── reference_links.md     ← 引用记忆
├── team/                  ← Team Memory（需 feature flag）
│   ├── MEMORY.md
│   └── coding_std.md
└── logs/                  ← 助手模式日志（KAIROS feature flag）
    └── 2026/
        └── 06/
            └── 2026-06-01.md

3.2 记忆类型

四种类型，每种有明确的保存时机和使用方式：

3.3 记忆文件格式

---
name: 用户偏好
description: 用户的工作偏好和纠正
type: feedback
---

不要 mock 数据库——上次 mock 通过但生产迁移失败了。

**Why:** 2026 Q1 事故，mock/prod 不一致掩盖了迁移 bug
**How to apply:** 集成测试必须连真实数据库

3.4 什么不该存为记忆

• 代码模式、架构、文件结构——可以从代码推导
• Git 历史——git log 是权威来源
• 调试方案——修复已在代码中，上下文在 commit message
• CLAUDE.md 已有的内容
• 临时任务细节、当前对话上下文

3.5 记忆的检索

新会话启动时，记忆通过两条路径注入上下文：

1. 自动加载：MEMORY.md 作为 system prompt 的一部分始终注入（≤200行/25KB）
2. 按需检索：findRelevantMemories() → 扫描所有记忆文件的 frontmatter → Sonnet 模型做相关性选择（最多 5 个）→ 作为 Attachment 注入

四、记忆是怎么被生成的

记忆有两条生成路径，互斥运行：

路径一：主代理直接写入

主代理的 system prompt 中包含完整的记忆保存指令。当对话中出现值得记忆的信息时，主代理直接调用 Write/Edit 工具写入 memory 目录。

特点：

• 实时性强——信息出现时立即保存
• 无额外 token 消耗——在主对话中完成
• 写入后，后台提取代理会跳过该轮（hasMemoryWritesSince 检测）

路径二：Archivist 后台提取代理

当主代理没有主动写入记忆时，系统在每轮对话结束后自动 fork 一个后台代理（Archivist）来提取记忆。

触发条件

每轮对话结束（handleStopHooks）
  → 检查：是否主代理？是
  → 检查：feature flag tengu_passport_quail 是否开启？是
  → 检查：autoMemory 是否启用？是
  → 检查：是否远程模式？否
  → 检查：主代理本轮是否已写入记忆？否
  → 检查：节流门控（tengu_bramble_lintel，默认每 1 轮触发一次）
  → 全部通过 → 启动 Archivist

执行流程

Archivist 在后台 2-4 轮完成提取：先 Read 所有可能更新的记忆文件（并行），然后 Write/Edit 写入新记忆并更新 MEMORY.md。它通过游标机制（lastMemoryMessageUuid）确保每条消息只被处理一次。

权限隔离

Archivist 的工具权限被严格限制：Read/Grep/Glob 无限制（只读），Bash 仅只读命令，Edit/Write 仅 memory 目录内的路径，其他所有工具拒绝。

并发控制

通过互斥锁（inProgress 标志）防止重叠运行；如果提取进行中又有新消息，stash 上下文，当前提取完成后自动运行一次尾随提取。

与主代理的缓存共享

Archivist 通过 createCacheSafeParams() 与主代理共享 prompt cache——相同的 system prompt、相同的 tools、相同的消息前缀。这意味着 Archivist 的 API 调用大部分 token 命中缓存，成本远低于全新请求。

五、记忆的整理：Dream

记忆会随时间积累、过时、重复。autoDream 服务定期整理记忆，保持记忆库的精炼和准确。

5.1 触发条件

每轮对话结束时检查：距上次整理 ≥ 24 小时，上次整理后有 ≥ 5 个新会话，无其他进程正在整理——全部通过则启动 Dream。

5.2 整理流程（4 阶段）

5.3 Dream 的权限

与 Archivist 相同的权限隔离——只读 Bash + 仅 memory 目录内可写。

5.4 Dream 与 Archivist 的关系

六、全链路：从对话到记忆到检索

用户与 Claude 对话
  │
  ├─ 主代理直接写入记忆？──── 是 ──→ 写入 memory/ 目录
  │                                      │
  │                                      ▼
  │                                 推进游标，跳过 Archivist
  │
  └─ 主代理未写入 ──→ Archivist 后台提取
                        │
                        ▼
                   写入 memory/ 目录
                        │
                        ▼
              ┌──── 积累 ────┐
              │               │
              ▼               ▼
         24h + 5会话      用户手动 /dream
              │               │
              ▼               ▼
           autoDream 整理（合并、去重、修剪、更新索引）
              │
              ▼
         精炼的记忆库
              │
              ▼
    ┌── 新会话启动 ──┐
    │                 │
    ▼                 ▼
  MEMORY.md        findRelevantMemories()
  自动加载          Sonnet 选最多 5 条
  (≤200行)         按需注入
    │                 │
    └────┬────────────┘
         ▼
    代理基于历史知识工作

原文链接： Claude Code 的会话历史与记忆系统 ，转载请注明来源！