Agent记忆管理实战：基于MCP与Docker构建长期记忆系统

1. 从“hindsight”说起为什么Agent的记忆问题值得单独做一个项目第一次看到“hindsight”这个词我脑子里蹦出来的不是词典释义而是过去两年做Agent项目时反复踩过的那个坑——会话一断记忆全丢。你辛辛苦苦调教出来的助手上一轮还记得用户说过“我对花生过敏”下一轮开个新会话它又能热情地推荐花生酱饼干。这不是模型笨是架构里压根没给它留“记忆”的位置。hindsight这个项目从标题和关联词来看核心要解决的就是Agent的长期记忆与工作记忆管理问题。它不是一个单纯的LLM应用而是一套围绕“记忆”构建的基础设施层。关联词里出现了agent memory、working memory、MCP、Docker、TencentDB agent memory这些关键词基本可以勾勒出它的技术轮廓用MCP协议做能力暴露用Docker做部署封装用数据库做记忆持久化服务于LLM驱动的Agent系统。我为什么对这个方向特别有感触因为绝大多数人做Agent第一版都是“把历史对话塞进context”了事。对话短的时候没问题一旦超过几千token要么爆context window要么成本飙升要么模型开始“遗忘”中间内容。更麻烦的是跨会话、跨任务的记忆根本无从谈起。hindsight这类项目要做的就是把记忆从“临时塞进prompt的字符串”升级成“有结构、可检索、可持久化的独立层”。这篇文章适合谁看如果你正在做Agent应用被记忆问题折磨过如果你想了解MCP协议在真实项目里怎么落地如果你对Docker部署一套带数据库的LLM基础设施感兴趣——那这篇就是写给你的。我会从设计思路、核心机制、实操部署、问题排查四个维度把这类项目拆透让你看完能自己动手复现一套。2. 记忆层的整体设计与思路拆解2.1 为什么不能只靠context window做记忆先说一个我实测过的数据。一个中等复杂度的客服Agent单轮对话平均消耗800到1200 token。如果要把最近20轮对话都塞进context光历史就占掉2万token左右。按主流模型的定价每千次对话的成本会翻好几倍。这还只是成本问题更致命的是注意力稀释——context越长模型对关键信息的召回率越低这是有大量实验支撑的结论。所以正确的做法是把记忆分层。我在实际项目里通常分三层工作记忆working memory放当前任务正在用的信息短期记忆放本次会话的历史长期记忆放跨会话的用户偏好、事实知识、历史决策。hindsight这个项目从命名和关联词看重点就在工作记忆和长期记忆的衔接上。提示不要一上来就追求“全自动记忆”。我见过太多项目记忆写入逻辑过于激进把用户的每句话都存进去结果检索时噪声比信号还多。记忆的第一原则是选择性写入。2.2 MCP协议在这里扮演什么角色MCPModel Context Protocol这两年被讨论得很多但很多人对它的理解还停留在“让AI调用工具”这个层面。实际上MCP的价值在于标准化了模型与外部能力的交互契约。在hindsight这类记忆项目里MCP的作用是把“记忆的读写”抽象成一组标准接口存一条记忆、查相关记忆、更新记忆、删除过期记忆。这样做的好处是什么解耦。记忆的存储实现可以是TencentDB可以是Postgres可以是向量库但对上层Agent来说它只需要知道“我通过MCP调用了一个叫memory的工具”。换存储后端不用改Agent代码这是工程上极大的便利。我试过在几个项目里手写记忆管理逻辑最后都演变成一堆难以维护的胶水代码。用MCP把接口固定下来之后整个系统的可测试性和可替换性都上了一个台阶。2.3 Docker封装带来的部署确定性关联词里Docker出现频率极高这不是偶然。记忆层涉及数据库、可能涉及向量检索、还要暴露MCP服务依赖关系复杂。如果让用户手动装这一堆东西光是环境问题就能劝退80%的人。Docker Compose把这些服务编排在一起一条命令拉起这是这类基础设施项目能被人真正用起来的前提。我在Windows上部署过类似架构踩过的坑后面会详细讲。这里先给个结论用Docker Compose而不是单个Docker run因为记忆服务通常需要和数据库、缓存一起启动Compose能管理依赖顺序和网络。2.4 方案选型的几个关键取舍取舍点方案A方案B我的建议记忆存储纯向量库关系库向量混合结构化字段走关系库检索方式纯语义检索语义关键词混合检索召回更稳写入时机每轮自动写显式触发写显式为主自动为辅部署形态单体进程容器编排容器编排便于扩展这个表格是我从多个项目里总结出来的。纯向量库的问题是像“用户ID”“时间戳”这类结构化过滤做起来别扭纯语义检索的问题是精确匹配场景比如查某个订单号召回率不稳定。混合方案虽然复杂一点但实际效果最可靠。3. 核心细节解析与实操要点3.1 工作记忆与长期记忆的边界怎么划这是设计记忆系统时最容易搞混的地方。我的经验是工作记忆服务于“当前这一个任务”长期记忆服务于“这个用户/这个Agent的所有任务”。举个例子。用户说“帮我订明天去上海的机票”。工作记忆里存的是出发地、目的地、日期、舱位偏好。这些信息在任务完成后就可以清理。但如果用户之前说过“我出差都选靠窗座位”这条应该进长期记忆因为它跨任务有效。hindsight这类项目通常会在MCP接口里区分这两类操作。工作记忆的写入可能带一个session_id长期记忆的写入带user_id。检索时工作记忆优先长期记忆兜底。注意工作记忆的清理策略要明确。我见过项目因为工作记忆不清理导致上一个任务的信息污染下一个任务Agent开始“幻觉”出用户没提过的需求。3.2 记忆的写入策略什么时候该记这是实操中最考验判断力的部分。我的原则是三条用户显式表达的偏好和事实必记。比如“我不吃辣”“我的工位在3楼”。任务的关键决策点必记。比如“用户选择了方案B而不是方案A”。重复出现的信息考虑记。如果同一个信息在多次会话里出现说明它是稳定的。反过来寒暄、临时情绪、一次性的中间结果不要记。我踩过的坑是早期把用户说的“今天好累”也存进长期记忆结果下次对话Agent上来就问“你今天还累吗”非常尴尬。写入的实现上通常是一个MCP工具调用参数包括content、memory_type、user_id、metadata。metadata里可以放时间、来源、置信度这些。3.3 检索环节的参数调优检索是记忆系统的“出口”出口不好前面存得再好也白搭。核心参数有几个top_k返回几条记忆。太小会漏太大会引入噪声。我一般从5开始调根据实际召回情况增减。相似度阈值低于阈值的直接丢弃。这个阈值需要根据你用的embedding模型来定不能照搬别人的。时间衰减越久远的记忆权重越低。但不是所有场景都适用比如“用户过敏史”这种再久也不能衰减。我实测下来混合检索语义关键词配合时间衰减在大多数Agent场景里效果最稳。纯语义检索在遇到专有名词、编号、代码片段时经常翻车。3.4 MCP接口的设计细节一个记忆MCP服务通常暴露这几个工具store_memory写入一条记忆search_memory检索相关记忆update_memory更新已有记忆delete_memory删除记忆list_memories列出某用户/会话的记忆接口设计上有个细节容易被忽略返回格式要稳定。我见过项目今天返回JSON明天返回纯文本上层Agent解析逻辑天天改。定好schema就别乱动。另外错误处理要明确。记忆服务挂了Agent应该降级运行比如只用当前context而不是整个崩溃。这个降级逻辑要在MCP客户端侧实现。4. 实操过程与核心环节实现4.1 环境准备与Docker部署假设你在一台干净的机器上从零开始。第一步是装Docker。Windows用户注意Docker Desktop需要开启虚拟化支持如果BIOS里没开启动会报“virtualization support not detected”这类错误。这个坑我踩过进BIOS开一下VT-x或AMD-V就行。Linux用户直接用包管理器装docker和docker-compose。装完之后验证docker --version docker compose version两个命令都能输出版本号说明环境OK。接下来是编排文件。一个典型的记忆服务Compose结构大概是这样version: 3.8 services: memory-db: image: postgres:15 environment: POSTGRES_PASSWORD: yourpassword POSTGRES_DB: memory volumes: - ./data:/var/lib/postgresql/data ports: - 5432:5432 memory-service: build: . depends_on: - memory-db environment: DB_HOST: memory-db DB_PORT: 5432 DB_NAME: memory DB_PASSWORD: yourpassword ports: - 8080:8080这里的关键点是depends_on它保证数据库先起来。但要注意depends_on只保证启动顺序不保证数据库已经ready。生产环境里服务端要有重试逻辑。4.2 数据库表结构设计记忆存储的表结构我建议至少包含这些字段字段名类型说明iduuid主键user_idvarchar用户标识session_idvarchar会话标识长期记忆可为空contenttext记忆内容memory_typevarcharworking/long_termembeddingvector向量表示metadatajsonb扩展信息created_attimestamp创建时间updated_attimestamp更新时间如果用的Postgres装个pgvector扩展就能存向量。这样语义检索和结构化查询在同一个库里完成省去同步的麻烦。提示embedding的维度要和你的模型对齐。换embedding模型意味着所有历史记忆要重新计算向量这个成本要提前考虑。4.3 记忆写入的完整流程以一次对话为例走一遍完整流程Agent收到用户输入。调用search_memory用当前输入去检索相关记忆。把检索到的记忆和当前输入一起组装成prompt发给LLM。LLM返回回复。判断这一轮是否有值得写入的信息。如果有调用store_memory。返回回复给用户。第5步的判断逻辑可以先用规则比如检测到“我喜欢/我不喜欢/记住/我的XX是”这类模式就触发写入。进阶一点可以用一个小模型做分类。我建议先规则后模型规则能覆盖80%的场景且可控。4.4 检索的代码实现要点检索的核心是构造查询。伪代码逻辑def search_memory(query, user_id, top_k5, threshold0.7): query_embedding embed(query) results db.query( SELECT content, metadata, 1 - (embedding %s) AS similarity FROM memories WHERE user_id %s AND 1 - (embedding %s) %s ORDER BY similarity DESC LIMIT %s , (query_embedding, user_id, query_embedding, threshold, top_k)) return results注意是pgvector的余弦距离操作符。相似度用1 - 距离来算。阈值和top_k要根据实际数据调没有万能值。4.5 与Agent框架的对接MCP服务起来之后Agent侧需要配置MCP客户端。不同框架配置方式不同但核心都是提供服务的地址和认证信息。对接时要注意超时设置记忆检索是网络调用超时要合理太短会误判服务不可用太长会拖慢响应。降级策略记忆服务不可用时Agent要能继续工作。并发控制高并发场景下记忆服务的连接池要配够。我实测下来记忆检索的P99延迟控制在200ms以内用户体验基本无感。超过500ms就会明显感觉Agent“卡了一下”。5. 常见问题与排查技巧实录5.1 Docker相关的高频问题问题一Docker Desktop启动失败提示虚拟化未检测到。这是Windows上最常见的问题。解决步骤重启进BIOS找到Intel VT-x或AMD-V设为Enabled。如果用的是Hyper-V还要确认Windows功能里Hyper-V和虚拟机平台都开了。问题二容器之间网络不通。Compose默认会创建一个网络服务之间用服务名互相访问。如果连不上先检查是不是用了localhost而不是服务名。在容器里localhost指的是容器自己不是宿主机。问题三数据库数据丢失。十有八九是没配volume。容器删了数据就没了。一定要把数据库的数据目录挂到宿主机。5.2 记忆检索效果差怎么排查检索效果差先分清楚是存的问题还是查的问题。排查顺序直接查数据库看记忆有没有存进去内容对不对。手动算一下query和某条记忆的相似度看数值是否合理。检查embedding模型是否一致存和查用的必须是同一个模型。检查阈值是不是设太高导致该召回的被过滤了。我遇到过一次检索死活召回不了最后发现是存的时候用了模型A查的时候用了模型B向量空间都不在一个维度上。5.3 记忆污染与幻觉这是记忆系统特有的问题。表现是Agent“记得”用户没说过的话。原因通常是工作记忆没清理上个任务的信息串到当前任务。检索时召回了其他用户的记忆user_id过滤没做好。LLM在组装prompt时把记忆和当前输入混淆了。解决办法严格隔离user_id和session_id工作记忆任务结束即清理prompt里明确标注哪些是“历史记忆”哪些是“当前输入”。5.4 常见问题速查表现象可能原因排查方向服务起不来端口占用/依赖未就绪看日志检查端口和depends_on检索无结果阈值过高/向量不一致降阈值核对embedding模型记忆串用户user_id过滤缺失检查查询条件响应慢检索top_k过大/无索引减top_k加向量索引数据丢失无volume挂载检查Compose的volumes配置5.5 几个我踩过的坑第一个坑embedding维度不匹配。换模型时忘了重新计算历史数据导致新旧向量混在一起检索结果乱七八糟。教训是换模型必须全量重算。第二个坑MCP服务没做鉴权。内网测试没问题一暴露到公网就被人扫到。记忆里可能有用户隐私鉴权是必须的。第三个坑过度依赖自动写入。早期版本让模型自己判断要不要记结果它什么都记噪声爆炸。后来改成规则触发加人工确认质量才上来。6. 记忆系统的扩展方向与个人体会这套架构跑通之后能扩展的方向不少。比如加一层记忆摘要把多条相关记忆压缩成一条减少检索噪声。再比如加记忆重要性评分让检索时优先返回高价值记忆。还可以做跨Agent共享记忆多个Agent共用一个记忆池这在多Agent协作场景里很有用。我在实际项目里的体会是记忆系统的价值不在于技术多复杂而在于克制。存什么、什么时候存、怎么检索每个环节都要有明确的策略而不是一股脑全交给模型。模型很聪明但也很容易被噪声带偏。把记忆层做扎实Agent的体验会有质的提升这个投入是值得的。最后分享一个小技巧调试记忆系统时把每次检索的query、召回结果、相似度都打日志。出问题时翻日志比瞎猜快得多。这个习惯帮我省了无数时间。