Hindsight Retain 管线深度解析：从原始文本到带知识图谱的结构化记忆-北京尧图网络

Hindsight Retain 管线深度解析从原始文本到带知识图谱的结构化记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文以 Hindsight 0.6 版文档 Retain: How Hindsight Stores Memories 为主线系统讲解retain()写入管线的完整机制富事实提取、实体识别与消歧、四类知识图谱连接、双时间维度建模以及如何用 retain mission 与抽取模式控制提取行为。结合hindsight-api-slim中的管线编排源码与测试你将理解从一次retain()调用到可被recall()/reflect()检索的记忆库之间发生的每一步并拿到可直接复制的调用示例。1. Retain 做了什么一条从文本到记忆库的管线当你调用retain()时Hindsight 会把对话、文档等内容转换成结构化、可检索的记忆同时保留语义与上下文。官方文档给出的整体流程是从源码结构看这条管线由 retain 编排器协调engine/retain/目录下的各模块分别负责模块职责fact_extraction.py调用 LLM 从分块内容中抽取结构化事实entity_processing.py、entity_labels.py实体解析、实体标签写入link_creation.py创建时间/语义/因果三类连接embedding_processing.py事实向量化供 ANN 语义链接与后续检索使用chunk_storage.py、fact_storage.py文档分块与事实落库编排器将写入拆成显式阶段Phase 1 在独立连接上执行读密集操作实体解析的三元组 GIN 扫描共现取数打分、HNSW 语义 ANN 探测避免在写事务中持有行锁见 _pre_resolve_phase1 的注释与实现Phase 2 在单个数据库事务内插入事实与检索所依赖的关键连接保证原子性见 _insert_facts_and_links。这个读与写分离的设计正是文档流程图背后真正的工程实现。最小调用示例文档中最基本的 retain 调用取自官方示例client.retain( bank_idmy-bank, contentAlice works at Google as a software engineer )保留整段对话时推荐作为一个 item 提交消息按Name (timestamp): text格式排列LLM 据此把事实归因到正确的说话人并解析跨消息的时间指代retain API 文档、示例conversation \n.join([ Alice (2024-03-15T09:00:00Z): Hi Bob! Did you end up going to the doctor last week?, Bob (2024-03-15T09:01:00Z): Yes, finally. Turns out I have a mild peanut allergy., Alice (2024-03-15T09:02:00Z): Oh no! Are you okay?, Bob (2024-03-15T09:03:00Z): Yeah, nothing serious. Just need to carry an antihistamine., Alice (2024-03-15T09:04:00Z): Good to know. Well avoid peanuts at the team lunch., ]) client.retain( bank_idmy-bank, contentconversation, contextteam chat, timestamp2024-03-15T09:04:00Z, document_idchat-2024-03-15-alice-bob, )其中context、timestamp、document_id三个参数直接决定了下文要讲的事实质量、时间锚定与幂等性参数详解见 Retain API 文档。2. 富事实提取不止说了什么还有为什么Hindsight 保存的不只是被说出的内容而是为什么、如何、意味着什么。提取什么对 retain Alice joined Google last spring and was thrilled about the research opportunitiesHindsight 会抽出三层信息核心事实Alice joined GoogleAlice 加入了 GoogleThis happened last spring发生在去年春天情绪与含义She was thrilled她非常兴奋It represented an important opportunity这代表一个重要机会推理动机She chose it for the research opportunities她是因为研究机会而选择这种富抽取使得后续可以问 Why did Alice join Google?Alice 为什么加入 Google得到有含义的答案而不仅仅是她加入了 Google。保留完整叙事上下文传统系统会把信息碎片化Bob suggested Summer VibesAlice wanted something uniqueThey chose Beach BeatsHindsight 则保留完整叙事Alice and Bob discussed naming their summer party playlist. Bob suggested Summer Vibes because its catchy, but Alice wanted something unique. They ultimately decided on Beach Beats for its playful tone.这意味着检索结果携带完整上下文而非互不相连的片段。从源码结构看这一点由两个输入参数在提取 prompt 层面支撑context如team meeting、slack会被直接注入 LLM prompt主动塑造事实的提取方式——同一句 the project was terminated 在performance review与product roadmap两种 context 下会产出不同的记忆metadata也会进入提取 prompt让 LLM 把来源、标题等信息当作抽取依据retain API 文档。文档给出的示例示例源码client.retain( bank_idmy-bank, contentAlice got promoted to senior engineer, contextcareer update, timestamp2024-03-15T10:00:00Z )两种事实类型Hindsight 区分world事实关于他人的世界知识与experience对话与事件类型描述示例world关于人、地点、事物的事实Alice works at Googleexperience对话与事件I recommended Python to Alice注意观察Observations会在retain()操作完成后由后台自动完成整合consolidation该过程会把新事实中的模式综合进记忆库的知识层详见第 9 节。3. 实体识别与消歧Hindsight 会自动识别并跟踪实体——重要的人物、组织与概念。识别哪些实体人物PeopleAlice、Dr. Smith、Bob Chen组织OrganizationsGoogle、MIT、OpenAI地点PlacesParis、Central Park、California产品与概念Products ConceptsPython、TensorFlow、machine learning实体归一Entity Resolution同一实体的不同称呼会被归一Alice Alice Chen Alice C. → 同一个人Bob Robert Chen → 同一个人昵称解析为什么重要你可以问 What do I know about Alice?即使她曾在某些对话中被称为 Alice Chen也能拿到全部相关记忆。从源码结构看Phase 1 的实体解析在 entity_processing.resolve_entities 中完成其注释明确列出三步trigram GIN scan三元组 GIN 索引扫描 co-occurrence fetch共现取数 scoring打分解析器实现位于 entity_resolver.py。Phase 1 解析时使用的是占位 unit id真正的事实行在 Phase 2 事务中插入后再由 _remap_phase1_results 把占位 id 重映射为真实的 UUID保证实体链接指向正确的memory_units行。此外retain 的 item 还支持entities参数显式提供你希望保证被识别的实体每项含text与可选type默认CONCEPT与 LLM 自动抽取的实体取并集——当你知道某些实体重要但 LLM 可能漏掉或称呼不一致时显式传入可确保它们一定进入知识图谱参数说明。上下文感知的消歧如果 Alice 多次与 Google、Stanford 同现则新出现的提及这些实体的 Alice 大概率是同一个人。Hindsight 利用**共现模式co-occurrence patterns**来消歧常见名字——这正是 Phase 1 中 co-occurrence fetch scoring 步骤的用途。实体标签Entity Labels你可以定义一套key:value形式的受控分类词汇表如pedagogy:scaffolding、engagement:active在 retain 时抽取并作为实体存储。由于标签会成为实体它们会自动在知识图谱中把相关记忆链接起来同时改善语义检索与关键词检索的效果。标签还可以选择性地写入记忆单元的 tags从而在 recall 与 reflect 中支持标准 tag 过滤memory-banks 配置文档。实现位于 entity_labels.py行为由 test_entity_labels.py 覆盖。4. 构建连接四类知识图谱边记忆不是孤立的——Hindsight 会构建一个包含四类连接的知识图谱它们都在 Phase 2 的同一事务内写入实体连接Entity Connections所有提及同一实体的事实被链接在一起。支撑查询Tell me everything about Alice → 取出所有与 Alice 相关的事实。从源码结构看检索并不依赖单独的实体边表unit_entities表上的自连接即可回答某实体的全部记忆面向 UI 的实体边由/graph端点按需从unit_entities派生见 _insert_facts_and_links 中 Phase 2 的注释。基于时间的连接Time-Based Connections时间上接近的事实互相关联日期越近连接越强由 create_temporal_links_batch 批量生成orchestrator 调用点。支撑查询What else happened around then? → 找到上下文相关的事件。语义连接Meaning-Based Connections语义相似的事实会被链接即使措辞不同。连接阈值由配置项semantic_link_min_similarity控制批内相似性在事务内计算跨已有记忆的相似性则来自 Phase 1 预先用 HNSW 索引探测出的 ANN 结果compute_semantic_links_ann 调用与 create_semantic_links_batch 调用。支撑查询Tell me about similar topics → 找到主题相关的信息。因果连接Causal Connections因果关系被显式跟踪由create_causal_links_batch基于事实中携带的因果关系字段构建调用点。支撑查询Why did this happen? → 追踪推理链示例Alice felt burned out ← 由 ← She worked 80-hour weeks 引起相关行为由 test_causal_relations.py、test_causal_relation_offsets.py 等测试验证底层数据结构见 causal_links.py。5. 时间建模事件发生时间 vs 学习时间Hindsight 跟踪两个时间维度。事件何时发生When It Happened对事件会议、旅行、里程碑记录其实际发生时间 Alice got married in June 2024 → occurred in June 2024对一般事实偏好、特征没有具体发生时间 Alice prefers Python → 持续性偏好retain的timestamp参数正是这个维度的输入。它被注入 LLM 事实提取 prompt让模型用它作锚点解析内容中的相对时间表达last Monday 等。该参数有三种形式参数说明取值行为省略 /null默认取摄入当前时间ISO 8601 字符串如2024-01-15T10:30:00Z使用给定时间unset不带任何时间戳存储内容适用于参考文档、书籍、虚构内容等不存在真实事件时间的材料此时 prompt 显示Event Date: Unknown模型会对所有事实的when字段返回N/A你何时学到它When You Learned ItHindsight 同时跟踪你告诉它每条事实的时间。为什么两者都要假设 2025 年 1 月有人告诉你 Alice 2024 年 6 月结婚了历史查询可用What did Alice do in 2024? → 找到结婚事件新近度排序可用较新的提及在检索中获得优先时间推理可用What happened before her marriage? → 找到更早的事件没有这种区分旧信息要么无法按日期检索要么会被当作无关信息。6. 记忆打标签Tagging Memories标签实现可见性范围控制——当一个记忆库服务多个用户、但每人只应看到自己的记忆时尤为有用Item tags用特定 scope 给单条记忆打标签Document tags把标签应用到整个批次的所有 itemTag filtering在 recall/reflect 时按标签过滤官方示例# 给单个 item 打标签实现可见性隔离 client.retain_batch( bank_idmy-bank, items[ { content: User Alice said she loves the new dashboard, tags: [user:alice, feedback], document_id: user_feedback_001 }, { content: User Bob reported a bug in the search feature, tags: [user:bob, bug-report], document_id: user_feedback_002 } ] ) # document_tags 应用到批次内所有 item client.retain_batch( bank_idmy-bank, items[ {content: Alice mentioned she prefers dark mode, document_id: support_session_123_msg_1}, {content: Bob asked about keyboard shortcuts, document_id: support_session_123_msg_2} ], document_tags[session:123, support] )代码中tags与document_tags的合并逻辑可在 _build_retain_params 中确认item 级标签与文档级标签取并集随文档行一起持久化。标签过滤的完整用法见 Recall API 文档。7. 文档级行为幂等 upsert、append 与 delta retainretain 的参数文档retain.mdx定义了围绕document_id的文档级语义它们与本文第 1 节的管线直接对应document_id幂等键提供后 Hindsight 对文档做 upsert——若该 ID 的文档已存在先删除它及其全部记忆再处理新内容因此可以安全地重放 retain例如对话线程新增了消息不会累积重复记忆。省略document_id时每次请求分配随机 UUID重复摄入同一内容会产生重复记忆。update_mode | 取值 | 行为 | |------|------| |replace默认 | 删除旧文档及其全部记忆从头处理新内容 | |append| 把新内容拼接到现有文档文本后重新处理合并文档delta retain 会自动跳过未变化的 chunk只有新增部分触发 LLM 抽取 |append 模式必须搭配document_id。适用于增量增长的日志、日记、聊天记录——只发新内容即可{ items: [ { content: New entry to add to the existing document., document_id: my-growing-doc, update_mode: append } ] }源码层面对 append 有一条严格的单调性守卫append 产出的文档体必须扩展而非截断已存储的文档体否则抛出AppendWouldTruncateDocument拒绝写入防止静默销毁已提交内容assert_append_extends_stored_body。delta 路径只重写发生变化的 chunk由 attempts_delta_retain 门控——delta 只在文档的首个sub-batch 上执行行为由 test_delta_retain.py、test_retain_append_mode.py 等测试覆盖。8. 用 Retain Mission 与抽取模式引导提取默认情况下retain()会从内容中提取所有显著事实。你可以用retain missionretain_mission收窄关注点——一段自然语言描述这个记忆库应该关注什么e.g. Always include technical decisions, API design choices, and architectural trade-offs. Ignore meeting logistics, greetings, and social exchanges.mission 会与内置规则一起注入提取 prompt——它引导 LLM但不替换提取逻辑并且与任何抽取模式concise、verbose、custom兼容。更细粒度的控制来自抽取模式模式适用场景concise默认通用——选择性强、快verbose需要携带完整上下文与关系的更丰富事实custom完全自定义抽取规则配置方式有两种通过 memory-banks 配置 APIretain_mission/retain_extraction_mode或环境变量HINDSIGHT_API_RETAIN_MISSIONconfiguration 文档。源码中可确认的实现细节config.py环境变量名为HINDSIGHT_API_RETAIN_MISSION解析逻辑为os.getenv(ENV_RETAIN_MISSION) or DEFAULT_RETAIN_MISSION默认值为None即未设置时不注入额外 mission见 config.py 定义与读取抽取模式经 _validate_extraction_mode 校验非法值会记录告警并回落到默认模式从源码结构看还存在一种特殊情形当 LLM provider 配置为none时系统会强制retain_extraction_modechunks并在配置中记录警告config.py可以推断此时退化为不依赖 LLM 的分块存储路径。9. retain 完成后观察整合Observation Consolidationretain()完成后Hindsight 会在后台自动触发观察整合observation consolidation将新事实与已有观察对比分析当模式浮现时创建新观察用新证据细化已有观察跟踪每条观察由哪些事实支撑该过程是异步的——你的retain()调用立即返回整合在后台运行。整理器实现位于 engine/consolidation/ 目录围绕它的原子性、重试预算、失败隔离等大量行为由 tests 中的test_consolidation_*.py系列测试覆盖如 test_consolidation_dedup.py、test_consolidation_retry_budget.py。整合机制的完整说明见 Observations 文档。10. retain 之后你得到什么retain()完成后记忆库中沉淀了结构化事实保留含义、情绪与推理归一化实体解析同一实体的不同名字变体知识图谱实体、时间、语义、因果四类连接时间锚定同时支持历史查询与新近度排序可选标签用于 recall 时的过滤全部存放在你隔离的memory bank中随时可供recall()与reflect()使用。相关文档Observations— retain 之后知识如何被整合Retrieval / Recall— 多策略检索如何召回相关记忆Reflect— agentic loop 如何使用观察Retain API— 完整代码示例与参数含批量摄入、文件上传、异步摄入与 Batch API 成本优化管线主入口与阶段划分orchestrator.py端到端行为测试见 test_retain.py【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Hindsight Retain 管线深度解析：从原始文本到带知识图谱的结构化记忆

相关推荐

广州24小时自助健身房软硬件解决方案实战指南

Plandex CLI 2.0.4 版本解析：新增内置模型、浏览器调试、model-packs 命令与可靠性增强

DSGE模型在信息缺失下的鲁棒预测与Matlab实现

更多资讯

SAP Gateway $expand 深度解析，从 Framework Expand、Data Provider Expand 到 inline 初始状态

Hadoop+Spark旅游景点数据分析系统：从环境搭建到可视化大屏完整实现

基于大数据的化妆品销售系统（毕设源码+文档）

配电网韧性提升：MPS动态调度Matlab实现与优化

自己动手重装Win10/Win11：U盘启动盘、BIOS设置与常见故障排查指南

PSO算法优化光伏MPPT：解决局部遮阴问题

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？