用编码代理（Claude Code、Codex、Cursor 这类）的人都有一个共同的痛：每个会话都是失忆重启。上周明明讨论过「为什么这个项目用 RLS 而不是应用层鉴权」，这周它又要从头读代码重新推一遍。上下文窗口越做越大，但那是「短期记忆」，解决不了「学习」。

Hindsight（Vectorize 出品，MIT 协议）就是冲着这个问题来的——口号是 Agent Memory That Learns：不只是记住对话，而是让代理随时间积累出信念和结论。它在 LongMemEval 基准上拿了同类最优，且成绩被弗吉尼亚理工 Sanghani 中心和《华盛顿邮报》独立复现过（其他竞品多为自报分数）。

我自己在生产环境跑了两个多月，这篇把技术机制拆开讲透，再给一份编码代理的实战教程。

一、它和 RAG 有什么本质区别

先把最容易混的概念厘清。RAG 是检索：把文档切块、向量化、查询时捞最相关的几块塞进上下文——它回答「资料在哪」，但读完就忘，下次还要再捞。

Hindsight 的定位是记忆系统：信息进来后经过抽取、规范化、巩固，逐渐形成有层次的结构，并且会随新证据修正旧结论。官方的对比是：RAG 给你一个书架，Hindsight 给你一个会写读书笔记的大脑。

二、技术分析：四层记忆 + 三个操作

记忆是分层的，不是一堆向量

这是 Hindsight 最值得学的建筑设计，四层结构明显借鉴了人类记忆模型：

层	存什么	例子
世界事实（World Facts）	关于世界的一般事实	「炉子会烫」
亲历经验（Experiences）	代理自己的经历	「我碰了炉子，真的很疼」
观察（Observations）	从大量记忆巩固出的、带证据的信念	多条记忆汇聚成的结论
心智模型（Mental Models）	对某个问题的常驻答案	「这个用户偏好极简输出」

关键在第三层的 Observations 巩固机制：原始事实不是躺平不动，后台任务会把相关事实合并成去重的「观察」——每条观察保留支持它的原文引用和证据计数。新证据到来时是精炼而非覆盖：加强、削弱或延伸已有信念，而不是悄悄替换。这一点直接决定了它不会像普通向量库那样「新旧事实打架」。

第四层 Knowledge Pages（知识页） 是心智模型的「傻瓜化」包装：你定义一个问题（比如「这个仓库的测试约定是什么」），Hindsight 写出答案、存起来、并在后台随记忆增长持续重写。读取时是纯数据库读——不走检索、不调 LLM，所以代理每次开工可以直接揣着一页「定稿知识」出场，不用每个会话重新发现一遍。

三个操作各司其职

retain 写入。输入任意文本，背后由 LLM 抽取关键事实、时间、实体和关系，经规范化后建成「实体 + 关系 + 时间序列 + 稀疏/稠密向量」的多重表示——这一步是后面精准召回的地基。

recall 检索。这是性能担当，四路策略并行执行：

• 语义：向量相似度
• 关键词：BM25 精确匹配
• 图：实体 / 时间 / 因果链接
• 时序：时间范围过滤（「六月发生了什么」）

四路结果用 RRF（倒数排名融合）+ 交叉编码器重排合并，再按 token 预算裁剪。四路并行是它在 LongMemEval 上拉开差距的核心——单一向量检索天然搞不定时序问题和指代消解。

reflect 深思。回答「为什么 / 该注意什么」这类需要跨记忆建立联系的问题，比如项目经理代理反思项目风险、销售代理反思哪种外联话术有效。可以理解为对记忆库的一次定向 RAG+推理，而不是简单查找。

三个工程细节，看得出用心

• Bank 严格隔离：一个 bank 就是一个「大脑」（一个用户、一个代理或一个项目），无跨库泄漏，还能配置「性格特质」（怀疑度、字面度、共情度）影响 reflect 的推理风格。
• 多语言原生：输入什么语言，事实就存什么语言，实体保留原生文字——张伟就是张伟，不会被翻译成 “Zhang Wei”。
• Memory Defense：可选的按库策略，对每次写入扫描 45 种密钥/PII 模式，命中则脱敏（[REDACTED:github_token])或拦截。

三、部署形态：从 Docker 到托管

方式	一句话
Docker 单容器	内嵌 PostgreSQL（pg0 卷），docker run 一条命令起全栈，API 8888 / UI 9999
Docker + 外部 PG	docker/docker-compose 编排，生产常用
pip 裸机	pip install hindsight-api，Windows/Linux/macOS 都支持
Kubernetes	官方 Helm chart（ghcr.io/vectorize-io/charts/hindsight）
Python 嵌入	pip install hindsight-all，无需服务器，进程内起
Hindsight Cloud	托管版，按量计费，99.9% SLA

存储用 PostgreSQL + pgvector（企业可换 Oracle 23ai）。LLM 侧支持 25+ 提供商——包括用 claude-code、openai-codex 这类直接复用现有订阅的选项，连 API Key 都不用另买。我自己的部署走的是 Docker 路线，挂在自己的域名后面。

四、实战教程：给编码代理装上长期记忆

这是 Hindsight 最「开箱即用」的集成——一个包搞定 CLI 编码代理的项目记忆：

# 自动检测并接入所有已装代理
npx @vectorize-io/hindsight-coding-agents install all

# 或只接一个（claude-code / codex / cursor / copilot / opencode …）
npx @vectorize-io/hindsight-coding-agents install claude-code

装完之后发生了什么（我拆过包，说细节）

安装器做的事：写入 ~/.hindsight/coding-agent.json（服务端地址 + Token，支持自部署或 Cloud）、落一份插件目录（当前 0.8.2 版本），包含——

• 三个钩子：SessionStart（开工时把知识页注入上下文）、UserPromptSubmit（每条消息时注入「先搜记忆」的提醒）、Stop（会话结束时把对话自动摄取入库）；
• 一个 MCP 服务器：把 search / read / list / reflect / capture-initiative / ingest-document 等工具挂给代理；
• 一份技能文档：告诉代理什么时机该查记忆、什么时机该记录。

摄取是全自动的，没有 setup 命令：每个仓库自动建一个专属 bank，从 git 历史和历次会话里持续积累，再由后台巩固出架构、约定、决策、在途工作等几张知识页。你正常干活就行，它在旁边默默记笔记。

实战心法（两个月用下来的三条）

1. 新会话先搜记忆，再读代码。让代理回答「为什么」类问题前先 search 知识页——很多时候过去已经吵过、定过，别重新开庭。
2. 动手做新功能前，先记一条 initiative。用 capture_initiative 把「打算做什么、为什么」写进记忆，中途计划变了再更新同一条——这样知识页里跟踪的是当前计划而不是开工时的旧版本。
3. 发现记忆错了，别绕过，去纠正。记忆是过去的记录，可能过时。验证出错误后用 ingest_document 写一篇「Correction: 〈主题〉」说明旧说法、新事实和证据，新事实会在巩固时盖过旧记忆。绕过它，错误结论会一直躺在知识页里。

什么时候不该用

官方文档说得很诚实：简单的 n8n 工作流这类场景属于杀鸡用牛刀。记忆系统的价值在跨会话、跨周的学习——如果你的代理每次任务都是独立的、不需要积累，那 RAG 甚至上下文窗口就足够了。

写在最后

参考：vectorize-io/hindsight（MIT）· 官方文档 · 编码代理集成页 · 架构图为本刊依据官方文档自绘。

代理的记忆这件事，2026 年正在从「锦上添花」变成「基础设施」。Hindsight 的分层记忆 + 四路检索 + 知识页巩固，目前是我见过最完整的一套答案——而它对编码代理的「零配置摄取」设计，是真正让人愿意天天用的那种工程判断力。