1. 从“hindsight”这个词说起为什么记忆是Agent落地的最后一公里“hindsight”这个词本身很有意思字面意思是“事后的洞察力”也就是我们常说的“后见之明”。把这个词放在Agent和LLM的语境里它指向的问题非常具体一个Agent在完成一轮任务之后能不能把这一轮里发生的事、踩过的坑、验证过的结论变成下一轮可以直接调用的经验大多数做Agent的人都会经历同一个阶段Demo跑起来很惊艳一旦进入真实场景就开始露怯。用户上周告诉过它“我们公司的报销单要用A系统提交”这周再问它一脸茫然上一轮对话里已经确认过“这个项目的部署环境是Docker Compose编排的”下一轮它又从头问起。这不是模型能力的问题而是记忆架构的缺失。我接触过不少团队他们在Agent上投入的精力分布大概是这样的Prompt调优占40%工具接入占30%剩下的30%里记忆相关的工作可能连5%都不到。但实际跑下来用户感知最强烈的短板恰恰就在记忆上。一个记不住上下文的Agent工具接得再多也像个失忆的专家——能力有但每次都要重新自我介绍。“hindsight”这个项目标题加上agent memory、working memory、MCP、Docker这几个关键词指向的是一个很明确的工程命题如何给Agent构建一套可持久化、可检索、可演进的记忆系统并且让它能通过MCP协议与外部工具链打通最终以Docker化的方式部署落地。这篇文章适合三类人看第一类是在做Agent产品、被“记不住”问题困扰的开发者第二类是对MCP协议感兴趣、想知道它怎么和记忆系统结合的技术人第三类是想了解Agent记忆架构设计思路、但还没找到切入点的架构师。我会从记忆的本质讲起一路拆到Docker部署和MCP集成的实操细节中间会穿插我自己踩过的坑和验证过的方案。2. Agent记忆不是“存聊天记录”那么简单2.1 三种记忆类型的分工与边界很多人一提到Agent记忆第一反应就是“把对话历史存下来”。这个理解不能说错但太粗糙了。真正跑过生产环境的人会告诉你Agent的记忆至少要分成三层每层的存储介质、检索方式、生命周期都不一样。第一层是工作记忆Working Memory。这是Agent在当前任务执行过程中临时持有的信息比如“用户刚才说的订单号是12345”“当前正在调用的工具返回了一个错误码”。工作记忆的特点是生命周期极短任务结束就可以丢弃但它对当前任务的正确性至关重要。实现上通常就是一个内存中的数据结构比如一个队列或者一个字典不需要持久化。第二层是情景记忆Episodic Memory。这是Agent对“过去发生过什么”的记录包括每一次对话的摘要、每一次工具调用的结果、每一次任务的成功或失败。情景记忆需要持久化因为它要跨会话使用。存储上可以用关系型数据库也可以用文档数据库关键是要能按时间、按会话、按任务类型检索。第三层是语义记忆Semantic Memory。这是Agent从大量情景中提炼出来的“事实性知识”比如“这个用户偏好用中文回复”“这个项目的代码规范要求用TypeScript”“这个API的速率限制是每分钟100次”。语义记忆不是原始记录而是经过抽象和压缩的结论通常用向量数据库来存储和检索。这三层的关系可以用一个类比来理解工作记忆是你在开会时脑子里临时记的东西情景记忆是你的会议纪要语义记忆是你从多次会议中总结出来的“这个客户最关心交付时间”。没有工作记忆Agent连当前任务都完不成没有情景记忆Agent每次都要重新了解背景没有语义记忆Agent永远学不会“这个用户不喜欢废话”。2.2 为什么“全量存对话”是个陷阱我见过不少团队的做法是把每一轮对话原封不动地存进数据库然后在Prompt里塞最近N轮。这个方案在Demo阶段能用一上量就崩。原因有三个。第一Token成本会失控。假设每轮对话平均500个Token存50轮就是25000个Token。每次请求都带上这些历史成本直接翻好几倍。而且随着对话轮次增加这个数字还会继续涨。第二检索精度会下降。全量存储意味着噪声和信号混在一起。用户三周前随口说的一句“今天天气不错”和昨天确认的“部署环境用Docker”在检索时权重是一样的但后者才是真正有用的信息。第三上下文窗口会被浪费。模型的上下文窗口是有限资源塞进去的历史越多留给当前任务推理的空间就越少。一个塞满无关历史的Prompt效果往往不如一个精简但精准的Prompt。正确的做法是分层处理工作记忆实时维护情景记忆做摘要后存储语义记忆做提炼后入库。每一层都有明确的写入策略和检索策略而不是一股脑全存。2.3 记忆的写入时机比存储格式更重要存储格式当然重要但我的经验是写入时机的设计才是记忆系统成败的关键。什么时候该写工作记忆什么时候该把工作记忆提升为情景记忆什么时候该从情景记忆里提炼语义记忆这些决策点如果设计不好存进去的全是垃圾。一个经过验证的写入策略是这样的工作记忆每次工具调用返回后、每次用户输入后立即更新。不需要持久化任务结束即丢弃。情景记忆任务完成或对话轮次结束时用LLM对本次会话做摘要摘要内容包含“用户意图、执行动作、关键结果、异常情况”四个要素然后存入数据库。语义记忆定期比如每天一次对情景记忆做批量分析提取出重复出现的模式或事实经过置信度评估后写入向量库。这个策略的核心逻辑是原始信息只在工作记忆里存在进入持久化层之前必须经过压缩和结构化。这样既控制了存储成本又保证了检索质量。3. MCP在记忆系统里扮演什么角色3.1 MCP不是“另一个API协议”MCPModel Context Protocol这两年被讨论得很多但很多人的理解还停留在“又一个工具调用协议”的层面。如果只是把它当成API的替代品那就低估了它的价值。MCP的核心设计理念是把“上下文”作为一种可标准化的资源来管理。传统的工具调用是“你告诉我调什么、传什么参数、返回什么结果”而MCP在这之上加了一层资源Resource和提示Prompt也是一等公民。这意味着一个MCP Server不仅可以暴露“查询天气”这样的工具还可以暴露“用户的历史偏好”这样的资源以及“根据当前场景生成合适的系统提示”这样的提示模板。对于记忆系统来说这个设计非常关键。因为记忆的本质就是上下文的管理和供给。一个Agent需要的不只是“调用一个检索工具”而是“在合适的时机、以合适的格式、获取合适的记忆片段”。MCP的资源抽象恰好能承载这个需求。3.2 用MCP Server封装记忆层的三种模式在实际项目中我见过三种用MCP封装记忆层的模式各有适用场景。模式一工具式封装。把记忆的读写操作封装成MCP工具比如memory_write、memory_search、memory_forget。Agent在需要的时候主动调用这些工具。这种模式最灵活但对Agent的决策能力要求高——它得知道什么时候该写、什么时候该查。模式二资源式封装。把记忆库作为MCP资源暴露Agent可以通过资源URI直接读取比如memory://user/12345/preferences。这种模式适合“总是需要加载”的记忆比如用户画像、项目配置。缺点是资源是静态的不适合动态检索。模式三混合式封装。这是我在生产环境里用得最多的方案。把高频、固定的记忆做成资源比如用户偏好、系统配置把低频、动态的记忆做成工具比如历史案例检索、相似任务匹配。Agent启动时自动加载资源执行过程中按需调用工具。提示混合式封装的关键是划分清楚“什么该自动加载、什么该按需检索”。我的经验法则是如果一条记忆在80%的任务里都会用到就做成资源如果只在特定场景下用到就做成工具。3.3 MCP Server的Docker化部署要点MCP Server本身是一个独立进程用Docker部署是最自然的选择。但这里有几个坑需要注意。第一通信方式的选择。MCP支持stdio和SSE两种传输方式。stdio适合本地进程间通信SSE适合远程调用。如果MCP Server和Agent在同一台机器上用stdio最简单不需要暴露端口。如果跨机器部署就必须用SSE这时候要注意SSE连接的保活和重连机制。第二状态管理。记忆系统是有状态的但Docker容器默认是无状态的。如果把记忆存在容器内部的文件系统里容器重启数据就丢了。正确的做法是把记忆存储外置——要么挂载Volume要么连接外部数据库。我通常会用Docker Compose同时编排MCP Server和数据库容器通过内部网络通信。第三资源限制。记忆检索是计算密集型操作尤其是向量检索。如果不限制容器的CPU和内存一个大的检索请求可能把整个宿主机拖垮。建议在Docker Compose里明确设置deploy.resources.limits给MCP Server容器分配合理的资源上限。services: memory-mcp: image: hindsight-mcp:latest ports: - 8080:8080 environment: - MEMORY_DB_URLpostgresql://user:passmemory-db:5432/memory - VECTOR_STORE_URLhttp://vector-db:6333 deploy: resources: limits: cpus: 2.0 memory: 4G depends_on: - memory-db - vector-db这个Compose片段是我在一个项目里实际用过的核心思路是把MCP Server、关系型数据库、向量数据库分成三个容器各司其职。MCP Server只负责逻辑不负责存储这样扩容和迁移都方便。4. 从零搭建一套可用的Agent记忆系统4.1 存储选型关系库、向量库、图数据库怎么选记忆系统的存储选型是第一个要做的决策。我的建议是不要试图用一种存储解决所有问题而是根据记忆类型分别选型。记忆类型推荐存储理由典型查询工作记忆内存Redis/进程内生命周期短读写频繁按会话ID读取当前状态情景记忆PostgreSQL/MySQL结构化查询事务保证按时间范围、任务类型检索语义记忆向量数据库Qdrant/Milvus相似度检索按语义相似度召回关系记忆图数据库Neo4j实体关系推理多跳关系查询关系记忆这一层很多人会忽略但在复杂Agent场景里很有用。比如“用户A负责项目B项目B依赖服务C服务C的负责人是用户D”这种关系链用图数据库查起来比SQL join高效得多。如果项目初期不想引入太多组件可以先用PostgreSQL的pgvector扩展同时承担关系存储和向量检索等量级上来了再拆分。这个渐进式方案我在两个项目里用过效果不错。4.2 记忆写入的完整流程与代码骨架写入流程的设计直接决定了记忆质量。我用的流程分四步捕获、压缩、结构化、入库。import json from datetime import datetime from typing import Any class MemoryWriter: def __init__(self, llm_client, db_client, vector_client): self.llm llm_client self.db db_client self.vector vector_client def capture(self, session_id: str, turn: dict) - dict: 第一步捕获原始交互 return { session_id: session_id, timestamp: datetime.utcnow().isoformat(), user_input: turn.get(user_input), agent_output: turn.get(agent_output), tool_calls: turn.get(tool_calls, []), raw: turn } def compress(self, raw_turn: dict) - str: 第二步用LLM压缩成摘要 prompt f请将以下交互压缩成一段简洁的摘要包含四个要素 1. 用户意图 2. 执行动作 3. 关键结果 4. 异常情况如有 交互内容 {json.dumps(raw_turn, ensure_asciiFalse)} return self.llm.generate(prompt) def structure(self, summary: str, raw_turn: dict) - dict: 第三步结构化为可检索的记录 return { session_id: raw_turn[session_id], timestamp: raw_turn[timestamp], summary: summary, intent: self._extract_intent(summary), entities: self._extract_entities(summary), embedding: self.vector.embed(summary) } def persist(self, record: dict): 第四步双写关系库和向量库 self.db.insert(episodic_memory, record) self.vector.upsert( collectionmemory, idrecord[session_id], vectorrecord[embedding], payload{summary: record[summary], timestamp: record[timestamp]} )这个骨架的核心设计是双写关系库存结构化字段用于精确查询向量库存embedding用于语义检索。两边通过session_id关联检索时可以先用向量召回候选再用关系库过滤条件。注意压缩这一步的Prompt设计非常关键。我试过让LLM自由发挥做摘要结果它经常把关键的数字和ID丢掉。后来改成强制要求包含“意图、动作、结果、异常”四个要素摘要质量稳定了很多。4.3 检索策略什么时候该查记忆、查哪一层写入做好了检索是下一个难点。Agent不可能每次请求都把所有记忆查一遍那样延迟和成本都受不了。我的策略是按需检索、分层召回。具体来说Agent在处理一个请求时先判断这个请求是否需要记忆支持。判断逻辑可以很简单如果请求里包含指代词“那个”“上次说的”、或者涉及用户特定信息“我的偏好”“我们项目”就触发记忆检索。检索时按以下顺序先查工作记忆当前会话的临时状态延迟最低。再查语义记忆用户偏好、系统配置这类高频信息用向量检索召回Top-3。最后查情景记忆相似历史案例用向量检索召回Top-5再用时间衰减加权。时间衰减加权是个实用技巧。同样相似度的两条记忆一条是昨天的一条是三个月前的前者的权重应该更高。我用的公式是score similarity * exp(-λ * days_ago)λ取0.01左右效果比较自然。4.4 记忆的遗忘机制不是所有东西都值得记住这一点很少有人提但非常重要记忆系统必须有遗忘机制。一个只写不删的记忆库用不了多久就会变成垃圾场。遗忘策略可以分三种时间衰减超过一定时间且未被检索过的记忆降低权重或归档。冲突消解当新记忆与旧记忆矛盾时比如用户改了偏好旧记忆标记为失效。容量淘汰当记忆库超过容量上限时按“最近使用时间使用频率”淘汰。我在一个客服Agent项目里实现过这套机制运行三个月后记忆库的检索准确率比不遗忘的版本高了将近20个百分点。原因很简单噪声少了信号就突出了。5. Docker化部署中的真实踩坑记录5.1 容器网络不通一个折腾了两小时的教训MCP Server容器连不上向量数据库容器这个问题我遇到过不止一次。表面现象是连接超时但原因可能有好几种。第一次遇到时我以为是端口没暴露检查了ports配置发现没问题。后来才发现Docker Compose默认创建的网络里容器之间应该用服务名通信而不是localhost。我在MCP Server的配置里写了VECTOR_STORE_URLhttp://localhost:6333但在容器内部localhost指向的是容器自己不是向量数据库容器。改成http://vector-db:6333就通了。第二次遇到时服务名写对了但还是不通。排查后发现是向量数据库容器启动比MCP Server慢MCP Server启动时向量库还没准备好。解决方案是在Compose里加depends_on配合健康检查services: vector-db: image: qdrant/qdrant:latest healthcheck: test: [CMD, curl, -f, http://localhost:6333/health] interval: 5s timeout: 3s retries: 10 memory-mcp: depends_on: vector-db: condition: service_healthy这个condition: service_healthy是关键它保证MCP Server等到向量库真正可用之后才启动。5.2 数据持久化Volume挂载的路径陷阱记忆数据丢了这是最让人崩溃的事故。我见过一个团队因为容器重启导致所有情景记忆丢失原因是他们把数据存在了容器内的/app/data目录但没有挂载Volume。正确的做法是在Compose里明确挂载services: memory-db: image: postgres:16 volumes: - memory_data:/var/lib/postgresql/data environment: - POSTGRES_PASSWORDyour_password volumes: memory_data: driver: local这里有个细节PostgreSQL的数据目录是/var/lib/postgresql/data不是/var/lib/postgres。挂错路径的话数据还是存在容器里重启就丢。这个坑我踩过一次后来养成了习惯——每次挂载前先查官方镜像的文档确认数据目录。5.3 资源竞争当记忆检索拖垮了整个Agent记忆检索是计算密集型操作尤其是向量检索。在一个并发量稍高的场景里如果不对MCP Server做资源限制它可能把宿主机的CPU吃满导致Agent的其他组件响应变慢。我的做法是在Compose里给每个服务设置资源上限并且用reservations保证最低资源deploy: resources: limits: cpus: 2.0 memory: 4G reservations: cpus: 0.5 memory: 1G另外向量检索本身也可以优化。比如限制召回数量Top-K不要设太大5到10就够了、对embedding做降维从1536维降到768维精度损失很小但速度翻倍、开启向量库的索引加速Qdrant的HNSW索引。5.4 镜像体积从2GB瘦身到300MB的过程MCP Server的Docker镜像一开始有2GB多原因是基础镜像用了完整的Python镜像还装了一堆用不到的依赖。后来做了三件事把体积压到了300MB左右。第一换基础镜像。从python:3.11换成python:3.11-slim体积直接少了一半多。第二多阶段构建。编译依赖在builder阶段装运行阶段只拷贝必要的产物FROM python:3.11-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --user -r requirements.txt FROM python:3.11-slim WORKDIR /app COPY --frombuilder /root/.local /root/.local COPY . . ENV PATH/root/.local/bin:$PATH CMD [python, -m, hindsight_mcp]第三清理缓存。pip install之后加--no-cache-dirapt安装后清理/var/lib/apt/lists。这些小操作加起来能省几百MB。6. 记忆质量调优那些文档里不会写的经验6.1 摘要Prompt的迭代过程摘要质量直接决定检索质量。我前后迭代了五版摘要Prompt才找到一个稳定的版本。第一版让LLM自由发挥结果摘要里全是“用户询问了某个问题Agent进行了回答”这种废话。第二版加了格式要求但LLM经常不遵守。第三版用了few-shot示例效果好了一些但示例本身的质量成了瓶颈。最终稳定下来的版本有几个关键设计强制四要素结构、要求保留具体实体数字、ID、名称、限制摘要长度在100字以内。另外我会在Prompt里明确说“如果某个要素不存在写‘无’”这样避免LLM编造内容。6.2 向量检索的相似度阈值怎么定向量检索返回的Top-K结果里不是每一条都相关。如果不设阈值可能会召回一些相似度很低但恰好排在前面的噪声。阈值设多少合适我的经验是先用一批标注数据跑一遍画出相似度分布曲线然后取准确率和召回率的平衡点。在大多数embedding模型下余弦相似度0.75以上基本是相关的0.6到0.75之间需要结合其他信号判断0.6以下基本可以忽略。但这个数字因模型而异不能照搬。我建议在项目初期花半天时间做一次阈值标定后面会省很多事。6.3 记忆冲突的处理策略用户上周说“我喜欢简洁的回复”这周说“能不能详细一点”这两条记忆是冲突的。如果都存着检索时可能同时召回Agent就不知道该听哪个。我的处理策略是时间优先显式覆盖。新记忆写入时先检索是否有语义相似的旧记忆。如果有且相似度超过阈值比如0.9就把旧记忆标记为superseded新记忆标记为active。检索时只返回active状态的记忆。这样既保留了历史用于审计又保证了当前决策的一致性。6.4 冷启动问题没有记忆时怎么办新用户第一次使用时记忆库是空的。这时候Agent不能干等着而是要有冷启动策略。我的做法是准备一套默认的语义记忆模板比如“默认回复语言中文”“默认详细程度中等”“默认技术栈偏好无”。这些默认值在用户没有明确偏好时生效随着用户交互逐渐被真实偏好覆盖。这个策略看起来简单但效果很明显。没有冷启动策略的Agent新用户第一轮体验往往很差因为Agent什么都不知道问什么都要反问。有了默认值至少能给出一个合理的初始响应。7. 这套架构还能往哪些方向延伸7.1 多Agent共享记忆的可行性单个Agent的记忆系统跑通之后自然会想到多Agent场景。多个Agent能不能共享同一套记忆技术上可行但有几个问题要解决。首先是权限隔离。Agent A的记忆不一定对Agent B可见需要设计访问控制。其次是写入冲突。两个Agent同时写入相似记忆时需要去重和合并。最后是检索范围。共享记忆库大了之后检索效率会下降需要做分片或分层。我的建议是先做命名空间隔离再做选择性共享。每个Agent有自己的私有记忆空间同时有一个公共空间存放跨Agent共享的知识。写入时明确指定命名空间检索时按需跨空间查询。7.2 记忆的可解释性让用户知道Agent“记得什么”用户对Agent的记忆是有感知的。如果Agent突然说“你上次提到过...”用户会想知道它到底记得什么、记的对不对。所以记忆的可解释性是一个值得投入的方向。实现上可以提供一个“记忆查看”接口让用户看到Agent存储的关于自己的记忆并且可以手动修正或删除。这个功能不仅提升信任感还能收集用户反馈来优化记忆质量。我在一个项目里加了这个功能后用户主动修正的记忆有30%左右这些修正数据反过来又提升了记忆系统的准确率。7.3 从“记住”到“学会”记忆驱动的Agent进化记忆系统的终极形态不是“存储和检索”而是驱动Agent自我进化。当Agent积累了足够多的情景记忆和语义记忆后它可以从中发现模式、总结规律、优化策略。比如Agent发现“每次处理这类任务时先调用工具A再调用工具B的成功率更高”这个规律就可以固化成一条策略记忆下次遇到类似任务时直接应用。再比如Agent发现“用户对某类回复的满意度较低”就可以调整自己的回复风格。这个方向目前还在探索阶段但已经有一些有意思的实践。核心思路是把记忆系统从“被动存储”变成“主动学习”让Agent在运行过程中不断优化自己。8. 一些零散但实用的建议最后分享几个在实际项目中总结的小经验不一定成体系但都验证过有用。关于embedding模型的选择不要盲目追求大模型。1536维的embedding比768维的精度提升有限但存储和检索成本翻倍。在大多数Agent记忆场景下768维甚至384维的模型就够用了。关键是选一个在你的领域数据上表现好的模型而不是参数最大的模型。关于记忆的TTL设计不是所有记忆都需要永久保存。工作记忆的TTL可以设为任务结束情景记忆的TTL可以设为90天语义记忆可以永久保存但定期做压缩。给每类记忆设置合理的TTL能有效控制存储成本。关于监控记忆系统上线后一定要加监控。关键指标包括写入延迟、检索延迟、检索命中率、记忆库大小、遗忘速率。这些指标能帮你及时发现性能退化和质量问题。关于测试记忆系统的测试比普通系统难因为它的行为是概率性的。我的做法是构建一个“记忆测试集”包含若干组“输入-期望召回”的样本每次修改检索逻辑后跑一遍看召回准确率有没有下降。这个测试集不需要很大几十条就能覆盖主要场景。关于版本管理记忆的schema会随着需求变化而演进。每次变更schema时一定要做数据迁移并且保留旧版本的兼容读取能力。我见过因为schema变更导致历史记忆全部不可读的事故修复成本很高。这套记忆架构我在两个生产项目里完整落地过从最初的“全量存对话”到后来的分层记忆MCP集成Docker部署中间踩了不少坑也积累了一些经验。核心体会是记忆系统的难点不在技术选型而在策略设计——什么时候写、写什么、怎么压缩、怎么检索、什么时候忘这些决策比用什么数据库重要得多。希望这些内容对正在做Agent记忆的你有帮助。