GitHub 4.4万 Star，又一款开源的 Agent 记忆系统火出圈了

阅读全文

⭐⭐⭐ Spring Boot 项目实战	⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》	《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》	《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》	《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》	《Java 面试题 + Java 学习指南》

摘要: 原创出处 http://www.iocoder.cn/Fight/hindsight-agent-memory-system/ 「芋道源码」欢迎转载，保留摘要，谢谢！

🙂🙂🙂关注微信公众号：【芋道源码】有福利：

RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表

RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址

您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。

新的源码解析文章实时收到通知。每周更新一篇左右。

认真的源码交流微信群。

上周跟 AI 说过自己不吃辣、代码统一用单引号，这周新开一个会话，它又开始推荐川菜。模型不存状态，会话一关，说过的一切就没了。常见的办法是塞历史记录，或者接个 RAG 检索，解决的都是存和搜，学不到什么。

GitHub 上叫 Hindsight 的项目在冲榜，现在四万四千多 Star，Vectorize.io 开源的 Agent 记忆系统，MIT 协议。

仓库首页实时截图，Star 与 Fork 计数同时可见

这篇我聊它凭什么和一堆向量库不一样。

它把记忆拆成四层，而不是塞进一个库

记忆网络结构图，三个动作与四类记忆节点

论文叫《Hindsight is 20/20》。这名字是个英文双关，字面是「事后看什么都清楚」，hindsight 当动词用就是事后总结，跟这套系统做的事对得上。

摘要里有句话很关键。它说现有这一代记忆系统把记忆当成模型外面的一层，抽片段、塞进向量库或图库、查询时取 top-k 塞回 prompt，改善了个人化，但仍然把证据和推断搅在一起。

Hindsight 的解法是分四类存。

世界事实，客观知识。
经历，Agent 自己做过什么、被纠正过什么。
观察，从很多条记忆里归纳出的结论，每条都带证据。
心智模型，对某个问题的理解，会跟着新记忆更新。

前两类是证据，后两类是推断。观察那条后面跟着支撑它的原文引用和证据条数，能顺着看到它是从哪几条记忆推出来的。

写进去之前先理解一遍，读的时候四路同时找

retain 操作流程图，从抽取到四个存储桶

retain 是写入。原文不会直接进数据库，写入前先让模型抽事实、实体、关系和时间，再归一化，变成规范实体、时间序列和检索索引。纯向量库只做 embedding。

多花的那次调用换来的是查询侧的能力，写进来时已经拆成实体和时间，查询才能沿着关系找。

recall 操作流程图，四路并行后融合重排

recall 是查询，一次同时跑四路，语义向量匹配、BM25 关键词匹配、沿实体和时间关系的图谱检索、按时间范围过滤，汇总后先拿 RRF 融合排序，再过交叉编码器重排，按 token 预算裁剪。

每一路都不是新技术，BM25 是上个世纪的东西。它的做法是四路都跑完再融合，覆盖面宽，代价是召回得多，靠重排压回来。

reflect 是它最像会学的地方

reflect 操作流程图，分析后回写

reflect 不是再查一次，是在已有记忆上做分析、得出新结论。官方举了三个例子。

项目管理 Agent 可以分析当前项目有哪些风险要处理。
销售 Agent 可以总结哪类 outreach 话术回复率高。
客服 Agent 能发现哪些问题在产品文档里还没有答案。

第三个例子最能说明它和检索的区别，检索只能告诉你文档里有什么，reflect 能告诉你文档里缺什么。

记忆库还能配性格参数，怀疑度、字面度、共情度。同样的证据，不同性格的 Agent 观点不一样。观点带置信度，来了新证据是在原来的判断上更新，不会直接覆盖。

它把事实和推断分开放，这样 Agent 才说得清自己凭什么这么想。

每个用户一个独立记忆库，写入还有一道闸门

记忆存在 bank 里，一个用户或一个项目对应一个 bank，库之间严格隔离。多语言这块比较细，中文人名张伟存进去还是张伟，不会变成 Zhang Wei。

写入还有一道闸门叫 Memory Defense，会扫密钥和隐私信息，内置 45 种模式，可以打码也可以直接拦下来。

心智模型值得单独说。给一个 bank 提一个固定问题，Hindsight 把答案写好存起来，后台来了新记忆就重写一遍。读它是一次数据库读取，不走检索也不调模型，Agent 启动就能带着一页现成知识开工。知识页是它的简化版，能导出成 markdown。

接入成本低到只需要一次包装

已有的 Agent 要接，最省事的是 LLM Wrapper，把原来的 LLM 客户端包一层，两行代码，之后每次调用自动存和取。官方列了 60 多个集成，LangGraph、CrewAI、n8n、Dify 都能接。每个 bank 自带 MCP 端点，默认开着，地址是 http://localhost:8888/mcp/{bank_id}/。

写代码的场景有个单独的包，一条命令给 Claude Code、Codex CLI、Cursor CLI 这些工具装上项目级长期记忆，记忆库按 git 历史和历史会话自动建。

一条 Docker 命令跑起来，模型随便挑

本地起服务一条命令就够。

export OPENAI_API_KEY=sk-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:latest

API 在 8888 端口，管理界面在 9999 端口。数据卷给内嵌数据库落盘用，不挂的话容器一重建记忆就没了。OPENAI_API_KEY 只是官方沿用的变量名，用哪家的 key 都行。

模型支持 25 家以上，DeepSeek、MiniMax 都在里面。想本地跑接 Ollama、LM Studio 或 llama.cpp，OpenAI 兼容接口也能用，改 HINDSIGHT_API_LLM_PROVIDER 就行。代码里主要就三个方法。

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

# Retain: store information
client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")

# Recall: search memories
client.recall(bank_id="my-bank", query="What does Alice do?")

# Reflect: generate an answer
client.reflect(bank_id="my-bank", query="Tell me about Alice")

不想起服务，pip install hindsight-all 能在 Python 里嵌入式跑。生产存储是 PostgreSQL 加 pgvector，也能换甲骨文的 AI Database，上 Kubernetes 有现成的 Helm chart。官方还有托管版 Hindsight Cloud，按量计费，没有固定月费和席位费。

分数很好看，但这些事得先知道

LongMemEval 基准对比，四家分值横向排列

仓库的对比图里，Hindsight 是 94.6%，GPT-4o 60.2%，Zep 71.2%，SuperMemory 85.92%。论文里写的是 91.4%，对应把骨干模型继续往上推之后的成绩。20B 开源模型配上它是 83.6%，同一个模型不用它、把全部历史塞进上下文只有 39.0%。

第一件是复现关系。论文合作方里有弗吉尼亚理工 Sanghani 中心和华盛顿邮报的研究人员，官方说基准由这两家独立复现过，但这两家本身也是论文共同作者。README 还写了一句，只有它的分数经过独立复现，其他厂商的分数由厂商自报。

第二件是竞品的反驳，这次有数字。Zep 官网的对比页说，Hindsight 的 91.4% 是在 8192 token 检索预算下测出来的，Zep 拿到同档 90.2% 只用约 4408 token，差 1.9 倍；多出来的上下文每次查询都要喂给答案模型，按 token 对齐后差距会缩小甚至反转。它还指出对比图引用的 Zep 71.2% 是 2025 年旧数字。Zep 是竞品，这只是它的立场，90.2% 同样没有第三方测定。

第三件是治理。官方把租户、认证、存储列成扩展点，竞品指出它没有内置 RBAC 和 ABAC，默认认证是一个静态 key 且默认关闭。

到底适不适合你

想找一个能自己部署的记忆层、看重长跨度召回精度、能接受写入时多花一次模型调用，可以认真看它。

主要诉求是个人化聊天记录、读写比又高，那得先算 token 账，把检索预算和模型成本拉到自己场景跑一遍。

要的是开箱即用的企业级治理，权限、审计、合规一条都不能少，这块目前得自己补。

只是想给 Agent 加个轻量记忆，官方口径里也说了，对简单工作流它可能偏重。

仓库地址是 https://github.com/vectorize-io/hindsight 。最后交代一句，我没跑过基准也没部署过服务，上面所有数字都来自官方材料和竞品公开页面，选型前请拿自己场景实测一遍。