最近半个月我一直在折腾一个 AI 编码代理项目的上下文管理模块起因是一个很尴尬的现场同一个编码代理在会话开头两小时内表现堪称专家能准确说出我们代码库里某个废弃接口在哪几处还有调用两小时之后它开始对着旧接口名写新代码还一本正经地告诉我这是当前最佳实践。我把同样的任务单独丢给底层模型它又能做对——问题不在模型身上在我给它的记忆里。这篇博文就是从这个教训开始的把我从 ChatMemory 滑动窗口一路做到 Context-mode MCP 上下文优化的完整过程、代码思路和踩坑记录都整理出来给同样在做 AI 编码代理上下文工程的朋友做个参考。1. 为什么编码代理的记忆比模型参数更值钱1.1 模型能力已经过剩注意力预算才是硬约束这几年编码模型的能力进步有目共睹单次对话里给出一个完整函数、一个模块甚至一次重构方案都已经不是新鲜事。但一个容易被忽略的事实是模型的能力是静态的它在你发消息那一刻就已经固定了。真正决定它能发挥多少能力的是它眼前能看到什么。代码库是一个信息密度极高的环境。一个中型的 monorepo 可能有几千个文件、几十万个符号而你只有一个上下文窗口。哪怕用 200K token 的大窗口模型随便加载几个核心模块的源码、加一份架构说明、再塞进过去两小时的对话记录窗口就已经快满了。更麻烦的是编码代理不是跑一次就结束它要在一个会话里连续完成十几步修改每一步都要依赖上一步的结论。所以我一直觉得编码代理的瓶颈不是模型笨而是记忆不够聪明。上下文工程做的事情本质上是回答一个问题在一段有限的 token 预算里怎么把当前任务最需要的信息以最高密度、最低噪声的方式放到模型面前。1.2 失忆的表象背后是上下文策略失效你遇到的AI 突然变得健忘十有八九不是模型退化而是某个关键约束被挤出了窗口。举个例子我们之前有一条规定是所有数据库时间字段统一用 UTC 存储这条规则在会话早期被明确讨论过。两小时后AI 开始写CURRENT_TIMESTAMP还附带一句注释说这里用数据库本地时间更合理。它不是在故意违反约定而是那条约定已经在窗口中被后来几十轮代码讨论给冲掉了。我把这类问题总结成三个评估维度相关性模型能否在需要时找到与当前任务相关的那段历史时效性模型是否清楚哪些约定已经过期、哪些代码是最近改的一致性模型前后的决策是否相互矛盾比如同一个接口是否出现了两种命名当这三个维度中任何一个出问题用户感知到的就是AI 能力不行。所以上下文工程不是一个优化手段而是编码代理能不能在真实项目里用起来的先决条件。这也是我为什么把它当成一个正经的系统工程来做而不是靠改两句 prompt 碰运气。2. ChatMemory 滑动窗口第一版实现与朴素策略的崩溃点2.1 滑动窗口的工作原理滑动窗口是聊天记忆里最经典、也最朴素的策略维护一个固定大小的消息队列新消息进来最旧的消息被移出去。它解决的问题非常直接——对话历史无限增长但上下文窗口有上限。如果不做任何限制一个会话跑上几个小时光是把历史消息全部拼进上下文就能把窗口撑爆更不用说留出空间让模型生成回答了。我为什么第一版先做滑动窗口因为它是唯一一个绝对不会错的起点实现简单、计算开销为零、不需要调用模型做额外加工、行为完全可预测。在上下文工程还没有成型的时候先把无限增长这个硬约束解决掉是优先级最高的事。第一版实现大概长这样用 TypeScript 写的interface ChatMessage { role: user | assistant | tool; content: string; timestamp: number; } class ChatMemory { private window: ChatMessage[] []; constructor(private readonly maxMessages: number) {} add(message: ChatMessage): void { this.window.push(message); if (this.window.length this.maxMessages) { this.window.shift(); // 把最老的挤出去 } } snapshot(): ChatMessage[] { return this.window; } }这段代码的逻辑没有任何难度maxMessages是窗口大小队列满了就移除最早的消息。你把所有历史消息的snapshot()结果拼进系统提示词一个最基础的记忆模块就算跑起来了。当年我跑通这个之后还挺得意直到第一次长会话测试被现实教育。2.2 窗口大小的取舍按条数还是按 token第一个让我纠结的问题是窗口大小到底怎么定。按消息条数可以按 token 数也可以但两者各有代价。粒度优点缺点按消息条数实现简单队列长度可控各条消息长度差异大可能出现虽然有 60 条消息但全是超大内容的情况按 token 数精确控制预算不会超限需要每个消息都有 token 估算能力驱逐逻辑要多维护一个累计值我最终选的是按条数 上限保护的组合按条数控制对话轮数的保留量但每条消息入库前做一次长度裁剪超过额定上限的内容先截断再入队。这样既保证了对话结构完整又不会让某一条特别长的工具调用结果把整个窗口的预算吃掉。一个具体的预算计算例子假设你给对话记忆分配 60K token一条普通问答消息按 1K token 估算那么窗口最多保留约 60 条消息。但如果其中混入了几段代码 diff一条可能就有 5K 甚至 10K token那 60 条的上限就明显撑不住了。所以窗口大小不应该拍脑袋定而是根据你对典型消息长度的统计结果来反推。先跑几天把消息长度分布打印出来再决定参数比一开始就追求越大越好靠谱得多。2.3 朴素滑动窗口的崩溃点上下文崩溃滑动窗口最大的问题是它用时间作为唯一的驱逐标准。一个再重要的约束只要位于窗口之外就会被毫不留情地丢掉。这导致了一个严重的现象我借用一个社区里的说法叫上下文崩溃当关键历史被挤出后模型的行为会退回到没有看过任何历史的零样本状态。在对话初期即使某个约定只出现过一次模型也会认真遵守但过了某个时间点它像失忆了一样开始凭着模型的先验知识自由发挥。更麻烦的是编码场景的上下文崩溃比通用聊天更隐蔽。通用聊天里你说过我住在北京这种事实丢了之后顶多再问一句但在编码场景里AI 不会主动问你还记得之前定过 UTC 存储的约定吗它默认你看到的就是全部然后带着残缺的信息做决策产出错误的代码。这种错误难以察觉因为在代码层面它往往是合法的、能编译的问题要在代码评审或运行测试时才会暴露。所以我在第一版跑通后很快就意识到滑动窗口只能做个兜底不是最终答案。时间线驱赶策略对通用闲聊够用但对项目级事实密度极高的编码代理来说必须把记忆的淘汰标准从时间远近升级为信息价值。3. 三个改进方向滚动摘要、分层存储、按需重放3.1 滚动摘要让被挤出去的消息换一种方式活着既然丢掉关键消息不行那么一个直觉的方案是被挤出窗口的消息先让模型总结成一段摘要再丢。这就是所谓的滚动摘要rolling summary。消息本身可以被淘汰但它的精华留在长期的摘要区后续每一轮请求都可以把摘要重新放进上下文让模型对更早的会话内容保持基本认知。这里有一个关键设计点摘要不是简单地说这段聊了什么而是要有意识地保住编码场景中的高价值信息。我给摘要模块写的指令大概包含这些要求保留具体的文件名、函数名、变量名、API 名称保留明确的架构决策及其理由保留尚未完成的任务清单和下一步计划保留用户表达过的偏好和禁忌为什么要强调这些因为模型做摘要时天然倾向于概括语义比如把 我们把UserRepository.findById改成了UserQuery.loadById原因是避免 Repository 语义混淆 概括成 我们调整了用户查询接口。表面上没错但代码里需要的恰恰是findById→loadById这个映射。摘要一旦丢了符号细节就失去了在编码场景里的使用价值。滚动摘要的代码骨架也很简单但有一个细节比第一版丰富了驱逐消息时不是立即丢弃而是先进入一个待摘要批处理区攒到一定数量后一次性调用模型生成摘要合并进长期区。3.2 分层存储短期窗口、长期事实库、任务状态滚动摘要能解决一部分问题但还不够。它本质上还是按时间顺序压缩无法做到项目级事实的长期稳定保存。比如这个项目用 pnpm 不用 npm、数据库统一 UTC 存储这种规则它跟时间线没有必然关系应该在一进入会话就被记住不应该等它被摘要时才发现。所以我后来把记忆拆成了三层各干各的层级内容保留策略使用时机短期窗口最近 N 条原始消息、工具调用记录滑动窗口触发摘要每轮都直接注入长期事实库项目约定、架构决策、符号改动映射结构化存储只增不改组装系统提示词时注入任务状态当前任务目标、已完成步骤、待办清单每轮更新每轮注入到用户消息之前这个结构解决了一个很重要的问题不同类型的信息有不同的生命周期。对话细节是短命的项目事实是长命的任务状态是当前活跃的。把三者混在一个滑动窗口里本质上是用管理短期数据的办法管理所有数据必然后者被误杀。长期事实库的写入方式也要讲究。我不会让模型在每轮对话末尾自由总结事实而是在它做出明显决策时通过一个结构化的协议让记忆管理器提取事实条目。比如 AI 在回复里写了我们用 pnpm workspace 管理依赖记忆层识别出项目事实包管理器 pnpm然后写入事实库。下次无论窗口怎么滑动这条事实都会稳定出现在系统提示词里。3.3 按需重放相关性驱动的记忆检索前两个方案都是固定拼装第三个改进是按需检索。它的思路和 RAG 非常像不要预先把所有记忆塞进窗口而是在每一轮开始时根据当前任务的目标去检索相关的历史记忆只把命中内容注入上下文。举个例子。当前任务是修改checkout流程的库存扣减逻辑记忆层就去检索与 checkout、库存、库存扣减事务 相关的历史消息、代码文件、以及之前的决策记录。那些两小时前关于登录页面样式调整的讨论和当前任务毫无关系就不该出现在上下文里。这里我要特别说明一下按需重放的检索索引不是只靠文本相似度。文本相似度对代码场景经常失灵因为两个符号名不同、但涉及同一块业务逻辑的消息字面上可能差很远。更靠谱的做法是给关键消息打元数据标签比如涉及的文件路径涉及的模块/业务领域关联的任务 ID消息类型决策、问题、代码变更、用户偏好检索时用文件路径匹配 模块标签匹配 语义相似度三者加权命中率会高很多。这一步才真正把记忆从时间轴中解放出来变成了一张可以按需查询的信息网。4. Context-mode MCP把上下文编排逻辑拆到协议层4.1 先快速过一遍 MCP 的三层关系到这里为止记忆管理的逻辑都存在编码代理进程内部本质上是客户端自己管自己的记忆。但我在实际推进中遇到了一个很现实的麻烦代理里面不是只有一个模型调用还有很多外部工具——文件读取、搜索、shell 执行——而这些工具本身也携带上下文。如果每个工具都往上下文里塞东西记忆层根本无法控制总预算。这时候 MCP 就派上用场了。MCPModel Context Protocol是一个标准协议用来连接 AI 应用Host和各种外部能力Server。基本角色有三个Host比如编码代理客户端负责持有上下文和调度模型ClientHost 内部与 MCP Server 建立连接的组件Server暴露能力的一方能力分三类原语作用我的理解Tools可执行的操作比如运行命令、改文件能干活的Resources可读取的数据比如代码文件、文档片段能查的资料Prompts可复用的提示模板把上下文组织成固定格式现成的编排模板MCP 真正吸引我的地方在于它把上下文从哪儿来这个问题从应用代码里剥离出去了。以前我要在代理的提示词构建器里写死一堆如果读取了某个资源就拼进系统提示词的逻辑有了 MCP 之后资源如何暴露、按什么格式填充都成了 Server 侧可以独立维护的配置。4.2 Context-mode 的含义以上下文构建为中心的 MCP 用法标题里写的 Context-mode MCP 不是某个官方规范里的标准名词而是我在实践里对一种 MCP 用法的概括把 MCP 当作一个上下文编排层来使用Server 不仅提供原始数据还直接提供已经加工好的上下文片段。你可以把它理解为 MCP 的一种工作模式——以上下文构建为中心而不是以工具调用为中心。在这个模式下Server 的职责不是把数据库里的数据扔出去而是把模型需要知道的事情整理成上下文。比如我的 memory-server 不会暴露原始的消息堆而是暴露这样三类资源memory://conversations/recent?limit10 memory://projects/{projectId}/facts memory://tasks/{taskId}/decisionsHost 端只要按需读取这些资源就能拿到结构化的记忆摘要而不是自己处理原始消息再决定怎么组织。换句话说加载哪些上下文、以什么顺序加载、要不要裁剪——这些决策逻辑从 Host 的提示词构建器下沉到了 MCP Server 和它上面的配置模板里。这带来一个很实际的好处你可以把上下文策略打包成一个 Server 组件在不同编码代理之间复用。今天在 Claude Code 用这套明天换别的 Host只要它支持 MCP 资源读取整个上下文工程体系就可以原样搬过去。4.3 一个 memory-server 的落地设计我在项目里实现的 memory-server 不大但结构很清晰它可以作为一个参考模板。它对外暴露三件事资源、工具、提示模板。资源侧的设计原则是单一职责、可组合。比如memory://conversations/recent专门返回最近对话的滑动窗口快照memory://projects/{id}/facts专门返回项目事实库中的关键条目。Host 端不是一次性拉走全部资源而是在每一轮根据任务类型决定拉哪几个。比如新任务是修 bug就只拉conversations/recent和tasks/{id}/decisions任务是跨模块重构就额外拉projects/{id}/facts和相关的代码文件资源。工具侧我给了一个检索接口tool: memory.query 输入参数: { query: string, top_k: number, filters: { filePath?, module? } } 输出: 按相关性排序的历史消息片段这个工具对应的就是我前面说的按需重放逻辑。Host 在组装上下文时把当前任务描述作为 query 传给memory.query拿回一段高相关的历史记忆再注入到用户消息之前。和 RAG 的区别是这里检索的源不是文档库而是这个会话自身的记忆库所以它更强调任务间的依赖关系。提示模板侧是 Context-mode 的精华。我不让 Host 端自己拼提示词而是在 memory-server 里定义了一个上下文构建器模板记忆注入模板 --- 项目事实最新 20 条 {project_facts} 当前任务 {current_task} 相关历史决策 {relevant_decisions} 当前任务状态 {task_progress} ---Host 只要请求这个模板填入变量就能得到一份格式统一的上下文片段。这样做的好处是上下文组织策略和 Host 代码彻底解耦了以后要调整排序、增减段落只改 Server 端的模板就行不需要动代理的主流程。5. 完整上下文管线的组装从用户输入到模型输入5.1 管线的数据流前面这些模块如果没有串起来只是一堆散件。我最后把它们组成了一条完整的上下文管线每一轮用户请求进来都要经过四个阶段记忆写入、上下文装配、模型调用、记忆更新。文字描述一下管线不用图表也能说清楚第一步用户消息进来后先做记忆写入判断。不是每条消息都要写入记忆简单问题、纯闲聊就不进长期区只进短期窗口。但如果这条消息修复了之前的一个 bug或者做出了一个新决策记忆管理器会提取出对应事实写入长期事实库和任务状态。第二步进入上下文装配阶段。系统提示词由固定部分角色设定、项目描述加动态部分长期事实库组成对话历史用短期窗口的snapshot()再根据当前任务调用 memory-server 的检索工具拉取相关历史组合成项目事实 当前任务 相关历史决策 最近对话的最终上下文。第三步模型调用。这个阶段不需要额外逻辑但要留一个输出钩子把模型产出的关键信息比如我决定把CartService拆成两个类捕获下来供后面更新记忆使用。第四步记忆更新。根据模型输出和工具调用结果更新任务状态、追加短期窗口、判断是否需要触发摘要必要时把新的项目事实写入长期事实库。如果这一步漏了下一轮上下文仍然读不到刚才发生的变更等于白做。5.2 关键代码上下文装配器这个装配器是整个管线的主干我用伪代码把一个简化版写出来class ContextAssembler: def assemble(self, user_message: str, task_id: str): recent self.memory_client.read_resource( memory://conversations/recent?limit10 ) facts self.memory_client.read_resource( fmemory://projects/{self.project_id}/facts ) relevant self.memory_client.call_tool( memory.query, {query: user_message, top_k: 5, filters: {task_id: task_id}} ) progress self.memory_client.read_resource( fmemory://tasks/{task_id}/decisions ) return self.assemble_prompt( system_factsfacts, task_progressprogress, recent_historyrecent, relevant_historyrelevant, user_inputuser_message, )你注意看这个装配器把从哪里读上下文的细节全部委托给了 MCP 客户端调用。它自己不知道记忆存哪、怎么索引、怎么裁剪只负责把读回来的片段拼成模型输入。这样的分层让每一块的职责都非常清楚装配器管组装memory-server 管记忆的存储与检索。5.3 效果观察与参数调整管线跑通之后我做了几轮对比观察重点看四个指标指标观察内容我这边的情况上下文容量单轮注入模型的总 token 数是否稳定从无管理的随会话增长稳定到每轮 25K~35K 区间事实召回模型是否还能正确提到早期的关键约定会话 3 小时后UTC 约定仍能稳定出现决策一致性同一接口、同一功能的命名是否前后矛盾命名反复的情况明显减少端到端延迟装配上下文增加的时间开销增加约 150ms~300ms主要是检索耗时可接受参数调整方面我最常动的是top_k和事实库条数上限。top_k太大会挤占窗口太小会漏关键信息。我实测之后倾向于把历史检索的top_k控制在 3~5 条把事实库条数控制在 20 条以内。宁可少放也不能让无关内容稀释了真正重要的决策信息。这个观察结论不一定通用但可以作为你调参时的起点。6. 踩坑实录符号名丢失、注意力稀释与记忆竞态6.1 坑一摘要把符号名平滑没了这是滚动摘要上线后遇到的第一个坑。现象是模型明明看过摘要却频繁写错接口名。我翻日志发现摘要模型把PaymentProcessor.chargeWithToken概括成了处理支付的方法符号名在概括过程中被平滑掉了。这对人类是正常的概括对代码上下文则是灾难。修复办法是双向的。一方面在摘要指令中强制声明必须原样保留所有出现的符号名宁可摘要啰嗦不能丢符号并在摘要输出格式里单独开一个symbols字段把涉及的所有符号名专门列出来。另一方面在摘要注入时做一个二次校验——如果当前任务涉及的文件路径在摘要里找不到对应的符号映射就触发一次按需检索把原始消息翻出来。我把这个机制叫做摘要置信度检查摘要可以用来提供背景但涉及具体符号的修改决策必须回到原文。6.2 坑二上下文堆得太满导致注意力稀释一开始我以为上下文工程的目标是尽可能多地保留信息所以事实库、检索结果、历史记录全都塞进系统提示词模型反而变笨了。后来发现模型在一个窗口里能真正注意到的内容是有优先级的塞入大量低相关的上下文会稀释它对当前任务关键信息的注意力。这里我要修正一下自己的认知上下文优化的核心不是塞更多是塞得更准。做过一次对比实验同一份代码修改任务一组我给了 20 条不相关历史 5 条相关历史另一组只给 5 条高质量相关历史后者的输出质量更高甚至更少出现幻觉。从那以后我把装配器的默认策略从有什么拉什么改成了只拉当前任务涉及模块的记忆并给每段注入的上下文打了优先级标签模型注意力优先落在高优先级片段上。6.3 坑三记忆写入与下一轮请求的竞态这个坑藏得很深。现象是AI 在一轮里明确做了一个决策下一轮立刻忘记了。日志查看发现决策确实被捕获了但写入长期事实库的操作是异步的在下一轮上下文装配发起时还没有落盘。竞态条件导致上一轮读不到这一轮写的窗口期。修复办法有两个层面。第一关键决策采用同步写入只有拿到写入确认才认为这一轮结束第二在装配器读取事实库时先检查本轮会话内新增的事实这个内存缓冲区把还没落盘的新增内容直接合成进提示词。这个双写策略既保证了低延迟又消除了竞态。这也提醒了我上下文工程里写完立即可读和写完持久可靠是两个独立的要求不能混在一起实现。6.4 排查方法论一套可复现的链路在踩坑过程中我总结出一个排查AI 失忆问题的固定链路每次遇到类似情况基本都能用同一套方法定位到根因而不是靠猜第一步拿到用户反馈明确 AI 忘了什么。第二步查记忆日志看这条信息在上一次被提及后是仍然存在、被摘要替换了还是被滑动窗口直接驱逐。第三步如果是被驱逐检索长期事实库和摘要区看是否能找到相关信息。第四步如果长期区里也没有说明问题出在写入侧——要么没被提取为事实要么摘要丢掉了符号细节。第五步分别对写入逻辑和摘要指令做修正再跑一个构造好的复现用例验证。关键是把记忆系统的日志做细。我在每个记忆操作里都会打一条结构化日志包含操作类型、涉及的消息 ID、是否被驱逐、是否被摘要。没有这些日志排查AI 为什么忘只能瞎猜。7. 如果你也要做上下文工程我建议先做这几件事把整套东西做完之后我有个很深的体会上下文工程不是某个单一的算法或配置它是一整套记忆系统设计。滑动窗口解决的是预算上限分层存储解决的是信息生命周期差异按需重放解决的是相关性MCP 解决的是上下文来源的统一管理。它们各自解决一个问题组合起来才是一个完整的答案。如果让我给打算入这个方向的人几条建议按优先级排序第一先埋点再做优化。上线第一天就把记忆日志打全观察真实会话里哪些消息被驱逐、哪些事实被覆盖、模型在哪一轮开始行为退化。没有数据支撑的上下文优化基本都是拍脑袋。第二从滑动窗口开始但不要停在滑动窗口。滑动窗口能解决上下文超限这个最紧急的问题但它只是底线工程。尽早把事实库和按需检索这两层加进去你会明显感觉到模型的长会话稳定性上了一个台阶。第三Symbol 级别的细节处理比架构设计更影响体验。架构再优雅如果摘要把接口名丢了用户感受到的就是AI 笨了。在编码场景的上下文工程里保住符号、保住文件名、保住具体的决策理由优先级最高。第四MCP 是值得投入的方向。把上下文编排逻辑从 Host 代码里拆出来短期内是增加了一层抽象但从复用和演进的角度看它让整套记忆方案变成了一个可独立升级的组件。我下一阶段计划做的就是多代理场景的记忆共享——多个编码代理协作同一个项目时project facts 层天然就应该由同一个 memory-server 提供服务。这个扩展方向上Context-mode 的价值会体现得更明显。我这边现在还在继续做上下文质量的自动评估目标是给每一轮注入的上下文打分低分时主动触发补充检索。这个比赛更多上下文管用得多。希望这篇把整个思考链路和实战方案讲清楚了能给正在折腾 AI 编码代理记忆系统的你一些可参考的落地方向。