github.com · vectorize-io/hindsight
hindsight - 开源琅嬛阁
项目介绍
Hindsight 是 Vectorize 推出的 Agent 记忆系统：多数记忆方案只负责「把对话历史找回来」，它则强调让智能体随时间学习——把事实、自身经验巩固成观察，再形成可读写的心智模型。记忆按 bank 隔离，提供 retain / recall / reflect 三操作，并可用 Docker、pip、Helm 自托管，或直接走 Hindsight Cloud。
核心特性
- 四种记忆形态：世界事实、自身经验、带证据的观察（observations），以及可当作「常驻答案」读取的心智模型 / 知识页
- 三操作 API：
retain写入并抽取实体与时间；recall并行走语义、BM25、图谱与时间四路检索再融合重排；reflect做更深的联结与 Disposition 感知回答 - 编码 Agent 一键接入：
npx @vectorize-io/hindsight-coding-agents install可为 Claude Code、Codex、Cursor CLI 等建立基于 git 与会话的项目级记忆 - LLM Wrapper：
wrap_openai()/wrap_anthropic()两行代码自动在每次调用前后 recall + retain，底层走 LiteLLM，覆盖 100+ 模型 - 生产向能力：PostgreSQL + pgvector（或 Oracle AI Database）、内置 MCP、多语言原样保留、可选 Memory Defense（密钥 / PII 扫描）
对用户价值
对话 Agent 与编码助手最常见的失败不是「不会搜」，而是不会形成稳定信念：同一用户偏好被覆盖、项目约定每次重讲、跨天任务无法延续。Hindsight 把写入、检索、反思拆开，后台把相关事实巩固成带引用的观察，并把「这个用户的偏好是什么」写成可直接读取的知识页，避免每轮都做一次昂贵检索。对产品团队，bank 隔离与 Disposition 让不同用户 / 角色不会串记忆；对编码场景，项目 bank 可从 git 历史自动灌入，减少反复对齐架构与进行中工作的成本。
与替代方案
- 相比直接把对话塞进 RAG 或知识图谱，Hindsight 官方定位是补其短板：事实会随证据强化 / 削弱 / 扩展，而不是被新切片静默覆盖；适合需要长期学习的 Agent，而不是一次性文档问答。
- 相比 Mem0 这类可嵌入的通用记忆层，Hindsight 更强调 reflect + 心智模型 / 知识页，以及 Docker / Helm / Cloud 的服务化部署；Mem0 往往更轻、更偏 SDK 即插即用。
- 相比 Letta（原 MemGPT）这类带记忆的 Agent 运行时，Hindsight 是记忆后端：你仍用现有 Agent 框架或编码助手，通过 SDK、MCP 或 Wrapper 接入。
- 相比 claude-mem 等宿主插件，Hindsight 覆盖对话产品、n8n / Dify 工作流与多编码 Agent；若只想给单一 IDE 加本地会话摘要，专用插件更轻，但跨产品复用记忆更弱。
- 官方称在 LongMemEval 上达到 SOTA，并由 Virginia Tech、华盛顿邮报协作复现；具体分数以 benchmarks.hindsight.vectorize.io 为准。简单工作流（例如小规模 n8n 流水线）可能过重。
适应人群
- 要给聊天机器人、客服或销售 Agent 做按用户隔离的长期记忆，而不只是滚动窗口的产品工程师。
- 使用 Claude Code / Codex / Cursor 等编码 Agent，希望项目约定与 git 历史自动进入上下文的开发者。
- 评估自托管记忆服务（Postgres / K8s）或托管 Cloud，并需要 MCP、PII 防护与多模型网关的平台团队。
如何使用
前置条件
- Docker（推荐）或 Python 环境；生产可用外部 PostgreSQL，或走托管 Cloud 免部署。
- 至少一个 LLM 提供商密钥。Hindsight 支持 25+ 提供商：
openai、anthropic、gemini、本地ollama/lmstudio，以及openai-codex、claude-code、github-copilot等已有订阅（后三者可不单独配 API Key）。详见 supported models。 - 了解 MIT 许可证；密钥不要写入仓库。
安装方式
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:latestAPI：http://localhost:8888 UI：http://localhost:9999
换提供商时设置 HINDSIGHT_API_LLM_PROVIDER（默认 OpenAI）。
pip 裸机
pip install hindsight-apiexport HINDSIGHT_API_LLM_API_KEY=sk-xxxhindsight-api客户端
pip install hindsight-client -Unpm install @vectorize-io/hindsight-client# 或：curl -fsSL https://hindsight.vectorize.io/get-cli | bash编码 Agent（可选）
npx @vectorize-io/hindsight-coding-agents install all# 或只装一个：npx @vectorize-io/hindsight-coding-agents install claude-code无自建服务时可注册 Hindsight Cloud，把客户端指向 https://api.hindsight.vectorize.io。Intel Mac 裸机请改用 hindsight-all-slim，见 安装指南。
首次运行
服务起来后，用 Python 客户端写入并检索一条记忆：
from hindsight_client import Hindsight
client = Hindsight(base_url="http://localhost:8888")client.retain(bank_id="my-bank", content="Alice works at Google as a software engineer")client.recall(bank_id="my-bank", query="What does Alice do?")client.reflect(bank_id="my-bank", query="Tell me about Alice")已有 OpenAI SDK 时，可用 Wrapper 自动记：
pip install hindsight-litellmfrom openai import OpenAIfrom hindsight_litellm import wrap_openai
client = wrap_openai(OpenAI(), bank_id="user-123", hindsight_api_url="http://localhost:8888")每个 bank 默认暴露 MCP：http://localhost:8888/mcp/{bank_id}/。
验证是否成功
- 浏览器打开
http://localhost:9999，确认 UI 可访问。 recall能返回刚retain的内容；reflect能给出基于记忆的综合回答。- 编码 Agent 安装后，新开会话应能注入项目 bank 中的约定与近期工作（无需再跑单独 ingest 命令）。
- 需要文档内嵌到编码助手时：
npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs
常见坑 / 注意事项
- bank 严格隔离，跨用户 / 跨项目必须分 bank，否则检索空间会对不齐。
- Intel Mac 不要直接
pip install hindsight-all，应使用hindsight-all-slim。 - 简单 n8n 类工作流可能过重；官方也说明 Hindsight 更适合需要持续学习、根据反馈改行为的 Agent。
- 生产密钥、PII 建议打开 Memory Defense，并分层配置（全局环境变量 → 租户 → bank）。
- 存储可选内嵌 pg0、外部 Postgres 或 Oracle；K8s 用官方 Helm chart。升级前查看 Releases。