Session模型与记忆：用AGENTS.md和SOUL.md构建可复现的上下文压缩方案

1. 长会话为什么会失忆Session 模型与记忆管理的真实痛点多轮对话跑久了你会发现一个很尴尬的现象前面明明说好的技术栈、命名规范、接口约定聊到第三十轮时模型全忘了甚至开始用另一套风格回答。这不是模型变笨而是上下文窗口被塞满了。Session 模型与记忆管理要解决的核心问题就是让关键信息在长会话里不丢同时把冗余历史压下去。我先把概念说清楚。Session 模型指的是把每一次对话流当成一个独立会话来管理区分「主会话」和「非主会话」前者拥有完整工具权限后者跑在受限沙箱里。记忆则是跨轮次持久化的上下文通常由两个文件承载AGENTS.md 放项目级上下文SOUL.md 放 Agent 的人格与行为约束。上下文压缩是在 token 接近窗口上限时把早期对话总结成摘要替换掉原始消息从而腾出空间继续聊。这套东西适合谁如果你在做 Coding Agent、客服机器人、多通道接入的助手或者只是想让自己的长对话不崩都用得上。它本质上是一套可复现的工程方案配置文件写死规则压缩策略可验证token 变化可量化。下面我会用可复制的 AGENTS.md / SOUL.md 片段加上压缩前后的 token 对比步骤把整条链路走一遍。你不需要先理解所有细节跟着配置和命令操作即可。2. TaoToken 前置准备Session 记忆方案接入的 API Key 与模型配置在动手写 AGENTS.md 之前得先把模型调用通道准备好。Session 记忆方案本身是应用层逻辑但它需要一个稳定的模型后端来执行总结和压缩。我用的是 TaoToken 的 API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意这个地址不带 UTM 参数配置时直接填。第一步去控制台创建 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后在 API Keys 页面新建一个密钥复制保存。这个 Key 后面要写进环境变量别硬编码到代码里。如果你还没决定用哪个模型可以先到模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试几条消息确认响应正常再往下走。第二步确认你要用的 Model ID。不同模型对长上下文的支持不一样压缩阈值也和窗口大小相关。比如你选一个 128K 窗口的模型压缩阈值可以设在 90K 左右如果窗口只有 32K阈值就得压到 24K。这个数字后面会写进配置。第三步把 Key 和 Base URL 写进环境变量。Linux/macOS 下可以这样export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的密钥 $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你打算长期跑编码类 Agent建议看一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题可以对照查。这里有个容易踩的坑Base URL 末尾不要多加/v1或斜杠不同客户端拼接路径的方式不一样多写反而会 404。我试过在某个客户端里多加了/v1结果一直报路径错误去掉就正常了。3. 可复制配置AGENTS.md 与 SOUL.md 的完整片段这一节是重点直接给可复制的配置。先建一个 Workspace 目录比如~/agent-workspace在里面放两个文件。AGENTS.md 负责项目上下文每次对话自动注入到 System Prompt。内容要精炼因为它是每轮都占 token 的。下面是我实测下来比较稳的写法# 项目说明 这是一个 Node.js 24 TypeScript Express 的后端服务。 ## 技术栈 - 运行时Node.js 24 - 语言TypeScript 5.x - 框架Express 4.x - 测试Vitest - 包管理pnpm ## 编码规范 - 使用 ESM 模块import 路径带 .js 后缀 - 所有导出函数必须有 JSDoc 注释 - 提交前必须运行 pnpm lint 和 pnpm test - 错误处理统一用 AppError 类禁止裸 throw ## 目录约定 - src/routes 放路由 - src/services 放业务逻辑 - src/utils 放工具函数 - tests 放测试文件与 src 结构镜像 ## 禁止事项 - 不要引入新的依赖除非明确说明理由 - 不要修改 tsconfig.json 的 strict 配置 - 不要删除现有测试用例SOUL.md 负责 Agent 人格定义它怎么说话、怎么决策# 人格设定 - 回答简洁直接先给结论再给理由 - 全程中文交流代码注释也用中文 - 不确定时先提问不要猜测 - 遇到破坏性操作删除、覆盖必须先确认 ## 工作方式 - 修改代码前先读相关文件 - 每次改动后说明改了哪个文件、为什么 - 如果任务超过三步先列计划再执行 ## 记忆优先级 - 用户明确说的偏好 AGENTS.md 规范 默认行为 - 如果用户要求与 AGENTS.md 冲突先提醒再执行这两个文件放在 Workspace 根目录Agent 启动时会自动读取。注入顺序是基础指令 工具定义 AGENTS.md SOUL.md 对话历史。也就是说AGENTS.md 和 SOUL.md 在对话历史之前优先级更高不容易被后续对话冲掉。如果你用的是 Claude Code 类客户端配置方式略有不同。需要在 settings 里指定 Base URL、Key 和 Model ID 三件套。以 settings.json 为例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: 你的模型ID } }注意这里 Base URL 同样不带 UTMModel ID 要和你实际选的一致。Cline 或 MCP 类工具也是同样的三件套逻辑Base URL 填https://taotoken.net/apiKey 填你的密钥Model ID 填模型标识。Codex 的 auth.json 里则是把 key 和 base_url 写进对应字段。不管哪个客户端这三样缺一不可少一个就会报认证失败。配置写完后建议先跑一次/status看当前会话状态确认 AGENTS.md 和 SOUL.md 被正确加载。如果状态里看不到这两个文件检查路径是不是放错了或者文件名大小写不对。4. 验证压缩效果token 对比与关键记忆保留测试配置好了接下来验证压缩到底有没有用。核心思路是构造一段长对话记录压缩前的 token 数触发压缩再记录压缩后的 token 数同时检查关键信息是否还在。先看自动压缩的触发逻辑。当对话 token 数超过阈值时系统会自动总结早期对话。阈值怎么定假设你用 128K 窗口的模型留 20% 余量给输出阈值设在 100K 左右比较稳。手动压缩则用/compact命令随时可以触发。下面是一组实测数据。我构造了一段约 45,000 token 的对话内容包含项目规范讨论、代码修改、测试反馈。执行/compact后Context compressed: 45,000 → 8,200 tokens (82% reduction)压缩率 82%效果很明显。但光看数字不够得验证关键记忆有没有丢。我在对话早期埋了三个关键信息技术栈是 Node.js 24、测试用 Vitest、错误处理用 AppError 类。压缩后继续提问「我们用什么测试框架」模型回答 Vitest说明记忆保留了。验证步骤可以这样操作第一步新建会话输入/new。第二步把 AGENTS.md 的内容通过对话方式确认一遍比如问「我们的技术栈是什么」让模型复述。第三步连续进行 20 轮以上的对话每轮都涉及项目细节把 token 堆上去。第四步用/status查看当前 token 数确认接近阈值。第五步执行/compact记录压缩前后的数字。第六步压缩后立即问几个关键问题检查答案是否与压缩前一致。如果你想更精确地量化可以在每轮对话后打印 token 计数。大多数客户端支持在响应里返回 usage 字段把prompt_tokens和completion_tokens记下来画一条曲线就能看到压缩前后的拐点。这里有个细节压缩不是无损的。早期对话的原始措辞会被摘要替换所以如果你需要精确引用某句话最好在压缩前把它写进 AGENTS.md 或单独存档。我的做法是把关键决策写进 AGENTS.md 的「禁止事项」或「目录约定」里这样即使对话被压缩规范依然在 System Prompt 里不会丢。另外SOUL.md 里的人格设定也会影响压缩后的表现。如果 SOUL.md 写了「不确定时先提问」压缩后模型遇到模糊问题会更倾向于反问而不是瞎猜。这一点在长会话里特别有用能减少压缩带来的信息损失。5. 常见报错排查401、local proxy failed 与 choices 读取失败配置和压缩过程中最容易撞上几个报错。我按实际遇到的频率排一下。401 Unauthorized。这个基本是 Key 的问题。检查三件事Key 有没有复制完整有时候复制会漏掉末尾字符、环境变量有没有生效echo $TAOTOKEN_API_KEY看一下、Base URL 有没有写错。如果 Key 是对的但还报 401可能是 Key 被禁用或额度用完去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 确认状态。local proxy failed。这个报错通常出现在客户端配置了本地代理但代理没启动或端口不对。解决办法是检查客户端的代理设置把 Base URL 直接指向https://taotoken.net/api不要经过本地转发。如果你之前配过什么本地端口先清掉。reading choices 失败。这个报错说明响应格式和客户端预期的不一致。常见原因是 Model ID 填错了或者客户端把非 OpenAI 格式的响应当 OpenAI 格式解析。检查 Model ID 是否和实际模型匹配Base URL 是否带了多余的路径。有些客户端需要在 Base URL 后自动拼/v1/chat/completions如果你手动加了/v1就会变成/v1/v1/...直接 404。OAuth 相关报错。如果你用的是 Claude Code 类工具可能会遇到 OAuth 认证失败。这类工具默认走 OAuth 流程但用 API Key 接入时需要关掉 OAuth 模式改成 Key 认证。具体做法是在 settings 里把认证方式设为 api_key并填好 Base URL、Key、Model ID 三件套。三件套缺一个都会报认证错误。压缩后模型答非所问。这不是报错但很常见。原因是压缩摘要丢了你关心的细节。解决办法是把关键信息前置到 AGENTS.md或者调低压缩阈值让压缩来得晚一点。也可以手动在压缩前把重要内容用/status确认一遍。排查时有个通用思路先确认网络能通curl https://taotoken.net/api看返回再确认 Key 有效最后确认 Model ID 和路径拼接正确。三步走下来大部分问题都能定位。6. 长期编码与 Agent 场景的落地建议如果你打算把这套 Session 记忆方案用在长期编码或 Agent 场景有几个实践建议。第一AGENTS.md 要定期维护。项目变了规范也要跟着变。我一般每周 review 一次把过时的条目删掉新增的约定补上。文件越长每轮占的 token 越多所以要克制只写真正影响行为的规则。第二SOUL.md 的人格设定要稳定。频繁改人格会让模型行为不一致长会话里更明显。定好之后尽量少动需要调整时一次性改完。第三压缩策略要结合业务。客服场景可以激进压缩因为对话历史价值低编码场景要保守因为上下文细节重要。阈值和压缩频率都可以调找到适合自己场景的平衡点。第四多会话管理要用好 sessions_list、sessions_history、sessions_send 这几个工具。主会话跑核心任务非主会话处理群组消息通过 sessions_send 跨会话通信。这样既能隔离权限又能保持信息流转。第五长期跑 Agent 的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 比按量计费更划算尤其是高频调用场景。接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有完整的参数说明配置时对照着填能少走弯路。最后说一个我踩过的坑一开始我把所有项目信息都塞进 AGENTS.md结果每轮 token 消耗巨大压缩频繁触发反而丢记忆。后来精简到只留技术栈、规范、禁止事项三类token 降了一半压缩频率也下来了关键记忆反而更稳。记忆管理不是塞得越多越好而是把真正重要的东西放在不会被压缩的位置。