做AI编码代理调优这一年多，我踩过最大的坑不是它写错代码，而是它干到一半突然失忆。上下文窗口看着有20万token，听着大，可真跑起来完全不够看——几十轮对话、几百次工具调用、一堆文件扫描结果，很快就顶到天花板。一旦触发上下文压缩，代理就像被拉去做了一场“脑叶切除术”：它还认得最近几轮对话，但你是谁、项目是什么架构、刚才改到第几行、你反复强调过哪些约束，全被切得干干净净，什么都不剩。
为了从这种“术后失忆”里活下来，我把两套老古董哲学请了出来：一套是Unix init.d的启动顺序机制，一套是电影《记忆碎片》里的外部化记忆思路。组合打完，我的AI编码代理现在对上下文压缩基本免疫，压缩之后还能无缝续上进度。这套方案不挑代理、不挑项目，纯靠文件组织和一套启动习惯。这篇就把完整思路和实战配置拆开给你看。
1. 先搞清楚：AI编码代理是怎么“失忆”的
1.1 上下文窗口的物理极限
想解决失忆，得先明白大模型的工作方式。一个编码代理本质上是个拿着工具箱的对话机器人：它一边跟你聊，一边调工具去读文件、搜代码、跑命令，每做一步，都会把新的内容追加进自己的上下文窗口。而大模型的“工作记忆”只有这个窗口——超出窗口范围的内容不参与注意力计算，模型根本看不见。
20万token听起来很大，我们来算一笔账。一个普通代码文件一次性读进来，少则两三千token，多则上万；一个目录扫描结果试试看，轻轻松松上千token；一次测试执行的输出更恐怖，经常直接把几万token烧掉。我实际用下来，代理干活干得稍微深入一点，一次会话烧掉10万token是家常便饭，跑到15万以上也很常见。也就是说，上下文不是慢慢用光的，是“几下就烧光”的。这不是夸张，是数着token算出来的结果。
更麻烦的是，token消耗往往集中在你最需要它记住的时刻。你花大代价喂给它一堆代码和日志，换来的理解、判断和决策，恰恰是在上下文接近满溢、即将被压缩的时候才刚形成。这就像一台机器刚学会操作手册，下一秒电源就被拔了。
1.2 “脑叶切除术”到底切掉了什么
窗口满了，各家处理方式大同小异：要么静默丢弃最早的内容，要么把历史对话自动折叠成一段摘要。听起来很合理，但真正丢掉的往往是最不该丢的东西。我自己复盘过几次典型的失忆现场，总结了四个“高危丢点”。
第一是核心目标。代理只记得自己“在改代码”，却忘了这次大目标是“给支付模块增加幂等处理”。第二是硬性约束。用户明明白白交代过“不要动数据库层的表结构”，压缩之后代理又开始顺手调整数据库，你需要花好多轮才能把它拉回正轨。第三是当前进度。改到文件A第120行，下一步正要给服务B补测试，压缩后代理从头扫描项目，重新猜了一遍当前在做什么。第四是历史决策。为什么选方案A不选方案B，当时讨论半天才定下来，压缩后它又绕回方案B重新分析，白白烧掉大量token。
“脑叶切除术”这个比喻一点都不夸张。压缩切掉的不是零散细节，而是方向感、约束和进度——这三样恰恰是长时间编码任务里最不能缺的东西。方向丢了，代理就乱逛；约束丢了，代理乱改；进度丢了，代理永远在原地打转。
1.3 压缩免疫的核心命题
既然压缩不可避免，问题就不是“怎么不让它压缩”，而是“压缩之后怎么让它快速恢复”。我在设计方案之前，先把自己的目标拆成了三条硬标准。
第一条，关键信息必须外部化。所有需要跨会话记住的东西，都要写进项目文件里，而不是只存在对话里。对话里的内容压缩了就没了，文件里的内容还在硬盘上，谁也删不掉。第二条，恢复路径必须自动化。代理开新会话之后，要能自己找到并加载这些外部信息，不能靠用户手把手喂。第三条，信息之间必须可自洽。记忆文件可以有多份，但它们的优先级、时序、范围要明确，不能互相打架。
这三条标准其实是逼着你想清楚“记忆存在哪、怎么找、怎么用”。想明白了，下面的方案就是水到渠成的事。
2. 两种记忆哲学的启发：init.d 与《记忆碎片》
2.1 为什么偏偏是Unix init.d
用过Linux的人应该都记得，低版本的SysV init在系统启动时会遍历 /etc/init.d 目录，按文件名顺序依次执行里面的脚本，01开头的先跑，99开头的后跑。这套机制最精彩的地方在于它的哲学：不管上一次关机时系统处于什么乱七八糟的状态，每次开机，所有脚本都从第一行重新执行一遍，按确定的顺序把系统拉回一个确定的状态。
这套“每次开机都重跑一遍”的逻辑，和AI编码代理简直是绝配。代理每开一个新会话，本质上就是一次“系统启动”——窗口里空空如也，之前所有状态全没了。如果我能给每个项目准备一个类似init.d的启动目录，让代理在会话一开始就按顺序把角色、项目背景、约定、当前任务全部加载进来，那它就等于每次都从“开机脚本”走到正常状态，不管上一次对话的结局多破碎。
关键细节是文件命名要带数字前缀，比如00、10、20。这不止是为了排序好看，更重要的是给代理一个明确的执行顺序：先读基础设定，再读项目信息，再读工作进度，最后读禁区。顺序本身就是信息，它让代理知道哪些内容是地基、哪些是当前焦点。
2.2 《记忆碎片》教会我的外部化记忆
电影《记忆碎片》讲的是一个失去长期记忆能力的人如何破案。因为记不住事，他把所有关键线索写在纸条上、照片背面，甚至把最重要的信息纹在身上。别人靠脑子记，他靠外部载体记。每一次醒来，脑子都是空的，但只要顺着纸条和照片，他就能重新接上因果链条，继续追查真相。
这给我的启发非常直接：AI代理的上下文窗口就是“短期记忆”，每次压缩就像一次短期记忆清空。我们没法阻止清空，但可以学主角的做法——把所有关键状态写在“外部纸条”上。代理不需要在脑子里记住自己做过什么，它只需要知道“该去哪里找到自己做过什么的记录”。
具体落地就是一组记忆文件，包括进度账本、决策日志、状态快照。代理每次开工前先翻这些文件，就像主角醒来先翻口袋。上下文里只留一句轻量提示：项目记忆放在.agent-memory/下面，开工前必须全部过一遍。这比把几万字背景全塞进提示词要省token得多，也更可靠。外部纸条不会因为对话折叠而消失。
2.3 核心设计原则
把init.d和《记忆碎片》合起来，我总结出四条设计原则。这四条原则是后面所有实现的地基，也是我调了好几月才稳定下来的条条框框。
- 幂等启动。每次新会话，代理都执行同一个启动流程，不管上次对话结束在哪个奇怪的时间点，不依赖任何记忆残留。这一步想明白了，压缩就不可怕了，因为启动流程会把代理重新带到轨道上。
- 外部优先。凡是需要跨会话记住的信息，一律落盘。对话里聊得再透彻，只要没写进文件，就当它不存在。
- 顺序加载。记忆按编号优先级加载，防止代理只读最新进度，漏了基础规则和禁区。基础规则漏了，代理就容易跑偏；禁区漏了，极可能就是灾难。
- 可审计状态。状态文件要能让代理核对自己现在进行到哪一步、下一步动作是什么，而不是靠它自己从头分析。可审计意味着代理能回答“我现在在哪”，而不是“我觉得我在哪”。
这四条原则说起来简单，落地时我踩了不少坑。下面直接上一套完整目录结构和启动配置。
3. 落地：搭建一套“压缩免疫”的记忆骨架
3.1 项目文件清单与目录规划
我用的目录结构长这样：
project_root/ ├── .agent-memory/ │ ├── boot/ │ │ ├── 00-role.md │ │ ├── 10-project.md │ │ ├── 20-conventions.md │ │ ├── 30-current-task.md │ │ ├── 40-progress.md │ │ └── 90-freeze.md │ ├── state/ │ │ ├── ledger.json │ │ ├── decisions.log │ │ └── checkpoints/ │ └── RULES.md └── (项目正常代码目录)每个文件的用途我拆开解释一下。boot/ 是启动目录，相当于代理世界的init.d，里面每个文件都是一个“启动项”。RULES.md 是整个系统的中央规则文件，只有一页，写最不可违背的约定，适合代理高频翻阅。state/ 存放动态记忆，对应《记忆碎片》里的纸条和照片，内容会随任务进展频繁更新。checkpoints/ 是每个阶段完工时的手动快照，专门用来兜底。
这套结构里最关键的纪律是：boot/ 是只读的“宪法”目录，原则上代理不得修改；真正天天变的是 state/ 下的动态文件。静态规则和动态状态必须分开存放。如果不分开，规则文件很快就会被代理改得面目全非，等于宪法被天天修订，一旦改错方向，整个恢复体系就崩溃了。
3.2 编写每次会话都会执行的启动脚本
启动脚本不需要写成真正的bash代码，AI代理直接读Markdown就够。关键在于内容要写成指令式的、命令式的，而不是背景介绍式的。我来展示几个实际能用的模板。
00-role.md 最简单，通常一两段话：
你是本项目的编码代理。你的角色是资深工程师，负责在本项目内完成用户下达的编码任务。 无论你上一段对话经历了什么，现在你回到项目现场。开工前必须依次读取 boot/ 目录下所有文件，再读取 state/ 目录下的动态记忆文件。 你不允许跳过上述流程，否则视为违规。为什么用“必须”“不允许”这种强字眼？因为我实测对比过，LLM对祈使句的遵循率远高于陈述句。很多人写“你可以参考一下项目背景”，代理读完就当参考，压缩一出全忘；换成“必须依次读取”，代理执行的概率大幅提升。指令式的语气不只是风格问题，它是启动流程能被真正执行的前提。
10-project.md 记录项目静态背景。比如项目用什么语言、核心模块有哪些、目录怎么组织、构建和测试命令是什么。20-conventions.md 记录代码约定，包括命名风格、错误处理习惯、测试要求、数据库限制等等。
30-current-task.md 是最重要的文件，它就是当前任务的“唯一真相”。里面明确写当前在推进什么目标、已完成到哪一步、下一步动作是什么。这个文件每次任务有进展都要更新，是记忆碎片系统的主干。40-progress.md 是里程碑列表，记录哪些子任务已关闭、哪些还开着。即使30丢了，代理也能从40恢复大方向。
90-freeze.md 是“禁区清单”，放最后意思是让代理在决定行动前最后扫一眼。我通常列用户反复强调不能动的部分，比如“不要改数据库迁移脚本”“不要动导入路径”“重构期间不允许改测试用例”。它排在末尾，优先级最高，一旦发现冲突以这里的约束为准。
写这些文件时记住一个原则：每个文件控制在几十到一两百行以内，核心信息用列表，不写长篇大论。文件越短，代理越愿意完整读；文件越长，越容易读了一半就“视觉疲劳”，漏掉底部关键约束。我看过有人把项目背景写了一千行，代理光是读一个文件就烧掉两万token，后面根本没法干活。
3.3 设计状态文件与决策日志
状态文件是动态记忆的落点。我用的 ledger.json 长这样：
{ "project": "order-service", "updated_at": "2026-07-12T10:30:00+08:00", "current_task": "为支付模块增加幂等键检查", "status": "in_progress", "last_file": "src/payment/service.py", "last_line": 120, "next_action": "在 src/payment/test_service.py 中补充幂等场景测试", "open_issues": ["并发下重复请求的边界情况", "补偿事务的回滚日志"], "closed_issues": ["幂等键生成规则"], "constraints_applied": ["不要改数据库表结构", "不要动迁移脚本"] }注意几个关键设计。时间戳字段不是摆设，代理看到 updated_at 才知道这份状态是不是最新，不会拿三天前的进度当现状。next_action 是核心道具，压缩后代理不需要重新分析项目，照着下一动继续干就行。open_issues 和 closed_issues 用来区分进展和未竟事项，避免代理把已经完成的问题当成新问题再处理一遍。
decisions.log 是面向文本的滚动记录，每条都带时间戳和一句原因，我习惯写成这样：
2026-07-11 14:02 - 选择方案A(内部重试)而非方案B(外部消息队列)，原因：团队暂未引入消息中间件，重试成本更低。 2026-07-12 09:40 - 支付回调状态机从两态改为三态，原因：需要区分“接收”与“成功”。决策日志的价值在于，压缩后代理如果重新冒出方案B，日志会提醒它“这个问题已经讨论过了，结论是A”。减少重复决策，就是在省token、省时间、省用户的耐心。
3.4 在代理工作流中接入恢复机制
文件全摆好后，最后一步是让代理真的去用。这一步被很多人忽略：建了一堆记忆文件，代理根本不读，因为代理的默认指令里压根没有“读记忆文件”这个动作。文件写得再好，不加载等于零。
我强烈建议把启动流程写进代理工具的自定义指令入口，让它在每次会话一开始自动执行。你可以把下面这段固定指令放到代理配置里：
在你开始任何工作之前，先读取 project_root/.agent-memory/RULES.md，然后按序号读取 boot/ 目录下所有文件，再读取 state/ledger.json 和 state/decisions.log。 读取后，先用一段话向我说明：当前任务是什么、进行到哪一步、下一步是什么。如果发现文件内容缺失或冲突，先向我确认，不得自行假设。注意我加了一句“先用一段话向我说明”，这个小动作很关键。它逼着代理真的去读文件，因为要就输出内容，代理人得真看；读完以后你也能快速发现它有没有理解错。另一个必写项是“冲突先确认”，记忆文件一旦冲突，代理自行发挥反而更糟。
接入之后还有一条日常纪律：每完成一个重要动作就更新 ledger.json 和 decisions.log。建议在正常对话里明确告诉代理：每完成一个文件修改、一个测试通过、一个方案敲定，如果导致状态变化，就同步更新状态文件。一开始代理会忘，多提醒几次就变成习惯了。等它形成惯性，你会发现项目里多了一位“自动写日志”的好队友，整个记忆体系自己就能转起来。
4. 实战演示：一次完整的“术后苏醒”过程
4.1 模拟场景设定
空谈理论没用，我拿一个虚构但很典型的小项目走一遍全流程。项目叫 order-service，一个下单服务。用户让代理做一次中型改动：给支付模块增加幂等处理，包括新增幂等键、改造支付回调状态机、补测试。任务拆成三个子任务，预计要跨两个会话完成。
会话一里，代理干活很顺利。它先按启动流程读了 boot 和 state，确认了当前任务是“给支付模块增加幂等键”，也记得约束是“不要改数据库表结构”。它花了大概6万token完成了第一部分：改好了幂等键生成逻辑，更新了 ledger，记录了决策“选择内部重试方案，团队还没引入消息中间件”。到这个时候，上下文已经烧掉大约16万token，离20万窗口上限很近了。
4.2 会话一走到一半，压缩来了
就在代理准备开始第二部分、改造支付回调状态机的时候，上下文触发了压缩。系统把早前的大量对话折叠成了一份几百字的摘要。代理的即时感受是：它还隐约记得“最近几条工具结果”，但项目整体目标、用户身份、根本约束，都快在折叠摘要里变得模糊了。
如果你没有记忆系统，接下来大概率会发生这样的事：代理重新读一遍整个项目目录，重新猜测用户要什么，它靠“支付模块”“幂等处理”这些关键词开始从头设计方案。更要命的是，它可能自作主张去改数据库表结构——因为“不要改表结构”这条约束已经被折叠摘要挤到了记忆边缘。用户辛苦叮嘱的禁区，就这么被“脑叶切除术”切掉了。
但这个项目里，代理醒来后的第一步是执行启动流程。它先读 RULES.md，然后按序号读 boot 下五个文件。00-role 告诉它“你是本项目编码代理”；10-project 告诉它项目结构和模块关系；20-conventions 告诉它代码风格和测试要求；30-current-task 直接指出“当前任务：为支付模块增加幂等键检查，状态 in_progress”；40-progress 列出已关闭子任务“幂等键生成规则”和未关闭子任务“并发下重复请求的边界情况”。最后 90-freeze 再次提醒：不要改数据库表结构，不要动迁移脚本。
4.3 压扁之后，代理如何无缝续上
再配合 state/ledger.json，代理得到了完整坐标：上次改到了 src/payment/service.py 第120行，下一动是去 test_service.py 补幂等场景测试。它不需要重新分析，直接打开测试文件，照着 ledger 写的方向干活。这就像电影主角醒来后翻到一张纸条，上面写着“下午三点，去码头找那个人”，他不需要记得为什么，直接执行就行。
decisions.log 也在这个阶段派上了用场。如果代理写测试时突然想“也许应该换成外部消息队列方案”，它翻开日志就能看到 7月11日 已经决定用内部重试，原因写得很清楚。于是它不会推翻旧决策，继续保持方向一致，不会在同一个坑里反复横跳。
整个“苏醒”过程大约只花了一两分钟和几千token。如果没做记忆系统，重新分析加上重新决策可能要烧掉几万token，还得用户一遍遍地纠正。这才是“幸存”的真正含义：不是项目不塌，而是塌完之后恢复成本足够低，低到你可以当压缩没发生过。
5. 常见问题与排查技巧实录
5.1 记忆文件互相矛盾怎么办
这套方案跑久了，最常见的坑就是文件内容打架。典型场景：30-current-task 说“正在改B模块”，但 ledger.json 的 next_action 还指向A模块的老任务；90-freeze 说“不要动A文件”，20-conventions 却又写着“所有公共接口都可以改”。代理遇到这种冲突，要么随机挑一个执行，要么停下来反复问用户，直接把工作流卡死。
我的解决办法很直接：在 RULES.md 里写死一条冲突处理规则——按 boot 目录序号从大到小为准，序号越大的文件优先级越高。我把 90-freeze 放最后，就是因为它优先于一切。动态记忆里，ledger 的新条目优先于 decisions.log 里的旧条目。有了这条规则，代理遇到冲突不再纠结，按优先级处理，最多在 decisions.log 里留一句“检测到冲突，已按优先级选择XX”。这一条规则救了我不下十次。
5.2 代理不爱读记忆文件怎么办
“代理就是不读记忆文件”，这是新手最容易吐槽的问题。有些代理工具对自定义指令的遵循度确实不高，写了“必须读boot目录”，它读了个开头就跑去扫描代码了。我的排查流程分几步走。
第一步，确认指令放对了地方。很多工具支持项目级指令文件，但有些只认固定文件名，你改个名字它根本不加载。第二步，把启动指令从“建议”改成“强制动作”。“建议阅读”改成“必须依次读取”，并且加一句“读取后向我输出摘要”，这招非常有效，因为代理为了输出摘要，必须真的读过才有内容可写。第三步，加惩罚性描述：“如果未读取记忆文件就修改代码，视为违规。”LLM对高代价描述更敏感，这句话能显著提高遵循率。最后，个别顽固的代理我会把启动流程封装成一个 shell 脚本（比如 .agent-memory/boot.sh），让它先跑脚本拿输出，再汇总结果。脚本输出比纯文本指令更“硬”。
5.3 记忆膨胀与token浪费
随着项目越滚越大，ledger.json 和 decisions.log 会长得飞快。decisions.log 尤其容易变成几千行的大文档，每轮启动都要全部读一遍，token开销蹭蹭涨，这就违背了“低成本恢复”的初衷——记忆系统自己变成新的上下文炸弹。
我给了两个实操办法。第一，定期封存归档。把旧决策按月份移到 state/archive/，ledger 只保留最近30天或最近20条活跃决策。第二，给 ledger 做瘦身，每条记录压到一行以内，只留结论和一句原因，不写分析过程。checkpoints 也一样，旧快照只留最近两三个就可以，其余删掉。我大概每两周手动做一次记忆GC，一次只要十分钟，省下的token远超成本。
5.4 实用避坑清单
最后整理一个速查清单，全部来自我实操里反复踩过的坑。
- boot 目录文件不要超过7个。超过之后代理的读取顺序容易被截断，反而漏读关键文件。
- 文件命名不要用中文和空格。部分工具对路径解析有坑，统一用数字前缀加英文最稳。
- 状态文件更新必须带时间戳，否则多会话协作时代理无法判断新旧。
- 记忆文件里只写确定性结论，不写大段分析过程。分析是对话里的临时内容，结论才是要持久化的。
- 更新记忆的时机是“完成一个可验证动作之后”，而不是“对话开始前”。只读不写，记忆就会腐烂。
- 一旦发现代理输出开始偏离约束，优先检查 90-freeze 是不是被改动了。被改了就直接恢复原样。
6. 进阶：让记忆系统自我维护
6.1 给记忆加版本控制
记忆文件既然是项目的“宪法”和“纸条”，就该有版本痕迹。我建议直接把 .agent-memory/ 放进项目仓库统一管理，每次修改都会留到git记录里。想更细一点，还可以设置每天自动提交一次记忆文件，提交信息里写“记忆文件同步”。
版本控制的价值在出事的时候特别明显。某天代理把记忆改坏了，或者某份状态文件被写成了半截内容，一个 git diff 就能看到到底改了什么，快速回滚到前几天可用版本。查问题的时候还可以顺着记忆文件的演变历史还原当时的决策上下文，排查效率高很多。没有版本控制的记忆系统是裸奔。
6.2 自动检查点与滚动摘要
还有一个更进阶的做法，我强烈推荐：让代理在完成一个阶段目标后自动生成一个检查点快照。快照内容包括当前任务完整描述、已完成事项、未完成事项、关键代码文件路径、下一步计划。把快照放到 state/checkpoints/checkpoint-20260712.md 这种带日期的文件里。
这样就算整个 ledger.json 因为误操作丢了，你还有其他快照可以重建方向。再配合滚动摘要：每隔一段时间，把 decisions.log 里过期的内容压缩成一份月度摘要，把旧条目归档。两个机制配合起来，记忆系统就能自动维持在一个健康体积，既不膨胀到烧token，也不丢关键上下文。
6.3 从编码代理推广到其他长对话场景
说实话，这套方案不止适用于编码代理。我用同样的思路处理过文档写作、数据分析、教学问答等一切需要长对话的任务。核心思想永远一样：关键状态不断落盘，让每个新上下文都从外部记忆重新引导。只要记住“init.d每次开机重跑一遍、记忆碎片主角靠纸条续命”这两句话，你就掌握了一种通用于任何大模型应用的状态恢复模式。
我个人实践下来最深的一条体会是：别指望厂商把上下文压缩做到完美，也别指望代理永不出错，真正可靠的办法，是把项目的记忆从易失的对话里搬出来，放到代理可以反复触碰的外部世界里。这个思路最大的门槛不是技术，而是你能不能坚持“每完成一步就写一笔状态”这个笨功夫。笨功夫做到位了，再猛的“脑叶切除术”也只是帮你清一清缓存，而不是真的要你的命。
