# AI 智能体记忆：上下文压缩、工具结果清理和记忆工具

> AI 智能体记忆，指的是上下文窗口快满或一次会话结束时，智能体留下来的东西。压缩把整段对话换成一份摘要；工具结果清理丢掉智能体随时能重新获取的旧工具输出；记忆工具让智能体把笔记写进文件，下一次会话再读回来。三者各管一种增长。

Mindket 编辑部 · 发布于 2026-11-06 · 更新于 2026-11-06 · https://mindket.com/cn/learn/context-engineering/agent-memory

## 要点

- 先弄清窗口被什么占满，再决定用哪种办法。
- 文件随时能重新打开时，就让旧的读取结果离开窗口。
- 摘要必须保留的数字要点名写出来，否则就当它会丢。
- 记忆文件夹要小、要有条理，不放任何机密。

## 开始之前

你需要一个能跑的智能体循环，比如[用 Claude API 构建 AI 智能体](https://mindket.com/cn/learn/claude-api/build-ai-agent-claude-api)里那一个，也需要知道长窗口为什么会拉低准确率，这在[上下文腐化那一课](https://mindket.com/cn/learn/context-engineering/context-rot)里讲过。示例用 Python 3.11 或更高版本、`anthropic` 包和一个 API 密钥。

有两个词会贯穿全课。**触发值**（trigger）是某项编辑开始生效时的输入 token 数。**工具结果**是你的代码运行工具之后发回去的那个块，比如智能体要求读取的某个文件的全文。

## 看一个研究智能体怎样填满窗口

Anthropic 的[上下文工程 cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/context_engineering/context_engineering_tools.ipynb) 给智能体八篇合成的综述论文，主题是衰老研究用到的各种实验动物，每篇约 4 万 token，要求它做一份对比。不做任何上下文管理时，笔记本里打印的那次运行在五个回合内涨到了 335,279 个 token，用的模型是 Claude Sonnet 5.5。智能体早已在自己笔记里总结过的每一篇论文，到最后一个回合仍然留在窗口里。

在 100 万 token 的窗口里，这次运行能跑完，只是第一篇论文被之后读进来的所有内容压在下面。换成 20 万 token 窗口的模型，API 会拒绝下一次请求，任务半途而止。笔记本用同一批论文跑每一种方案，你能直接看到每个工具改变了什么。每次运行的各个回合加起来，要发出几十万到一百多万个输入 token。光是没有上下文管理的那次运行，五个回合加起来就有一百万左右，全部跑之前先看看你的 API 预算。

1. 克隆 [anthropics/claude-cookbooks](https://github.com/anthropics/claude-cookbooks)，以 `tool_use/context_engineering` 为工作目录，打开 `tool_use/context_engineering/context_engineering_tools.ipynb`。
2. 把 `ANTHROPIC_API_KEY` 写进 `.env` 文件，安装 `anthropic`、`python-dotenv` 和 `matplotlib`。
3. 运行基线单元格，记下它打印的上下文峰值。
4. 运行清理、压缩和记忆三个单元格。标着 CLEARING 或 COMPACTION 的行，表示该编辑在哪个回合生效。
5. 把每个峰值和基线比较，再读列出这次运行丢了什么的那个单元格。

## 每次运行留下了什么，又丢了什么

清理一共生效四次。每次它都把旧的文件内容换成一个简短的占位符，同时保留“读过这个文件”的记录。到最后，八篇论文里有七篇已经不在窗口里，智能体只能依靠自己的笔记，或者重新去读。

压缩只生效一次，在第 4 个回合，把之前的一切换成一份约 2,783 个 token 的摘要，整次运行结束时只有 5,829 个 token。笔记本随后在摘要里查找六个事实：与任务核心相关的三个都还在，比如这批动物里哪一种是寿命最短的脊椎动物；来自附录表格单个格子的三个则全部丢了。

记忆解决的是另一个问题。第二次会话如果记忆文件夹是空的，就把八篇论文全部读了一遍，包括第一次会话已经读过的那四篇。如果 `/memories` 里有第一次会话留下的笔记，它只读了四篇，峰值是 172,623 个 token。

**cookbook 各次运行的上下文峰值** 笔记本打印的每次运行最高点时窗口里的 token 数。两行记忆数据是一项后续任务，只宜彼此比较。

- 不做上下文管理: 335,279 个 token
- 工具结果清理: 173,137 个 token
- 压缩: 169,164 个 token
- 第二次会话，记忆为空: 333,977 个 token
- 第二次会话，带着记忆: 172,623 个 token

来源：[Claude cookbooks: Context engineering tools notebook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/context_engineering/context_engineering_tools.ipynb) (2026-11-06 查阅)

## 三种工具，对付三种增长

压缩作用于整段记录：用户的回合、智能体的推理、工具调用和它们的结果，全部进入同一份摘要。清理的范围要窄得多，它遍历消息列表，只替换 `tool_result` 块里的内容，不需要调用模型。记忆工具则把信息整个移出窗口，存进由你的代码保管的文件里。

| 设置 | 压缩 | 工具结果清理 | 记忆工具 |
| --- | --- | --- | --- |
| 类型 | `compact_20260112` | `clear_tool_uses_20250919` | `memory_20250818` |
| Beta 请求头 | `compact-2026-01-12` | `context-management-2025-06-27` | 无 |
| 何时生效 | 输入超过 `trigger`，默认 15 万，最低 5 万 | 输入超过 `trigger`，默认 10 万 | 模型调用它的时候 |
| 保留什么 | 整段对话的一份摘要 | 默认保留最近 3 次工具调用，用 `keep` 设置 | 智能体自己选择写下的内容 |
| 付出什么 | 原话和少见的细节 | 旧的结果，直到智能体重新获取 | 每次读写都多一次工具调用 |

## 在一次请求里同时打开三种工具

cookbook 最后一次运行把三者叠在一起用。下面的设置原样抄自那里，两个触发值都定在第一批读取之上，好让每项编辑生效得足够晚、看得清楚。再把 `{"type": "memory_20250818", "name": "memory"}` 加进 `tools`，并在你自己的代码里处理记忆命令。

````python
COMBO_CLEARING_TRIGGER = 200_000
COMBO_COMPACTION_TRIGGER = 180_000

betas=["context-management-2025-06-27", "compact-2026-01-12"],
context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": COMBO_CLEARING_TRIGGER},
            "keep": {"type": "tool_uses", "value": 6},
            "clear_at_least": {"type": "input_tokens", "value": 30_000},
            "exclude_tools": ["memory"],
        },
        {
            "type": "compact_20260112",
            "trigger": {"type": "input_tokens", "value": COMBO_COMPACTION_TRIGGER},
        },
    ],
},
````

- `exclude_tools: ["memory"]` 让清理不去碰记忆工具的读写。少了它，智能体可能忘记自己刚刚存过什么。
- `clear_at_least` 让每次清理至少腾出一定数量的 token。清理会改变提示词前缀，打断[提示词缓存](https://mindket.com/cn/learn/claude-api/claude-prompt-caching)，所以一次多清一些，才抵得上重新写缓存的开销。
- 在打印出来的那次运行里，清理从第 5 个回合开始生效，之后每个回合都会再清一次。压缩只运行了一次，也在第 5 个回合，把剩下的内容总结成约 2,839 个 token，智能体往 `/memories` 存了三个笔记文件，最终用 13 个回合、以 13,749 个 token 收尾。

## 告诉压缩该留下什么

摘要只保留它的提示词要求保留的东西。默认提示词要求在 summary 块里写下“状态、下一步、心得等等”。一旦传入 `instructions`，你的文字会完全替换默认提示词，所以它除了写明任务绝不能丢的细节，还得要求写出状态和下一步。

针对这个研究智能体，cookbook 的写法点名了探查中发现有风险的那些数字：

````python
context_management={
    "edits": [{
        "type": "compact_20260112",
        "trigger": {"type": "input_tokens", "value": 150_000},
        "instructions": (
            "Summarize this research agent transcript. Preserve every "
            "quantitative lifespan figure and effect size with its "
            "source organism, and note which documents have been read "
            "and which remain. Wrap the summary in <summary></summary>."
        ),
    }]
}
````

- Claude Code 会总结历史，保留架构决策、尚未解决的 bug 和实现细节，再带上最近访问过的五个文件继续工作，这是 [Anthropic 上下文工程文章](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)里的描述。
- 从 2.1.299 版起，一段 20 万 token 以上的对话闲置约 54 分钟后，Claude Code 也会在它一小时的提示词缓存过期之前把它压缩掉（见 [CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)）。
- OpenAI 的 Responses API 在 `context_management` 里设了 `compact_threshold` 之后会在服务器端压缩，也可以通过 `/responses/compact` 按需压缩。[压缩指南](https://developers.openai.com/api/docs/guides/compaction)说它返回的压缩项是加密的、不透明的，你没法打开它，看看到底留下了什么。
- 触发值要远高于一份摘要的大小。[压缩 cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/automatic-context-compaction.ipynb) 提醒，触发值设得太低，摘要本身就可能再触发一次压缩。

## 让智能体自己写笔记

记忆工具给 Claude 一个文件夹 `/memories` 和六条命令。存什么、什么时候存，由 Claude 决定，你的代码负责在你掌控的存储上执行每条命令。API 会自动加一段系统提示词，养成一个习惯：“做任何事之前，先查看你的记忆目录”（原文全部大写），所以新会话一开始就会读上一次留下的东西。

笔记的好坏，取决于智能体选择写下什么。cookbook 里有两句话可以引导它。第一句要求智能体只记下与你指定的主题相关的信息。第二句针对越来越乱的文件夹，要求它让内容保持“最新、连贯、有条理”，并允许它重命名或删除不再相关的文件。要跨很多次会话的工作，可以让第一次会话先搭好进度日志和检查清单，再开始正式干活，[长时间运行的智能体那一课](https://mindket.com/cn/learn/harness-engineering/long-running-agents)就是在这个模式上展开的。

把这个文件夹当作不可信的输入。记忆文件会被读回 Claude 的上下文，被人塞进去的文字就相当于一次提示词注入。[记忆 cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb) 要求校验每一个路径，让 `../` 逃不出这个文件夹，也不要把密码、API 密钥和个人数据写进去。每个用户或每个项目各用一个文件夹。

Claude Code 同时运行两套记忆。`CLAUDE.md` 放的是你写下并提交进仓库的规则，[CLAUDE.md 指南](https://mindket.com/cn/blog/claude-md-file)讲过怎么写。自动记忆放的是 Claude 为自己写的东西：从 2.1.59 版起，它会自行保存有用的上下文，用 `/memory` 管理。它的 `MEMORY.md` 索引超过 200 行或 25KB 就会被截断；从 2.1.75 版起，记忆文件带有最后修改时间，Claude 能据此分辨笔记是新是旧。

| 命令 | 作用 | 参数 |
| --- | --- | --- |
| `view` | 显示一个文件夹或一个文件 | `path` |
| `create` | 新建或覆盖一个文件 | `path`、`file_text` |
| `str_replace` | 替换文件里的一段文字 | `path`、`old_str`、`new_str` |
| `insert` | 在某一行插入文字 | `path`、`insert_line`、`insert_text` |
| `delete` | 删除一个文件或文件夹 | `path` |
| `rename` | 重命名或移动一个文件 | `old_path`、`new_path` |

## 对聊天本身做裁剪或摘要

聊天应用就算不碰任何文件，也会撞上同一堵墙，因为对话本身在变长。OpenAI 的[会话记忆 cookbook](https://developers.openai.com/cookbook/examples/agents_sdk/session_memory) 写了两种自定义会话。一种是 `TrimmingSession`，它继承 SDK 的 `SessionABC`，和 [Agents SDK 那一课](https://mindket.com/cn/learn/openai-api/openai-agents-sdk)里搭过的 `SQLiteSession` 是[同一个基类](https://github.com/openai/openai-agents-python/blob/main/src/agents/memory/sqlite_session.py)，只保留最近 N 个用户回合，默认是 8 个，其余的直接丢掉。另一种是 `SummarizingSession`，它是一个普通类，不继承 `SessionABC`，但自己定义了同样的四个方法。它把最近几个回合原样保留，对话超过 `context_limit` 个回合后，就把更早的部分折叠成一份摘要。

裁剪可以预测，也不增加延迟，但用户会发现它对更早的事情突然“失忆”。摘要能保住长程记忆，代价是每次刷新都要多调用一次模型，而且一个错误的事实会被一轮轮带下去，cookbook 把这叫作上下文中毒。它的建议是：工具调用多、任务彼此独立的，用裁剪；长时间的规划或分析对话，用摘要。

## 按占满窗口的东西来挑

加任何一种工具之前，先问清楚你的智能体到底是哪种问题，因为每加一层，就多一些要调的设置和要追查的相互影响。cookbook 把不同的工作负载对应到首选方案：

每次会话都应该从头开始时，就不要用记忆，比如面向用户、每段对话都必须彼此独立的聊天机器人。会话本来就放得下时，就不要用压缩，否则是拿细节去换根本用不上的空间。智能体需要把几段文字并排比较、又没法快速重读回来时，就不要用清理。从一开始就少载入一些，是这件事的另一半，[按需载入上下文](https://mindket.com/cn/learn/context-engineering/just-in-time-context)讲的就是它。

| 如果你的智能体 | 先试 | 留意 |
| --- | --- | --- |
| 会话要持续几天或几周 | 记忆工具 | 事实变了以后笔记过时 |
| 有很大、但能重新获取的工具结果 | 清理 | 智能体重读刚被清掉的内容 |
| 主要是对话和推理 | 压缩 | 数字在摘要里被概括掉 |
| 有无法重新获取的工具结果，比如上传的文件 | 用压缩而不是清理 | 摘要能把这些结果保留到什么程度 |
| 会话一直远小于窗口 | 不用压缩 | 丢掉了本不必丢的细节 |

## Andrej Karpathy 怎样让模型打理它自己的维基

Andrej Karpathy 是 OpenAI 的创始成员之一，他在 2026 年 4 月 2 日[发帖](https://x.com/karpathy/status/2039805659525644595)谈到由 LLM 替他搭建的知识库。文章和论文等原始资料放进一个 `raw/` 文件夹，模型把它们编译成一个由 Markdown 文件组成的维基，里面有摘要、概念页和相互链接。他那份研究维基已经有大约 100 篇文章、40 万个单词。他原以为得用上复杂的 RAG，结果在这个规模上，模型维护的索引文件和简短摘要，已经足够让它找到需要的内容。

两天后，他把这个想法[写成一份文件分享出来](https://x.com/karpathy/status/2040470801506541998)，让你自己的智能体照着搭。[那份 gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 又加了三样东西：智能体最先读的 `index.md`，只能追加的 `log.md`，以及 `CLAUDE.md` 或 `AGENTS.md` 这样的结构说明文件。`/memories` 要想长期好用，也是这个样子：先读索引，笔记归智能体所有，定期做一次检查，找出互相矛盾和已经过时的说法。在记忆文件夹里的文件超过寥寥几个之前，就把这三样配齐。

Claude Code 这一侧，Claude 官方频道有[一段短视频](https://www.youtube.com/watch?v=eW3oTyfeWZ0)，讲什么时候用 `/compact`，什么时候用 `/clear`。

> 你几乎从不手动写或改这个维基，那是 LLM 的地盘。
>
> Andrej Karpathy, AI 研究者和教育者，OpenAI 创始成员之一，引文为译文, [X](https://x.com/karpathy/status/2039805659525644595) (2026-11-06 查阅)

[![Andrej Karpathy（@karpathy）2026 年 4 月 2 日在 X 上发帖，标题是 LLM Knowledge Bases：最近我发现一件很有用的事，就是用 LLM 为各种研究课题搭建个人知识库。](https://mindket.com/blog/shots/x-karpathy-llm-knowledge-bases.webp?v=7550af1a0dcb)](https://x.com/karpathy/status/2039805659525644595)

Andrej Karpathy 在 X 上，2026 年 4 月 2 日

[Context Management in Claude Code](https://www.youtube.com/watch?v=eW3oTyfeWZ0)

Claude 官方 YouTube 频道讲解在 Claude Code 里何时用 /compact、何时用 /clear，2026 年 5 月 18 日发布。

> X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 6 日，时间为 UTC。X 用“Show more”把帖子截短了。点击截图可到 X 上打开原帖。

## 常见错误

- 把记忆工具自己的结果也一并清掉，结果智能体忘了上一个回合刚存过什么。
- 把压缩的 `instructions` 当成追加的一句话来写。它会替换默认提示词，你不要求的话，状态和下一步就没了。
- 同时使用 `context_management` 里的压缩编辑和 `runner.compact_before_next_turn()`。工具运行器会拒绝，每个运行器只能选一种。
- 把读回来的记忆文件当成可信的指令，或者让 API 密钥和个人数据落进去。
- 对很短的任务，或者需要完整审计记录的任务做压缩，丢掉的细节比腾出的空间更要紧。
- 删减 OpenAI 的 `/responses/compact` 返回的窗口，而不是原样整体传下去。

## 自己试一试

- 把 cookbook 的清理单元格跑两次，`keep` 分别设成 4 和 8。智能体重复读了多少次文件？
- 写一段压缩指令，要求保留附录里的某一个数字，再检查摘要里是否还有它。
- 从三者合用的设置里删掉 `exclude_tools`，看清理生效之后智能体会怎么做。
- 在你的某个项目里打开 Claude Code 的 `/memory`，读一读自动记忆到目前为止存了什么。

## 自测一下

1. 智能体反复读取它随时都能重新打开的文件，这些读取占满了窗口。首先该用哪种工具？

   A. 压缩
   B. 工具结果清理
   C. 记忆工具
   D. 更大的上下文窗口

   答案：B。 清理会丢掉智能体能重新获取的旧结果，保留每次调用的记录，而且自身不需要调用模型。

2. 传入你自己的指令之后，默认的压缩提示词会怎样？

   A. 你的文字追加在它后面
   B. API 把两者合并
   C. 你的文字完全替换它
   D. 第一次压缩时它仍然生效

   答案：C。 自定义指令会替换默认提示词，所以它也必须要求写出状态和下一步。

3. 清理和记忆工具一起用时，为什么要加 exclude_tools: ["memory"]？

   A. 让智能体记得自己刚刚存过什么
   B. 让记忆文件被加密
   C. 因为记忆工具需要自己的 beta 请求头

   答案：A。 少了它，清理可能会删掉记忆的读写记录，智能体就不知道自己存过什么了。

4. 在 cookbook 的研究运行里，压缩摘要丢掉了什么？

   A. 智能体读过哪些动物
   B. 它的下一步
   C. 与任务核心相关的事实
   D. 附录表格里的单个格子

   答案：D。 探查发现三个核心事实都在摘要里，三个附录细节一个也没有。

## 常见问题

### 什么是 AI 智能体记忆？

它是智能体越过一个上下文窗口、或一次会话的边界之后还能带着走的一切。在会话之内，指的是压缩和清理旧的工具结果；跨会话时，指的是智能体写进文件、之后再读回来的笔记，比如记忆工具的 `/memories` 文件夹，或者 Claude Code 的 `MEMORY.md`。

### 压缩和记忆工具有什么区别？

压缩把当前窗口改写成一份摘要，只在一次会话之内起作用，而且会丢细节。记忆工具写到窗口之外的存储里，笔记会原封不动地带进下一次会话，不过只有智能体选择存下的那些。

### 上下文编辑也能清掉旧的思考块吗？

能，前提是开启了扩展思考。记忆 cookbook 加了一项 `clear_thinking_20251015` 编辑，用 `keep` 设定保留几个回合的思考，而且它必须排在 `edits` 列表的第一位。比起腾出空间，你更看重缓存命中时，把 `keep` 设成 "all"。

### 记忆工具把文件存在哪里？

存在你的代码放的地方。这个工具运行在客户端：Claude 针对 `/memories` 下的路径发出 `view`、`create` 这样的命令，由你的处理程序映射到一个文件夹、一个数据库或云存储。

### Claude Code 的自动记忆和记忆工具是一回事吗？

不是。前者是 Claude Code 的一部分，笔记放在它自己的文件夹里，除非你用 `autoMemoryDirectory` 设置另指一个。后者是 Messages API 里的一个工具，每个文件放在哪里由你自己的处理程序决定。两者有一个共同的习惯：智能体给下一次会话留笔记。

## 资料来源

- [Claude cookbooks: Context engineering tools notebook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/context_engineering/context_engineering_tools.ipynb) (2026-11-06 查阅)
- [Claude cookbooks: Context editing and memory for long-running agents](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb) (2026-11-06 查阅)
- [Claude cookbooks: Automatic context compaction](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/automatic-context-compaction.ipynb) (2026-11-06 查阅)
- [Anthropic Engineering: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) (2026-11-06 查阅)
- [Claude Code CHANGELOG on GitHub](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) (2026-11-06 查阅)
- [OpenAI API docs: Compaction](https://developers.openai.com/api/docs/guides/compaction) (2026-11-06 查阅)
- [OpenAI Cookbook: Short-term memory management with sessions](https://developers.openai.com/cookbook/examples/agents_sdk/session_memory) (2026-11-06 查阅)
- [GitHub: openai-agents-python, sqlite_session.py](https://github.com/openai/openai-agents-python/blob/main/src/agents/memory/sqlite_session.py) (2026-11-06 查阅)
- [X: Andrej Karpathy on LLM knowledge bases](https://x.com/karpathy/status/2039805659525644595) (2026-11-06 查阅)
- [X: Andrej Karpathy shares the LLM Wiki idea file](https://x.com/karpathy/status/2040470801506541998) (2026-11-06 查阅)
- [GitHub Gist: Andrej Karpathy, LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (2026-11-06 查阅)
- [YouTube: Claude, Context Management in Claude Code](https://www.youtube.com/watch?v=eW3oTyfeWZ0) (2026-11-06 查阅)

[浏览 AI 智能体](https://mindket.com/cn/agents)