Hindsight 与 OMO 集成实战：为 oh-my-openagent 智能体接入跨会话长期记忆

Hindsight 与 OMO 集成实战为 oh-my-openagent 智能体接入跨会话长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文围绕 Hindsight 官方发布的 OMOoh-my-openagent集成changelog 记录于 skills/hindsight-docs/references/changelog/integrations/omo.md完整讲解该集成的安装部署、五个生命周期钩子的工作机理、全部配置项与优先级规则并结合仓库源码hindsight-integrations/omo深入剖析 recall / retain 的执行链路。读完本文你将能够独立为 OMO 智能体接入 Hindsight 长期记忆自动在每次提示前召回相关上下文、在会话结束后沉淀学习成果并针对多项目隔离、多记忆库召回等场景完成进阶配置。一、集成背景OMO Changelog 0.1.0 带来了什么在 OMO Integration Changelog 中Hindsight 官方记录了该集成的首个版本0.1.0新增了一个面向Oh-My-OpenAgentOMO的 Hindsight 集成提供了一整套hooks钩子与 scripts脚本用于在会话之间保留retain与召回recall记忆该版本由 dcbouius 贡献对应提交为6dc56498。这份 changelog 本身只有一条 Feature 记录但它在仓库中对应的实现却是完整可用的集成目录 hindsight-integrations/omo 下包含 README、hooks 配置、5 个入口脚本、4 个公共库模块、规则文件、demo 与测试用例。本文后续内容即围绕这套真实实现展开使 changelog 中跨会话记忆这一句话落地为可操作的技术细节。二、集成架构与工作流程OMO 集成的设计目标很明确让 OMO 智能体在每次提示前自动召回相关历史记忆注入上下文并在会话中/会话结束时把对话沉淀进 Hindsight 记忆库。整体数据流如下见 README 中的架构图OMO (orchestrator) ├── SessionStart hook → health check健康检查 ├── UserPromptSubmit hook → recall memories → inject as additionalContext ├── Stop hook → retain session transcript (async)异步保留对话 ├── SubagentStop hook → retain sub-agent findings (async)异步保留子智能体结论 └── SessionEnd hook → force final retain强制最终保留这一架构由 hooks/hooks.json 落地实现五个钩子事件与行为对应关系如下Hook 事件触发时机动作SessionStart会话开始健康检查若缺失 API Key 则给出警告UserPromptSubmit每次用户提示前向 Hindsight 查询相关记忆注入为上下文Stop智能体完成提取对话记录异步发送给 Hindsight 做事实提取SubagentStop子智能体完成与 Stop 相同——捕获子智能体的学习成果SessionEnd会话终止对短会话强制执行最终 retain在 hooks/hooks.json 中可以看到每个钩子均通过command类型执行对应 Python 脚本并设置了差异化的超时与异步策略UserPromptSubmit超时 45 秒召回需要等待远端结果注入Stop/SubagentStop超时 15 秒且标记async: true异步执行避免阻塞SessionEnd超时 10 秒。命令统一写作python3 ${PLUGIN_ROOT}/scripts/xxx.py || python ${PLUGIN_ROOT}/scripts/xxx.py通过||回退兼容仅安装python命令的环境。降级设计所有钩子都以优雅降级为原则——如果 Hindsight 服务不可达OMO 继续正常工作只是没有记忆功能。这一点在脚本实现中被反复强化详见下文源码分析。三、安装与部署1. 获取 API Key前往 Hindsight 云服务注册并创建 API Key形如hsk_...。2. 安装集成文件从仓库的hindsight-integrations/omo/目录执行安装详见 README# Hooks全局 mkdir -p ~/.omo/hooks cp hooks/hooks.json ~/.omo/hooks/hindsight-hooks.json # Scripts settings全局 mkdir -p ~/.omo/plugins/hindsight/scripts cp -r scripts/ ~/.omo/plugins/hindsight/scripts/ cp settings.json ~/.omo/plugins/hindsight/settings.json # Rules按项目安装 —— 在项目根目录执行 mkdir -p /path/to/your/project/.omo/rules cp rules/hindsight-memory.md /path/to/your/project/.omo/rules/hindsight-memory.md安装说明中体现了集成的三层结构hooks全局注册到~/.omo/hooks/让 OMO 在五个生命周期事件上调用 Hindsight 脚本scripts settings全局插件本体${PLUGIN_ROOT}指向~/.omo/plugins/hindsight/rules按项目项目级规则文件指导智能体何时使用记忆工具。3. 设置 API Keyexport HINDSIGHT_API_TOKENhsk_your_key_here或持久化写入~/.hindsight/omo.json{ hindsightApiToken: hsk_your_key_here }4. 在 OMO 配置中放行环境变量在~/.config/opencode/oh-my-openagent.jsonc中{ mcp_env_allowlist: [ HINDSIGHT_API_URL, HINDSIGHT_API_TOKEN, HINDSIGHT_BANK_ID ] }完成以上四步后启动 OMO记忆功能即自动生效。5. 自托管模式可选若使用自托管的 Hindsight 实例通过环境变量覆盖 API 地址export HINDSIGHT_API_URLhttp://localhost:8888或写入~/.hindsight/omo.json{ hindsightApiUrl: http://localhost:8888, hindsightApiToken: null }本地实例无需 API Token。从源码看HindsightClientscripts/lib/client.py会校验 API URL 必须为http/https协议且包含主机名否则抛出ValueErrorrecall.py与retain.py中还有一条兜底逻辑——当 API 地址包含api.hindsight.vectorize.io即云模式但未配置 Token 时直接静默跳过避免在未认证状态下反复报错。四、配置体系三级优先级与完整参数表1. 配置加载顺序配置按以下顺序加载后者覆盖前者见 scripts/lib/config.py 中load_config()的实现内置默认值云 URL 预置定义于DEFAULTS字典插件默认settings.json${PLUGIN_ROOT}/settings.json即安装到~/.omo/plugins/hindsight/settings.json的文件用户配置~/.hindsight/omo.json稳定、与版本无关HINDSIGHT_*环境变量最高优先级。环境变量映射表在 scripts/lib/config.py 的ENV_OVERRIDES中定义且做了类型转换_cast_env布尔值接受true/1/yes整数直接int()转换失败则忽略该变量。配置文件中值为null的键不会覆盖既有值_load_settings_file中if v is not None过滤。2. 关键配置参数官方 README 给出的核心参数表如下配置项环境变量默认值说明hindsightApiUrlHINDSIGHT_API_URLhttps://api.hindsight.vectorize.ioAPI 端点hindsightApiTokenHINDSIGHT_API_TOKEN—API Keyhsk_...云模式必需bankIdHINDSIGHT_BANK_IDomo记忆库名称autoRecallHINDSIGHT_AUTO_RECALLtrue提示前自动召回autoRetainHINDSIGHT_AUTO_RETAINtrue响应后自动保留retainEveryNTurns—10保留频率轮次recallBudgetHINDSIGHT_RECALL_BUDGETmid召回深度low/mid/highdynamicBankIdHINDSIGHT_DYNAMIC_BANK_IDfalse按项目隔离记忆库debugHINDSIGHT_DEBUGfalse向 stderr 输出调试日志3. 完整默认配置settings.json 提供了比 README 更完整的默认配置可作为自定义配置的基线模板。除上表参数外还包括召回相关recallMaxTokens: 1024召回结果的最大 token 数、recallTypes: [world, experience]召回的事实类型、recallContextTurns: 1召回时纳入的上下文轮数、recallMaxQueryChars: 800查询文本截断长度、recallRoles: [user, assistant]参与构造查询的角色、recallPromptPreamble注入上下文时的引导语提示模型优先采纳近期记忆、只使用直接有用的记忆保留相关retainMode: full-session保留模式可选chunked分块模式、retainOverlapTurns: 2分块模式的重叠轮数、retainToolCalls: false是否保留工具调用、retainContext: omo、retainTags: [{session_id}]支持模板变量的标签、retainMetadata: {}银行相关bankMission与retainMission记忆库使命设定用于指导事实提取详见下文、bankIdPrefix: 、dynamicBankGranularity: [agent, project]、resolveWorktrees: true、directoryBankMap: {}连接requestTimeoutSeconds: null全局请求超时覆盖。其中bankMission与retainMission的默认文案值得关注settings.jsonbankMissionYou are an OMO (oh-my-openagent) orchestrator. Focus on technical discussions, decisions, architectural context, and coding patterns relevant to the users projects.retainMissionExtract technical decisions, architectural choices, user preferences, project context, debugging insights, and tool/library relationships. Ignore routine greetings and transient operational details.它们通过 scripts/lib/bank.py 的ensure_bank_mission()在首次使用时调用client.set_bank_mission()对应 APIPATCH /v1/default/banks/{bank}/config设置reflect_mission与retain_mission写入记忆库且已设置的银行会记录在本地状态bank_missions.json中避免重复调用。4. 动态记忆库 ID多项目隔离启用按项目隔离{ dynamicBankId: true, dynamicBankGranularity: [agent, project] }这会产生形如omo::myproject、omo::other-repo的记忆库。从 scripts/lib/bank.py 的derive_bank_id()源码看记忆库 ID 的解析顺序为directoryBankMap显式映射cwd精确匹配映射中的目录时直接返回对应银行 ID支持bankIdPrefix前缀静态模式dynamicBankIdfalse使用单一bankId默认omo动态模式dynamicBankIdtrue按dynamicBankGranularity字段组合生成合法字段为agent、project、session、channel、user用::连接其中project通过_resolve_project_name()解析——当resolveWorktrees开启时会调用git rev-parse --path-formatabsolute --git-common-dir识别 git worktree 并统一映射到主仓库名使同一仓库的所有 worktree 共享记忆库。5. 多记忆库召回在召回主记忆库之外可附加查询其他记忆库{ recallAdditionalBanks: [shared-team-knowledge] }在 scripts/recall.py 中主库召回结果会与每个附加库的召回结果合并results results extra_results任一附加库失败只记录 debug 日志不影响主流程。五、源码级解析五个钩子脚本的执行链路1.SessionStart健康检查session_start.py会话开始时执行一次。逻辑要点若autoRecall与autoRetain均关闭则直接跳过云模式API URL 含api.hindsight.vectorize.io下未配置 Token 时向 stderr 打印警告Using Hindsight Cloud but no API key set...否则构造HindsightClient并调用health_check(timeout3)GET/health返回 200 即视为可达任何异常均被捕获main()最终sys.exit(0)——绝不因健康检查失败阻断会话启动。2.UserPromptSubmit自动召回recall.py这是集成的核心路径每次用户提示前执行autoRecall关闭则直接退出从 stdin 读取 OMO 钩子输入 JSON提取prompt或user_prompt长度不足 5 个字符则跳过避免琐碎输入触发召回构造HindsightClientderive_bank_id()推导记忆库ensure_bank_mission()确保使命已写入查询构造默认recallContextTurns1时直接用当前 prompt 作为查询大于 1 时读取钩子输入中的transcript_pathJSONL 对话记录通过compose_recall_query()把最近若干轮user/assistant消息与当前 prompt 组合成上下文查询再用truncate_recall_query()截断到recallMaxQueryChars默认 800 字符发起召回调用client.recall()对应 APIPOST /v1/default/banks/{bank}/memories/recall携带query、max_tokens、budget、types参数超时 10 秒多库合并遍历recallAdditionalBanks执行附加召回并合并结果注入上下文把召回结果格式化为hindsight_memories.../hindsight_memories包裹的消息块包含recallPromptPreamble引导语与当前时间写入状态文件last_recall.json最后以hookSpecificOutput.additionalContext的形式输出到 stdoutOMO 会将其作为额外上下文注入本次提示。注意其异常处理策略召回失败只打印[Hindsight] Recall failed到 stderr 并返回不注入任何内容脚本末尾的兜底异常处理器在debug模式下退出码为 2、否则为 0——始终不阻断 OMO 主流程。3.Stop/SubagentStop异步保留retain.pyStop与SubagentStop共用retain.py由 hooks.json 配置为async: true异步执行。核心流程autoRetain关闭则退出读取钩子输入中的session_id与transcript_path轮次控制retainEveryNTurns 1且非强制forceFalse时通过increment_turn_count(session_id)计数仅当计数整除retainEveryNTurns才执行保留保留模式retainModechunked且轮次间隔大于 1 时用slice_last_turns_by_user_boundary()按用户消息边界截取最近retainEveryNTurns retainOverlapTurns轮默认 12 轮重叠 2 轮实现滑动窗口式分块保留默认full-session模式则保留全部消息转录格式化prepare_retention_transcript()按retainRoles默认 user/assistant过滤消息retainToolCalls控制是否包含工具调用文档 ID 策略分块模式生成{session_id}-{毫秒时间戳}完整模式通过track_retention()跟踪分块序号生成{session_id}或{session_id}-c{chunk_index}并检测到 transcript 收缩compaction时自动推进分块序号避免覆盖已有文档标签与元数据retainTags支持模板变量{session_id}、{bank_id}、{timestamp}、{user_id}_resolve_template替换值为空的key:形式标签会被过滤retainMetadata同样支持模板替换并自动附加retained_at、message_count、session_id发起保留调用client.retain()对应 APIPOST /v1/default/banks/{bank}/memories携带content、document_id、context默认omo、metadata、tags请求体async: true服务端异步处理事实提取。4.SessionEnd强制最终保留session_end.py会话终止时执行解决短会话问题如果会话轮次不足retainEveryNTurns常规保留永远不会触发导致学习成果丢失。session_end.py在autoRetain开启且存在transcript_path时以forceTrue调用run_retain()强制跳过轮次计数条件完成最终保留。retain.py中force参数直接绕过了retain_every_n的取模判断确保短会话也能落库。5. 公共库模块scripts/lib/config.py默认值、环境变量映射与加载合并逻辑上文已述scripts/lib/client.py纯标准库urllib实现的 HTTP 客户端无第三方依赖包含 URL 校验、Authorization: Bearer头、User-Agent: hindsight-omo/0.1.0、health_check/recall/retain/set_bank_mission四个方法request_timeout_override可在全局覆盖所有请求超时scripts/lib/bank.py记忆库 ID 推导目录映射 → 静态 → 动态与使命写入scripts/lib/state.py轮次计数、保留分块跟踪、last_recall.json/bank_missions.json等本地状态读写scripts/lib/content.py召回查询组合、转录格式化、记忆格式化等文本处理。六、项目规则文件指导智能体何时使用记忆安装步骤第 2 步中按项目复制了 rules/hindsight-memory.md这是一份alwaysApply: true的规则文件指导 OMO 智能体正确使用记忆能力何时召回开始非平凡任务前从用户请求提取 3–5 个关键术语搜索既往解决方案、调试洞察或架构决策琐碎任务错别字修复、简单问答不召回何时保留完成重要工作后存储可能复现的问题解决方案、关键架构决策及理由、用户偏好、难以发现的调试洞察不保留琐碎修改、应用代码已在 git 中跟踪与敏感数据API Key、凭据、密钥何时反思当用户要求跨主题综合或需要对大量记忆进行模式推理时使用reflect工具。七、测试与验证集成自带完整的单元测试目录 hindsight-integrations/omo/tests# 运行单元测试 cd hindsight-integrations/omo pip install pytest python -m pytest tests/ -v # 针对本地 Hindsight 服务器运行交互式 demo HINDSIGHT_API_URLhttp://localhost:8888 python demo.py测试覆盖了 test_bank.py记忆库 ID 推导与使命管理、test_config.py配置加载优先级与环境变量覆盖、test_hooks.py钩子输入处理等关键模块可用于验证配置合并逻辑与银行解析规则是否符合预期。八、总结OMO 集成0.1.0见 changelog是 Hindsight 生态中为 Agent 提供长期记忆的又一个落地案例。它的核心价值可以概括为三点全生命周期覆盖通过SessionStart、UserPromptSubmit、Stop、SubagentStop、SessionEnd五个钩子实现会话开始检查 → 每次提示前召回 → 会话中/子代理完成后保留 → 会话结束强制落库的闭环零侵入的优雅降级所有脚本都以绝不阻断 OMO 主流程为底线Hindsight 不可用时记忆静默失效不影响智能体正常工作灵活可配三级配置优先级、动态记忆库隔离、多记忆库召回、分块保留与标签模板等机制使其既能开箱即用也能适应多项目、多用户的复杂部署场景。对于想要为 OMO 智能体补上跨会话连续性的开发者按照本文第三节的安装步骤操作即可快速接入如需进一步定制可对照 settings.json 与 scripts/lib/config.py 调整参数并借助单元测试验证配置行为。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考