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

开始之前

你需要一个能跑的智能体循环，比如用 Claude API 构建 AI 智能体里那一个，也需要知道长窗口为什么会拉低准确率，这在上下文腐化那一课里讲过。示例用 Python 3.11 或更高版本、anthropic 包和一个 API 密钥。

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

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

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

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

1. 克隆 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。

三种工具，对付三种增长

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

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

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

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。清理会改变提示词前缀，打断提示词缓存，所以一次多清一些，才抵得上重新写缓存的开销。
• 在打印出来的那次运行里，清理从第 5 个回合开始生效，之后每个回合都会再清一次。压缩只运行了一次，也在第 5 个回合，把剩下的内容总结成约 2,839 个 token，智能体往 /memories 存了三个笔记文件，最终用 13 个回合、以 13,749 个 token 收尾。

告诉压缩该留下什么

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

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

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 上下文工程文章里的描述。
• 从 2.1.299 版起，一段 20 万 token 以上的对话闲置约 54 分钟后，Claude Code 也会在它一小时的提示词缓存过期之前把它压缩掉（见 CHANGELOG）。
• OpenAI 的 Responses API 在 context_management 里设了 compact_threshold 之后会在服务器端压缩，也可以通过 /responses/compact 按需压缩。压缩指南说它返回的压缩项是加密的、不透明的，你没法打开它，看看到底留下了什么。
• 触发值要远高于一份摘要的大小。压缩 cookbook 提醒，触发值设得太低，摘要本身就可能再触发一次压缩。

让智能体自己写笔记

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

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

把这个文件夹当作不可信的输入。记忆文件会被读回 Claude 的上下文，被人塞进去的文字就相当于一次提示词注入。记忆 cookbook 要求校验每一个路径，让 ../ 逃不出这个文件夹，也不要把密码、API 密钥和个人数据写进去。每个用户或每个项目各用一个文件夹。

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

对聊天本身做裁剪或摘要

聊天应用就算不碰任何文件，也会撞上同一堵墙，因为对话本身在变长。OpenAI 的会话记忆 cookbook 写了两种自定义会话。一种是 TrimmingSession，它继承 SDK 的 SessionABC，和 Agents SDK 那一课里搭过的 SQLiteSession 是同一个基类，只保留最近 N 个用户回合，默认是 8 个，其余的直接丢掉。另一种是 SummarizingSession，它是一个普通类，不继承 SessionABC，但自己定义了同样的四个方法。它把最近几个回合原样保留，对话超过 context_limit 个回合后，就把更早的部分折叠成一份摘要。

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

按占满窗口的东西来挑

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

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

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

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

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

Claude Code 这一侧，Claude 官方频道有一段短视频，讲什么时候用 /compact，什么时候用 /clear。

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