1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”第一次看到“hindsight”这个词我脑子里蹦出来的不是词典释义而是每次调完Agent之后拍大腿的那个瞬间——早知道刚才那轮对话应该把用户偏好写进记忆、早知道这个工具调用结果应该缓存下来、早知道那个失败分支不该直接丢掉。Hindsight直译就是“后见之明”但在Agent Memory这个语境里它指的是一套让LLM驱动的智能体能够回看、检索、复用历史交互信息的记忆机制。说白了就是给Agent装一面后视镜让它别每次上路都像第一次开车。这个项目标题背后要解决的问题非常具体当前大多数基于LLM的Agent在单次会话里表现还行一旦跨会话、跨任务记忆就断片了。用户上周说过“我对花生过敏”这周问“推荐个零食”Agent照样推花生酱饼干。这不是模型笨是记忆架构没搭好。hindsight要做的就是把Agent的working memory、episodic memory、semantic memory分层管理起来配合MCP协议做工具调用用Docker做环境隔离和快速部署形成一套可复现、可扩展的Agent记忆方案。适合谁来参考如果你正在用LLM框架搭Agent、被MCP协议的各种配置折腾过、或者单纯想搞清楚“Agent存储working memory”到底该怎么落地这篇内容就是写给你的。我会从整体设计思路讲到Docker环境搭建、MCP工具接入、记忆分层实现再到实际跑起来之后踩过的坑尽量把每个“为什么这么选”都说明白。不堆术语不搞玄学能抄的配置直接给。2. 整体架构设计hindsight的记忆分层与MCP接入逻辑2.1 为什么不能只靠一个向量库打天下很多人做Agent记忆的第一反应是搞个向量数据库把历史对话全塞进去检索的时候做相似度匹配就完了。我一开始也这么干过结果就是检索出来的东西要么太泛把三周前聊天气的记录翻出来要么太碎只召回半句话上下文全丢了。问题出在记忆没有分层。hindsight的核心设计思路是把Agent记忆拆成三层。第一层是working memory对应单次任务执行期间的临时状态比如当前对话轮次、已调用的工具、中间结果生命周期短读写频繁用内存或Redis就够。第二层是episodic memory记录的是“什么时候发生了什么”比如“用户在第3轮对话中要求查询订单状态工具返回了已发货”这类记忆需要带时间戳和事件边界适合用结构化存储加向量索引。第三层是semantic memory沉淀的是从多次交互中抽象出来的稳定知识比如“该用户偏好简洁回复”“该用户所在时区是UTC8”这类记忆更新频率低但复用价值高。这么分层的理由很直接不同记忆的读写模式、生命周期、检索方式完全不同。working memory要求低延迟episodic memory要求时间范围过滤semantic memory要求高召回精度。混在一起用一个向量库就像把冰箱、衣柜、工具箱全塞进一个纸箱找东西全靠翻。2.2 MCP协议在hindsight里的角色定位MCPModel Context Protocol在这个项目里承担的是“记忆工具化”的职责。什么意思传统做法是把记忆读写逻辑硬编码在Agent的prompt或者代码里改一次记忆策略就要动核心逻辑。hindsight把记忆操作封装成MCP Server暴露的工具Agent通过标准协议调用比如memory_write、memory_search、memory_forget。这样做的优势是记忆层和Agent逻辑解耦换记忆后端不用改Agent代码加新记忆类型只需要注册新工具。MCP本身是软件协议层面的概念跟硬件协议不是一回事。你可以把它理解成Agent和外部能力之间的USB接口标准——只要双方都遵守这个标准插上就能用。hindsight里我用MCP封装了三个核心工具写入记忆、检索记忆、按条件遗忘。每个工具的参数设计都围绕前面说的三层记忆模型来比如写入时需要指定memory_typeworking/episodic/semantic、ttl生存时间、tags标签。2.3 Docker化部署的取舍用Docker跑hindsight不是赶时髦是实际踩坑之后的必然选择。Agent记忆系统依赖的组件不少向量数据库、关系型数据库存episodic、Redis做working memory缓存、MCP Server进程、Agent运行时。本地直接装版本冲突和环境污染能折腾掉一整天。Docker Compose一把起网络互通、卷挂载、环境变量全在配置文件里换机器直接docker compose up。但Docker化也有代价。GPU直通在Windows上一直是个痛点如果你要用本地LLM做embedding得额外配WSL2和NVIDIA Container Toolkit。我的建议是embedding阶段先用API等整个记忆流程跑通了再考虑本地化。另外Docker Desktop在Windows上偶尔会报“Virtualization support not detected”这个后面排查章节细说。3. 环境搭建实操从Docker安装到MCP Server跑通3.1 Docker与Docker Desktop的安装避坑Windows环境下装Docker Desktop最容易卡住的地方不是安装过程本身是装完之后启动报错。我遇到过两种典型情况。第一种是BIOS里虚拟化没开报错信息里带“Virtualization support not detected”解决方法是重启进BIOS找Intel VT-x或AMD-V选项启用。第二种是WSL2内核没更新Docker Desktop启动后一直转圈这时候在PowerShell里跑wsl --update然后wsl --shutdown重启WSL子系统。安装步骤本身不复杂官网下载Docker Desktop安装包双击运行勾选“Use WSL 2 instead of Hyper-V”装完重启。验证安装成功的命令是docker --version docker compose version docker run hello-world第三条命令能正常输出“Hello from Docker!”就说明容器运行时没问题。如果卡在拉镜像阶段检查一下Docker Desktop的代理设置国内网络环境下建议配镜像加速器。Ubuntu环境下装Docker更干净用官方脚本curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER最后一行是把当前用户加入docker组避免每次敲命令都要sudo。执行完需要重新登录shell才生效。3.2 用Docker Compose编排hindsight依赖组件hindsight的依赖组件我整理了一个compose文件核心服务包括Redis做working memory、PostgreSQL加pgvector做episodic和semantic存储、MCP Server进程、以及一个可选的Agent运行时容器。version: 3.9 services: redis: image: redis:7-alpine ports: - 6379:6379 volumes: - redis_data:/data command: redis-server --appendonly yes postgres: image: pgvector/pgvector:pg16 environment: POSTGRES_USER: hindsight POSTGRES_PASSWORD: hindsight_dev POSTGRES_DB: hindsight ports: - 5432:5432 volumes: - pg_data:/var/lib/postgresql/data mcp-server: build: ./mcp-server depends_on: - redis - postgres environment: REDIS_URL: redis://redis:6379/0 DATABASE_URL: postgresql://hindsight:hindsight_devpostgres:5432/hindsight ports: - 8080:8080 volumes: redis_data: pg_data:这里选pgvector而不是独立向量库理由是episodic memory需要同时做时间范围查询和向量相似度检索PostgreSQL一个引擎就能覆盖少维护一个组件。Redis开appendonly是防止working memory在容器重启后全丢虽然working memory生命周期短但调试阶段丢了很麻烦。启动命令就一句docker compose up -d docker compose logs -f mcp-server看到mcp-server日志输出“Memory MCP Server listening on 8080”就说明起来了。3.3 MCP Server的工具注册与Agent侧配置MCP Server这边我用Python写核心是注册三个工具。工具定义遵循MCP的schema规范每个工具声明名称、描述、参数结构。以memory_write为例mcp.tool() def memory_write( content: str, memory_type: str, tags: list[str] [], ttl_seconds: int 0 ) - dict: 写入一条Agent记忆。 memory_type: working | episodic | semantic ttl_seconds: 0表示永不过期 if memory_type working: redis_client.setex(fwm:{uuid4()}, ttl_seconds or 3600, content) elif memory_type episodic: embedding embed(content) db.execute( INSERT INTO episodic (content, embedding, tags, created_at) VALUES (%s, %s, %s, now()), (content, embedding, tags) ) elif memory_type semantic: embedding embed(content) db.execute( INSERT INTO semantic (content, embedding, tags, updated_at) VALUES (%s, %s, %s, now()), (content, embedding, tags) ) return {status: ok}Agent侧配置MCP连接不同框架写法不一样。以常见的配置方式为例在Agent的MCP配置里加上{ mcpServers: { hindsight-memory: { url: http://localhost:8080/sse, transport: sse } } }这里用SSE传输而不是stdio是因为MCP Server跑在Docker容器里stdio方式需要Agent进程和Server在同一容器耦合太紧。SSE方式Agent和Server可以独立部署也方便多个Agent共享同一套记忆。注意MCP Server的SSE端点默认不带鉴权本地开发没问题如果要暴露到局域网或公网务必加token校验。我见过有人直接把MCP端口开到公网结果记忆库被人清空的情况。4. 记忆读写核心逻辑三层记忆的落地细节4.1 Working Memory的TTL设计与淘汰策略Working memory的核心矛盾是Agent执行任务时需要记住的东西很多但内存有限不能无限堆积。hindsight的做法是给每条working memory设TTL默认3600秒任务结束后主动清理。但光靠TTL不够因为有些任务执行时间可能超过TTL中途记忆就丢了。我的改进方案是双轨制TTL兜底加显式清理。Agent在任务开始时调用memory_write写入working memory同时拿到一个session_id。任务执行过程中所有working memory都带这个session_id标签。任务结束时Agent调用memory_forget参数传session_id一次性清掉该会话所有working memory。TTL设长一点比如7200秒作为异常情况下的兜底。淘汰策略上Redis的allkeys-lru策略在working memory场景下够用但要注意如果Redis同时存了其他数据LRU可能误淘汰。所以hindsight里Redis实例是专用的只存working memory不混用。4.2 Episodic Memory的时间索引与检索Episodic memory的检索需求通常是“最近N次交互中关于X的记录”。纯向量检索做不到时间范围过滤所以hindsight在pgvector表上建了复合索引CREATE INDEX idx_episodic_time_vec ON episodic USING ivfflat (embedding vector_cosine_ops) WITH (lists 100); CREATE INDEX idx_episodic_created ON episodic (created_at DESC);检索时先用时间范围缩小候选集再做向量相似度排序。SQL大致长这样SELECT content, created_at, 1 - (embedding %s::vector) AS similarity FROM episodic WHERE created_at now() - interval 7 days AND tags %s ORDER BY embedding %s::vector LIMIT 10;这里tags %s是数组重叠操作用来做标签过滤。比如只检索带“订单”标签的记忆。实测下来先时间过滤再向量排序比纯向量检索的准确率高不少因为排除了太久远的不相关记忆。4.3 Semantic Memory的冲突消解与更新Semantic memory最麻烦的地方是冲突。比如Agent先学到“用户喜欢喝咖啡”后来又学到“用户戒咖啡了”两条记忆都存进去检索时可能同时召回Agent就懵了。hindsight的处理方式是写入semantic memory时先做相似度检查如果新记忆和已有记忆相似度超过阈值我设的0.92就走更新而不是插入。更新逻辑分两种情况。如果新记忆是对旧记忆的补充比如旧的是“用户喜欢喝咖啡”新的是“用户喜欢喝浅烘咖啡”那就合并成一条更具体的。如果新记忆和旧记忆矛盾比如“戒咖啡了”和“喜欢喝咖啡”那就把旧记忆标记为superseded检索时默认不返回但保留历史记录以便追溯。def upsert_semantic(content, tags): embedding embed(content) similar db.query( SELECT id, content, 1 - (embedding %s::vector) AS sim FROM semantic WHERE superseded false ORDER BY embedding %s::vector LIMIT 1, (embedding, embedding) ) if similar and similar[0][sim] 0.92: if is_contradiction(similar[0][content], content): db.execute(UPDATE semantic SET superseded true WHERE id %s, (similar[0][id],)) db.execute(INSERT INTO semantic (content, embedding, tags) VALUES (%s, %s, %s), (content, embedding, tags)) else: merged merge_content(similar[0][content], content) db.execute(UPDATE semantic SET content %s, embedding %s WHERE id %s, (merged, embed(merged), similar[0][id])) else: db.execute(INSERT INTO semantic (content, embedding, tags) VALUES (%s, %s, %s), (content, embedding, tags))is_contradiction这个判断我用了一个小LLM调用来做prompt就是让模型判断两句话是否矛盾。虽然多一次调用但比规则匹配靠谱得多。4.4 记忆检索的Token预算控制LLM的context window是有限的检索出来的记忆不能全塞进去。hindsight在检索层做了token预算控制先按相似度和时间新鲜度排序然后从高到低累加token数超过预算就截断。预算值根据Agent当前任务的复杂度动态调整简单问答给512 token复杂规划任务给2048 token。这个逻辑写在MCP Server的memory_search工具里返回结果带一个truncated标志Agent知道记忆被截断了可以在prompt里说明“以下记忆可能不完整”。5. 常见问题与排查实录5.1 Docker网络不通的排查路径Docker Compose起来之后mcp-server连不上postgres日志报connection refused。排查顺序是这样的先docker compose ps看容器状态确认postgres是healthy不是starting。然后docker compose exec mcp-server ping postgres如果ping不通说明不在同一网络。Compose默认会创建同名网络但如果用了network_mode: host或者自定义网络配置有误就会出问题。另一个常见原因是postgres启动慢mcp-server启动快mcp-server先起来连不上就退出了。解决办法是在compose里加depends_on配合healthcheckpostgres: healthcheck: test: [CMD-SHELL, pg_isready -U hindsight] interval: 5s retries: 5 mcp-server: depends_on: postgres: condition: service_healthy5.2 MCP工具调用超时的处理Agent调用memory_search偶尔超时尤其是episodic memory数据量大了之后。根因是pgvector的ivfflat索引在数据量增长后召回率下降查询变慢。解决方案有两个一是调大lists参数重建索引二是加probes参数提高查询精度。但更根本的是控制episodic memory的总量我加了一个定时任务把30天前的episodic memory归档到冷存储主表只保留近期数据。MCP Server侧也加了超时保护memory_search默认3秒超时超时返回空结果加timeout标志不让Agent卡死。5.3 记忆污染与误写入的防范Agent有时候会把工具返回的原始数据当记忆写进去比如把一整段JSON响应存成semantic memory。这种记忆污染会拉低检索质量。hindsight的防范措施是在memory_write工具里加内容校验semantic memory的内容长度超过500字符就拒绝episodic memory超过2000字符拒绝。同时Agent的prompt里明确写“只写入抽象后的结论不要写入原始数据”。还有一个坑是Agent把临时计算结果写成semantic memory。比如“当前订单金额是299元”这是episodic不是semantic。我在工具描述里加了明确指引并且给semantic memory的写入加了二次确认写入前先让LLM判断这条记忆是否具有跨会话复用价值。5.4 常见问题速查表问题现象可能原因排查命令解决方式Docker Desktop启动失败虚拟化未开启或WSL2未更新wsl --statusBIOS开VT-xwsl --updatemcp-server连不上postgres容器不在同一网络或启动顺序问题docker compose exec mcp-server ping postgres加healthcheck和depends_onmemory_search超时pgvector索引退化或数据量过大EXPLAIN ANALYZE查执行计划重建索引归档冷数据记忆检索结果不相关记忆污染或embedding模型不匹配抽查semantic表内容加写入校验统一embedding模型Agent重复写入相同记忆缺少去重逻辑查semantic表相似记录写入前做相似度检查6. 实操心得与后续扩展方向跑通hindsight这套流程之后有几个心得值得单独拎出来说。第一embedding模型的选择比向量库的选择重要得多。我试过用不同模型对同一批记忆做embedding检索准确率差异能到20%以上。建议先用一个中等规模的模型跑通流程再根据实际检索效果决定要不要换更大的模型。第二MCP工具的粒度要适中。太粗了Agent不会用太细了调用次数爆炸。hindsight三个工具write/search/forget是我试下来比较平衡的粒度。后续扩展方向有几个。一是加记忆重要性评分让Agent自己判断哪些记忆值得长期保留哪些可以快速遗忘。二是做跨Agent记忆共享多个Agent通过同一个MCP Server读写记忆实现团队级知识沉淀。三是接GraphRAG把semantic memory从扁平向量升级成知识图谱提升多跳推理能力。这些方向我还在实验中等跑出稳定结果再单独整理。最后分享一个调试技巧hindsight的MCP Server加一个/debug/memory端点返回当前所有记忆的摘要统计包括各层记忆数量、最近写入时间、检索命中率。调Agent行为的时候先看这个端点比翻日志快得多。
基于MCP与Docker的Agent记忆分层架构：hindsight实战指南
1. 从“hindsight”说起为什么我们需要给Agent装上“后视镜”第一次看到“hindsight”这个词我脑子里蹦出来的不是词典释义而是每次调完Agent之后拍大腿的那个瞬间——早知道刚才那轮对话应该把用户偏好写进记忆、早知道这个工具调用结果应该缓存下来、早知道那个失败分支不该直接丢掉。Hindsight直译就是“后见之明”但在Agent Memory这个语境里它指的是一套让LLM驱动的智能体能够回看、检索、复用历史交互信息的记忆机制。说白了就是给Agent装一面后视镜让它别每次上路都像第一次开车。这个项目标题背后要解决的问题非常具体当前大多数基于LLM的Agent在单次会话里表现还行一旦跨会话、跨任务记忆就断片了。用户上周说过“我对花生过敏”这周问“推荐个零食”Agent照样推花生酱饼干。这不是模型笨是记忆架构没搭好。hindsight要做的就是把Agent的working memory、episodic memory、semantic memory分层管理起来配合MCP协议做工具调用用Docker做环境隔离和快速部署形成一套可复现、可扩展的Agent记忆方案。适合谁来参考如果你正在用LLM框架搭Agent、被MCP协议的各种配置折腾过、或者单纯想搞清楚“Agent存储working memory”到底该怎么落地这篇内容就是写给你的。我会从整体设计思路讲到Docker环境搭建、MCP工具接入、记忆分层实现再到实际跑起来之后踩过的坑尽量把每个“为什么这么选”都说明白。不堆术语不搞玄学能抄的配置直接给。2. 整体架构设计hindsight的记忆分层与MCP接入逻辑2.1 为什么不能只靠一个向量库打天下很多人做Agent记忆的第一反应是搞个向量数据库把历史对话全塞进去检索的时候做相似度匹配就完了。我一开始也这么干过结果就是检索出来的东西要么太泛把三周前聊天气的记录翻出来要么太碎只召回半句话上下文全丢了。问题出在记忆没有分层。hindsight的核心设计思路是把Agent记忆拆成三层。第一层是working memory对应单次任务执行期间的临时状态比如当前对话轮次、已调用的工具、中间结果生命周期短读写频繁用内存或Redis就够。第二层是episodic memory记录的是“什么时候发生了什么”比如“用户在第3轮对话中要求查询订单状态工具返回了已发货”这类记忆需要带时间戳和事件边界适合用结构化存储加向量索引。第三层是semantic memory沉淀的是从多次交互中抽象出来的稳定知识比如“该用户偏好简洁回复”“该用户所在时区是UTC8”这类记忆更新频率低但复用价值高。这么分层的理由很直接不同记忆的读写模式、生命周期、检索方式完全不同。working memory要求低延迟episodic memory要求时间范围过滤semantic memory要求高召回精度。混在一起用一个向量库就像把冰箱、衣柜、工具箱全塞进一个纸箱找东西全靠翻。2.2 MCP协议在hindsight里的角色定位MCPModel Context Protocol在这个项目里承担的是“记忆工具化”的职责。什么意思传统做法是把记忆读写逻辑硬编码在Agent的prompt或者代码里改一次记忆策略就要动核心逻辑。hindsight把记忆操作封装成MCP Server暴露的工具Agent通过标准协议调用比如memory_write、memory_search、memory_forget。这样做的优势是记忆层和Agent逻辑解耦换记忆后端不用改Agent代码加新记忆类型只需要注册新工具。MCP本身是软件协议层面的概念跟硬件协议不是一回事。你可以把它理解成Agent和外部能力之间的USB接口标准——只要双方都遵守这个标准插上就能用。hindsight里我用MCP封装了三个核心工具写入记忆、检索记忆、按条件遗忘。每个工具的参数设计都围绕前面说的三层记忆模型来比如写入时需要指定memory_typeworking/episodic/semantic、ttl生存时间、tags标签。2.3 Docker化部署的取舍用Docker跑hindsight不是赶时髦是实际踩坑之后的必然选择。Agent记忆系统依赖的组件不少向量数据库、关系型数据库存episodic、Redis做working memory缓存、MCP Server进程、Agent运行时。本地直接装版本冲突和环境污染能折腾掉一整天。Docker Compose一把起网络互通、卷挂载、环境变量全在配置文件里换机器直接docker compose up。但Docker化也有代价。GPU直通在Windows上一直是个痛点如果你要用本地LLM做embedding得额外配WSL2和NVIDIA Container Toolkit。我的建议是embedding阶段先用API等整个记忆流程跑通了再考虑本地化。另外Docker Desktop在Windows上偶尔会报“Virtualization support not detected”这个后面排查章节细说。3. 环境搭建实操从Docker安装到MCP Server跑通3.1 Docker与Docker Desktop的安装避坑Windows环境下装Docker Desktop最容易卡住的地方不是安装过程本身是装完之后启动报错。我遇到过两种典型情况。第一种是BIOS里虚拟化没开报错信息里带“Virtualization support not detected”解决方法是重启进BIOS找Intel VT-x或AMD-V选项启用。第二种是WSL2内核没更新Docker Desktop启动后一直转圈这时候在PowerShell里跑wsl --update然后wsl --shutdown重启WSL子系统。安装步骤本身不复杂官网下载Docker Desktop安装包双击运行勾选“Use WSL 2 instead of Hyper-V”装完重启。验证安装成功的命令是docker --version docker compose version docker run hello-world第三条命令能正常输出“Hello from Docker!”就说明容器运行时没问题。如果卡在拉镜像阶段检查一下Docker Desktop的代理设置国内网络环境下建议配镜像加速器。Ubuntu环境下装Docker更干净用官方脚本curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER最后一行是把当前用户加入docker组避免每次敲命令都要sudo。执行完需要重新登录shell才生效。3.2 用Docker Compose编排hindsight依赖组件hindsight的依赖组件我整理了一个compose文件核心服务包括Redis做working memory、PostgreSQL加pgvector做episodic和semantic存储、MCP Server进程、以及一个可选的Agent运行时容器。version: 3.9 services: redis: image: redis:7-alpine ports: - 6379:6379 volumes: - redis_data:/data command: redis-server --appendonly yes postgres: image: pgvector/pgvector:pg16 environment: POSTGRES_USER: hindsight POSTGRES_PASSWORD: hindsight_dev POSTGRES_DB: hindsight ports: - 5432:5432 volumes: - pg_data:/var/lib/postgresql/data mcp-server: build: ./mcp-server depends_on: - redis - postgres environment: REDIS_URL: redis://redis:6379/0 DATABASE_URL: postgresql://hindsight:hindsight_devpostgres:5432/hindsight ports: - 8080:8080 volumes: redis_data: pg_data:这里选pgvector而不是独立向量库理由是episodic memory需要同时做时间范围查询和向量相似度检索PostgreSQL一个引擎就能覆盖少维护一个组件。Redis开appendonly是防止working memory在容器重启后全丢虽然working memory生命周期短但调试阶段丢了很麻烦。启动命令就一句docker compose up -d docker compose logs -f mcp-server看到mcp-server日志输出“Memory MCP Server listening on 8080”就说明起来了。3.3 MCP Server的工具注册与Agent侧配置MCP Server这边我用Python写核心是注册三个工具。工具定义遵循MCP的schema规范每个工具声明名称、描述、参数结构。以memory_write为例mcp.tool() def memory_write( content: str, memory_type: str, tags: list[str] [], ttl_seconds: int 0 ) - dict: 写入一条Agent记忆。 memory_type: working | episodic | semantic ttl_seconds: 0表示永不过期 if memory_type working: redis_client.setex(fwm:{uuid4()}, ttl_seconds or 3600, content) elif memory_type episodic: embedding embed(content) db.execute( INSERT INTO episodic (content, embedding, tags, created_at) VALUES (%s, %s, %s, now()), (content, embedding, tags) ) elif memory_type semantic: embedding embed(content) db.execute( INSERT INTO semantic (content, embedding, tags, updated_at) VALUES (%s, %s, %s, now()), (content, embedding, tags) ) return {status: ok}Agent侧配置MCP连接不同框架写法不一样。以常见的配置方式为例在Agent的MCP配置里加上{ mcpServers: { hindsight-memory: { url: http://localhost:8080/sse, transport: sse } } }这里用SSE传输而不是stdio是因为MCP Server跑在Docker容器里stdio方式需要Agent进程和Server在同一容器耦合太紧。SSE方式Agent和Server可以独立部署也方便多个Agent共享同一套记忆。注意MCP Server的SSE端点默认不带鉴权本地开发没问题如果要暴露到局域网或公网务必加token校验。我见过有人直接把MCP端口开到公网结果记忆库被人清空的情况。4. 记忆读写核心逻辑三层记忆的落地细节4.1 Working Memory的TTL设计与淘汰策略Working memory的核心矛盾是Agent执行任务时需要记住的东西很多但内存有限不能无限堆积。hindsight的做法是给每条working memory设TTL默认3600秒任务结束后主动清理。但光靠TTL不够因为有些任务执行时间可能超过TTL中途记忆就丢了。我的改进方案是双轨制TTL兜底加显式清理。Agent在任务开始时调用memory_write写入working memory同时拿到一个session_id。任务执行过程中所有working memory都带这个session_id标签。任务结束时Agent调用memory_forget参数传session_id一次性清掉该会话所有working memory。TTL设长一点比如7200秒作为异常情况下的兜底。淘汰策略上Redis的allkeys-lru策略在working memory场景下够用但要注意如果Redis同时存了其他数据LRU可能误淘汰。所以hindsight里Redis实例是专用的只存working memory不混用。4.2 Episodic Memory的时间索引与检索Episodic memory的检索需求通常是“最近N次交互中关于X的记录”。纯向量检索做不到时间范围过滤所以hindsight在pgvector表上建了复合索引CREATE INDEX idx_episodic_time_vec ON episodic USING ivfflat (embedding vector_cosine_ops) WITH (lists 100); CREATE INDEX idx_episodic_created ON episodic (created_at DESC);检索时先用时间范围缩小候选集再做向量相似度排序。SQL大致长这样SELECT content, created_at, 1 - (embedding %s::vector) AS similarity FROM episodic WHERE created_at now() - interval 7 days AND tags %s ORDER BY embedding %s::vector LIMIT 10;这里tags %s是数组重叠操作用来做标签过滤。比如只检索带“订单”标签的记忆。实测下来先时间过滤再向量排序比纯向量检索的准确率高不少因为排除了太久远的不相关记忆。4.3 Semantic Memory的冲突消解与更新Semantic memory最麻烦的地方是冲突。比如Agent先学到“用户喜欢喝咖啡”后来又学到“用户戒咖啡了”两条记忆都存进去检索时可能同时召回Agent就懵了。hindsight的处理方式是写入semantic memory时先做相似度检查如果新记忆和已有记忆相似度超过阈值我设的0.92就走更新而不是插入。更新逻辑分两种情况。如果新记忆是对旧记忆的补充比如旧的是“用户喜欢喝咖啡”新的是“用户喜欢喝浅烘咖啡”那就合并成一条更具体的。如果新记忆和旧记忆矛盾比如“戒咖啡了”和“喜欢喝咖啡”那就把旧记忆标记为superseded检索时默认不返回但保留历史记录以便追溯。def upsert_semantic(content, tags): embedding embed(content) similar db.query( SELECT id, content, 1 - (embedding %s::vector) AS sim FROM semantic WHERE superseded false ORDER BY embedding %s::vector LIMIT 1, (embedding, embedding) ) if similar and similar[0][sim] 0.92: if is_contradiction(similar[0][content], content): db.execute(UPDATE semantic SET superseded true WHERE id %s, (similar[0][id],)) db.execute(INSERT INTO semantic (content, embedding, tags) VALUES (%s, %s, %s), (content, embedding, tags)) else: merged merge_content(similar[0][content], content) db.execute(UPDATE semantic SET content %s, embedding %s WHERE id %s, (merged, embed(merged), similar[0][id])) else: db.execute(INSERT INTO semantic (content, embedding, tags) VALUES (%s, %s, %s), (content, embedding, tags))is_contradiction这个判断我用了一个小LLM调用来做prompt就是让模型判断两句话是否矛盾。虽然多一次调用但比规则匹配靠谱得多。4.4 记忆检索的Token预算控制LLM的context window是有限的检索出来的记忆不能全塞进去。hindsight在检索层做了token预算控制先按相似度和时间新鲜度排序然后从高到低累加token数超过预算就截断。预算值根据Agent当前任务的复杂度动态调整简单问答给512 token复杂规划任务给2048 token。这个逻辑写在MCP Server的memory_search工具里返回结果带一个truncated标志Agent知道记忆被截断了可以在prompt里说明“以下记忆可能不完整”。5. 常见问题与排查实录5.1 Docker网络不通的排查路径Docker Compose起来之后mcp-server连不上postgres日志报connection refused。排查顺序是这样的先docker compose ps看容器状态确认postgres是healthy不是starting。然后docker compose exec mcp-server ping postgres如果ping不通说明不在同一网络。Compose默认会创建同名网络但如果用了network_mode: host或者自定义网络配置有误就会出问题。另一个常见原因是postgres启动慢mcp-server启动快mcp-server先起来连不上就退出了。解决办法是在compose里加depends_on配合healthcheckpostgres: healthcheck: test: [CMD-SHELL, pg_isready -U hindsight] interval: 5s retries: 5 mcp-server: depends_on: postgres: condition: service_healthy5.2 MCP工具调用超时的处理Agent调用memory_search偶尔超时尤其是episodic memory数据量大了之后。根因是pgvector的ivfflat索引在数据量增长后召回率下降查询变慢。解决方案有两个一是调大lists参数重建索引二是加probes参数提高查询精度。但更根本的是控制episodic memory的总量我加了一个定时任务把30天前的episodic memory归档到冷存储主表只保留近期数据。MCP Server侧也加了超时保护memory_search默认3秒超时超时返回空结果加timeout标志不让Agent卡死。5.3 记忆污染与误写入的防范Agent有时候会把工具返回的原始数据当记忆写进去比如把一整段JSON响应存成semantic memory。这种记忆污染会拉低检索质量。hindsight的防范措施是在memory_write工具里加内容校验semantic memory的内容长度超过500字符就拒绝episodic memory超过2000字符拒绝。同时Agent的prompt里明确写“只写入抽象后的结论不要写入原始数据”。还有一个坑是Agent把临时计算结果写成semantic memory。比如“当前订单金额是299元”这是episodic不是semantic。我在工具描述里加了明确指引并且给semantic memory的写入加了二次确认写入前先让LLM判断这条记忆是否具有跨会话复用价值。5.4 常见问题速查表问题现象可能原因排查命令解决方式Docker Desktop启动失败虚拟化未开启或WSL2未更新wsl --statusBIOS开VT-xwsl --updatemcp-server连不上postgres容器不在同一网络或启动顺序问题docker compose exec mcp-server ping postgres加healthcheck和depends_onmemory_search超时pgvector索引退化或数据量过大EXPLAIN ANALYZE查执行计划重建索引归档冷数据记忆检索结果不相关记忆污染或embedding模型不匹配抽查semantic表内容加写入校验统一embedding模型Agent重复写入相同记忆缺少去重逻辑查semantic表相似记录写入前做相似度检查6. 实操心得与后续扩展方向跑通hindsight这套流程之后有几个心得值得单独拎出来说。第一embedding模型的选择比向量库的选择重要得多。我试过用不同模型对同一批记忆做embedding检索准确率差异能到20%以上。建议先用一个中等规模的模型跑通流程再根据实际检索效果决定要不要换更大的模型。第二MCP工具的粒度要适中。太粗了Agent不会用太细了调用次数爆炸。hindsight三个工具write/search/forget是我试下来比较平衡的粒度。后续扩展方向有几个。一是加记忆重要性评分让Agent自己判断哪些记忆值得长期保留哪些可以快速遗忘。二是做跨Agent记忆共享多个Agent通过同一个MCP Server读写记忆实现团队级知识沉淀。三是接GraphRAG把semantic memory从扁平向量升级成知识图谱提升多跳推理能力。这些方向我还在实验中等跑出稳定结果再单独整理。最后分享一个调试技巧hindsight的MCP Server加一个/debug/memory端点返回当前所有记忆的摘要统计包括各层记忆数量、最近写入时间、检索命中率。调Agent行为的时候先看这个端点比翻日志快得多。
