Claude Code 学习笔记 - Day 3: 上下文压缩与记忆系统

一、上下文压缩（Compact）系统

1. 三种压缩模式

2. 压缩 prompt 的精妙设计

结构化输出要求（9 个 section）：

1. Primary Request and Intent
2. Key Technical Concepts
3. Files and Code Sections（含完整代码片段！）
4. Errors and fixes
5. Problem Solving
6. All user messages（关键！用户原话）
7. Pending Tasks
8. Current Work
9. Optional Next Step（必须引用原话）

分析先行：要求先写 <analysis> 做思考，再写 <summary> 输出。formatCompactSummary() 会自动剥离 analysis 块，只保留 summary。

3. NO_TOOLS_PREAMBLE — 防止模型在压缩时调工具

CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.- Tool calls will be REJECTED and will waste your only turn

原因：压缩是在 maxTurns: 1 的子调用中执行的，如果模型试图调工具被拒绝，就没有输出 → 浪费一次调用。把禁令放在最前面，用大写强调后果。

4. 恢复对话的 continuation prompt

Continue the conversation from where it left off without asking the user any further questions.Resume directly — do not acknowledge the summary, do not recap what was happening.Pick up the last task as if the break never happened.

关键：禁止"好的，我继续"这种废话，直接接上。

Proactive 模式还有额外指令："你之前就在自主工作，不是首次唤醒，不要打招呼。"

二、Session Memory 系统

1. 结构化会话笔记

默认模板有 9 个 section：

• Session Title（5-10 词信息密集标题）
• Current State（当前在做什么）
• Task specification
• Files and Functions
• Workflow（常用命令和顺序）
• Errors & Corrections
• Codebase and System Documentation
• Learnings
• Key results（完整精确复制用户要求的输出）
• Worklog（步骤摘要）

2. 自动更新机制

每次压缩后触发笔记更新，prompt 规则：

• 不能改 section header 和斜体描述（模板结构必须保留）
• 只更新内容部分
• 跳过没有新信息的 section
• 要求"DETAILED, INFO-DENSE"
• 每个section 限制 ~2000 tokens
• 总预算 12000 tokens
• 永远更新 Current State（压缩后连续性关键）

3. 预算与截断

• 单 section 上限：~2000 tokens
• 总上限：12000 tokens
• 超预算时：自动在 prompt 中注入提醒，要求"aggressively shorten"
• 压缩时插入 session memory 会做 truncation，按行边界截断

三、MemDir — 持久化记忆系统

1. 四种记忆类型（封闭分类法）

2. 核心原则：只保存不可推导的信息

明确不保存：

• 代码模式、架构、文件结构 → 可以 grep/read
• Git 历史 → 可以 git log/blame
• 调试解决方案 → 代码和 commit message 有
• CLAUDE.md 已有的内容
• 当前任务状态 → 用 task/plan 工具

即使用户明确要求保存 PR 列表，也要问"什么是令人意外或非显而易见的？" — 只保存那部分。

3. 两步保存法

Step 1：写独立文件（带 frontmatter）

---name: {{memory name}}description: {{one-line description}}type: {{user, feedback, project, reference}}---{{content}}

Step 2：在 MEMORY.md 添加一行索引

- [Title](file.md) — one-line hook

MEMORY.md 是索引，不是记忆本身。限制 200 行 / 25KB。

4. Feedback 记忆的 body 结构

要求三部分：

1. 规则本身
2. Why: 原因（通常是过去的事故或强烈偏好）
3. How to apply: 何时/何地适用

为什么要 Why？→ "Knowing why lets you judge edge cases instead of blindly following the rule."

5. 信任与验证

"Before recommending from memory" section（独立 section，不在 "when to access" 下）：

• 记忆说某文件存在 → 先检查文件是否存在
• 记忆说某函数可用 → 先 grep 确认
• 用户要行动时 → 必须先验证

"The memory says X exists" is not the same as "X exists now."

Drift caveat：记忆会过时。冲突时信任当前观察，并更新/删除过期记忆。

6. KAIROS 模式：日记式记忆

长期运行会话不用 MEMORY.md 做实时索引，改为：

• 每天追加到日期文件：logs/YYYY/MM/YYYY-MM-DD.md
• 每条带时间戳
• append-only，不重组
• 夜间进程自动提炼到 MEMORY.md

7. 记忆搜索

提供具体搜索方式：

grep -rn "<search term>" ~/.claude/memory/ --include="*.md"

搜不到时才搜 session transcript（JSONL 大文件，慢）。

可借鉴的模式

Prompt 工程技巧

1. +

    分离 — 让模型先思考再输出，然后程序化剥离思考部分
2. NO_TOOLS_PREAMBLE 置顶 — 在 maxTurns: 1 场景防止浪费唯一一次机会
3. "Do not acknowledge the summary" — 压缩后恢复时禁止寒暄
4. 封闭分类法 — 只允许四种记忆类型，防止模型乱写
5. 结构化 body_template — feedback 必须有 Why + How to apply，不是自由文本
6. Header 用词影响效果 — "Before recommending from memory" 比 "Trusting what you recall" 测试效果好得多（3/3 vs 0/3）

架构技巧

1. MEMORY.md 是索引不是存储 — 200 行限制，详细内容在独立文件
2. 两步保存 + frontmatter — 结构化元数据 + 独立内容文件
3. 预算自动提醒 — 超限时在 prompt 中注入 section 大小信息
4. session memory vs memory 的分工 — session memory 是会话级，memory 是跨会话
5. 位置敏感 — 同样的文字作为独立 section vs 作为 bullet，效果差异巨大

写作风格观察

• Compact prompt 最像"需求文档"：精确的 9 点输出格式
• Session Memory prompt 最像"操作手册"：CRITICAL RULES + 结构保留提醒
• Memory Types prompt 最像"设计文档"：用 XML 结构定义类型系统 + 丰富示例
• 所有 prompt 都强调"具体 > 抽象"：不要写"数据库相关"，要写"pipeline bugs 在 Linear INGEST 项目"