AI Agent记忆系统实现教程：从短期到长期

一、教程目标与适用场景

很多开发者都有过类似的挫败经历：耗费数月打造了一个“全天候数字伴侣”，接入了主流大语言模型，并慷慨地为其分配了很大的上下文窗口。用户第一天告诉它“我对花生严重过敏”，但到了第五天、经过上百轮闲聊后，当用户问起“今晚吃什么”时，这个看似聪明的Agent却兴奋地推荐了花生酱三明治。问题的根源在于：仅依赖大模型的上下文窗口做“记忆”，本质上只是短期记忆，窗口会被新的对话不断冲刷，历史关键信息随之丢失。

本教程的目标是帮助你完成三件事：第一，理解Agent记忆系统的理论来源与分层设计思想；第二，动手实现一套“短期记忆+长期记忆”的完整架构，包括记忆写入、检索、注入、更新与遗忘全链路；第三，掌握结果验证方法与常见问题的排查思路。

本教程适合以下读者：希望为对话类应用增加个性化记忆能力的应用开发者；负责智能客服、数字助手、陪伴型产品的算法工程师；需要对记忆架构做技术选型与评审的技术负责人。适用场景包括个人助理、智能客服、教育辅导、健康生活助手等任何需要Agent“记住用户、越用越懂你”的业务。

二、理论溯源：从认知科学到冯·诺依曼架构的记忆模型

在设计架构之前，先回答“为什么这么做”。Agent记忆并非凭空发明，而是对两套经典体系的工程映射。

第一套是认知科学中的多存储模型。人类的记忆处理流程大致分为三段：感觉记忆（瞬间接收的外部刺激）、工作记忆（当前正在思考、容量有限的“草稿纸”）、长期记忆（可长期保存的信息仓库）。长期记忆又细分为情景记忆（“昨天用户说他对花生过敏”这类具体事件）、语义记忆（“用户不吃花生”这类抽象事实与知识）、程序性记忆（“遇到饮食建议先排除过敏原”这类技能与规则）。这套分层结构直接对应了Agent的记忆设计：上下文窗口是工作记忆，会话内的多轮消息是短期情景，而抽取后沉淀的事实与偏好应当进入长期记忆库。

第二套是冯·诺依曼架构的经典思想：存储与计算的分离与协同。可以把大模型的上下文窗口理解为“内存”——读写快、容量有限、断电即失；而持久化的记忆库相当于“外存”——容量大、可长期保存，需要时再调入内存参与计算。Agent的每一轮推理，就是一次“从外存调入相关数据到内存、再执行计算”的过程。理解了这个类比，架构设计的方向就清晰了：不要试图把所有历史都塞进上下文窗口，而应建立“外存层”（持久化记忆库）与“内存层”（上下文窗口管理）之间的调度机制。

三、前置准备

在动手实现前，请确认以下条件就绪：

1. 模型接入能力：需要一个支持对话补全、且最好支持函数调用（工具调用）的大模型服务。函数调用能力用于在写入管道中做结构化信息抽取，若不具备，也可用严格的JSON输出提示词替代。
2. 向量检索能力：长期记忆的核心检索手段是向量相似度检索。你可以自建向量检索组件，也可以使用云服务商提供的托管向量数据库服务（百度智能云等主流云厂商均提供此类通用能力），后者可显著降低运维成本。
3. 常规后端环境：一门后端语言运行时（如Python）、关系型数据库或文档数据库（存储记忆元数据）、以及基本的消息队列（可选，用于异步写入）。
4. 基础知识：理解embedding（文本向量化）的含义、token预算的概念，以及提示词组装的基本方式。
5. 数据准备：确保会话日志可被访问，包含user_id、session_id、角色、内容、时间戳等字段，这是记忆抽取的原料。

四、第一步：设计统一的记忆数据模型

记忆系统的地基是一个清晰的记忆Schema。推荐包含以下字段：

• memory_id：记忆唯一标识；
• user_id / agent_id：用户与Agent标识，用于多租户隔离，防止记忆串扰；
• memory_type：记忆类型，取值如episodic（情景）、semantic（语义）、preference（偏好）、procedure（规则）；
• content：记忆原文或结构化内容，如“用户对花生严重过敏”；
• embedding：content经向量化后的向量，用于相似度检索；
• importance：重要性评分，可由模型打分（如按“影响后续决策的程度”0到10分）；
• created_at / last_accessed_at：创建与最近访问时间，用于时间衰减与清理；
• valid_until / ttl：可选的有效期，如“用户下周去旅行”这类临时记忆；
• version / superseded_by：版本与替代指针，用于冲突消解。

配置风险提示：字段一旦上线，修改成本高。建议初期就加入version字段，为后续Schema演进留余地；importance与ttl是可选增强项，若初期不确定可先置空，但user_id隔离与memory_type分类不建议省略。

五、第二步：实现短期记忆层（工作记忆）

短期记忆的职责是在单次会话内维持连贯。它管理的是“进入上下文窗口的内容”，核心是token预算控制。

做法分三种，按复杂度递增：其一，滑动窗口，即只保留最近N轮消息，实现简单但可能截断早期关键信息；其二，滚动摘要，当历史消息超过token预算时，将较早的若干轮压缩为一段摘要，替换原文放入上下文；其三，混合策略，对系统提示与关键事实保留原文，对普通闲聊做摘要。

示意伪代码如下：

def build_short_term_context(session):
    budget = model_context_limit - reserved_for_system - reserved_for_output
    messages = session.recent_messages
    while token_count(messages) > budget:
        oldest = messages.pop_early_chunk()
        session.rolling_summary = summarize(session.rolling_summary + oldest)
        messages = [summary_block(session.rolling_summary)] + messages
    return messages

注意点：摘要本身由模型生成，需在提示词中明确“保留用户偏好、事实性陈述、未完成任务，可丢弃寒暄”，否则压缩过程会把“花生过敏”这类关键事实一并丢掉。

六、第三步：构建长期记忆写入管道

长期记忆不是把对话原样存库，而是经过一条加工管道。推荐按以下顺序实现：

1. 触发时机：常见做法有两种——每轮实时抽取（延迟低但调用成本高）或每N轮/会话结束时批量抽取（成本低但有延迟）。陪伴类、助理类产品通常采用批量抽取加关键轮次实时抽取的组合。
2. 信息抽取：调用模型，从对话中抽取结构化事实。提示词要求输出JSON数组，每条包含type、content、importance。例如从“我对花生严重过敏，千万别给我推荐”中抽取{type:”preference”, content:”用户对花生严重过敏，需在饮食建议中排除花生及制品”, importance:9}。
3. 去重与冲突检测：新记忆入库前，用向量相似度检索已有记忆中相似度高于阈值者。若语义一致则跳过；若语义冲突（用户之前说“爱吃花生”，现在说“过敏”），则将旧记忆标记为superseded，写入新记忆并递增版本。遵循“时间新者优先”原则。
4. 向量化入库：对content做embedding，连同元数据写入记忆库。此步建议异步执行（经消息队列），避免阻塞对话主链路。

七、第四步：实现长期记忆检索与注入

检索是记忆系统的“临门一脚”。推荐采用混合检索加加权重排：

1. 候选召回：以当前用户输入（及其向量）为查询，在记忆库中做向量相似度检索取Top-K，同时并行做关键词检索（用于精确匹配“花生”这类专有名词，弥补向量对低频词的偶发失灵），两者结果合并去重。
2. 加权重排：最终得分 = 相似度 × w1 + importance × w2 + 时间近因性 × w3。时间近因性可用指数衰减函数表达，模拟“遗忘曲线”，使陈旧记忆自然沉底。权重建议从w1=0.6、w2=0.25、w3=0.15起步，再用评测集调优。
3. 注入上下文：将Top-N条记忆格式化为简洁文本块，注入系统提示中的预留占位区，例如“【已知用户信息】1. 用户对花生严重过敏……”。注意控制注入字数，通常数百token以内，否则会挤占工作记忆预算。

示意伪代码：

def retrieve_memories(user_id, query, top_n=5):
    cands = vector_search(query.embedding, user_id, k=20) \
            + keyword_search(query.text, user_id, k=10)
    for m in cands:
        m.score = (w1*m.sim + w2*m.importance/10
                   + w3*exp(-days_since(m.last_accessed_at)/half_life))
    return rank_and_dedup(cands)[:top_n]

八、结果验证

上线前请完成三类验证。功能验证：重演开篇场景——第一天注入“对花生严重过敏”，随后模拟数十轮无关闲聊，第五天询问“今晚吃什么”，检查Agent的推荐是否排除了花生制品，且能主动引用该偏好。检索质量验证：构建黄金评测集（问题-应命中的记忆对），统计命中率与排序正确率，目标是关键事实类问题命中率接近全部命中。性能与成本验证：观察检索延迟（通常应控制在毫秒到数十毫秒级）、每轮注入的token数量、写入管道的端到端耗时，确保未拖慢主对话链路。

九、常见问题与排查

问题一：记忆召回不准。排查方向：embedding模型与业务语料的匹配度、相似度阈值是否过高、混合检索中关键词通道是否生效、importance与时间衰减权重是否失衡。问题二：上下文频繁超限。排查方向：短期记忆的token预算计算是否扣除了系统提示与输出预留，滚动摘要是否真正执行。问题三：多用户记忆串扰。这几乎都是检索时未加user_id过滤导致，务必在检索层强制租户隔离过滤。问题四：用户修改偏好后旧答案仍在。排查方向：去重与冲突检测的相似度阈值是否过高导致新旧记忆被判为“不同事实”，以及superseded标记是否在检索层被正确排除。问题五：长期记忆无限膨胀。需引入定期清理任务：依据ttl过期、时间衰减得分低于阈值、长期未被访问等条件归档或删除冷记忆。

十、优化建议

性能方面：对热点用户的高频记忆做缓存，写入链路全面异步化。成本方面：存摘要而非原文、冷热分层存储（冷数据转入低成本对象存储），抽取调用采用批量合并以减少模型调用次数。安全与合规方面：记忆库涉及大量个人信息，应做敏感字段脱敏与加密存储，支持用户发起的“遗忘请求”（删除该用户全部记忆），并严格按用户隔离。可维护性方面：记忆Schema做版本化管理，保留评测集并纳入持续回归，任何检索权重的调整先离线评测再灰度上线。

十一、总结

本教程从认知科学与冯·诺依曼架构出发，阐明了“上下文窗口只是工作记忆”这一核心认知，并完整走通了分层记忆系统的落地路径：设计记忆数据模型，实现带token预算与滚动摘要的短期记忆，搭建抽取、去重、向量化、入库的写入管道，实现混合检索与加权重排的记忆注入，最后补齐冲突消解、遗忘机制与验证排查方案。后续你可以继续探索的方向包括：跨Agent的记忆共享策略、基于图结构的关联记忆检索，以及记忆重要性模型的持续学习，让Agent真正从“聊过就忘”进化为“越用越懂你”。