Hindsight × Omnigent：为 Meta-Harness 编排的每一个 Agent 统一接入持久记忆

Hindsight × Omnigent：为 Meta-Harness 编排的每一个 Agent 统一接入持久记忆

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight

Hindsight 为 Omnigent（一个可同时包装并编排 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 等多个 AI Agent 的 meta-harness）提供开箱即用的持久化长期记忆。本文讲解如何通过pip install "omnigent[memory]"一次性为所有被编排的 harness 接入hindsight_recall/hindsight_retain/hindsight_reflect三个内置记忆工具，并深入解析其拦截执行原理、Bank 作用域解析顺序、完整配置项与自托管方式，让读者能在自己的多 Agent 编排环境中用一套配置获得跨会话的共享记忆。

为什么选择 Omnigent：一个中心化的记忆桥

大多数 Agent 记忆集成都只解决单一工具的问题：给 Cursor 加 Hindsight，Cursor 会记忆；给 Aider 加 Hindsight，Aider 会记忆。每一次都要单独安装、单独配置、单独维护。

Omnigent 打破了这种模式。它是一个 meta-harness，即位于所有被包装 Agent 之上的统一编排层，同时协调 Claude Code、Codex、Cursor、OpenCode、Hermes、Pi 等工具。当你在 Omnigent 中接入 Hindsight 时，等于通过一个位置、一套配置为所有这些 Agent 增加了持久记忆；对于没有任何原生 Hindsight 集成的 harness（包括自研定制 harness），Omnigent 本身就是它的记忆层。记忆桥活在 Omnigent 的 runner 中，被包装的 Agent 无需自己携带集成逻辑。

安装

记忆工具是 Omnigent 的可选附加组件，按需安装即可：

pip install "omnigent[memory]"

该扩展的唯一依赖是hindsight-client，随后导出 API Key：

export HINDSIGHT_API_KEY=hsk_...

• Hindsight Cloud：在 Hindsight Cloud 控制台获取 API Key；
• 自托管：通过HINDSIGHT_API_URL指向自己的 Hindsight 服务器。

设置：在 Agent 的 YAML Spec 中挂接三个工具

Omnigent 的 Agent 用 YAML 定义。在tools.builtins下添加三个内置记忆工具即可：

name: my-agent tools: builtins: - name: hindsight_recall api_key: ${HINDSIGHT_API_KEY} bank_id: my-agent-memory # 可选；默认回退到 agent_id budget: mid # low / mid / high max_tokens: 4096 - name: hindsight_retain api_key: ${HINDSIGHT_API_KEY} bank_id: my-agent-memory - name: hindsight_reflect api_key: ${HINDSIGHT_API_KEY} bank_id: my-agent-memory

重启 Agent 后，三个工具就会出现在其工具列表中，配置到此即全部完成。

工作原理：Runner 级拦截 + 本地执行

Omnigent 在runner 层面拦截hindsight_*调用——在调用到达被包装 harness 之前就将其截获，通过hindsight-client在本地执行，然后把结果返回给 Agent。这意味着：

• 被包装的 harness（Claude Code、Codex、Cursor、Pi 等）完全不需要处理这些调用，runner 全权代办；
• 原生模式的 harness（以 native 模式运行 Agent 时）同样会收到被转发的工具；
• 一套配置覆盖全部。这些 harness 大多有自己的原生 Hindsight 集成，但通过 Omnigent，你只需配置一次记忆，它就能作用于所有被编排的 harness，包括没有任何原生选项的定制 harness。

与若干"钩子式"集成不同，Omnigent 的 Agent显式调用这三个工具，不存在自动生命周期钩子。因此需要在 Agent 的系统提示（system prompt）中加入调用指令：

- At the start of each task, call hindsight_recall with the user's request to load relevant decisions, preferences, and project context. - When the user gives you a durable fact (a convention, a decision, a preference), call hindsight_retain to store it. - Call hindsight_reflect to synthesize what you know about a topic across sessions.

这种显式调用设计是有意为之：Omnigent 把能力交给 Agent，由 Agent 根据系统指令自主决定何时使用，行为完全透明——读 Agent spec 就能看到记忆操作发生在何时。

三个内置工具详解

• hindsight_recall：对 Bank 执行语义搜索，返回与当前消息最相关的记忆。budget与max_tokens控制返回多少 token 的记忆。在 Python 客户端中，recall 的默认参数与此一一对应：max_tokens=4096、budget="mid"，还支持types（按事实类型过滤）、tags/tags_match（按标签过滤）等高级参数，见 hindsight_client.py。
• hindsight_retain：把一条信息存入 Bank。存什么由 Agent 判断，可通过配置中的tags引导，以便后续更细粒度地过滤。
• hindsight_reflect：基于 Bank 中累积的观测，综合生成一个答案，适合"我们对 X 了解多少"这类跨会话的综合问题。与 recall 的差异在于：recall 检索与具体查询匹配的记忆，reflect 则跨累积观测进行综合推理；reflect 还支持通过response_schema输出结构化结果，并可返回生成答案所依据的底层事实。

Bank 作用域：记忆的隔离边界

记忆按 Bank 隔离。Omnigent 按以下顺序解析使用哪个 Bank：

1. YAML 配置中的显式bank_id——最可预测，推荐用于生产；
2. Agent 的agent_id——每个 Agent 一个 Bank，跨该 Agent 的所有会话共享；
3. conversation_id——每个会话一个 Bank，会话结束后记忆不再被引用（Bank 本身仍存在，只是不再被指向）。

在 Omnigent 中运行多个 Agent 并希望它们共享记忆（例如共享项目 Bank）时，让它们指向同一个bank_id即可。

从 Hindsight 的设计看，Bank 是"回忆边界"：recall、retain、reflect都只在一个 Bank 内操作，不存在跨 Bank 查询（详见 bank 策略文档）。因此"两个 Agent 是否共享 Bank"本质上等同于"A 存入的记忆 B 是否应当能召回"。而由于 Bank 首次使用时才惰性创建，新的bank_id字符串就是一个全新的空记忆——这也是"每个会话一个 Bank"导致跨会话失忆的根本原因。

配置参考

关于标签匹配的细节可以对照服务端请求模型中的枚举定义（recall_request.py）：

• any（默认）：OR 匹配，且包含未打标签的记忆——适合把标签当作提示而非硬性边界；
• all：AND 匹配，仍包含未打标签的记忆；
• any_strict/all_strict：匹配逻辑同上，但排除未打标签的记忆；
• exact：记忆的标签集合必须与查询的标签集合完全相等（排除未打标签的记忆）。

由于any默认包含未打标签记忆，标签属于软分区：便于组织，但不能作为安全控制。若某条记忆绝不允许出现在错误上下文中，应将其放入独立的 Bank，而非依赖可能被遗忘的标签过滤。

自托管

使用api_url指向自己的服务器即可；开放服务器无需 token：

- name: hindsight_recall api_url: http://localhost:8888 bank_id: local-memory

Hindsight 的 API 客户端（hindsight-client）同样以base_url指向服务器地址，其余操作（retain / recall / reflect / 创建 Bank 等）保持一致，完整用法可参考 Python 客户端文档 及其 客户端包装实现。

工作示例：Remy 对话助手

Omnigent 自带一个完整可运行示例examples/remy/config.yaml——一个对话助手，三个记忆工具全部挂接，并配有"何时调用哪个工具"的指令。运行它只需要一条命令：

HINDSIGHT_API_KEY=hsk_... omnigent run examples/remy

与 Remy 进行几轮对话后，询问它在之前会话中学到的内容：它会调用hindsight_recall针对你的问题检索记忆，找到相关内容并作答——如果没有记忆层，这些上下文早已丢失。

哪些 Harness 受益

大多数上述 harness 已有原生 Hindsight 集成，在单独运行该工具时是理想选择。Omnigent 的价值在于：一份中心化记忆配置即可横跨所有被编排的 harness，同时覆盖没有任何原生选项的定制或内部 harness——你只需配置一次，而不是每个工具各配一次。

Omnigent 工具 vs 原生集成：如何选择

若某 harness 两种路径都支持，应如何取舍？核心规则：每个 Bank 只选一条路径。不要同时启用工具的原生 Hindsight 集成和指向同一 Bank 的 Omnigent 记忆工具，否则会出现两条 recall/retain 路径重复写入同一会话的问题。

两种方式的取舍：

• 原生集成：往往自动化，钩住工具自身的生命周期，recall/retain 无需 Agent 思考即可发生；但作用域限于单个工具，且需逐工具配置。
• Omnigent 记忆工具：一份中心化配置即可横跨所有被编排的 harness，但由 Agent 驱动——Agent 依据系统指令显式调用。

简单判断规则：单独运行某个工具时，优先使用该工具的原生集成；通过 Omnigent 编排多个 harness 并希望它们共享同一份记忆、同一套配置时，使用 Omnigent 的记忆工具。

常见问题

Omnigent 会自动调用 recall 和 retain 吗？不会。Agent 在系统指令指示时才调用这些工具，行为透明可审计。

两个 Agent 能共享一个 Bank 吗？可以。在两个 Agent 的工具配置中设置相同的bank_id，它们读写同一存储；一个 Agent retain 的事实，另一个 Agent 在 recall 时即可获得。

切换 harness 后记忆还在吗？在。Bank 存放在 Hindsight 中而非 harness 中。把 Omnigent 的 Agent 从 Codex 切换到 Claude Code，Bank 原封不动。

hindsight_reflect能做什么而hindsight_recall不能？Recall 检索与特定查询相关的记忆；Reflect 跨累积观测综合推理，适合获取"Agent 在多轮会话中学到了什么"的总结，而非仅匹配单条查询的事实。Reflect 还支持通过response_schema输出结构化结果，并可返回其生成答案所依据的底层事实。

能否把 recall 过滤到特定主题或用户？可以。recall_tags与recall_tags_match配置字段过滤参与回忆的记忆；在hindsight_retain上设置tags标记存储内容，在hindsight_recall上设置recall_tags只取回匹配标签的记忆。当一个 Bank 服务多个用户或项目时非常有用。

延伸阅读

• 让多个 Agent 指向同一 Bank，实现"一份记忆覆盖所有 AI 工具"：见 one-memory-for-every-ai-tool 相关讨论；
• Agent 调用hindsight_retain时底层发生了什么，以及 Bank 应如何划分（recall 边界、标签 vs 独立 Bank），可深入 Bank 策略指南；
• 本集成的官方文档页：docs-integrations/omnigent.md；
• 若在 Omnigent 中运行 Claude Code，可参考 Claude Code 的共享记忆配置方式（见 hindsight-docs 下的 Claude Code 集成文档）；
• 底层hindsight-client的完整 API 参考：Python 客户端。

【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight