1. 为什么你的 Agent 一关会话就“失忆”长期记忆架构的根因拆解先说结论Agent 长期记忆做不起来九成不是模型不行而是记忆链路根本没搭。你让一个 128K 上下文窗口的模型去扛三天协作项目它必然在某个节点开始丢早期信息你让一个只读当前会话的助手去记住“这个项目用 pnpm、测试跑 vitest、部署走 Docker”它下次开新对话照样问你一遍。这不是模型笨是架构缺层。我把 Agent 记忆粗分成三层这个分法在工程上最好落地工作记忆就是上下文窗口里的对话历史。它容量有限而且成本随长度线性上涨。很多人误以为“窗口够大就不用记忆系统”实测下来窗口越大越容易注意力稀释早期关键约束反而被淹没。短期记忆是当前任务状态比如“做到第几步、卡在哪个报错、下一步该干嘛”。不少 Agent 用临时文件或 session 变量存问题是会话一结束就清空跨会话完全接不上。长期记忆是跨会话、跨项目复用的持久化知识比如技术栈偏好、架构约定、历史决策。绝大多数自建 Agent 压根没有这一层所以每次开新对话都像在跟一个刚入职的新同事说话——能力很强昨天的事一概不知。那为什么长期记忆这么难我踩过的坑集中在四个点。第一记什么。不是所有内容都值得写进长期记忆。“我用 pnpm”要记“帮我查下现在几点”不用记。什么都往里塞检索时全是噪音召回质量直接崩。工程上要按功能拆事实类项目用 React 18、偏好类提交信息用中文、可迁移经验类这个仓库的 CI 必须先跑 lint。三类分开存、分开检索比混在一条记录里强得多。第二怎么检索。存了 100 条记忆怎么在需要时精准捞出来纯关键词搜不到语义相近的表达纯语义相似度对“话题回忆”好用对“因果回溯”几乎无效——早期那个决策和它导致的结果在语义上可能完全不像。所以检索层要至少两条路语义召回 结构化/因果链接召回。第三过时怎么办。“项目用 React 18”在升级后就是错的但 Agent 不知道它过时还会按旧版本给建议。记忆必须带时间戳和来源写入时做冲突检测检索时优先取新版本旧版本降权而不是直接删。第四出错怎么定位。记忆管线有摄入、检索、过滤、生成多个阶段端到端只看“回答对不对”根本不知道哪一环坏了。要在每个阶段打点单独验证。把这几件事想清楚再谈接入。下面我用 TaoToken 做统一模型通道把记忆写入和召回链路跑通你可以直接照着复现。2. TaoToken 前置准备统一 Key 与 API 通道接入模型调用记忆系统本身不产生智能它靠模型做三件事把原始对话压缩成结构化记忆、把用户 query 改写成检索查询、把召回结果和当前问题一起生成回答。这三步都要调模型如果每换一个模型就改一遍代码记忆链路会非常难维护。所以我用 TaoToken 做统一入口一个 Key、一个 Base URL模型 ID 按需切换。先明确它是什么TaoToken 是一个模型 API 聚合通道兼容 OpenAI 风格的接口协议你拿到 Key 之后把 Base URL 指向它就能用统一的调用方式访问不同模型。对记忆系统来说好处是写入用便宜的小模型、召回改写用中等模型、最终生成用强模型切换只改一个 model 字段。适合谁正在自建 Agent、需要跨会话记忆、又不想被单一模型供应商绑死的开发者。如果你只是偶尔对话用官方网页就够了但你要做记忆管线统一通道能省掉大量适配代码。前置准备分三步。第一步注册并拿到 API Key。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就重建。第二步确认 API 端点。基础地址是 https://taotoken.net/api 不带任何查询参数。所有模型调用都走这个 Base URL路径按 OpenAI 兼容格式拼比如 /v1/chat/completions。第三步选模型 ID。记忆写入这种“压缩总结”任务用便宜快速的小模型就够召回查询改写可以用中等模型最终回答生成再用强模型。具体可用模型 ID 在控制台的模型列表里查或者用模型对话页面先试跑 https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这里有个关键点记忆系统里所有模型调用都走同一个 Key 和 Base URL只是 model 参数不同。这样你的记忆管线代码只依赖一个客户端换模型不动架构。如果你用的是 Claude Code 这类编码 Agent它需要单独配置。Claude Code 走的是 Anthropic 协议TaoToken 提供了对应的接入方式文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。配置时同样要写全三件套Base URL、API Key、Model ID缺一个都会报认证或模型不存在。长期跑编码 Agent 的话可以考虑 Coding Plan它更适合高频、长时间的 Agent 调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。记忆系统本身调用量不大但如果你把记忆和编码 Agent 合在一起跑这个更划算。Key 拿到后先别急着写记忆逻辑用一条最简单的请求验证通道通不通。下一节给可复制的配置和代码。3. 可复制的记忆分层配置写入、召回与存储选型这一节是核心我给一套能直接跑的最小记忆架构。存储选型上我建议分两层结构化记忆用 SQLite本地、零依赖、方便回归测试语义检索用本地向量库比如 Chroma 或 sqlite-vec两者用同一个 memory_id 关联。这样既能做精确过滤又能做语义召回。先建目录结构mkdir -p agent-memory/{data,config} cd agent-memory配置文件用 JSON路径固定为config/memory.json内容如下{ taotoken: { base_url: https://taotoken.net/api, api_key: sk-你的Key, models: { extract: gpt-4o-mini, rewrite: gpt-4o-mini, answer: gpt-4o } }, memory: { db_path: data/memory.db, vector_path: data/vectors, max_recall: 8, decay_days: 30 } }注意base_url就是https://taotoken.net/api不要加/v1路径在代码里拼。api_key换成你控制台创建的那个。记忆写入链路分四步摄入原始对话 → 抽取结构化记忆 → 去重与冲突检测 → 落库并建索引。抽取这一步调模型prompt 要强制输出 JSON字段固定为typefact/preference/insight、content、source、timestamp。这样三类记忆分开存检索时可以按 type 过滤。写入的 Python 代码import json, sqlite3, time, uuid from openai import OpenAI cfg json.load(open(config/memory.json)) client OpenAI(base_urlcfg[taotoken][base_url], api_keycfg[taotoken][api_key]) def extract_memory(dialog: str): prompt f从下面对话中抽取长期记忆只输出 JSON 数组。 每条包含 type(fact/preference/insight)、content、source。 不要抽取临时信息如时间查询。对话 {dialog} resp client.chat.completions.create( modelcfg[taotoken][models][extract], messages[{role: user, content: prompt}], temperature0 ) return json.loads(resp.choices[0].message.content) def save_memory(items): conn sqlite3.connect(cfg[memory][db_path]) conn.execute(CREATE TABLE IF NOT EXISTS memories( id TEXT PRIMARY KEY, type TEXT, content TEXT, source TEXT, ts INTEGER, active INTEGER DEFAULT 1)) for it in items: conn.execute(INSERT OR REPLACE INTO memories VALUES(?,?,?,?,?,1), (str(uuid.uuid4()), it[type], it[content], it[source], int(time.time()))) conn.commit() conn.close()召回链路分三步把用户 query 改写成检索查询 → 语义召回 结构化过滤 → 按时间和类型重排。改写这步很关键用户问“上次那个部署问题怎么解决的”直接拿这句去搜语义相似度很低要改写成“部署 报错 解决方案”这类检索友好的查询。召回代码def rewrite_query(query: str): resp client.chat.completions.create( modelcfg[taotoken][models][rewrite], messages[{role: user, content: f把下面问题改写成适合检索记忆的关键词只输出关键词{query}}], temperature0 ) return resp.choices[0].message.content def recall(query: str, top_k8): kw rewrite_query(query) conn sqlite3.connect(cfg[memory][db_path]) rows conn.execute( SELECT id,type,content,ts FROM memories WHERE active1 AND content LIKE ? ORDER BY ts DESC LIMIT ?, (f%{kw.split()[0]}%, top_k)).fetchall() conn.close() return rows这是最小可用版本用 LIKE 做粗召回。生产环境把 LIKE 换成向量检索SQLite 可以装 sqlite-vec 扩展或者单独跑 Chroma。关键是接口不变只换召回实现。存储选型对照方案适合场景优点注意SQLite单机、结构化记忆零依赖、易回归测试语义检索需扩展Chroma本地语义召回上手快、API 简单数据量大要调索引向量数据库云服务多机、大规模免运维成本和网络依赖我建议先用 SQLite LIKE 跑通全链路确认写入和召回逻辑对了再换向量检索。一上来就上向量库出问题你分不清是抽取错了还是检索错了。4. 验证请求与成功结果跑通一次完整的记忆写入与召回配置写完必须验证否则你不知道是通道问题还是逻辑问题。分两步先验证 TaoToken 通道再验证记忆链路。第一步用 curl 验证通道。这是最直接的排障方式curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role:user,content:只回复 ok}], temperature: 0 }成功的话返回 JSON 里choices[0].message.content是ok。如果这里就失败先别碰记忆代码按第 5 节的报错对照排查。第二步跑记忆写入。准备一段模拟对话dialog 用户这个项目我习惯用 pnpm不要用 npm。 助手好的记下了。 用户测试框架用 vitestCI 里先跑 lint 再跑测试。 助手明白。 items extract_memory(dialog) print(items) save_memory(items)预期输出类似[ {type:preference,content:项目使用 pnpm 而非 npm,source:用户对话}, {type:fact,content:测试框架使用 vitest,source:用户对话}, {type:insight,content:CI 流程先跑 lint 再跑测试,source:用户对话} ]如果模型返回的不是合法 JSON检查 prompt 里有没有明确“只输出 JSON 数组”以及 temperature 是否为 0。第三步跑召回。新开一个进程模拟新会话result recall(这个项目包管理器用什么) for r in result: print(r[1], r[2])预期输出包含preference 项目使用 pnpm 而非 npm。这一步成功说明跨会话记忆链路通了——写入进程和召回进程完全独立数据从 SQLite 读出来。第四步做回归测试。记忆系统最怕改一处坏一处所以要有一组固定用例。建tests/memory_cases.json[ {dialog: 我用 pnpm, query: 包管理器, expect: pnpm}, {dialog: 测试用 vitest, query: 测试框架, expect: vitest}, {dialog: 今天几号, query: 日期, expect: null} ]第三条是负例验证临时信息不被写入长期记忆。跑测试时逐条写入、召回、断言 expect 是否出现在结果里。这套用例每次改抽取 prompt 或召回逻辑都跑一遍能挡住大部分回归。实测下来这套最小架构在单机跑几百条记忆没问题。数据量上千后LIKE 召回会变慢这时候把召回层换成向量检索其他代码不动。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 对照记忆链路跑不通报错通常集中在通道层。我按真实遇到的报错逐个说。401 Unauthorized。最常见原因是 Key 错了或没带。检查三处config/memory.json里的api_key是否是完整 Key请求头是否是Authorization: Bearer sk-xxxBearer 后面有空格Key 是否被删除或过期。如果 curl 也 401就是 Key 本身问题去控制台重建。404 model not found。模型 ID 写错了。TaoToken 的模型 ID 要和控制台列表一致大小写敏感。另外确认 Base URL 是https://taotoken.net/api路径拼/v1/chat/completions不要重复拼成/api/v1/v1/...。local proxy failed 或 connection refused。这类报错说明请求根本没发出去通常是本地网络或代理配置问题。检查你的 HTTP 客户端有没有读到系统代理环境变量HTTP_PROXY、HTTPS_PROXY如果指向一个没启动的本地端口就会报这个。临时清掉这两个环境变量再试。注意不要配置任何非官方的网络转发工具直接用官方 API 地址即可。reading choices of undefined。这个报错说明返回体里没有choices字段代码却直接取了。根因通常是请求失败但没检查状态码或者返回的是错误 JSON。修法是在取choices前先判断data resp.json() if choices not in data: raise RuntimeError(fAPI 返回异常: {data}) content data[choices][0][message][content]这样报错信息会直接告诉你真实原因而不是一个模糊的 undefined。OAuth 相关报错。如果你用 Claude Code 或类似工具它可能默认走 OAuth 登录流程而你要用 API Key 接入。这时候要在配置里显式指定 API Key 模式并写全三件套Base URL、API Key、Model ID。缺 Model ID 会报模型不存在缺 Base URL 会走默认端点导致认证失败。Claude Code 的接入配置参考文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。JSON 解析失败。抽取记忆时模型返回了带 markdown 代码块的 JSONjson.loads直接崩。修法是先剥掉json 和或者用正则提取第一个[到最后一个]之间的内容。更稳的做法是在 prompt 里明确“不要用 markdown 代码块包裹”。记忆召回为空。写入成功但召回查不到先确认active1再确认召回用的关键词和写入内容有重叠。如果用了改写查询打印改写结果看看是不是改偏了。最后确认写入和召回用的是同一个db_path相对路径在不同工作目录下会指向不同文件建议用绝对路径。6. 把记忆接进你的 Agent从验证模型到长期编码的通道选择记忆链路跑通后下一步是把它接进真实 Agent。这里的关键是模型通道要稳定因为记忆系统会在每次对话前后各调一次模型调用频率比普通对话高。如果你只是想先验证记忆效果用模型对话页面手动试几条 query看召回是否合理https://taotoken.net/api?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。这一步不写代码纯验证“记忆内容对不对”。如果你要把记忆接进编码 Agent 长期跑比如让 Agent 记住项目约定、历史决策、常用命令那调用量会上来建议用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它更适合高频、长时间的 Agent 场景记忆写入和召回都走同一个通道不用来回切配置。接入时统一用 API Keys 管理你的凭证https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。建议给记忆系统单独建一个 Key方便按项目统计用量和随时吊销不要和编码 Agent 共用同一个 Key。最后给一个实用技巧记忆写入不要每轮对话都触发那样又慢又贵。我的做法是每 N 轮或检测到“决策类语句”比如“以后都用”“记住”“约定”时才触发抽取。召回则每轮都做但限制 top_k避免把上下文塞爆。这样一套跑下来Agent 才真正从“每次失忆”变成“越用越懂你”。