Hindsight 中 AI Agent 的短期记忆与长期记忆两层架构、retain/recall 实现与落地评估方法【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight理解短期记忆 vs 长期记忆这一主题最有效的入口不是术语而是工作流短期上下文负责让当前任务保持连贯长期记忆负责让有用知识在任务结束后继续存活。在开源项目 HindsightAgent Memory That Learns中这两层分别由 prompt 工作区与retain/recall两条持久化 API 承担。读完本篇你将能够明确两层记忆的职责边界、识别常见的单层记忆失效模式并基于 Hindsight 仓库源码理解写入—晋升—检索的完整调用链最后用一份五步评估清单检验自己的记忆栈。快速结论两层记忆各自负责什么原文档给出的三句话结论值得原样保留短期记忆short-term memory当前任务的活跃工作集active working set。长期记忆long-term memory在任务结束后仍保留事实、偏好与历史决策。成熟的 Agent 系统会有意识地在这两层之间搬运信息而不是把两者混为一谈。模糊两层的代价是系统变得难以推理清晰的分离则让保留retention、检索retrieval与 prompt 设计都更可靠。为什么这个区分在实际工程中如此重要许多团队在拥有词汇之前就先注意到了症状Agent 在单个 session 里表现 capable到下一个 session 却变得脆弱。这通常意味着系统依赖的是 prompt 状态prompt state而不是持久记忆durable memory。这也是为什么从 demo 走向生产工作流时临时上下文与持久记忆的边界变得关键。一个实用的记忆设计要能让 Agent 复先前的工作成果同时不把整个历史拖进每一条 prompt。这正是 Hindsight 提供两条 API 的动机retain API 文档存储持久信号durable signalsrecall API 文档在后续工作中按需恢复正确的上下文。同样的模式也出现在仓库内的真实集成中例如 Claude Code 集成 与 Codex 集成——它们都是会话内工作上下文 跨会话持久记忆的典型落地。单层记忆设计中常见的三种失效模式原文档列出的三个典型故障值得逐条对照自己的系统检查一切内容都留在 prompt 里直到被窗口挤出去——上下文被截断后早期关键信息无声丢失有用信息从未在恰当的时机被晋升到持久记忆——session 结束时没有沉淀动作系统召回过多因为它无法区分活跃上下文与已存储上下文——检索结果稀释了当前任务的注意力。这些故障孤立看都不大但会叠加轻微的遗忘变成重复的 onboarding重复 onboarding 变成返工返工最终降低用户对Agent 能否带着关键上下文跨会话工作的信任。更好的记忆层做什么四项设计准则与 Hindsight 源码印证更好的设计是选择性的selective不试图永远保留每个 token而是聚焦那些能改进未来工作的信号并在需要时让它们可被恢复。好的系统通常包含四个要素维护一个小型的、相关的工作上下文把持久信号晋升promote到长期存储仅当长期记忆支持当前任务时才检索它让两层都保持可观测、可调试。写入路径retain 负责把短期信号沉淀为长期记忆架构比标签更重要一个产品可以宣称自己有记忆却表现得像一个挂了搜索的长 prompt。有用的系统必须保留得好、检索得好并能把结果干净地放回活跃上下文。Hindsight 的写入入口在 memory_engine.pyretain接收bank_id、content、context这条记忆形成的场景与event_date事件发生时间同步版本只是retain_async的薄封装而后者又收敛到retain_batch_async统一处理。从源码结构看单条写入最终走批量管线这意味着嵌入计算、分块等开销可以在批次内摊薄。写入管线并非原样落库。retain 子模块目录 下可以看到事实抽取fact_extraction.py、实体处理entity_processing.py、记忆单元预算memory_budget.py、链接创建link_creation.py与折叠fold.py等组件——这正对应原文档所说的选择性保留内容先被解析成结构化的记忆单元与语义/时间链接而不是整段文本堆进向量库。晋升路径consolidation 把原始事实折叠为观察在恰当的时机把信号晋升为长期记忆在 Hindsight 中由 consolidation 模块 承担它周期性地把离散的原始事实facts折叠成更高层次的观察observations并在合并后刷新对应嵌入。测试文件 test_mental_model_consolidation_refresh_scope.py 与 test_consolidation_dedup.py 覆盖了刷新作用域与去重行为可以推断这是防止记忆越攒越碎的关键机制。读取路径recall 用多路并行检索 预算控制只在需要时召回仅当长期记忆支持当前任务时才检索在实现上体现为 recall_async 的设计。从源码结构看它执行N×4 路并行检索对每种 fact type 并行跑四种检索方式语义向量、BM25 关键词、图激活、时间图谱对应 search 子模块 中的向量检索、BM25 选词bm25_term_selection.py、图检索graph_retrieval.py与时间抽取temporal_extraction.py最终融合排序。同时召回规模受两个预算参数约束直接回答了召回过多的失效模式budget图遍历的单元预算注释中标明low100, mid300, high600 unitsmax_tokens返回 token 上限默认 4096且只统计text字段。recall_async还暴露了prefer_observations、include_chunks、tags、created_after/created_before、min_scores、temporal_window、reranking默认cross_encoder等参数见 memory_engine.py让调用方可以精细控制召回什么粒度、什么时间窗、多严格的分数下限。可观测性两层都留痕让两层可观测在 Hindsight 中落到具体机制上retain 管线带计时装饰器timing.pyrecall 支持enable_trace返回详细 trace 对象memory_engine.py 中enable_trace: If True, returns detailed trace object另有 audit 模块 记录操作审计。配合文档中 retain 使用指南存储与召回模型清晰到可以被检查——这正是原文档好的记忆系统因为模型可检查而更容易被信任的工程注脚。典型工作流这种区分在哪里最有价值原文档列出的三个工作流可以对照上述架构理解短期层保留什么、长期层晋升什么跨多个 PR 工作的编码 Agent短期层是当前 PR 的 diff 与讨论上下文长期层是这个仓库的测试惯例、上次的架构决策。Hindsight 的document_id参数见retain_async签名支持对同一文档做 upsert 式更新适合同时跟踪文档演进的历史版本与最新状态。回访持续主题的研究助理短期层是本次对话的引用上下文长期层是已排除的假设、已确认的结论。fact_type区分world事实与experience经验——recall_async中fact_type: list[str] | None参数允许按类型召回。把账户历史带入新会话的客服系统短期层是当前工单上下文长期层是跨会话的账户偏好与历史处理结果。bank_id作为记忆银行隔离键天然支持每个账户一个 bank的多租户隔离。在自己的技术栈中评估五步检查清单原文档给出的评估框架简洁有效这里把它展开为可操作的清单并对应到 Hindsight 中的验证点确定一件今天学到、明天必须记得的事。例如用户偏好某个输出格式、项目里某个 API 的正确用法。判断该信号属于个人、项目还是共享记忆。这对应bank_id的划分策略——个人 bank、项目 bank、团队共享 bank。验证系统能有意地保留它。调用 retain 后应能拿到创建的记忆单元 IDretain_async返回list[str]的 unit IDsHindsight 的 retain API 文档 描述了完整参数。测试它能否在正确的后续工作流中回来。用 recall 以相关查询检索确认目标单元命中且排在前列enable_traceTrue可检查四路检索各自的贡献。检查召回上下文是否足够简洁——有帮助而不是干扰。用budget与max_tokens收窄返回对照原文档 FAQ 的标准concise enough to help instead of distract。FAQ问聊天记录是短期记忆还是长期记忆通常属于短期上下文除非系统选择性地将其部分内容持久化存储。在 Hindsight 中只有经过 retain 管线处理的内容才会进入长期存储。问长期记忆能取代 prompt 上下文吗不能。模型仍然需要一个活跃工作集来执行当前任务——这是原文档明确否定的方案也是短期与长期是搭档而非替代这一核心结论。问什么内容应该进入长期记忆偏好preferences、持久事实durable facts、结果outcomes与决策decisions都是好的候选。对照 Hindsight 的fact_type划分稳定的事实归world从交互中习得的经验归experience。小结短期记忆与长期记忆的分层不是概念游戏它决定了 Agent 系统能否把单会话能力转化为跨会话信任。Hindsight 用 retain选择性写入 结构化解析、consolidation原始事实向观察的晋升、recall四路并行检索 双预算控制与 trace/audit可观测性四个环节把原文档的四项设计准则落到了可检查的源码与 API 上。按五步清单在自己的栈中验证一次是判断你的记忆系统是真记忆还是长 prompt最快的方式。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hindsight 中 AI Agent 的短期记忆与长期记忆：两层架构、retain/recall 实现与落地评估方法
Hindsight 中 AI Agent 的短期记忆与长期记忆两层架构、retain/recall 实现与落地评估方法【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight理解短期记忆 vs 长期记忆这一主题最有效的入口不是术语而是工作流短期上下文负责让当前任务保持连贯长期记忆负责让有用知识在任务结束后继续存活。在开源项目 HindsightAgent Memory That Learns中这两层分别由 prompt 工作区与retain/recall两条持久化 API 承担。读完本篇你将能够明确两层记忆的职责边界、识别常见的单层记忆失效模式并基于 Hindsight 仓库源码理解写入—晋升—检索的完整调用链最后用一份五步评估清单检验自己的记忆栈。快速结论两层记忆各自负责什么原文档给出的三句话结论值得原样保留短期记忆short-term memory当前任务的活跃工作集active working set。长期记忆long-term memory在任务结束后仍保留事实、偏好与历史决策。成熟的 Agent 系统会有意识地在这两层之间搬运信息而不是把两者混为一谈。模糊两层的代价是系统变得难以推理清晰的分离则让保留retention、检索retrieval与 prompt 设计都更可靠。为什么这个区分在实际工程中如此重要许多团队在拥有词汇之前就先注意到了症状Agent 在单个 session 里表现 capable到下一个 session 却变得脆弱。这通常意味着系统依赖的是 prompt 状态prompt state而不是持久记忆durable memory。这也是为什么从 demo 走向生产工作流时临时上下文与持久记忆的边界变得关键。一个实用的记忆设计要能让 Agent 复先前的工作成果同时不把整个历史拖进每一条 prompt。这正是 Hindsight 提供两条 API 的动机retain API 文档存储持久信号durable signalsrecall API 文档在后续工作中按需恢复正确的上下文。同样的模式也出现在仓库内的真实集成中例如 Claude Code 集成 与 Codex 集成——它们都是会话内工作上下文 跨会话持久记忆的典型落地。单层记忆设计中常见的三种失效模式原文档列出的三个典型故障值得逐条对照自己的系统检查一切内容都留在 prompt 里直到被窗口挤出去——上下文被截断后早期关键信息无声丢失有用信息从未在恰当的时机被晋升到持久记忆——session 结束时没有沉淀动作系统召回过多因为它无法区分活跃上下文与已存储上下文——检索结果稀释了当前任务的注意力。这些故障孤立看都不大但会叠加轻微的遗忘变成重复的 onboarding重复 onboarding 变成返工返工最终降低用户对Agent 能否带着关键上下文跨会话工作的信任。更好的记忆层做什么四项设计准则与 Hindsight 源码印证更好的设计是选择性的selective不试图永远保留每个 token而是聚焦那些能改进未来工作的信号并在需要时让它们可被恢复。好的系统通常包含四个要素维护一个小型的、相关的工作上下文把持久信号晋升promote到长期存储仅当长期记忆支持当前任务时才检索它让两层都保持可观测、可调试。写入路径retain 负责把短期信号沉淀为长期记忆架构比标签更重要一个产品可以宣称自己有记忆却表现得像一个挂了搜索的长 prompt。有用的系统必须保留得好、检索得好并能把结果干净地放回活跃上下文。Hindsight 的写入入口在 memory_engine.pyretain接收bank_id、content、context这条记忆形成的场景与event_date事件发生时间同步版本只是retain_async的薄封装而后者又收敛到retain_batch_async统一处理。从源码结构看单条写入最终走批量管线这意味着嵌入计算、分块等开销可以在批次内摊薄。写入管线并非原样落库。retain 子模块目录 下可以看到事实抽取fact_extraction.py、实体处理entity_processing.py、记忆单元预算memory_budget.py、链接创建link_creation.py与折叠fold.py等组件——这正对应原文档所说的选择性保留内容先被解析成结构化的记忆单元与语义/时间链接而不是整段文本堆进向量库。晋升路径consolidation 把原始事实折叠为观察在恰当的时机把信号晋升为长期记忆在 Hindsight 中由 consolidation 模块 承担它周期性地把离散的原始事实facts折叠成更高层次的观察observations并在合并后刷新对应嵌入。测试文件 test_mental_model_consolidation_refresh_scope.py 与 test_consolidation_dedup.py 覆盖了刷新作用域与去重行为可以推断这是防止记忆越攒越碎的关键机制。读取路径recall 用多路并行检索 预算控制只在需要时召回仅当长期记忆支持当前任务时才检索在实现上体现为 recall_async 的设计。从源码结构看它执行N×4 路并行检索对每种 fact type 并行跑四种检索方式语义向量、BM25 关键词、图激活、时间图谱对应 search 子模块 中的向量检索、BM25 选词bm25_term_selection.py、图检索graph_retrieval.py与时间抽取temporal_extraction.py最终融合排序。同时召回规模受两个预算参数约束直接回答了召回过多的失效模式budget图遍历的单元预算注释中标明low100, mid300, high600 unitsmax_tokens返回 token 上限默认 4096且只统计text字段。recall_async还暴露了prefer_observations、include_chunks、tags、created_after/created_before、min_scores、temporal_window、reranking默认cross_encoder等参数见 memory_engine.py让调用方可以精细控制召回什么粒度、什么时间窗、多严格的分数下限。可观测性两层都留痕让两层可观测在 Hindsight 中落到具体机制上retain 管线带计时装饰器timing.pyrecall 支持enable_trace返回详细 trace 对象memory_engine.py 中enable_trace: If True, returns detailed trace object另有 audit 模块 记录操作审计。配合文档中 retain 使用指南存储与召回模型清晰到可以被检查——这正是原文档好的记忆系统因为模型可检查而更容易被信任的工程注脚。典型工作流这种区分在哪里最有价值原文档列出的三个工作流可以对照上述架构理解短期层保留什么、长期层晋升什么跨多个 PR 工作的编码 Agent短期层是当前 PR 的 diff 与讨论上下文长期层是这个仓库的测试惯例、上次的架构决策。Hindsight 的document_id参数见retain_async签名支持对同一文档做 upsert 式更新适合同时跟踪文档演进的历史版本与最新状态。回访持续主题的研究助理短期层是本次对话的引用上下文长期层是已排除的假设、已确认的结论。fact_type区分world事实与experience经验——recall_async中fact_type: list[str] | None参数允许按类型召回。把账户历史带入新会话的客服系统短期层是当前工单上下文长期层是跨会话的账户偏好与历史处理结果。bank_id作为记忆银行隔离键天然支持每个账户一个 bank的多租户隔离。在自己的技术栈中评估五步检查清单原文档给出的评估框架简洁有效这里把它展开为可操作的清单并对应到 Hindsight 中的验证点确定一件今天学到、明天必须记得的事。例如用户偏好某个输出格式、项目里某个 API 的正确用法。判断该信号属于个人、项目还是共享记忆。这对应bank_id的划分策略——个人 bank、项目 bank、团队共享 bank。验证系统能有意地保留它。调用 retain 后应能拿到创建的记忆单元 IDretain_async返回list[str]的 unit IDsHindsight 的 retain API 文档 描述了完整参数。测试它能否在正确的后续工作流中回来。用 recall 以相关查询检索确认目标单元命中且排在前列enable_traceTrue可检查四路检索各自的贡献。检查召回上下文是否足够简洁——有帮助而不是干扰。用budget与max_tokens收窄返回对照原文档 FAQ 的标准concise enough to help instead of distract。FAQ问聊天记录是短期记忆还是长期记忆通常属于短期上下文除非系统选择性地将其部分内容持久化存储。在 Hindsight 中只有经过 retain 管线处理的内容才会进入长期存储。问长期记忆能取代 prompt 上下文吗不能。模型仍然需要一个活跃工作集来执行当前任务——这是原文档明确否定的方案也是短期与长期是搭档而非替代这一核心结论。问什么内容应该进入长期记忆偏好preferences、持久事实durable facts、结果outcomes与决策decisions都是好的候选。对照 Hindsight 的fact_type划分稳定的事实归world从交互中习得的经验归experience。小结短期记忆与长期记忆的分层不是概念游戏它决定了 Agent 系统能否把单会话能力转化为跨会话信任。Hindsight 用 retain选择性写入 结构化解析、consolidation原始事实向观察的晋升、recall四路并行检索 双预算控制与 trace/audit可观测性四个环节把原文档的四项设计准则落到了可检查的源码与 API 上。按五步清单在自己的栈中验证一次是判断你的记忆系统是真记忆还是长 prompt最快的方式。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考