Hindsight 记忆结构化实战：如何为 Agent Memory 整理聊天日志

Hindsight 记忆结构化实战如何为 Agent Memory 整理聊天日志【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文围绕 Hindsight 的retain摄取链路讲解聊天日志的形状如何决定 Agent 记忆质量。核心要点是Hindsight 并不保存原文而是将文本切块后交给 LLM 抽取事实因此谁说了什么、在什么时间、什么情境下说的必须由你输入的文本直接表达清楚。读完本文你将掌握从原始对话转录到高质量持久记忆的完整方法整段保留、说话者标注、context归属、时间锚定、噪音清理、metadata/tags结构化以及可复制的完整retain调用示例。先理解 Hindsight 如何记住抽取事实而非保存原文Hindsight 不会存储你的聊天记录。当你调用retain保留一段对话时实际发生的是整篇文档被切块chunking每个文本块被送入 LLM 做事实抽取fact extraction抽取出的事实而非原始转录被分类、实体消解、链接并去重最终合并为持久记忆。这一设计选择正是输入结构如此重要的原因模型只能从文本中明确表达的信息里抽取事实。一份形状良好的转录会产生干净、归属正确的记忆而一大片无标注的文本只会产生猜测。好消息是没有需要学习的 schema也没有强制格式。纯文本、JSON、Markdown 都可以只要它能传达谁说了什么、在何时说的。本篇讨论的就是如何做到这一点以及那些能把平庸摄取变成优秀摄取的少数高杠杆选择。从源码可以印证这一管道的存在fact_extraction.py 负责将内容交给 LLM 抽取事实fact_storage.py 负责事实落库而 orchestrator.py 统辖整条 retain 流水线。TL;DR六条黄金法则把整段对话作为一条记录 retain而不是每条消息一条。事实抽取需要完整上下文才能交叉引用而稳定的document_id让重复摄取具备幂等性。文档长度不是约束。Hindsight 会把整篇文档分解为事实长转录的尾部不会被丢弃或降权这是那些把原始文本塞进上下文窗口的系统的典型失败模式。分段应依据你多久之后需要回忆它而不是依据大小。为每一行标注说话者。最简单可靠的格式是Name (timestamp): text。Hindsight 依据谁在说话来判断一条陈述是关于世界的客观事实还是 Agent 自身的经验。通过context告诉 Hindsight 说话者是谁。类似Customer Maria is speaking的上下文能让她的 I bought a Tesla 存储为关于 Maria 的事实而不是被误判为 Agent 的行为。锚定时间。传入真实的timestamp模型才能解析 last Monday 这类相对时间后续的时间维度回忆temporal recall才能生效。去掉噪音。剥离系统提示词以及任何 Hindsight 之前注入回对话的记忆。它们是指令和回声不是值得记住的事实。唯一规则谁说了什么何时说的其他一切规则都由此衍生。因为抽取是一个 LLM 在阅读你的文本转录必须让说话者和时间对读者可读。文档推荐的格式刻意保持朴素Alice (2024-03-15T09:00:00Z): 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 carrying an antihistamine now.Name (timestamp): text每轮一行仅此而已。如果你已经有 JSON 格式的数据JSON 也可以模型同样能解析。但带标注的纯文本是最低摩擦的选择也最容易在调试抽取结果时肉眼核对。值得注意的源码细节Hindsight 的切块逻辑会识别逐行带说话者标注的转录。在 orchestrator.py 中merge_json_array_parts专门处理整段对话以 JSON 数组存储的情况——如果每条消息是一个对象且整个转录是单一 JSON 数组append 时会合并数组元素而不是用换行拼接从而保证下一次 append 周期切块时仍能正确解析说话者归属对应 issue #2409。这说明说话者标注会一路影响到底层的切块与归属逻辑。保留整段对话而非逐条消息一个常见的直觉是每收到一条消息就调用一次retain。不要这样做。请把完整对话作为一条记录发送。理由有二。第一事实抽取在有上下文时质量更高Yeah, nothing serious 单独看毫无意义但紧跟在 I have a mild peanut allergy 之后就含义明确。把对话拆成逐条消息的 retain恰好剥离了模型需要的上下文。第二对话是活的东西会不断增长而 Hindsight 正是为此设计的给每段对话一个稳定的document_id。用同一个 ID 再次 retain 会执行upsert旧版本及其记忆被删除更新后的内容从头重新处理。记忆永远反映最新状态且不会产生重复。对于逐条增长的转录使用update_mode: append。无需重发全部历史只需发送新增的轮次Hindsight 会把新内容拼接到既有文档上并跳过对未变化块的重新抽取。从 types.py 可以看到update_mode的两种取值语义replace默认删除旧数据并重新处理append将新内容拼接至既有文档后重新处理。append 模式下orchestrator.py 的append_document_body会读取documents.original_text与新增内容拼接——这是文档主体的唯一权威定义拼接与后续切块不会产生分歧。所以模式是每段对话一个document_id拿到完整内容时用 replace 重 retain消息流式到达时用 append。仓库中的测试对此有直接验证test_retain_append_mode.py 与 test_append_coalesces.py 覆盖了 append 的拼接与合并行为test_retain_params_roundtrip.py 则验证了各参数在 API 中的往返传递。多长算太长按回忆延迟分段而不是按大小一个常见的担忧——也是其他记忆系统真实的失败模式——是长转录的尾部会被遗漏。把几千条消息塞进上下文窗口模型会悄悄低估结尾部分的内容。Hindsight 不是这样工作的这正是它的核心价值所在。它不会保留原始转录、寄希望于回忆时正确的那段恰好出现在视野中。它会把整篇文档切块、从每一个块中抽取事实然后分类、链接、去重合并为统一记忆。对话的任何部分都不会因为所处位置而被优待或丢弃。文档长度本身不是需要优化的对象。因此真正的问题不是一个文档应该多大而是你多久之后需要回忆其中的内容这才是分段依据的轴如果 Agent 需要就今天早些时候说过的内容采取行动不要把一天或一周的日志缓冲成一个巨型文档再 retain——否则今晚落盘之前你都无法回忆起今早的细节。请以更小、更及时的单元 retain。如果材料是参考级的很久之后才会查询那么更激进的批量处理完全没问题。为回忆的新鲜度分段而不是为了某个长度上限。昂贵且有价值的工作是把一段对话拆解为事实并合并它们让回忆返回最佳答案而非一堆原始行——这正是 Hindsight 存在的意义而且无论文档多长都会发生。流式处理实时对话如果你接近实时地摄取对话有两点实操提示把几条消息一起缓冲而不是每行触发一次 retain。一批轮次能给抽取器提供足够的上下文来产出优质事实孤零零的一条lol或um则无可记之事。小型的滚动缓冲几条轮次或一个短时间窗口是甜点区间。Hindsight Cloud 有适度的按用户摄取速率限制缓冲天然让你处于限制之下。如果需要更高的持续吞吐把相关条目合并进一次 retain 调用。标注说话者并告诉 Hindsight 他是谁这是最高杠杆的部分也是天真的摄取最常见的翻车点。Hindsight 会按陈述捕获了谁的视角来分类每一条抽取的事实。当 bank 自己的 Agent 是行动者或观察者时I patched the auth bug该事实是experience经验当它关于某人或某物时Maria drives a Tesla是world世界事实。这个划分由谁在说话决定而非语法。第一人称的 I bought a Tesla 只有在说话者是 Agent 时才算是 experience出自客户之口它就是关于客户的 world 事实。在 fact_extraction.py 的源码中可以看到这个映射的落地LLM 输出的fact_type字段中只有assistant会被映射为experience其余一律归为world若字段意外缺失则回退到fact_kind判断再默认world。同一文件的提取提示词fact_extraction.py还包含一条关键指令当context指明转录中的第一人称说话者是用户/客户时把这些陈述归属给该说话者并分类为world而非assistant。这从实现层面印证了说话者决定归属的设计。转录中的说话者标签只完成一半工作。context参数完成另一半它会被直接注入提取提示词主动引导归属client.retain( bank_idsupport-agent, content( Maria (2024-03-15T09:00:00Z): I switched to the Pro plan last month but Im still being billed for Basic.\n Agent (2024-03-15T09:01:00Z): Thanks Maria — Ill fix the billing today. ), contextCustomer Maria is speaking with the support agent, document_idticket-4471, )那个context确保 Maria 的第一人称陈述落为关于 Maria 的world事实而 Agent 的 Ill fix the billing 被记录为 Agent 自己的 experience。文档说得直白持续提供 context 是提升记忆质量最高杠杆的事情之一。同样一句话在performance review与product roadmap两种上下文里含义完全不同——context正是用来消除歧义的。从 fact_extraction.py 可以看到抽取提示词的结构包含Event Date:与Context:两个显式段落——context与event_date是被系统性地嵌入提示词、供 LLM 全程参考的。锚定时间对话里充满了相对时间last Monday、the meeting yesterday、since the launch。模型只有在一个锚点上才能解析它们所以要传入对话发生时真实的timestampISO 8601。它会被注入提取提示词作为参照点也是后续时间维度回忆比如客户去年春天报告了什么能真正工作的前提。三种取值形式timestamp值行为省略 /null默认为摄取时的当前时间。ISO 8601如2024-03-15T09:00:00Z作为锚点用于解析相对时间引用。unset存储时不带时间。适用于文档、书籍、小说等永恒性参考资料没有真实事件时间。在 API 与内部类型中这个参数对应RetainContent的event_date字段types.py类型为可空的datetime省略时默认当前时间。抽取侧还有一道兜底逻辑当 LLM 未能从 last night、yesterday 等相对表达中抽取occurred_start时_infer_temporal_date会基于event_date锚点推算日期偏移last night/yesterday→ -1 天today/this morning→ 0 天等保证相对时间仍能被解析为绝对日期。如果你的转录已经带逐行时间戳如上例所示请保留它们因为它们帮助模型排序对话内事件。顶层的timestamp则为整段对话锚定。去掉噪音并非聊天会话中的一切都值得记住。官方集成在 retain 之前会统一剥离两类内容值得照抄系统提示词System prompts。它们是给模型的指令不是关于用户或世界的事实。retain 它们会污染 bank产生诸如 the assistant should be concise 之类的记忆。Hindsight 注入的记忆。如果你 recall 出记忆并拼接进对话作为上下文那就不要再把同样的文本 retain 回去否则等于在重新记忆 bank 自己的回声每轮累积放大。剩下的——真实的用户与助手轮次、工具调用、工具结果——才是信号。例如 LiteLLM 集成就把这些渲染成USER: ...、ASSISTANT: ...、TOOL_RESULT: ...这样的行用空行分隔别无其他。仓库中metadata的清洗逻辑也印证了只留信号的设计RetainContent.__post_init__types.py会丢弃值为null的 metadata 键因为读路径将MemoryFact.metadata校验为dict[str, str]空值会毒化读取对应 issue #3209。用 metadata 和 tags 承载其余结构化信息还有两个参数承载不适合放进正文散文的结构化上下文metadata任意的字符串键值对例如{source: slack, channel: engineering, thread_id: T123}。它被喂入提取提示词并且存储在每条产出的记忆上因此之后无需二次查询就能按来源过滤或链接记忆。注意键值类型约束为字符串dict[str, str]见 types.pynull值会被自动丢弃。tags可见性作用域。一条记忆只有在回忆时其 tags 与 recall 过滤器相交才会被返回这正是让一个 bank 安全地服务多个用户或会话的机制。使用一致的命名模式user:id、session:id、room:id、topic:name。链接与附件对话承载的不止文本还有 URL、文件、图片。需要设置几个预期链接以文本形式进入。把 URL 放进 content 就会作为对话的一部分被 retain围绕它的那些事实Maria shared the new pricing page会被记住链接会随记忆一起返回。Hindsight不会抓取或解析链接指向的页面。记忆是关于上下文中的链接而非其内容。附件不会被直接摄取。目前没有文件上传接口。常见模式是把文件存到别处例如 S3 bucket然后把链接作为参考文本放在消息旁外加你已有的任何标题或描述。这样即使附件的字节在别处附件也能从记忆中可被发现。如果你需要文件与页面的内容成为记忆那属于文档检索retrieval-over-documents的范畴是与会话记忆不同的另一条管道。组合起来一次完整的 retain 调用一段客服对话的完整、规范的 retainclient.retain( bank_idsupport-agent, content( Maria (2024-03-15T09:00:00Z): I switched to Pro last month but Im still billed for Basic.\n Agent (2024-03-15T09:01:00Z): Sorry about that, Maria. Ive corrected the billing and credited the difference.\n Maria (2024-03-15T09:03:00Z): Thank you! Also, can you make my account email mariaexample.com going forward? ), contextCustomer Maria is speaking with the support agent, timestamp2024-03-15T09:00:00Z, document_idticket-4471, metadata{source: zendesk, ticket_id: 4471}, tags[user:maria, topic:billing], )仅仅这一次调用Hindsight 就会抽取关于 Maria 的 world 事实她之前是 Basic 套餐、已切换 Pro、希望更新邮箱记录 Agent 的 experience修正了计费、应用了退款链接相关实体并把这一切作用域限定到 Maria等她下次联系时即可召回。回顾决策速查表决策这样做为什么粒度每段对话一条记录而非每条消息抽取需要周边上下文长度不要为它优化按回忆延迟分段整篇文档被分解尾部不会被丢弃流式每次 retain 缓冲几条轮次留意按用户速率限制上下文优于单独一条纯噪音行重复摄取稳定document_id重写用replace流式用append幂等、无重复说话者每行标注Name (timestamp): text驱动 world 与 experience 的划分归属用context指明说话者让用户的 I… 成为关于用户的事实时间传真实的timestamp解析相对日期启用时间维度回忆噪音剥离系统提示词与注入的记忆它们是指令和回声不是事实结构化上下文metadata管来源tags管作用域无需重新抽取即可过滤与链接你不需要预先总结、预先切块或手工抽取事实。Hindsight 会完成这一切然后在后台合并规律。你的工作只是交给它一份诚实交代了谁在何时、何种情境下说话的转录。把这四件事做对记忆质量自会水到渠成。进一步探索Retain API摄取对话与完整参数列表见 engine/retain/types.py 中RetainContent/RetainContentDict的字段文档以及 engine/retain/orchestrator.py 的管道实现retain 如何工作事实抽取、实体消解与 world/experience 划分的提示词细节见 engine/retain/fact_extraction.pyRecall回忆记忆含 tag 过滤可结合 engine/memories/base.py 中recall_unified等接口阅读测试佐证append 语义见 tests/test_retain_append_mode.py参数往返见 tests/test_retain_params_roundtrip.py试用Hindsight Cloud 或使用 docker 自托管 一条命令起服务后用 Python 客户端hindsight-clients/python即可按本文模式接入。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考