Hindsight × OpenAI Codex CLI 集成实践：用三个 Hooks 为编码 Agent 装配长期记忆

Hindsight × OpenAI Codex CLI 集成实践用三个 Hooks 为编码 Agent 装配长期记忆【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight本文基于 Hindsight 仓库中 hindsight-integrations/codex/README.md 及配套源码讲解如何为 OpenAI Codex CLI 接入长期记忆通过SessionStart、UserPromptSubmit、Stop三个 Codex hooks 分别完成服务预热、记忆召回注入与会话留存读完后你将掌握安装步骤、完整配置项含义、Cloud 与本地 daemon 两种接入模式以及召回/留存钩子的源码级工作机制与排障方法。一、集成架构三个 Hook 各司其职Hindsight 对 Codex CLI 的集成核心是三个自动化 hook它们由 Codex 在会话生命周期中自动触发无需人工干预即可保持记忆同步Hook动作对应脚本超时秒SessionStart在后台预热 Hindsight 服务session_start.py5UserPromptSubmit召回相关记忆并注入上下文recall.py45Stop将会话内容留存到长期记忆retain.py30hook 定义见 hooks.json其中每条命令形如python3 __SCRIPTS_DIR__/recall.py安装器会把__SCRIPTS_DIR__占位符替换为脚本的绝对路径后写入~/.codex/hooks.json。三个脚本的超时预算各不相同SessionStart只有 5 秒只做健康检查和后台预启动recall.py拿到 45 秒因为召回要等待记忆检索retain.py为 30 秒。三个脚本共同的健壮性设计是优雅降级从源码 docstring 看recall.py与retain.py的退出码约定为 0 — always (graceful degradation on any error)任何异常只向 stderr 打印[Hindsight]前缀的错误信息不会打断 Codex 主流程见 recall.py 与 retain.py 的__main__块。二、前置要求按 README.md 的要求OpenAI Codex CLIv0.116.0 或更高版本需要 hooks 支持Python 3.9用于运行 hook 脚本Hindsight 服务端Hindsight Cloud 或本地hindsight-embeddaemon 二选一。三、安装与卸载官方提供的一键安装命令curl -fsSL https://hindsight.vectorize.io/get-codex | bash安装器完成三件事下载脚本到~/.hindsight/codex/scripts/写入~/.codex/hooks.json指向脚本的绝对路径在~/.codex/config.toml中添加codex_hooks true位于[features]段落下见文末排障部分。同时默认配置会写入~/.hindsight/codex/settings.json仓库中的 settings.json 即为该默认配置当前版本为0.3.1。卸载curl -fsSL https://hindsight.vectorize.io/get-codex | bash -s -- --uninstall四、配置体系四层加载顺序配置加载逻辑实现在 lib/config.py 的load_config()中其 docstring 明确了加载顺序后者覆盖前者内置默认值DEFAULTS字典插件安装配置~/.hindsight/codex/settings.json由安装器写入升级时会被覆盖用户个人配置~/.hindsight/codex.json推荐的覆盖位置跨升级稳定环境变量覆盖。个人覆盖示例创建~/.hindsight/codex.json{ hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: your-api-key, bankId: my-codex-memory }环境变量覆盖在ENV_OVERRIDES中完整注册比 README 列出的更多例如还有HINDSIGHT_AGENT_NAME、HINDSIGHT_AUTO_RECALL、HINDSIGHT_AUTO_RETAIN、HINDSIGHT_RETAIN_MODE、HINDSIGHT_RECALL_BUDGET、HINDSIGHT_RECALL_MAX_TOKENS、HINDSIGHT_RECALL_MAX_QUERY_CHARS、HINDSIGHT_RECALL_CONTEXT_TURNS、HINDSIGHT_API_PORT、HINDSIGHT_DAEMON_IDLE_TIMEOUT、HINDSIGHT_EMBED_VERSION、HINDSIGHT_DYNAMIC_BANK_ID、HINDSIGHT_BANK_MISSION、HINDSIGHT_LLM_PROVIDER、HINDSIGHT_LLM_MODEL等。常用示例export HINDSIGHT_API_URLhttps://api.hindsight.vectorize.io export HINDSIGHT_API_TOKENyour-api-key export HINDSIGHT_BANK_IDmy-project export HINDSIGHT_RECALL_TIMEOUT30 export HINDSIGHT_DEBUGtrue布尔型环境变量按true/1/yes不区分大小写解析为True非法的数值/布尔值会被静默忽略并回落到文件配置。五、完整配置项说明README 的核心配置表如下并补充了 settings.json 中暴露但 README 未列全的字段标注补充键默认值说明hindsightApiUrl外部 API 地址留空则使用本地 daemonhindsightApiTokennullHindsight Cloud 的 API tokenbankIdcodex记忆库标识bankMission(set)引导 Hindsight 应留存哪些事实。默认值You are a Codex AI coding assistant. Focus on technical decisions, code changes, debugging sessions, and project context relevant to the users work.retainMission同bankMission补充更细粒度的留存指令。默认值Extract technical decisions, code patterns, debugging solutions, user preferences, project context, and architectural choices. Ignore routine greetings and transient operational details.autoRecalltrue每个 prompt 前注入记忆autoRetaintrue每轮结束后存储会话retainModefull-sessionfull-session或chunkedretainEveryNTurns10每 N 轮留存一次1 每轮recallBudgetmid召回深度low/mid/highrecallMaxTokens1024注入记忆的最大 token 数recallMinScores{}召回后的分数下限按分数字段键控如{semantic: 0.65, reranker: 0.2}。缺失或null的分数放行以免误杀仅 BM25 命中和透传重排器的结果当 cross-encoder 重排器激活时reranker下限是主要精度闸门且 reranker 分数是查询局部的不宜跨查询校准recallTimeout10召回 API 调用超时秒dynamicBankIdfalse按项目/会话分离记忆库dynamicBankGranularity[agent, project]动态 bank ID 的组成字段debugfalse向 stderr 输出调试信息recallTypes[world, experience]补充召回的记忆类型过滤recallContextTurns1补充召回查询携带的上下文轮数1 时从 transcript 组合多轮查询recallMaxQueryChars800补充召回查询字符上限recallRoles[user, assistant]补充参与召回查询的角色recallPromptPreamble(set)补充注入记忆的引导语默认提示冲突时优先近期记忆只使用对继续本对话直接有用的记忆retainToolCallstrue补充留存时是否包含工具调用retainRoles[user, assistant]补充留存的角色过滤retainOverlapTurns2补充chunked 模式下窗口外的重叠轮数retainTags[{session_id}]补充标签模板支持{session_id}、{bank_id}、{timestamp}变量retainMetadata{}补充附加元数据值同样支持模板变量retainContextcodex补充留存上下文标识apiPort9077补充本地 daemon 端口embedVersionlatest补充hindsight-embed包版本可用embedPackagePath指向本地源码目录agentNamecodex补充动态 bank 中的 agent 维度值可用HINDSIGHT_AGENT_NAME覆盖llmProvider/llmModel/llmApiKeyEnvnull补充本地 daemon 模式下的 LLM 显式配置为null时自动探测upgradeNoticetrue补充会话开始时的升级提示开关六、两种接入模式Cloud 与本地 daemonHindsight Cloud推荐无需自托管、无需 LLM API key、无需管理 daemon{ hindsightApiUrl: https://api.hindsight.vectorize.io, hindsightApiToken: your-api-key }自托管本地 daemonhindsight-embed把hindsightApiUrl留空并设置一个 LLM API keyHindsight 会自动启动本地服务器export OPENAI_API_KEYsk-your-key # 或 export ANTHROPIC_API_KEYyour-key从 lib/daemon.py 的get_api_url()看连接解析遵循三级优先级外部 API配置了hindsightApiUrl时直接使用完全跳过 daemon已有本地服务对http://127.0.0.1:{apiPort}默认 9077的/health做健康检查存活则复用自动托管 daemon仅当调用方允许启动时retain 钩子允许recall 钩子不允许通过uvx hindsight-embedversion或uv run指向embedPackagePath执行profile create codex --merge --port port配置画像再daemon --profile codex start启动并以最多 30 次每秒一轮的健康探测等待就绪。源码中还有一处值得注意的细节健康检查超时默认为 10 秒与 recall 钩子预算一致——注释解释这是为了避免繁忙但存活的 daemon正处于事实提取中被误判为死亡进而触发杀进程重启的死循环。SessionStart钩子则在服务不可达时调用prestart_daemon_background()以Popen(..., start_new_sessionTrue)完全非阻塞地在后台拉起 daemon确保首个 recall/retain 触发时服务已就绪见 session_start.py。在 macOS 上还会额外注入HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU1与HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU1环境变量。七、Recall 钩子记忆如何进入上下文recall.py绑定UserPromptSubmit的完整流程见 recall.py 头部 docstring 与实现从 stdin 读取 hook 输入session_id、transcript_path、prompt/user_prompt若autoRecall为false直接退出prompt 少于 5 个字符也跳过解析 API URL此时不允许启动 daemonallow_daemon_startFalse推导 bank ID 并确保 bank mission 已设置首次使用时调用set_bank_mission结果记录在~/.hindsight/codex/state/bank_missions.json中避免重复写入见 lib/bank.py若recallContextTurns 1读取 transcript 组合多轮查询否则直接用当前 prompt查询统一截断到recallMaxQueryChars调用client.recall(bank_id, query, max_tokens, budget, types, timeout)用recallMinScores过滤结果——实现采用fail-open策略分数缺失或为null的结果放行只有数值明确低于下限才丢弃filter_by_min_scores()recall.py将记忆格式化为hindsight_memories.../hindsight_memories包裹的上下文块含recallPromptPreamble与当前时间并通过 stdout 输出{ hookSpecificOutput: { hookEventName: UserPromptSubmit, additionalContext: hindsight_memories.../hindsight_memories } }这是 Codex hook 协议将内容注入模型上下文的标准方式。同时每次成功召回都会把本次注入内容、bank ID、结果数与时间戳写入last_recall.json状态文件便于排查。八、Retain 钩子会话如何变成记忆retain.py绑定Stop即每轮 agent 回复后流程见 retain.py读取完整 transcript受retainToolCalls、retainRoles过滤留存节流retainEveryNTurns 1时按会话维护轮次计数increment_turn_count(session_id)只有轮数是 N 的整数倍才触发否则日志记录 Turn X/N, skipping retain窗口选择full-session默认每次把整个会话作为一篇文档 upsert——document ID 直接用session_id因此同一会话反复留存是幂等的覆盖更新chunked只取最近retainEveryNTurns retainOverlapTurns轮按 user 边界切分document ID 为{session_id}-{毫秒时间戳}每个片段成为独立文档组装元数据retained_at、message_count、session_id再合并retainMetadata标签与元数据值支持{session_id}、{bank_id}、{timestamp}三个模板变量调用client.retain(bank_id, content, document_id, context, metadata, tags, timeout15)。记忆引擎侧随后从对话中提取事实、关系与经验这就是 README 中 How memory works 所述的效果你无需在每个新会话中重新解释自己的技术栈、偏好与历史决策。九、动态 Bank ID按项目隔离记忆开启动态 bank 后不同项目的记忆互不干扰{ dynamicBankId: true, dynamicBankGranularity: [agent, project] }lib/bank.py 的derive_bank_id()会用::连接各粒度字段例如codex::my-project。可选字段共四个agent取agentName默认codex、project取工作目录cwd的 basename、sessionhook 输入的session_id、user环境变量HINDSIGHT_USER_ID缺省为anonymous。README 所述自动创建codex::my-project这样的 bank使用工作目录名即project字段的os.path.basename(cwd)逻辑。无效的粒度字段会向 stderr 打印告警并回落到unknown。非动态模式下bankIdPrefix可加静态前缀。十、排障记忆不出现开启debug: true查看 stderr 中[Hindsight]前缀日志如 No memories found、Score floors dropped X/Y results。服务未启动配置hindsightApiUrl指向外部服务本地 daemon 模式则确保uvx在 PATH 上_is_embed_available()同时接受hindsight-embed在 PATH。Hooks 不触发确认~/.codex/config.toml的[features]段落下有codex_hooks true且 Codex CLI 版本 ≥ v0.116.0。另有一个通用调试技巧recall.py/retain.py在debug开启时遇到未捕获异常会以退出码 2 结束正常路径恒为 0可在 hook 配置层据此感知失败。参考文件集成文档hindsight-integrations/codex/README.mdHook 定义hindsight-integrations/codex/hooks/hooks.json默认配置hindsight-integrations/codex/settings.json钩子脚本recall.py、retain.py、session_start.py核心库lib/config.py、lib/daemon.py、lib/bank.py测试tests/test_hooks.py、tests/test_bank.py、tests/test_client.py【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考