1. 这个实验到底在折腾什么先把这个标题拆开看。上下文压缩指的是 AI 编码代理在长会话里因为上下文窗口有上限不得不把历史对话、代码片段、工具调用记录做摘要或截断腾出空间给新内容。AI 编码代理就是那种能自己读文件、改代码、跑命令、看报错的自动化编程助手比如 Codex 这类 CLI 工具。long_mem和engram是两种记忆机制的代称前者偏向长期记忆存储后者偏向痕迹式记忆召回。整个实验的核心问题就一句话当上下文被压缩之后代理还能不能接得上之前的工作不至于“失忆”或者“跑偏”。我之所以对这个题目感兴趣是因为我自己用 Codex 这类工具做项目时最头疼的不是它不会写代码而是它在长任务里会“断片”。你让它改一个跨十几个文件的模块前半小时它还记得你定的命名规范、接口约定、测试策略等到上下文一压缩它就开始自由发挥变量名风格变了错误处理方式变了甚至把你之前明确否掉的方案又捡回来。这不是模型能力问题是记忆衔接问题。这个实验用了 10 天、430 条公开记录来做验证说明它不是拍脑袋写个 demo而是有持续观察和记录的系统性尝试。适合谁来读如果你正在用 Codex、Cursor、Claude Code 这类编码代理做真实项目尤其是那种单次会话超过几十分钟、涉及多文件改动的任务那这篇内容就是给你写的。如果你只是偶尔让 AI 补个函数可能感受不深但只要你开始把编码代理当“半个同事”用上下文压缩后的衔接问题迟早会撞上你。我下面会从设计思路、核心机制、实操过程、问题排查几个角度把这个实验的逻辑和我自己的经验揉在一起讲。不是复述那 430 条记录而是把里面最值得抄作业的部分拆出来。2. 整体设计与思路拆解2.1 为什么上下文压缩一定会导致“接不上”先讲清楚一个底层事实所有大模型的上下文窗口都是有限的。你不可能把整个项目的所有文件、所有历史对话、所有工具输出都塞进去。当会话长度逼近上限时系统必须做取舍。常见的做法有三种滑动窗口截断、摘要压缩、关键信息抽取。滑动窗口最粗暴直接把旧内容扔掉摘要压缩是用模型把旧对话浓缩成一段话关键信息抽取则是挑出文件路径、函数签名、决策记录这类结构化信息保留。问题在于这三种方式都会丢信息。滑动窗口丢的是连续性摘要压缩丢的是细节关键信息抽取丢的是语境。编码代理最怕的就是语境丢失。比如你之前说过“这个模块不要用全局状态因为后面要支持多实例”这句话在摘要里可能被压成“避免全局状态”听起来差不多但代理再看到某个具体函数时它不一定能把这个约束和当前代码关联起来。这个实验的设计思路我理解下来是不试图阻止压缩而是让压缩后的代理能通过外部记忆机制重新“接上”。long_mem 负责存长期稳定的项目约定和决策engram 负责存短期可召回的操作痕迹。两者配合相当于给代理配了一个笔记本和一个便签墙。笔记本记大方向便签墙记刚才干了什么。2.2 long_mem 和 engram 的分工逻辑long_mem 的核心是持久化。它不依赖当前上下文窗口而是把关键信息写到外部存储里比如一个本地文件、一个向量库、或者一个结构化的 JSON。每次代理启动新会话或者上下文被压缩后它先去读 long_mem把项目级的约束加载回来。这些约束包括代码风格、目录结构约定、依赖版本、测试命令、禁止使用的 API、必须遵循的接口规范。engram 的核心是痕迹召回。它记录的是操作层面的东西刚才改了哪个文件、跑了什么命令、得到了什么报错、下一步打算做什么。engram 不需要长期保存但它需要在压缩后的短时间内能被快速检索到。你可以把它理解成代理的“工作记忆缓存”。这两者的分工很关键。如果只做 long_mem代理知道大方向但不知道刚才干到哪了容易重复劳动或者漏掉未完成的步骤。如果只做 engram代理知道刚才干了什么但不知道为什么要这么干容易在遇到冲突时做出错误决策。两者结合才能让压缩后的代理既记得“规矩”又记得“进度”。2.3 为什么选择 10 天、430 条记录这个规模10 天不算长但对于验证一个记忆衔接机制来说足够覆盖多种任务类型新功能开发、bug 修复、重构、测试补充、依赖升级。430 条公开记录平均每天 43 条说明实验者不是偶尔试一下而是高频使用并持续记录。这种规模的好处是能暴露出偶发问题比如某个特定压缩阈值下 engram 召回失败或者 long_mem 写入冲突。我自己做类似实验时前三天往往很顺因为任务简单、上下文没满。到第五天开始长任务多了压缩频繁了问题才集中出现。所以 10 天的跨度是有意义的它跨过了“蜜月期”进入了真实使用的疲劳区。430 条记录也说明实验者把每次压缩后的表现都记下来了这样才能做归因分析。2.4 方案选型的取舍为什么不直接换更大窗口的模型有人可能会问既然上下文不够换个窗口更大的模型不就行了。这个思路在理论上成立但实际中有三个问题。第一窗口再大也有上限项目大到一定程度照样会满。第二窗口越大推理成本和延迟越高编码代理需要频繁调用工具成本会迅速膨胀。第三也是最关键的窗口大不代表模型能有效利用所有信息中间部分的信息容易被忽略这就是所谓的“迷失在中间”现象。所以这个实验选择做记忆机制而不是单纯堆窗口是更务实的路线。它承认压缩不可避免然后在这个前提下想办法。这个思路我觉得是对的因为真实项目里你不可能无限扩窗口但你可以设计一套让代理自己管理记忆的流程。3. 核心细节解析与实操要点3.1 long_mem 的存储结构怎么设计long_mem 不能随便存否则读的时候找不到重点。我建议用分层结构至少分三层项目级、模块级、任务级。项目级存全局约定比如语言版本、包管理器、代码格式化规则、提交信息规范。模块级存该模块的特定约束比如“支付模块所有金额用整数分表示”“用户模块的 ID 是 UUID v4”。任务级存当前任务的临时约定比如“这次重构不改公共接口”“测试覆盖率必须达到 80%”。存储格式上JSON 比纯文本好因为代理可以直接解析字段不需要用自然语言理解去猜。但 JSON 的问题是写起来麻烦所以可以先用 Markdown 写再用一个简单的转换脚本转成 JSON。或者直接用 YAML兼顾可读性和结构化。注意long_mem 里不要存大段代码。代码会变存了也容易过期。存的是约束和决策不是实现。3.2 engram 的召回时机和触发条件engram 的关键是“什么时候去读”。如果每次操作都读开销太大如果压缩后才读可能已经晚了。我的经验是设三个触发点第一上下文使用率达到 70% 时主动写一次 engram 快照第二压缩事件发生后立即读一次 engram第三代理连续两次工具调用没有进展时读 engram 检查是不是忘了之前的步骤。engram 的内容要精简每条记录不超过三行。格式可以是时间戳、操作类型、目标文件、结果状态、下一步。比如“14:32 修改 src/auth.ts 添加 token 刷新逻辑 测试通过 待补充边界用例”。这样代理读的时候能快速定位。3.3 压缩策略的选择摘要还是抽取实验里应该试过多种压缩策略。我的建议是混合使用。对于对话历史用摘要压缩因为对话的细节不重要重要的是决策和结论。对于代码和工具输出用关键信息抽取因为代码的细节很重要摘要会丢关键行。对于错误日志保留原始文本因为错误信息里的每个字都可能有用。具体操作上可以在压缩前先做一次“标记”把重要段落打上标签压缩时优先保留标签内容。这需要代理在生成内容时就意识到哪些是重要的比如它可以在写决策时加一个[KEEP]前缀。这个习惯需要训练但一旦养成压缩质量会大幅提升。3.4 代理如何知道“自己失忆了”这是一个容易被忽略的点。代理如果不知道自己丢了信息它就不会去读 long_mem 和 engram。所以需要设计一个自检机制。比如在每次压缩后代理先问自己三个问题当前任务的目标是什么有哪些约束不能违反上一步操作是什么如果任何一个答不上来就去读记忆。这个自检可以用一个简单的提示词实现比如在系统提示里加一段“每次上下文压缩后先复述当前任务目标、关键约束和上一步操作再继续工作。” 这样代理会强制自己回忆回忆不出来就会触发记忆读取。3.5 工具选型Codex 这类 CLI 代理的适配要点Codex 这类 CLI 代理的特点是它通过命令行与文件系统和工具交互没有图形界面所有状态都在文本里。这对记忆机制其实是好事因为文本容易截取和存储。但要注意Codex 的工具调用输出可能很长比如跑一次测试输出几百行这些内容会迅速占满上下文。我的做法是在工具调用后立即做一次过滤只保留关键行。比如测试输出只保留失败用例和汇总行编译输出只保留错误和警告。这个过滤可以由代理自己完成也可以用一个包装脚本完成。过滤后的内容再进入上下文能显著延缓压缩的到来。4. 实操过程与核心环节实现4.1 环境准备与基础配置先假设你用的是 Codex CLI 这类工具。第一步是确认版本和配置。运行codex --version看版本然后检查配置文件通常在~/.codex/config或项目根目录的.codex文件里。你需要配置模型端点、API 密钥、默认工作目录。如果遇到codex无法加载组织设置这类报错通常是配置文件里的组织字段和实际账号不匹配删掉该字段或改成正确的值即可。第二步是准备 long_mem 的存储位置。我建议放在项目根目录的.agent/memory/下分long_mem.json和engram.jsonl两个文件。long_mem.json存结构化约束engram.jsonl每行一条操作记录。这样代理读写都方便也容易用 git 管理。第三步是写一个初始化脚本在代理启动时自动加载 long_mem。脚本可以用 bash 或 python 写核心逻辑就是读 JSON 文件把内容拼接到系统提示里。如果你用的是支持自定义提示词的代理直接把 long_mem 内容塞进提示词就行。4.2 第一次压缩前的准备动作在上下文还没满的时候就要开始为压缩做准备。具体做法是每完成一个阶段性任务就让代理写一次 long_mem 更新。比如完成登录模块后让它记录“登录模块使用 JWTtoken 有效期 2 小时刷新接口为 /auth/refresh禁止在客户端存储 refresh token。” 这些信息写进 long_mem 后即使后续上下文被压缩代理也能通过读取 long_mem 恢复这些约束。同时engram 要开始记录操作流水。每次文件修改、命令执行、测试运行后追加一条记录。记录不需要很详细但要有足够的信息让代理回忆起上下文。比如“修改 user.service.ts 的 findById 方法改为软删除过滤测试通过”。4.3 压缩发生时的处理流程当上下文使用率达到阈值压缩触发。这时候代理应该按以下顺序操作先把当前 engram 刷盘确保最新操作记录已写入。然后执行压缩压缩策略按前面说的混合方式。压缩完成后立即读取 long_mem 和 engram。复述当前任务目标、关键约束、上一步操作。如果复述内容与 engram 记录一致继续工作如果不一致以 long_mem 和 engram 为准修正理解。这个流程看起来简单但实际执行时代理可能会跳过第 3 步因为它觉得自己还记得。所以需要在系统提示里强制要求并且用工具调用日志来验证它确实读了文件。4.4 一个完整的任务示例假设任务是“给用户模块添加软删除功能”。代理的完整流程如下第一步读 long_mem确认项目约定TypeScript 严格模式、使用 Prisma ORM、测试用 Jest、禁止直接写 SQL。第二步读 engram看之前有没有相关操作。发现昨天改过 user.service.ts但没涉及删除逻辑。第三步开始工作。先改 Prisma schema加deletedAt字段。然后改 service把findById改成过滤deletedAt: null。再改 controller加删除接口。每改一个文件写一条 engram。第四步跑测试。测试输出过滤后保留失败用例。发现有两个测试因为软删除过滤而失败需要更新测试数据。第五步上下文达到 70%写 engram 快照记录当前进度schema 已改、service 已改、controller 已改、测试待修。第六步压缩触发。压缩后读 long_mem 和 engram复述任务目标和进度继续修测试。第七步测试通过更新 long_mem记录“用户模块已支持软删除删除接口为 DELETE /users/:id软删除字段为 deletedAt”。这个示例里关键点是每次阶段性完成后都写记忆压缩后强制读取。这样即使中间压缩了多次代理也不会跑偏。4.5 参数计算压缩阈值怎么定压缩阈值不能拍脑袋。我的经验公式是阈值 窗口大小 × 0.7。比如窗口是 128k token阈值设在 90k 左右。为什么是 0.7因为要留出空间给压缩后的恢复操作和后续工作。如果设到 0.9压缩后只剩 10% 空间代理读个 long_mem 就满了又得压缩陷入死循环。另外engram 的刷盘频率也要算。如果每次工具调用都刷开销大但安全如果每 5 次刷一次开销小但可能丢最近几步。折中方案是每 3 次工具调用刷一次或者在关键操作文件写入、测试运行后立即刷。5. 常见问题与排查技巧实录5.1 代理压缩后重复劳动怎么办这是最常见的问题。代理压缩后忘了刚才已经改过某个文件又改了一遍。排查思路是看 engram 记录里有没有该文件的操作。如果有但代理还是重复了说明它没读 engram或者读了但没理解。解决办法是在 engram 记录里加一个状态字段比如status: done或status: in_progress代理读的时候优先看状态避免重复。5.2 long_mem 写入冲突怎么处理多个任务并行时long_mem 可能被同时写入导致内容覆盖。解决办法是加锁或者用追加模式。追加模式下每次写入带时间戳和任务 ID读取时按时间排序取最新值。如果冲突严重可以按任务分文件每个任务一个 long_mem 文件最后合并。5.3 压缩后代理风格突变怎么修有时候压缩后代理的代码风格会变比如之前用驼峰命名突然变成下划线。这通常是 long_mem 里的风格约束没被读到。检查 long_mem 是否包含风格规则以及代理是否在压缩后读了 long_mem。如果都正常可能是压缩时把风格相关的对话摘要丢了需要在 long_mem 里显式写死风格规则。5.4 engram 召回失败怎么排查召回失败的表现是代理问“我们刚才在干什么”。排查步骤先看 engram 文件是否存在且非空再看代理是否有读取权限然后看读取路径是否正确最后看 engram 内容是否被压缩逻辑误删。如果都没问题可能是代理的读取工具调用被跳过了需要在提示词里强制要求。5.5 常见问题速查表问题现象可能原因排查动作解决方式压缩后重复改同一文件engram 未读或状态不明检查 engram 记录和读取日志加状态字段强制读取代码风格突变long_mem 风格约束丢失检查 long_mem 内容和读取时机显式写死风格规则代理问“刚才在干什么”engram 召回失败检查文件、权限、路径修复读取流程加提示词压缩后立即又压缩阈值设太高计算阈值和窗口比例降到 0.7 以下long_mem 内容过期未及时更新对比当前代码和记忆阶段性任务后强制更新5.6 独家避坑技巧第一个技巧在 long_mem 里加一个“最后更新时间”字段代理读取时先看这个时间如果超过一天就提醒自己可能过期需要验证。第二个技巧engram 记录用 JSONL 格式每行一条方便追加和解析不要用一个大 JSON 数组否则每次写入都要重写整个文件。第三个技巧压缩前让代理自己总结“如果我是新来的需要知道什么才能继续”这个总结直接写入 long_mem比事后补更准确。6. 记忆机制之外代理本身该怎么配6.1 Codex 这类工具的安装和基础设置如果你还没装 Codex先确认系统环境。Windows 桌面版和 CLI 版安装方式不同CLI 版通常用 npm 或 brew 安装。安装后运行codex login登录如果登录不上检查网络和账号状态。配置文件里要设置默认模型和端点如果遇到codex无法加载组织设置把组织字段留空或填正确值。codex windows设置未完成通常是路径里有空格或权限不足换个目录即可。6.2 模型选择与端点配置Codex 支持多种模型端点。如果你用第三方端点注意模型名称要匹配比如gpt-5.6-sol这类名称如果端点不支持会报model is not supported。解决办法是查端点文档用支持的模型名。如果遇到cc switch local proxy failed while handling codex endpoint /responses通常是本地代理配置和 Codex 的请求格式不匹配检查代理的路径和请求头设置。6.3 中文支持和提示词优化Codex 对中文的支持取决于模型。如果模型中文能力强直接用中文提示词没问题。如果中文能力弱建议用英文写系统提示但 long_mem 和 engram 可以用中文因为它们是给代理读的代理能理解就行。提示词里要明确要求代理在压缩后读记忆并且用中文复述这样你能快速判断它有没有接上。6.4 成本控制与调用频率编码代理的调用成本主要来自模型推理和工具执行。记忆机制会增加一些读写开销但相比重复劳动和错误修改这个开销是值得的。控制成本的关键是减少无效调用。比如工具输出过滤后上下文增长慢压缩频率低调用次数自然少。另外engram 刷盘可以用本地脚本完成不消耗模型调用。7. 这套机制还能怎么扩展7.1 从单代理到多代理协作如果多个代理同时工作long_mem 可以做成共享的每个代理读写同一份项目约束。engram 则按代理分文件避免互相干扰。协作时一个代理完成的任务要写入共享 long_mem其他代理读取后就知道进度。这比让代理之间直接对话更高效因为对话会迅速占满上下文。7.2 记忆的版本管理long_mem 和 engram 都可以用 git 管理。每次更新后提交这样能追溯记忆的变化。如果发现某次压缩后代理行为异常可以回滚到之前的记忆版本对比差异。这个做法在调试记忆机制时特别有用。7.3 自动化的记忆质量检查可以写一个脚本定期检查 long_mem 里的约束是否和当前代码一致。比如 long_mem 说“使用 Prisma”但 package.json 里已经换成 TypeORM脚本就报警。这样能防止记忆过期导致代理做出错误决策。7.4 从编码代理扩展到其他长任务场景这套记忆机制不限于编码。任何需要长会话、多步骤、上下文会压缩的场景都能用比如长文档写作、数据分析、自动化运维。核心逻辑是一样的长期记忆存约束短期记忆存进度压缩后强制召回。我在写长报告时就用类似方法让 AI 先读大纲和风格要求再写每一节写完一节更新进度效果比一次性生成好很多。7.5 未来可以尝试的方向一个方向是用向量检索做 engram 召回而不是简单的文件读取。这样代理可以根据当前任务语义召回最相关的历史操作而不是按时间顺序读。另一个方向是让代理自己决定什么时候写记忆而不是按固定频率。这需要代理有更好的元认知能力知道哪些信息未来会用到。目前来看固定频率加关键操作触发是更稳妥的方案。我个人在实际操作中的体会是记忆机制的关键不在于技术多复杂而在于执行是否严格。代理很容易“自信地忘记”所以必须用提示词和工具调用日志双重约束。踩过几次坑之后我现在每次压缩后都会手动检查代理有没有读记忆文件确认它复述的任务目标和我理解的一致再让它继续。这个习惯虽然多花几秒钟但能避免后面几十分钟的跑偏。