你是不是也遇到过这种情况AI编码代理在最开始表现得像资深工程师架构分得清、命名规范、思路清晰结果让它继续改到第10个文件时它开始反复问你“这个项目用的什么数据库”“登录逻辑现在在哪层”甚至把已经废弃的接口重新捡回来。这不是模型突然变笨了而是它的上下文窗口被大量中间过程塞满了。我最近在两个中大型项目里专门做了上下文工程改造核心路线就是标题里那套先用 ChatMemory 的滑动窗口做短期记忆管理再通过 Context-mode MCP 把项目关键记忆变成代理随时可以拉取的外挂资源。这篇文章不聊空泛的概念只讲我踩过的坑、调过的参数、最终跑通的配置以及最重要的——为什么这套组合能治“失忆症”。如果你正在用 Claude Code、Cursor 这类 Agent 写代码并且已经感觉到“越改越笨”的迹象这篇值得看完。1. AI编码代理“失忆症”的根源上下文窗口是有限的生产资源1.1 上下文窗口不是内存是工作台很多人把模型的上下文窗口理解成“内存”认为只要没超出 token 上限模型就应该记得所有事情。这个类比是错的。上下文窗口更像一张长条工作台模型所有的注意力都在工作台上展开。你每和代理说一句话、代理每跑一次工具、工具每返回一次结果都会在这张工作台上留下东西。台面长度有限一旦堆满后面真正要紧的图纸就放不下了。更麻烦的是即便台面还没满模型对早期内容的关注度也会自然下降。注意力机制是软性的不会被硬性“记住”。大量实验和实际使用都指向一个现象模型对上下文开头和结尾的内容召回率远高于中间部分。也就是说就算你把窗口堆到了 90%中间那批对话很可能已经被“大脑自动降噪”了。工程上必须主动把重要信息往前推、把噪音清出去而不是指望模型自己分辨。1.2 失忆的典型症状先对照一下你有没有中招先列几个高发症状省得有人读了半天还对不上号代理反复询问已经回答过的细节比如技术栈、目录结构、命名规范。同一会话里提出相互冲突的实现方案前面讨论了方案 A过了半小时开始写方案 B而且完全不觉得有问题。改一个模块时莫名其妙破坏了另一个无关模块因为它修 bug 时根本没“看到”相关依赖。日志、编译错误、重复代码占据大量窗口真正有用的设计约束反而被挤出工作台。如果中了两条以上基本可以判定上下文管理出了问题。这个问题的危险之处在于它会让代理的输出看起来“偶发不稳定”容易误判成模型能力问题其实病根在上下文工程。1.3 为什么提示词工程救不了这个病提示词工程优化的是“单次请求”的指令质量把 system prompt 写清楚、给几个 few-shot 示例、把任务目标精确到词模型短期表现确实会更好。但编码代理是长周期任务一个任务可能要连续执行几十步。你在第 1 步给了一条高质量指令到第 15 步的时候这条指令大概率已经滑出窗口或者被淹没在大量工具输出里。上下文工程和提示词工程最大的区别在于它管的是“哪些信息应该留在窗口里、哪些应该归档、归档之后如何按需取回”。打个比方提示词工程是教你如何把话说清楚上下文工程是教你如何整理文件夹。会话越短越不需要上下文工程一旦代理连续跑半小时以上上下文工程就成了决定成败的关键。这也是为什么“让代理写个 hello world”不会出问题而“让代理维护一个老项目”总是问题百出。2. ChatMemory 滑动窗口实战我如何让代理在长会话中保持清醒2.1 ChatMemory 的核心不是记住更多而是学会忘记我给代理加的第一层改造是一个叫 ChatMemory 的记忆管理层。它本质上是一个带滑动窗口的对话记录队列维护按时间排序的交互记录每新增一轮对话就把最旧的一轮挤出去。这里有个容易混淆的点窗口滑动的单位不是“轮数”而是 token 预算。按轮数滑很好理解但因为有的轮次里塞了整段编译日志有的轮次只有一行确认按轮数滑会让窗口的实际容量忽大忽小。按 token 预算滑窗口占用量才是可控的。我最初的实现长这样class SlidingWindowMemory: def __init__(self, max_tokens: int 12000): self.max_tokens max_tokens self.items [] # 每项: {role: str, content: str, tokens: int, pinned: bool} def add(self, item: dict): self.items.append(item) used sum(i[tokens] for i in self.items) while used self.max_tokens: # 优先丢非 pinned 且最靠前的pinned 表示不可变约束 to_remove None for i in self.items: if not i.get(pinned, False): to_remove i break if to_remove is None: break self.items.remove(to_remove) used - to_remove[tokens]别看代码简单核心逻辑都在“pinned”这个标记上。后面会详细说。2.2 窗口参数怎么定不是越大越好这里给出我实测后比较稳的参数组合你可以当成起点再微调参数初始值调整说明max_tokens12000约占模型上下文上限的三分之一到一半留足生成和工具输出空间min_recent_rounds10无论 token 多紧张最近 10 轮原始对话必须保留pinned 上限20 条只允许最关键约束置顶避免“全是重点等于没有重点”summary 间隔每 10 轮将最早的历史压缩成 500 token 以内的摘要放在窗口最前部为什么 max_tokens 不直接拉满因为上下文窗口不仅要装“历史对话”还要装用户的新指令、Agent 的中间思考、工具返回的大块内容以及最终要输出的代码。你把历史塞到 90%下一步模型连思考的空间都没有了。经验法则是窗口上限 模型上下文上限 - 单次工具返回最大体积 - 生成预留再除以 2。比如 200K 上下文模型工具一次可能返回 20K生成预留 40K那么历史窗口设到 60K 左右比较安全我实际取 40K 都够用。小参数模型则要更保守。2.3 加权保留策略不是所有记忆都一视同仁滑动窗口如果只做“最近优先”会丢掉一类很要命的信息——用户曾经明确表达过的“不可变约束”。比如“数据库一律用 PostgreSQL不要用 MySQL”“所有接口走 /api/v2 前缀旧版本不许动”。这些约束可能出现在第 3 轮到第 40 轮早就被滑出去了。代理后续就容易“自由发挥”。解决方案是引入重要性加权。给每条消息打一个 importance 分数分数高的消息不会被滑出而是被移入“长期记忆区”在每次窗口重建时置顶。这个分数怎么来最轻量的做法是规则 手动标记在AGENTS.md或项目约束文件里写明“全局约束”然后把这些约束映射成 pinned对会话中出现的高频约束词“必须”“禁止”“永远”“一律”调用模型打分但不要每轮都打开销太大。只有出现疑似约束的句子时才触发一次性评估。实际操作中我更推荐“全局约束写进文件会话内只保留执行状态”的方式。因为模型打分再准也不如白纸黑字的项目规范可靠。2.4 ChatMemory 的边界滑动窗口解决了增长问题但没解决“早退”问题滑动窗口让上下文体积可控了但它本质上是在做“减法”。早期架构决策如果只留下摘要会被压成一句“项目是 xxx”真正细节全丢了。比如“为什么支付模块要独立成服务”这种决策一旦丢失代理下次就可能把支付模块塞回主应用里引发一场灾难。摘要再好也是一种有损压缩。所以我很快就意识到窗口内做滑动还是不够必须把关键记忆落到窗口外在需要时精确取回。这就是下一步引入 Context-mode MCP 的原因。3. Context-mode MCP把上下文从“包袱”变成“外挂资源”3.1 MCP 到底解决什么问题给所有工具一个统一插口MCP 全称 Model Context Protocol作用是把 Agent 能调用的一切外部能力——文件系统、数据库、浏览器、各类服务——统一成一套标准的“接口协议”。你可以把它理解成 Agent 世界的 USB-C以前每个外设都要专用线现在一根线通用。MCP 最常见的形态是工具tools让代理执行 SQL、访问网页、操作浏览器。这些都属于“让代理动手干活”。但 MCP 还有一个被低估的用途上下文供给。也就是我文章标题里说的 Context-mode——把 MCP 从“工具调用”扩展到“记忆资源调用”。代理不一定要“动手”它也可以“读取”。项目历史决策、架构文档、用户偏好、踩坑记录都可以通过 MCP 暴露成资源让代理按需拉取。3.2 两种工作模式按需拉取与主动归档我落地 Context-mode MCP 时只用了两个核心操作Pull 模式get_context(query)根据当前任务关键词拉取相关记忆片段。Push 模式save_memory(key, content, importance)在完成任务里程碑时把关键决策写入外部存储。Pull 模式解决的是“早期信息丢失”问题。每次任务开始或者代理准备改某个模块时它先按模块名检索记忆库只把相关的几条引入工作窗口。Push 模式解决的则是“信息无处可存”问题。代理每完成一个子任务就主动把决策归档然后窗口里的旧消息就能被安全删除给后面的对话腾地方。下面是一个用 FastMCP 搭建最小 Context-mode server 的示意from mcp.server.fastmcp import FastMCP mcp FastMCP(context-memory) mcp.tool() def get_context(query: str, limit: int 5) - list[dict]: 根据关键词返回最相关的项目记忆片段 # 实际逻辑向量检索 关键词过滤 return [] mcp.tool() def save_memory(key: str, content: str, importance: int 0) - None: 将一条决策记录写入长期存储importance 越高越优先返回 # 实际逻辑写入索引tags 打上 key return None这个服务可以挂到本地文件也可以接数据库或向量库。我自己的项目先用了本地 JSON 存储几百条记录后改成 SQLite再后来上了向量检索原因是记忆条数一多关键词匹配的召回率就不够用了。3.3 为什么“外挂记忆”比“全文塞进窗口”靠谱一句话回答上下文窗口有上限项目记忆可以无限增长。如果每次任务都把整个项目的AGENTS.md、架构文档、历史决策全塞进窗口那相当于把所有书全堆在工作台上想找一行关键信息反而更难。外挂记忆的本质是粗粒度过滤只把相关片段加载进来不相关的不占窗口。这就像你查资料不会把整个图书馆搬回家而是用搜索引擎返回最相关的 10 条结果。模型面对 5 条精准记忆要比面对 5000 行无关日志更容易做出正确判断。这也是“上下文工程”里“压缩—检索—注入”三件套的核心思路窗口永远有限检索负责把外部信息压缩到窗口装得下。3.4 落地中最需要注意的属性错位在把 MCP 接入代理时我踩了三个比较深的坑先说理念层面的第一个坑是检索查询词的质量。get_context返回什么完全取决于代理用什么 query 去查。如果代理只在开头查了一次“项目背景”后面改动模块 B 时也不会再去查模块 B 的决策记录那外挂记忆等于没装。解决办法是在 system prompt 里写死规则“当任务涉及某个模块或某个接口变更时先调用 get_context(该模块名)”。规则越具体检索触发越及时。第二个坑是归档内容不要二次提炼。我最初让模型把“用户要求支付功能必须用 Stripe、不要用自研渠道”压成“支付模块有要求”结果检索回来后代理完全不知道这个要求的具体内容。归档时尽量保留原文关键词和背景只增加标签不要破坏细节。第三个坑是检索结果的数量和长度都要设上限。如果 get_context 一次返回 50 条每条 2000 字那和没过滤一样窗口照样爆炸。我目前的配置是最多 5 条每条不超过 800 字。宁可少而准不要多而杂。4. 完整改造案例一个多模块项目从上下文崩溃到稳定运行4.1 改造前的翻车现场项目背景是一个中型的 Web 应用React 前端 Node 后端 PostgreSQL分三个模块持续迭代。我用 AI 代理跑了大概 40 分钟要求它依次实现“改登录鉴权方式”“新增导出功能”“调整数据库索引”。听起来很常规结果翻车记录如下代理在第 20 分钟开始反复问“鉴权逻辑现在放在哪一层”而这个问题在第 5 分钟已经回答过。实现导出功能时代理重写了一个旧的 API 路由导致已上线的客户端接口回归。调整数据库索引时代理试图把表结构也顺带改了理由是“顺手优化”但需求里根本没提。事后检查日志发现代理其实“看到”过正确信息但那些信息在窗口里被大量编译输出和重复代码冲到了中段位置模型的注意力根本没落到那里。这不是模型笨是上下文管理失效了。4.2 改造链路四步让代理重新“清醒”我的改造顺序是固定不可变约束。把技术栈、架构边界、接口规范全部写进AGENTS.md并标记为 ChatMemory 的 pinned 项确保每次会话一开始就出现在窗口最前面。搭建 Context-mode MCP server。实现get_context和save_memory记忆按模块分类每条记录带 created_at 和 importance。配置滑动窗口参数。max_tokens 设为 12000保留最近 10 轮完整对话最早历史压缩成摘要置顶。绑定归档时机。在代理完成一个可交付节点后比如成功跑通测试、完成重构调用save_memory写下决策然后把窗口内已经归档的旧消息清除。这里有个关键点什么时候触发归档不要放在每条用户消息后面会频繁打断代理工作流。也不要完全依赖代理自觉。我后来把“里程碑归档”做成了一个用户指令比如在关键节点发送/milestone代理收到指令后先总结当前进度并归档再继续下一步。这样既保留了人工控制感又不至于让归档操作污染主任务。4.3 改造后的效果对比我在相同规模的三个小迭代任务上做了对比测试数据如下指标改造前改造后会话中重复提问频率平均每 3 轮一次基本消失上下文溢出或截断次数40 分钟会话发生 4 次0 次需求一次通过率约 60%约 90%单任务 token 消耗因返工和回滚多消耗约 35%稳定可控补充说明这是我个人项目里的抽样数据不同任务类型差异很大但趋势是一致的——上下文管理规范之后代理的偶发“变笨”显著减少。4.4 最终跑通的系统长什么样改造后的工作链路可以描述成下面这条流用户需求 → 启动代理时注入 pinned 全局约束 → 滑动窗口进入正常执行 → 遇到跨模块改动时调用get_context(模块名)拉取相关记忆 → 子任务完成后调用save_memory归档关键决策 → 归档内容从窗口移除腾出空间 → 继续下一步。这个链路的核心是“入窗—执行—归档—按需取回”的闭环。入窗的是最关键的约束执行时有足够空间归档后不占用窗口需要时又能精确取回。ChatMemory 负责窗口内的“减法”Context-mode MCP 负责窗口外的“存储与检索”两者缺一不可。5. 参数调优与踩坑记录窗口长度、归档时机和 MCP 接入的边界5.1 窗口长度不是越大越好我一开始犯过贪心的毛病把 ChatMemory 窗口调到模型上下文上限的 80%心想“能多记一点是一点”。结果代理反而变呆了因为窗口后半部分塞满了旧的工具输出真正需要关注的新指令和约束被挤到视觉盲区模型开始抓不住重点。后来我把窗口上限定为模型上下文的 30% 到 50% 之间具体数值取决于单次任务的平均工具返回体积。比如一个任务经常有 10K 的构建日志那窗口就压到 12K另一个任务工具返回都很短窗口可以放到 24K。没有固定答案但有一个不错的经验公式窗口上限 模型上下文上限 - 单次工具返回最大体积 - 生成预留x 0.5。还有一个细节当工具返回超大内容时比如一次性读了个 30K 的日志文件不要让原文直接落入窗口而是先让模型做一次“摘要压缩”把摘要留窗、原文丢弃。这个操作可以在 ChatMemory 的 add 方法里加一个预处理分支专门识别超大块文本。5.2 归档时机的选择别在代理思考中途打断它我踩过的一个很实在的坑为了让记忆库尽快丰富起来我在每轮用户消息后面都加了save_memory调用。结果是代理经常在两三步操作之间插入归档动作上下文切换开销大保存的内容还是中间状态价值很低。更重要的问题是归档动作本身会引入新的对话轮次消耗 token而且会把窗口里的“当前焦点”带偏。正确的做法是“里程碑式归档”。只在这几个时刻归档成功跑通一次测试后完成一个完整重构后切换到另一个模块前用户明确要求总结时。这样归档的记录是完整的决策不是半成品。用户主动触发/milestone是其中最安全的方案因为它不会在代理最忙的时候打断思考链。5.3 MCP 接入的三个边界边界一控制检索返回量get_context如果返回太多片段就失去了上下文工程的意义。我建议日常返回不超过 5 条每条不超过 800 字。如果项目记忆已经多到需要查询更广那就提高 query 的精确度而不是增加返回条数。检索的目标是“够用”不是“全量”。边界二处理记忆过期问题这是我最严重的一次翻车代理检索到一条 3 周前的记忆里面写着“用户决定使用方案 B”于是严格按照方案 B 实现。但用户已经在两周前改口方案 A只是当时没有把新决策保存进记忆库。代理基于旧记忆做了完全错误的选择。解决办法是给每条记忆打上created_at和status字段并且告诉代理当记忆内容与用户当前明确需求冲突时优先相信用户当前需求。记忆库是辅助不是权威。我不会让代理无脑“记忆优先”。边界三权限与安全如果把 MCP server 暴露在本地问题不大但如果通过 HTTP 方式接入必须加 token 认证否则等于把项目决策记录公开在网上。另外不要把敏感凭据、密钥写进记忆库。记忆库的定位是“项目决策经验”不是密码本。5.4 我如何理解 ChatMemory 和 Context-mode MCP 的组合关系单独用 ChatMemory 滑动窗口早期信息会丢单独用 MCP 记忆库而不做窗口管理窗口内还是会塞满。这两者必须配合。ChatMemory 负责窗口内做减法Context-mode MCP 负责窗口外做持久化。真正完整的上下文工程应该是“一边滑一边存按需取”的三位一体。如果让我现在重新配置一个新项目顺序一定是这样先把不可变约束固定进AGENTS.md并 pin 住然后搭 Context-mode MCP 记忆库最后再调滑动窗口参数。顺序反了会吃亏因为问题往往出在长期记忆没有出口而不是窗口不够大。这套组合我用了大半年不能说根治了所有长会话问题但至少让代理从“金鱼记忆”进化到了“带笔记本的实习生”。虽然偶尔还是会漏记但至少翻翻笔记就能想起来这已经比之前强太多了。