Retain: How Hindsight Stores Memories【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight导读retain()是 Hindsight 记忆管线的入口一次调用即可把对话、文档等原始内容转译为结构化的、可检索的长期记忆。本文将围绕 retain.md 展开逐层拆解事实抽取、实体识别与消解、知识图谱构建、双时间维度、标签体系、抽取任务Mission与观测合并Consolidation等机制并结合仓库源码与配置fact_extraction.py、entity_labels.py、config.py给出可落地的参数与示例。读完你将掌握如何让 Hindsight 记住什么、为何、何时以及如何用抽取模式与 Entity Labels 精确控制记忆的质量与检索效果。What Retain Does当调用retain()时Hindsight 会完成一次完整的记忆写入管线。原文档给出了如下工作流四个阶段依次为抽取事实Extract Facts→识别实体Identify Entities→构建连接Build Connections→写入记忆库Memory Bank。从源码结构看这一管线对应 engine/retain/ 目录中的若干模块fact_extraction.py调用 LLM 从文本中抽取语义事实、实体与时间信息entity_processing.py对抽取出的实体进行规范化与去重link_creation.py/link_utils.py构建实体、时间、语义、因果四类图连接fact_storage.py/chunk_storage.py将事实与分块写入记忆库orchestrator.py编排整个 retain 流程。retain()不是简单的存原文而是把内容转译成保留了含义meaning与上下文context的结构化记忆为后续recall()与reflect()提供高质量素材。Rich Fact Extraction不只记下说了什么Hindsight 保存的不只是谁说了什么而是为什么why、怎样how以及它意味着什么what it means。What Gets Captured以原文档的示例为例当输入Alice joined Google last spring and was thrilled about the research opportunities.Hindsight 会抽取核心事实core factsAlice 加入了 Google这件事发生在去年春天。情感与含义emotions and meaning她很兴奋thrilled这对她是一个重要机会。推理reasoning她选择 Google 是为了研究机会。这种富抽取带来的直接收益是之后你可以问Alice 为什么加入 Google得到的不是干巴巴的她加入了 Google而是包含动机与情感的有意义答案。从源码看这得益于抽取响应模型中的what字段——在 fact_extraction.py 中其定义为Core fact - concise but complete (1-2 sentences)即核心事实既要精炼又必须完整同时 verbose 模式下还有更丰富的字段定义对应ExtractedFactVerbose。Preserving Context保存完整叙事传统系统会把信息切碎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.这意味着搜索结果自带完整上下文而不是一堆互相割裂的片段。这也是 Hindsight 区别于朴素 RAG 切块检索的核心之一可对比 rag-vs-hindsight.md 中的定位阐述。Two Types of Factsworld 与 experienceHindsight 区分两类事实TypeDescriptionExampleworld关于他人、地点、事物的客观事实Alice works at Googleexperience对话与事件第一人称经历I recommended Python to Aliceworld facts描述外部世界的稳定属性experience facts描述我参与的对话和发生的事件。Note原文提示retain()操作完成后观测合并observation consolidation会在后台自动运行。该过程把新事实中涌现的模式综合进记忆库的知识体系。这一点将在本文后面的 Observation Consolidation 一节展开。Entity Recognition实体识别与消解Hindsight 会自动识别并持续追踪实体——那些重要的人、组织与概念。What Gets Recognized人物PeopleAlice、Dr. Smith、Bob Chen组织OrganizationsGoogle、MIT、OpenAI地点PlacesParis、Central Park、California产品与概念Products ConceptsPython、TensorFlow、machine learningEntity Resolution同实体归一同一个实体以不同方式出现时会被统一Alice Alice Chen Alice C. → 同一个人Bob Robert Chen → 同一个人昵称消解为什么重要你可以问What do I know about Alice?即使某些对话里她只被写作Alice Chen也能拿到关于她的全部信息。在实现层面实体归一依赖 entity_processing.py它会将 LLM 输出的实体列表做规范化与去重处理。Context-Aware Disambiguation上下文感知消歧如果Alice多次与Google和Stanford共同出现那么一个同样提及这些组织的Alice很可能是同一个人。Hindsight 使用**共现模式co-occurrence patterns**来消解常见姓名。这种消歧同时服务于知识图谱构建——共用实体的所有事实会被自动连接。Entity Labels受控词表标签你可以为记忆库定义一组key:value形式的受控分类标签例如pedagogy:scaffolding、engagement:active它们会在 retain 时被抽取并作为实体存储因为标签本身是实体它们会在知识图谱中自动关联相关记忆两条都带pedagogy:scaffolding的记忆会被链接同时提升语义检索与关键词BM25检索的效果标签还可以可选写入记忆单元的 tags从而在 recall / reflect 阶段启用标准标签过滤。完整配置细节见 memory-banks.mdx 中的 entity_labels 章节。Entity Labels 的源码实现在 entity_labels.py 中标签体系被建模为EntityLabelsConfig一组LabelAttributelabel group即一个分类维度每个 group 有key前缀、typevalue/multi-values/text/map、values枚举值、fieldsmap 字段、optional、tag等属性build_labels_lookup()为枚举型标签构建小写key:value的快速查找集合抽取时超出词表的值会被静默丢弃anything outside the list is silently droppedis_label_entity()判断某个实体串是否属于已配置的标签组label_tag_keys()返回tag: true的 group 键这些键的值会被投影_inject_label_tags到事实的tags数组从而支持tags/tags_match过滤。在 fact_extraction.py 中_build_labels_prompt_section()会把标签词表渲染进抽取 prompt枚举型列出可取值及描述文本型text/multi-text提示 LLM 自由书写map 型则要求按key:field:value结构输出例如person:name:Alice并复用既有实体存储无需变更 schema。Building Connections四类知识图谱连接记忆不是孤立的——Hindsight 会创建一个知识图谱包含四类连接Entity Connections实体连接所有提及同一实体的事实被互相链接。能力Tell me everything about Alice → 取回所有与 Alice 相关的事实。Time-Based Connections时间连接时间上接近的事实会被连接日期越近连接越强。能力What else happened around then? → 找到上下文相关的事件。Meaning-Based Connections语义连接语义相似的事实被连接即使它们用了不同的词。能力Tell me about similar topics → 找到主题相关的信息。Causal Connections因果连接因果关系被显式追踪。能力Why did this happen? → 追溯推理链。示例Alice felt burned out ← caused by ← She worked 80-hour weeks从源码看连接构建集中在 link_creation.py 与 link_utils.py。仓库测试 test_causal_relation_offsets.py、test_causal_relations.py 等验证了因果关系的抽取与存储细节测试目录下还有test_link_expansion_*、test_observation_expansion_*等用例覆盖连接相关的检索行为。Understanding Time双时间维度Hindsight 追踪两个时间维度这是它支持时间语义检索的基础。When It Happened事件发生时间对于事件会议、旅行、里程碑记录其发生时间Alice got married in June 2024 → occurred 于 2024 年 6 月对于一般事实偏好、特征没有特定发生时间Alice prefers Python → 持续偏好在实现上事实模型带有occurred_start/occurred_end字段并强制使用 ISO 时间戳格式见 fact_extraction.py 中的_with_iso_timestamp_pattern。此外还有一个兜底机制_infer_temporal_date()同文件 L83 起当 LLM 没有给出结构化时间而事实文本中出现 last night、yesterday、next week 等相对时间表达时会结合 retain 发生时的事件日期自动推算绝对日期。When You Learned It学习时间Hindsight 同时记录你告诉它每个事实的时间。为什么两者都要假设 2025 年 1 月有人告诉你Alice 在 2024 年 6 月结婚历史查询生效What did Alice do in 2024? → 能找到那场婚礼时效排序生效最近的提及在搜索中优先级更高时间推理生效What happened before her marriage? → 找到更早的事件。如果失去这个区分旧信息要么无法按日期检索要么会被当作无关内容处理。这一设计对应源码中的created_at/observed_at类时间字段与时间连接构建逻辑也是 retrieval.md 中时间窗过滤与时效排序能力的基础。Tagging Memories标签与可见性范围标签用于可见性范围控制visibility scoping——当一个记忆库服务多个用户、而每个用户只应看到自己相关的记忆时尤其有用。Item tags给单条记忆打上特定范围标签Document tags给一批batch中的全部条目统一打标签Tag filtering在 recall / reflect 阶段按标签过滤。代码示例见 Retain API过滤选项见 Recall API对应 retrieval.md。在实现上标签会写入记忆单元memory unit的 tags 字段并支持tags/tags_match过滤语义Entity Labels 中tag: true的分组也会把抽取出的key:value标签投影为单元标签与手动标签在同一套过滤机制下工作。What You Getretain() 完成后的产物当retain()完成后你得到结构化事实Structured facts——保留含义、情感与推理统一实体Unified entities——解析了不同名称变体知识图谱Knowledge graph——含实体、时间、语义、因果四类连接时间锚定Temporal grounding——同时支持历史查询与时效排序可选标签Optional tags——供 recall 阶段过滤使用。所有这些都存储在**相互隔离的记忆库memory bank**中随时可供recall()与reflect()使用。每个 bank 独立配置retain_mission、retain_extraction_mode、entity_labels等均按 bank 生效见 memory-banks.mdx。Steering Extraction with a 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 中与内置规则并列生效——它引导steerLLM 的注意力但不替换抽取逻辑。它适用于任何抽取模式concise、verbose、custom。从源码看这一机制位于 fact_extraction.py 的_retain_mission_preamble()mission 以用户消息前缀user message preamble的形式注入而不是写进系统 prompt——这样系统 prompt 保持与 bank 无关Gemini 等 provider 可以跨 bank 复用同一个缓存上下文cache不必为每个 mission 单独建缓存见同文件 L1485-L1490 的注释说明。抽取模式Extraction ModesMode何时使用concise(default)通用场景——有选择地抽取速度快verbose需要更丰富的事实、完整上下文与关系时custom想完全自定义抽取规则时配置方式通过bank config API设置retain_mission和retain_extraction_mode见 memory-banks.mdx 的 retain 配置章节或通过环境变量HINDSIGHT_API_RETAIN_MISSION见 configuration.md 的 retain 章节。环境变量与默认值仓库实测在 config.py 中可确认ENV_RETAIN_EXTRACTION_MODE HINDSIGHT_API_RETAIN_EXTRACTION_MODEL738ENV_RETAIN_MISSION HINDSIGHT_API_RETAIN_MISSIONL739DEFAULT_RETAIN_EXTRACTION_MODE concise合法取值集合为(concise, verbose, custom, verbatim, chunks)L1503-L1504DEFAULT_RETAIN_MISSION NoneL1505DEFAULT_ENABLE_AUTO_CONSOLIDATION True——retain 后自动合并默认开启L1571。也就是说除文档提到的三种模式外代码还保留了verbatim逐字抽取与chunks分块相关两种模式前者在 fact_extraction.py 中对应VERBATIM_FACT_EXTRACTION_PROMPT后者用于长内容分块抽取。配置示例export HINDSIGHT_API_RETAIN_MISSIONFocus on technical decisions, architecture choices, and team member expertise. Deprioritize social or personal information. export HINDSIGHT_API_RETAIN_EXTRACTION_MODEverbose在custom模式下还可以配合retain_custom_instructions完全替换内置抽取规则——只有当retain_extraction_mode为custom时才生效见 configuration.md 附近的环境变量示例。另外 configuration.md 还介绍了按策略覆盖per-strategy overridesretain_extraction_mode、retain_chunk_size、entity_labels、entities_allow_free_form、retain_mission等字段都可以在不同命名策略下分别配置L954 起适合同一服务器服务多种工作负载的场景。Observation Consolidationretain 后的自动合并retain()完成后Hindsight 会在后台自动触发观测合并observation consolidation。这一过程将新事实与既有观测observations做比对分析当新模式涌现时创建新的观测用新证据精炼已有观测追踪每条观测由哪些事实支撑。整个合并异步进行——retain()调用立即返回合并随后在后台完成。从配置与源码看服务级开关HINDSIGHT_API_ENABLE_AUTO_CONSOLIDATION默认true见 config.pybank 级开关enable_observations关闭后该 bank 不做任何合并与enable_auto_consolidation关闭后只在显式调用 consolidate 端点时合并见 memory-banks.mdx仓库测试 test_consolidation_*.py 系列如test_consolidation_retry_budget.py、test_consolidation_reschedule_after_round.py、test_consolidation_round_limit.py、test_consolidation_temporal_merge.py覆盖了合并的轮次限制、失败重试、跨轮刷新、时间合并等细节说明合并是带预算与重试机制的成熟后台任务。观测合并的完整机制详见 observations 文档。Next Steps继续深入Observations——retain 之后知识如何被合并成观测Recall——多策略搜索如何取回相关记忆Reflect——Agentic 循环如何使用观测Retain API / Bank 配置——retain_mission、retain_extraction_mode、entity_labels、retain_chunk_size等参数的完整配置说明与代码示例Configuration——HINDSIGHT_API_RETAIN_MISSION等环境变量的完整清单与分层配置说明源码参考fact_extraction.py、entity_labels.py、engine/retain/ 目录、config.py测试参考test_retain.py、test_entity_labels.py、test_consolidation_*.py 系列。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考