1. 为什么你的 Agent 聊三句就“失忆”如果你正在用 Cline、CC Switch 或者自己写的 LangGraph 骨架搭 AI Agent大概率遇到过这种场面第一轮告诉它“我是做后端的回答尽量简洁”第三轮它又开始长篇大论上一轮刚说“这个项目用 FastAPI”下一轮它给你生成 Flask 代码。这不是模型笨是记忆系统没接上。AI Agent 的记忆系统说白了分三层短期记忆管“当前这轮对话说了啥”长期记忆管“用户是谁、有什么偏好、踩过什么坑”向量记忆管“语义相关的历史经验怎么按需捞回来”。三者不是替代关系而是配合关系。短期记忆保证对话连贯长期记忆保证跨会话不重复问向量记忆保证知识库级别的模糊召回。这一篇不讲概念堆砌直接给你一份能跑起来的配置骨架在 Cline / CC Switch 这类工具的settings.json或config.toml里通过统一 Key / API 通道把三类记忆的调用链路接上 TaoToken然后逐项验证读写是否生效。适合已经能跑通单轮对话、准备把 Agent 从“工具”升级成“伙伴”的开发者。2. TaoToken 前置统一 Key 与 API 通道2.1 为什么记忆系统需要一个统一通道三类记忆的调用链路里短期记忆主要消耗对话模型的上下文窗口长期记忆在存取时可能触发一次轻量模型调用做摘要或抽取向量记忆则需要 embedding 模型把文本转成向量。如果每个环节各配一套 Key、各写一套 base_url配置文件会迅速膨胀排障时根本不知道是哪条链路断了。TaoToken 在这里的角色是统一入口一个 Key、一个 API 地址同时覆盖对话模型和 embedding 模型的调用。你不需要在settings.json里维护三组凭证只需要把 base_url 指向https://taotoken.net/api然后在不同记忆模块里复用同一个 Key。2.2 拿到 Key 并确认可用模型先到控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_settings创建后在 API Keys 页面复制完整 Key形如sk-xxxxxxxx。接着确认你要用的模型名记忆系统里通常需要两类一类是对话模型如gpt-4o、claude-3-5-sonnet等一类是 embedding 模型如text-embedding-3-small。具体可用列表以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_settings注意Key 只存在本地配置文件或环境变量里不要写进会提交到 Git 的代码。下面所有配置示例里用${TAOTOKEN_API_KEY}占位实际使用时替换成你的真实 Key 或从环境变量读取。2.3 记忆系统与 TaoToken 的对应关系记忆类型主要消耗走 TaoToken 的哪类模型配置位置短期记忆对话上下文 Token对话模型settings.json 的 model 段长期记忆摘要/抽取时的轻量调用对话模型可指定小模型settings.json 的 memory.long_term 段向量记忆文本转向量embedding 模型settings.json 的 memory.vector 段这张表是你后面排障的索引哪类记忆不生效就回到对应行检查模型名和 Key 是否被正确读取。3. 可复制配置settings.json 三类记忆骨架3.1 整体结构下面这份settings.json骨架同时适用于 Cline 类工具和自建 Agent 项目。核心思路是把 TaoToken 的 base_url 和 Key 放在顶层三类记忆各自引用避免重复。{ provider: { base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, default_model: gpt-4o }, memory: { short_term: { enabled: true, max_messages: 40, strategy: sliding_window }, long_term: { enabled: true, storage_path: ./memory/long_term.json, summarize_model: gpt-4o-mini, max_experiences: 100 }, vector: { enabled: true, embedding_model: text-embedding-3-small, persist_directory: ./chroma_db, collection_name: agent_memory, top_k: 5 } } }3.2 短期记忆段滑动窗口short_term段控制当前对话保留多少条消息。max_messages: 40表示只保留最近 40 条约 20 轮超出部分自动丢弃。strategy目前支持sliding_window后续可以扩展成summarize。如果你用的是config.toml骨架等价写法是[provider] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} default_model gpt-4o [memory.short_term] enabled true max_messages 40 strategy sliding_window3.3 长期记忆段文件持久化long_term段把用户偏好、事实、经验写到本地 JSON 文件。summarize_model指定做摘要时用哪个模型建议用小模型控制成本。max_experiences限制经验条数防止文件无限膨胀。long_term: { enabled: true, storage_path: ./memory/long_term.json, summarize_model: gpt-4o-mini, max_experiences: 100 }3.4 向量记忆段embedding 与持久化目录vector段是三类记忆里配置项最多的。embedding_model必须和 TaoToken 支持的模型名一致persist_directory是 Chroma 的落盘目录top_k控制每次召回几条。vector: { enabled: true, embedding_model: text-embedding-3-small, persist_directory: ./chroma_db, collection_name: agent_memory, top_k: 5 }3.5 把配置读进代码配置文件写好后需要在 Agent 初始化时读取。下面这段 Python 负责把settings.json里的 provider 和 memory 段加载进来并注入到对应的记忆模块。import json import os def load_settings(pathsettings.json): with open(path, r, encodingutf-8) as f: settings json.load(f) # 把 ${TAOTOKEN_API_KEY} 替换成环境变量 api_key settings[provider][api_key] if api_key.startswith(${) and api_key.endswith(}): env_name api_key[2:-1] settings[provider][api_key] os.environ.get(env_name, ) return settings settings load_settings() base_url settings[provider][base_url] api_key settings[provider][api_key]跑通这一步后面三类记忆的初始化都从settings里取参数不再硬编码。4. 逐项验证三类记忆读写是否生效4.1 验证短期记忆滑动窗口是否真的在截断短期记忆的验证最简单连续发超过max_messages条消息看最早的消息是否被丢弃。你可以写一个循环往 Agent 里塞 50 条“第 N 条消息”然后问它“第一条消息是什么”。from langchain_core.messages import HumanMessage from langgraph.graph import MessagesState from langgraph.graph.message import add_messages from typing import Annotated MAX_MESSAGES settings[memory][short_term][max_messages] def _windowed_messages(old, new): return add_messages(old, new)[-MAX_MESSAGES:] class AgentState(MessagesState): messages: Annotated[list, _windowed_messages]如果配置生效Agent 应该回答“我不记得第一条消息”而不是准确复述。这一步确认滑动窗口在截断短期记忆没有无限增长。4.2 验证长期记忆写入后重启还能读到长期记忆的关键是跨会话。先让 Agent 记住一个事实然后重启进程再问它这个事实。import json import os class LongTermMemory: def __init__(self, path): self.path path self.data self._load() def _load(self): if os.path.exists(self.path): with open(self.path, r, encodingutf-8) as f: return json.load(f) return {facts: {}, experiences: []} def _save(self): os.makedirs(os.path.dirname(self.path), exist_okTrue) with open(self.path, w, encodingutf-8) as f: json.dump(self.data, f, ensure_asciiFalse, indent2) def remember_fact(self, key, value): self.data[facts][key] value self._save() def recall_fact(self, key): return self.data[facts].get(key, 没有这条记忆) ltm LongTermMemory(settings[memory][long_term][storage_path]) ltm.remember_fact(用户职业, 后端工程师)执行后检查./memory/long_term.json应该能看到{facts: {用户职业: 后端工程师}, experiences: []}。重启 Python 进程后再调recall_fact(用户职业)如果返回“后端工程师”说明长期记忆落盘成功。4.3 验证向量记忆语义召回是否命中向量记忆的验证要稍微绕一点先存几条语义相关但字面不同的文本再用一个不包含原词的查询去召回。from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from langchain_core.documents import Document embeddings OpenAIEmbeddings( modelsettings[memory][vector][embedding_model], base_urlbase_url, api_keyapi_key, ) vectorstore Chroma( collection_namesettings[memory][vector][collection_name], embedding_functionembeddings, persist_directorysettings[memory][vector][persist_directory], ) vectorstore.add_documents([ Document(page_content用户喜欢简洁的回答风格, metadata{type: preference}), Document(page_content项目使用 Python 和 FastAPI, metadata{type: project}), Document(page_content上次部署遇到 Docker 内存不足, metadata{type: experience}), ]) results vectorstore.similarity_search(回答风格偏好, k2) for doc in results: print(doc.page_content, doc.metadata)如果输出里第一条是“用户喜欢简洁的回答风格”说明 embedding 调用和向量检索都通了。这一步同时验证了 TaoToken 的 embedding 通道可用。4.4 三类记忆联合验证把三类记忆串起来跑一个完整场景用户说“记住我用 FastAPI”Agent 调长期记忆写入下一轮问“我上次说用什么框架”Agent 先查短期记忆没命中再查长期记忆和向量记忆。from langchain.tools import tool tool def save_memory(key: str, value: str) - str: 保存信息到长期记忆。当用户说记住或提供重要信息时使用。 ltm.remember_fact(key, value) return f已记住{key} {value} tool def recall_memory(query: str) - str: 从长期记忆和向量记忆中检索信息。 fact ltm.recall_fact(query) if fact ! 没有这条记忆: return fact docs vectorstore.similarity_search(query, k3) return \n.join([d.page_content for d in docs]) or 没有找到相关记忆把这两个工具挂到 Agent 上跑一轮“记住我用 FastAPI” → 重启 → “我上次说用什么框架”如果回答“FastAPI”说明三类记忆的调用链路全部打通。5. 本篇常见错排查5.1 embedding 调用报 401 或 404最常见的原因是embedding_model名字写错或者api_key没被正确替换。先检查settings.json里provider.api_key是否还是${TAOTOKEN_API_KEY}字面量如果是说明环境变量没读到。再确认embedding_model的值和文档里列出的模型名完全一致大小写和连字符都不能错。5.2 长期记忆写了但重启读不到九成是storage_path相对路径的问题。如果你的 Agent 从不同工作目录启动./memory/long_term.json会指向不同位置。建议改成绝对路径或者在代码里用os.path.abspath统一转换。另外检查_save是否真的被调用可以在里面加一行print确认。5.3 向量记忆召回结果不相关先确认top_k是不是设得太大top_k: 5在小数据集上容易召回噪声。其次检查存入的文本是否太短embedding 模型对过短文本的语义区分度有限建议每条记忆至少 10 个字。如果还是不相关换一个 embedding 模型试试不同模型对中文语义的敏感度差异明显。5.4 短期记忆没截断上下文越来越长检查AgentState里的_windowed_messages是否真的被 LangGraph 调用。如果你用的是create_react_agent需要显式传state_schemaAgentState否则默认的MessagesState不会走你的截断逻辑。另外确认max_messages的值被正确读取不是硬编码的默认值。5.5 三类记忆都配了但 Agent 不主动调用这是 prompt 的问题不是配置的问题。在系统提示里明确写清楚什么时候用save_memory什么时候用recall_memory什么时候依赖短期记忆。工具描述也要写具体比如“当用户说‘记住’或提供个人信息时使用”而不是笼统的“保存信息”。6. 把记忆链路接稳之后记忆系统接上之后你的 Agent 才算真正有了“连续性”。短期记忆保证对话不跳戏长期记忆保证跨会话不重复问向量记忆保证经验能被语义召回。三者共用 TaoToken 一个 Key 和 base_url配置文件不会膨胀排障时也能顺着settings.json的段落逐项定位。如果你还没创建 Key从这里进控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_settings接入细节和模型列表看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_settings想先验证模型对话是否通可以直接在模型对话页试一轮https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_settings如果你准备长期跑编码类 AgentCoding Plan 的额度模型更适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmemory_settings我自己的习惯是先把短期记忆的max_messages调到 20 跑一天观察 Agent 在长对话里是否还连贯再逐步放开长期和向量记忆。记忆不是越多越好召回不准比不召回更伤体验。