Hindsight 记忆系统 FAQ 深度指南：从 RAG 对比、数据隔离到事件中心图的完整实战解析

Hindsight 记忆系统 FAQ 深度指南从 RAG 对比、数据隔离到事件中心图的完整实战解析【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightHindsight 是一个为 AI Agent 提供长期记忆的类生命体记忆系统它用结构化事实、心智模型Mental Models与事件中心图Event-Centric Graph替代传统 RAG 的文档块检索。本文以 Hindsight 官方 FAQ 为骨架结合仓库源码配置实现、Admin CLI、API 文档逐题拆解读完你将掌握 Hindsight 与 RAG 的本质差异、retain / recall / reflect 三个核心操作的选型、用户数据隔离方案、zombie 操作僵尸任务的恢复流程以及事件中心图 vs 传统知识图谱的底层设计原理。Hindsight 是什么它与 RAG 有何不同Hindsight 是一个使用**仿生数据结构biomimetic data structures**为 AI Agent 提供长期记忆的系统。与传统 RAGRetrieval-Augmented Generation相比核心差异在于存储结构化事实而非原始文档块构建心智模型随时间整合知识而非仅检索使用图结构关系连接实体与概念支持时间感知检索的时序推理支持倾向感知disposition-aware反思进行细致推理完整的六维能力对比见 RAG vs Memory能力RAGHindsight搜索策略仅语义相似度语义 关键词 图 时间多跳推理局限于检索到的块跨实体关系的图遍历时间查询关键词匹配spring日期解析与范围过滤实体理解无实体消解、共现追踪知识整合无状态综合并演进的心智模型倾向性无怀疑、字面、共情 3 种特质影响解释从架构看RAG 是嵌入查询 → 向量相似度搜索 → 返回 top-k 块 → 生成响应的单一检索策略而 Hindsight 是解析查询提取时间表达式、实体→ 并行执行 4 路检索语义、BM25、图、时间→ RRF 融合 → 交叉编码器重排 → 应用倾向特质 → 生成响应的多策略、跨会话持久状态流水线。官方 FAQ 中还提到 Hindsight 的独特优势包括基于 PostgreSQL久经考验、可靠且广泛认知、云原生架构支持水平扩展、支持自托管或 Hindsight Cloud、可扩展到数百万记忆且召回延迟 50–500ms并为 Python / TypeScript / Go / Rust 提供 SDK集成 LiteLLM / Vercel AI SDK 等。FAQ 中的相关描述如排行榜排名、延迟数据均以官方文档声明为准读者可对照 Models 与 Performance 文档核实细节。一句话总结向量数据库只做搜索RAG 做文档检索而 Hindsight 提供随用户共同演进的活记忆living memory。支持哪些客户端、语言、集成与 LLM 提供商客户端与语言Hindsight 提供多语言 SDK。仓库中对应实现Pythonhindsight-clients/python官方 Python SDKretain/recall/reflect等核心方法TypeScript / Node.jshindsight-clients/typescript 以及聚合包 hindsight-all-npmGohindsight-clients/go含 217 个 Go 源文件的完整客户端Rusthindsight-clients/rustCLIhindsight-cliRust 实现的命令行工具Embedhindsight-embed可直接嵌入应用的轻量运行方式集成仓库 hindsight-integrations 中包含了大量框架集成覆盖 Agent 框架LangGraph、OpenAI Agents、CrewAI、smolagents、Pydantic AI、AutoGen、Haystack、LlamaIndex、Google ADK、AG2、Agno 等、编程 AgentClaude Code、Cursor、Copilot CLI、Codex、OpenCode、Cline、Aider、Roo Code、Zed 等、对话平台Dify、Flowise、n8n、Zapier、Vapi、Obsidian、Eliza 等以及 LLM 网关LiteLLM等具体清单见 Integrations Hub。LLM 提供商FAQ 列出的支持提供商包括OpenAI、OpenAI Responses、Anthropic、Google Gemini、Vertex AI、Groq、Ollama、Ollama Cloud、LM Studio、llama.cpp、MiniMax、DeepSeek、z.ai、opencode-go、Atlas Cloud、Meta Model API、Volcano Engine、OpenRouter、Requesty、OpenAI Codex、Claude Code、GitHub Copilot、AWS Bedrock、Fireworks AI、Nous Portal、SuperGrok (OAuth)、OpenAI Compatible、LiteLLM100。完整列表、推荐模型与配置示例见 Models。从源码配置层看提供商能力Batch API、显式提示缓存在 models.md 中有对照表例如 OpenAIopenai、Groqgroq、Geminigemini、Fireworksfireworks支持批量 API约省 50% 成本Gemini / Vertex AI 支持显式提示缓存默认开启可用HINDSIGHT_API_LLM_PROMPT_CACHE_ENABLEDfalse关闭。该选哪个模型如何取舍FAQ 建议参考Model Leaderboard模型排行榜它在 accuracy准确率、speed速度、cost成本、reliability可靠性四个维度上对 retain、reflect 和 observation consolidation 进行基准测试是寻找合适 trade-off 的最佳入口。各提供商的默认模型未显式设置HINDSIGHT_API_LLM_MODEL时生效见 models.md包括提供商默认模型openaigpt-4o-miniopenai-responsesgpt-5.6anthropicclaude-haiku-4-5geminigemini-3.5-flashvertexaigoogle/gemini-3.1-flash-litegroqopenai/gpt-oss-120bollamagemma3:12bollama-cloudgemma3:12bllamacppgemma-4-e2b-it自动下载的 GGUFdeepseekdeepseek-v4-flashzaiglm-4.5-flashopenrouterqwen/qwen3.5-9bbedrockus.amazon.nova-2-lite-v1:0fireworksaccounts/fireworks/models/llama-v3p1-8b-instructxai-oauthgrok-4.5litellmgpt-4o-mini只需设置提供商即可使用默认模型# 自动使用 claude-haiku-4-5 export HINDSIGHT_API_LLM_PROVIDERanthropic export HINDSIGHT_API_LLM_API_KEYsk-ant-xxxxxxxxxxxx也可显式覆盖或做分操作覆盖retain 用一家、reflect 用另一家export HINDSIGHT_API_LLM_PROVIDERanthropic export HINDSIGHT_API_LLM_API_KEYsk-ant-xxxxxxxxxxxx export HINDSIGHT_API_LLM_MODELclaude-sonnet-4-5-20250929 # 全局默认用 OpenAI gpt-4o-mini export HINDSIGHT_API_LLM_PROVIDERopenai # retain 阶段改用 Anthropic 默认模型 export HINDSIGHT_API_RETAIN_LLM_PROVIDERanthropic重要约束未列出的其他模型也可以工作但必须支持至少 65,000 输出 token以保证可靠的事实抽取。若模型仅支持 32k 或更少的输出 token可调低 retain 的补全上限必须大于HINDSIGHT_API_RETAIN_CHUNK_SIZE默认 3000否则启动时校验会报错export HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS32000 # 或 16000FAQ 还特别提醒Groq 免费层不适合 Hindsight——免费层每分钟仅 8,000 token远低于单次 retain 调用约 64k 的需求。需要自己托管基础设施吗系统要求是什么不需要有两种选择Hindsight Cloud—— 全托管服务自托管Self-hosted—— 使用 Docker 或直接安装部署在自己的基础设施上自托管运行 Hindsight API 服务的最低系统要求Python 3.114GB RAM 起步生产环境建议 8GBLLM API KeyOpenAI、Anthropic 等或本地 LLM 方案自托管安装步骤见 Installation。仓库也提供了现成的部署素材Dockerdocker/standalone/Dockerfile、docker/standalone/start-all.sh以及 docker/docker-compose 下针对外部 PostgreSQL、AlloyDB、Timescale、CUDA、本地 LLM、S3 文件存储、TEI、pg_search、pgroonga、vchord 等多种后端的 compose 编排Kubernetes / Helmhelm/hindsight含 values.yaml 与 21 个模板文件StatefulSet 会自动处理 worker 身份下文详述什么是 zombie 操作如何恢复Zombie 操作是卡在processing状态的后台任务认领它的 worker 已经消失典型场景是 Docker 容器重启后但任务仍被标记为处理中。症状是/banks/{bank_id}/stats上的pending_consolidation或类似计数器永不下降即使 worker 日志显示有大量空闲槽位。根因几乎总是不稳定的HINDSIGHT_API_WORKER_ID。默认情况下 worker 使用容器 hostname 作为身份标识而 Docker 每次重启都会轮换容器 ID——新容器拿到不同的 ID便不认旧 worker 的认领这些任务就此搁浅。在源码层可以印证这一机制HINDSIGHT_API_WORKER_ID在 hindsight-api-slim/hindsight_api/config.py 中定义ENV_WORKER_ID HINDSIGHT_API_WORKER_IDworker 认领与释放的完整逻辑在 hindsight-api-slim/hindsight_api/worker/main.py 中实现。恢复使用 Admin CLI相关命令实现在 hindsight-api-slim/hindsight_api/admin/cli.py# 如果你知道哪个 worker 已死 hindsight-admin decommission-worker old-worker-id # 或者全舰队释放所有 worker 上卡住的任务 hindsight-admin decommission-workers两条命令都会把processing行重置回pending让活着的 worker 在下次轮询时重新认领。建议先用hindsight-admin worker-status查看按 worker 分组的处理中任务重点观察last_update_ago持续增长的 worker即为失联者完整诊断与恢复流程见 Admin CLI — Recovering stuck operations。预防设置一个稳定值HINDSIGHT_API_WORKER_IDDocker-e HINDSIGHT_API_WORKER_IDhindsight-prod多副本则每个副本一个名字KubernetesHelmchart 的 StatefulSet 已自动使用 pod 名称作为 worker ID无需额外配置见 helm/hindsight/templates/worker-statefulset.yaml裸机 / pip传--worker-id name或按进程设置环境变量如何隔离用户数据Memory Bank记忆银行是一个隔离的记忆存储类似一个大脑拥有自己的记忆、实体、关系和可选的倾向特质怀疑 skepticism、字面 literalism、共情 empathy。银行之间完全隔离无数据泄漏。多用户应用有两种方案方案 1每用户一个 Memory Bank推荐用于大多数场景为每个用户创建一个银行如bank_iduser-123设置最简单、数据隔离最强适合按用户查询与个性化每个银行可有独立的倾向特质和背景上下文局限无法做跨用户分析如所有用户讨论最多的主题是什么方案 2单一银行 标签适用于需要聚合洞察的应用整个应用只用一个银行retain 时给记忆打上用户标识标签如tags{user_id: user-123}recall/reflect 时按标签过滤实现按用户查询优势既支持按用户查询也支持跨用户聚合分析决策建议追求简单与隐私选每用户银行需要跨用户整体推理选单银行 标签。银行管理细节见 Memory Banks。retain、recall、reflect 有什么区别何时用 recall、何时用 reflect三个核心操作Retain保留存储数据事实、实体、关系Recall回忆基于查询搜索并检索原始记忆数据Reflect反思使用 AI Agent 基于检索到的记忆回答问题recall vs reflect 的选型用 recall 的场景想要原始事实来驱动自己的推理或 prompt需要对记忆的解释有最大控制权简单事实查询如Alice 对 X 说过什么延迟敏感——recall 明显更快50–500ms vs 1–10s想自己构建检索记忆之上的答案合成层用 reflect 的场景想要开箱即用的答案无需额外 LLM 调用需要由银行性格特质怀疑、字面、共情塑造的倾向感知响应查询需要在事实、观察、心智模型之间做多步推理需要结构化输出通过response_schema需要引用来源——reflect 会返回哪些记忆、心智模型和指令参与了答案recall(What food does Alice like?) # → [Alice loves sushi, Alice prefers vegetarian options] # 原始事实 reflect(What should I order for Alice?) # → Id recommend a vegetarian sushi platter — Alice loves sushi and prefers vegetarian options. # 有依据的答案关键区别recall 返回数据reflect 返回答案。recall 给你原始素材reflect 用银行的倾向和自主搜索循环替你完成推理。API 细节见 Recall 与 Reflect。何时使用心智模型Mental Models它与知识页面Knowledge Page有何区别心智模型是预计算的答案——由你定义问题Hindsight 从银行知识中综合生成并在后台随知识变化自动重写。适合以下需求超越原始事实的更高层理解如用户偏好函数式编程模式长期行为模式如客户对价格敏感但重视质量请求路径上零推理、即时可得的答案作为reflect期间 AI Agent 推理的上下文你只需创建心智模型并定义它的问题Hindsight 负责构建内容并保持其最新。Reflect 会先检查心智模型所以一个新鲜的心智模型可以不用下沉到观察和原始事实就直接作答。详细 API 见 Mental Models。Mental Model vs Knowledge Page知识页面就是一个心智模型——相同的引擎、相同的刷新行为——只是多了两个东西文件夹树中的一个位置以及一组面向文档而非答案的默认值仅从观察构建、每次整合后增量刷新、不受其他页面影响、更大的内容预算。心智模型知识页面形态对一个问题的常驻答案带 frontmatter 的 Markdown 文档组织扁平列表按标签限定作用域嵌套文件夹与页面来源默认所有事实类型默认仅观察刷新默认关闭每次整合后增量刷新典型消费者你的应用或 Agent按查找浏览和阅读的人或 Agent选型系统内按查找使用答案时用普通心智模型结果需要像 wiki 一样被浏览和直接阅读时用知识页面。心智模型上能配置的一切页面上也都能配置。参考 Mental Models 与开发者文档的 Knowledge Pages 章节。心智模型创建与自动刷新实战补充创建心智模型会在后台运行一次 reflect 并保存结果Python / Node.js / CLI 均可result client.create_mental_model( bank_idBANK_ID, nameTeam Communication Preferences, source_queryHow does the team prefer to communicate?, tags[team, communication] ) print(fOperation ID: {result.operation_id}) # 异步操作通过 operations 端点跟踪心智模型支持自动刷新触发器refresh_after_consolidation每次观察整合后刷新、refresh_cronUTC 5 字段 cron二者互斥、min_refresh_interval_seconds自动刷新最小间隔突发写入被折叠成一次刷新、tags_match默认all_strict可改any、fact_types、response_schema结构化输出等。刷新支持full整体重写与delta基于操作的增量编辑未涉及的内容逐字节原样保留两种模式对于长期存活的 delta 模式模型建议定期clear refresh如每 48 小时以重置累积漂移。recall 的典型延迟是多少典型延迟不重排without reranking50–100ms重排with reranking200–500ms取决于重排器模型与部署方式调优选项见 Performance。FAQ 也提到 Hindsight 宣称可扩展至数百万记忆且保持 50–500ms 的召回延迟生产级声明以官方文档为准。模型方面默认嵌入模型为BAAI/bge-small-en-v1.5384 维默认交叉编码器重排模型为cross-encoder/ms-marco-MiniLM-L-6-v2两者首次运行时自动从 HuggingFace 下载。支持元数据过滤吗Tags、实体标签与 metadata 的区别支持——通过 Tags标签。标签是 retain 时附加在记忆上的字符串标签在 recall/reflect 时作为可见性过滤器。只有标签匹配的记忆才会被返回# retain 时打标签 client.retain(bank_idmy-bank, items[{ content: ..., tags: [user:alice], }]) # recall 时按标签过滤 client.recall(bank_idmy-bank, query..., tags[user:alice])文档级标签等完整细节见 Tags。按实体过滤从记忆中抽取的实体人、地点、概念存储在知识图谱中并驱动图检索——所以查询tell me about Alice会自然浮现与 Alice 相关的记忆无需手动过滤。如果需要对实体类值做显式标签过滤请使用带tag: true的实体标签Entity Labels。实体标签让你定义一个受控的key:value分类词汇表如user:alice、topic:algebra在 retain 时抽取。设置tag: true后每个抽取出的标签会自动写入该记忆单元的标签中从而可用于标准tags/tags_match过滤# 银行配置带 tag: true 的实体标签组 { entity_labels: [{ key: user, type: text, tag: True, description: The user this memory belongs to }] } # user:alice 标签被抽取并作为标签写入 # 召回时用标准 tags 参数过滤 client.recall(bank_idmy-bank, query..., tags[user:alice])配置细节见 Entity Labels。在仓库源码中entity_labels与entities_allow_free_form是银行配置的正式字段见 hindsight-api-slim/hindsight_api/config.py 与 hindsight-api-slim/hindsight_api/api/http.py 中的LabelGroup模型并在 hindsight-api-slim/hindsight_api/engine/retain/entity_labels.py 中实现解析。那 document 的metadata呢文档元数据retain 项上的metadata键值对用途不同包含在事实抽取 prompt 中LLM 可将其作为额外上下文提升抽取准确度如知道文档标题或来源原样随每条被召回的记忆返回让应用无需额外查询即可把记忆关联回源系统如 URL、线程 ID、工单号metadata 不是过滤器——需要把 recall 限定到文档子集时请用标签。如何控制被召回的记忆类型如果银行混有不同形态的记忆如简短的规则与详细的操作规程而 recall 对某查询召回了错误的形态可用带tag: true的实体标签在 retain 时分类、在 recall 时硬过滤在银行上定义一个带tag: true和受控词汇表的标签组如rulevsprocedure正常 retain——LLM 自动为每个抽取的事实分类recall 时传tags[memory_type:rule]与tags_matchany_strict确定性只包含匹配的记忆这是一个在排序前应用的 SQL 级过滤器而非打分信号——被排除的记忆根本不进入检索管线。这比调整排序权重更可靠权重只会微调连续分数无法保证排序。完整演练见 Best Practices — Filtering by Memory Shape配置参考见 Entity Labels。保留对话的推荐格式是什么将整个对话作为单个文档传入并随对话增长不断 upsert——Hindsight 会自动分块无需手动拆分。首选格式JSON 数组[ {role: user, content: I moved to Berlin last month.}, {role: assistant, content: How are you finding it?}, {role: user, content: Love it, especially the food scene.} ]Hindsight 对 JSON 数组格式有内部分块优化因为这是最常见的对话形态。备选带前缀的纯文本[2025-06-01T10:32:00Z] user: I moved to Berlin last month. [2025-06-01T10:32:05Z] assistant: How are you finding it? [2025-06-01T10:32:20Z] user: Love it, especially the food scene.给每条消息加上用户名和时间戳前缀能提升抽取质量——LLM 利用这些信号正确归因事实并推理时序。使用稳定的文档 ID 来 upsertawait client.retain( bank_idmy-bank, documents[{ id: chat-session-abc123, # 稳定 ID 启用 upsert content: conversation, # 迄今为止的完整对话 }] )用相同id重新 retain 会替换旧文档及其事实因此对话增长时不会累积重复。在 retain.md 中document_id被定义为让 retain 幂等的关键字段提供它时 Hindsight 会 upsert先删旧文档及其关联记忆再处理新内容省略时每次请求分配随机 UUID重复摄取会生成重复记忆。不要预先摘要或预抽取事实——Hindsight 会自动完成这些并且需要完整对话作为上下文没有前后文yes, exactly或Ill go with option 2毫无意义。若内容是增量到达的如日志、聊天记录也可以用update_mode: append需document_id只发送新增部分Hindsight 会跳过未变的分块仅对新部分触发 LLM 抽取。Hindsight 的图与传统知识图谱有何不同Hindsight 使用事件中心图event-centric graph围绕时刻对话、观察、记忆组织数据而非静态孤立的事实。记忆是锚点实体附着于它们出现的记忆上记忆之间也可以直接相互链接。最贴切的类比是地图 vs 剪贴簿scrapbook。传统图如 Neo4j是地图——通过道路直接展示地点之间如何连接映射关于世界的刚性结构事实[Toronto] ──IS_IN── [Canada]Hindsight 的图是剪贴簿——每一页是一条记忆。在那一页上你把该时刻出现的所有人、概念和标签贴成贴纸。贴纸互不相连它们只是共存于同一页Scrapbook page: Math Class [Alice] [Acme] [pedagogy:scaffolding]两者如何应对随时间的变化传统图难以应对变化。如果 Alice 离开 Acme 去了 Stark Industries你必须手动删除或重写旧的[WORKS_AT]箭头否则图会自相矛盾地同时声称她在两家公司任职。传统图为绝对的当下而生数据变化时历史就丢了。Hindsight 轻松应对变化因为历史被保留。Alice 换工作不必改写过去只需新建一页剪贴簿——Memory: Tuesdays Call贴上[Stark Industries]的贴纸去年那页仍准确地将她链接到[Acme Corp]。图自然记录世界如何演进无需复杂的数据库维护。贴纸从哪来如何控制贴纸的创建是 AI 自动化与开发者控制的结合开放世界自动化默认Hindsight 的 LLM 管线自动从原始文本检测并抽取标准实体人物、地点、日期转化为贴纸通过entity_labels的开发者控制定义自定义 schema强制 LLM 用严格预定义词汇表对记忆分类。例如强制pedagogy键只能取scaffolding、direct_instruction或socratic_questioning。要锁定银行只使用你配置的标签并关闭上述开放世界自动化可在银行配置上设置entities_allow_free_form: false——LLM 随后完全跳过自由形式的命名实体只输出匹配你 schema 的条目能构建直接的实体到实体管线吗不能。在 Hindsight 中实体人物、地点、概念或分类标签之间没有直接箭头连接。它们通过锚定到同一个父记忆单元同一页剪贴簿来交互。实体不直接相连Hindsight 如何发现联系Recall 以语义搜索起步——找到与查询最相关的记忆作为种子页——然后通过三个并行信号从种子向外扩展共享实体Shared entities若记忆 A 和 B 都锚定同一实体节点如[pedagogy:scaffolding]Hindsight 遍历Memory A → [pedagogy:scaffolding] → Memory B——即同贴纸的剪贴簿页场景记忆间的语义链接Semantic links新记忆 retain 时Hindsight 预计算它与嵌入空间中最近邻的链接语义相关的页面无需共享贴纸即可直接相连记忆间的因果链接Causal linksHindsight 还会抽取记忆间显式的因果关系causes、caused_by、enables、prevents因果链成为一等公民边而非需要模型自行推断语义层选择起点图通过三个信号中对每个候选最强的那一个补全连接。这种图结构有助于减少 Agent 的幻觉吗是的——通过给消费方 LLM 提供更有依据的上下文来推理。剪贴簿模型的三个性质直接贡献于此历史被保留而非折叠模型看到的是有时间边界的事实Alice 去年在 Acme 工作现在在 Stark Industries而非迫使其调和或猜测的矛盾现在时边连接来自记录的链接而非推断recall 浮现两条相关记忆是因为它们共享实体、预计算语义邻居或显式因果边——链接出现在检索上下文中模型无需发明趋同证据累积多条记忆锚定同一实体会相互强化而非竞争模型得到的是可相互印证的声明而非单一无依据的说法仍有疑问本指南逐题覆盖了 Hindsight FAQ 的 17 个核心问题并结合仓库源码给出了实现层面的佐证。想继续深入对比完整能力矩阵RAG vs Memory管理员命令worker 状态、迁移、备份恢复、bank 修复与跨实例迁移Admin CLI提供商、模型与嵌入配置Models自托管与系统要求Installation三大核心 APIOperations、Recall、Reflect【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考