10分钟给Agent装上长期记忆：Hindsight部署实战指南

10分钟给Agent装上长期记忆Hindsight部署实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个开源的 Agent 长期记忆系统retain把对话提炼成事实recall按需召回相关记忆reflect对记忆做深度综合。读完本文你可以用一条 Docker 命令启动自托管实例再用几行客户端代码让任意 Agent 获得跨会话记忆并避开部署中最常见的几个坑。会话一关就失忆长上下文为什么救不了你先说一个扎心的事实上下文窗口context window再大也只是工作台不是仓库。1M token 的窗口每开一个新会话就清零而且注意力在填满之前就开始退化——Agent 对你上周说过的那件事一无所知。大多数 Agent 框架的记忆方案是拼接历史对话或做 RAG 检索前者撑不住跨会话后者只检索文本、不理解时间线、实体和因果关系。Hindsight 把这件事做成了独立系统记忆存进去时会抽取事实、实体、时间区间检索时语义、关键词、图谱、时序四条通道并行召回在 LongMemEval 这类长期记忆基准上拿到了当前最优成绩。判断标准很简单你的 Agent 需要记住人、记住决定、记住时间线而不只是查到一段旧文本那就值得上独立的记忆层。记忆三操作全景retain、recall、reflectHindsight 的全部能力收敛在三个动词上理解它们就理解了整个系统retain留存把信息推进记忆库。服务端会用 LLM 从内容里抽取关键事实、时间区间、实体与关系归一化后写入存储——你存一句爱丽丝升了高级工程师库里的是一条带时间戳、挂实体的事实而不是一坨原文。recall召回按查询检索记忆支持语义查询和六月发生了什么这类时间查询。reflect综合对已有记忆做深度推理回答需要想而不是查的问题比如我该了解爱丽丝的哪些风险点。所有记忆都存放在记忆库memory bank里一个库就是一个隔离的大脑——一个用户、一个 Agent 或一个项目一个库库与库之间零泄漏。动手部署Docker 起服务三行代码接客户端✅ 自托管最短路径就两步。第一步起服务——内置 PostgreSQLpg0无需另装数据库只需给一个 LLM Key 用于事实抽取export OPENAI_API_KEYsk-xxx docker run -it --pull always --name hindsight --restart unless-stopped -p 8888:8888 -p 9999:9999 \ -e HINDSIGHT_API_LLM_API_KEY$OPENAI_API_KEY \ -v hindsight-data:/home/hindsight/.pg0 \ ghcr.io/vectorize-io/hindsight:latestAPI 在http://localhost:8888图形界面在http://localhost:9999。数据全部落在hindsight-data卷里删容器不删数据。第二步接客户端Python 为例from hindsight_client import Hindsight client Hindsight(base_urlhttp://localhost:8888) client.retain(bank_idmy-bank, contentAlice works at Google as a software engineer) client.recall(bank_idmy-bank, queryWhat does Alice do?) client.reflect(bank_idmy-bank, queryTell me about Alice)Node.js 对应vectorize-io/hindsight-clientGo 也有官方客户端。不想管服务的话pip install hindsight-all可以进程内嵌入跑适合本地脚本和单机原型。完整安装清单含裸机 pip、Helm、外部 PostgreSQL见 hindsight-docs/docs/developer/installation.md部署方式对比见 README.md。召回为什么准四条通道加预算过滤看recall的内部流程就明白它为什么比向量相似度取 TopK可靠一次recall是四个检索器并行出结果语义向量相似度、关键词BM25 精确匹配、图谱实体/因果链遍历、时序时间范围过滤。四路结果用倒数排名融合RRF合并再过一个交叉编码器重排模型调序最后按 token 预算裁剪到你能塞进上下文的大小。这套设计对使用者的实际影响是三点精确名词工单号、代码符号、人名不会被语义检索吞掉BM25 通道兜底上次那个决定是什么时候做的这类时间问题有专门通道不用靠关键词碰运气返回结果有 token 预算上限recallMaxTokens等参数可调记忆再长也不会撑爆上下文。写入侧同理retain的抽取流水线如图所示LLM 先抽事实再做实体归一与链接构建最后按 World / Experience / Opinion / Observation 分路路由入库。常见问题排查404、假死与预算三件事部署后最容易踩的四个坑按出现频率排bank_id 拼错收到 404——这是特性不是 bug。读取不存在的 bank 会显式返回 404而不是假装健康地给空结果。所以看到 404 先查 bank 名拼写别怀疑服务挂了。/health返回慢或 5xx但 API 页面打得开。/health是就绪探针readiness会真实取一条数据库连接执行SELECT 1数据库连接池耗尽或 DB 抖动时它会失败而纯进程存活探针/health/live照常 200。排查时两个都打一遍/health/live正常 /health异常基本可以锁定数据库侧。recall正常但reflect报错提示 LLM 认证失效。检索走的是数据库综合才依赖 LLM。如果你同时有多个进程共用同一份订阅类凭据例如 Codex 的 refresh token 是单次的长驻服务会被别的进程刷掉凭据——给 Hindsight 单独配一份CODEX_HOME即可细节在 hindsight-docs/docs/developer/models.mdx。召回不够深或太慢。用recallBudgetlow/mid/high默认mid调投入强度low走固定小预算适合低延迟闲聊high把检索预算拉满适合关键任务的深度回忆。多用户场景再叠加 metadata 过滤retain 时带上user_idrecall 时按它筛就能一个库服务多个用户且互不串味做法见下文的 per-user 流程。从单库到多用户下一步路线个人原型跑通之后往生产的路线大致是多用户按一用户一 bank或单 bank metadata 过滤二选一需要 Agent 每次启动就带着结论进场就给 bank 配 mental model心智模型——你定义问题它在后台持续维护答案读取只是一次数据库查询担心对话里的密钥、证件号被存进记忆开启按 bank 的 Memory Defense 策略做入库前脱敏。两条延伸阅读hindsight-docs/docs/developer/retrieval.md 讲全召回参数hindsight-docs/docs/developer/configuration.md 是完整配置清单。回到开头的痛点新开会话 Agent 就谁也不认识。现在最短复现路径只有一条——Docker 起服务客户端调一次retain再开一个新会话调recall你会发现它还记得。记忆这件事从每次重新解释变成存一次用很多年只差这几行代码。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考