Hindsight 多仓库记忆银行实战Codex 动态银行 ID 配置、源码机制与验证闭环【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight让 Codex CLI 在订单服务里修一个查询 bug注入进上下文却冒出隔壁前端项目的 pnpm lint 约定——每条记忆都真实但全部来自错误的仓库。这就是多仓库共用一个 Hindsight 记忆银行时最典型的翻车现场。Hindsight 是面向 Agent 的长期记忆系统记忆银行 Bank 是其核心隔离单元本文从 Codex 集成插件的源码出发讲清如何用动态银行 ID 实现「一仓库一银行」团队规范又该放哪以及隔离是否生效的验证方法。1. 心智模型银行是一道数据隔离墙Hindsight 的所有写入retain与读取recall都限定在单个银行内部数据不会跨银行流动——这是整套布局策略成立的前提。默认配置下所有 Codex 会话共用名为codex的银行把dynamicBankId打开后银行 ID 不再由你手写而是运行时根据「代理名 工作目录名」自动派生如codex::orders不同仓库自然落进不同银行。布局上只有两种选择全单银行所有项目混在一起召回时无关内容互相竞争预算多银行按仓库自动分库另可加一个固定的共享银行承载跨仓库规范。本文推荐第二种且日常开发永远走动态派生。2. 三步配置让每个仓库拥有独立记忆银行第 1 步装好 Codex 钩子。按 Codex 集成 README 运行官方一键安装脚本要求 Codex CLI v0.116.0 以支持 hooksPython 3.9。安装器做三件事把钩子脚本落到~/.hindsight/codex/scripts/、写入~/.codex/hooks.json指向脚本的绝对路径、在~/.codex/config.toml打开codex_hooks true。第 2 步准备后端。接 Hindsight Cloud填hindsightApiUrl与hindsightApiToken或自托管pip install hindsight-api起服务或用 docker/docker-compose/ 下的编排文件。银行策略与后端无关两种方式效果一致。第 3 步开启按仓库分库。新建~/.hindsight/codex.json这是官方推荐的落配置的位置跨插件升级不丢{ dynamicBankId: true, dynamicBankGranularity: [agent, project] }几个影响体感的默认值均出自插件安装时写入的 settings.json 与内置 DEFAULTSbankId缺省codex、dynamicBankId缺省false、dynamicBankGranularity缺省[agent, project]、retainMode缺省full-session、retainEveryNTurns缺省10、recallBudget缺省mid、recallTimeout缺省 10 秒。不想碰配置文件时也可以全部用环境变量切换如HINDSIGHT_DYNAMIC_BANK_IDtrue、HINDSIGHT_AGENT_NAMEmyagent、HINDSIGHT_RECALL_TIMEOUT30完整映射见 config.py 中的ENV_OVERRIDES。3. ⚙️ 机制拆解银行 ID 是怎么拼出来的派生逻辑先静态后动态从源码 bank.py 的derive_bank_id可以看到两条路径静态模式dynamicBankId: false直接返回bankId配置值未配置则回落到codex若设置了bankIdPrefix拼成前缀-bankId。动态模式取dynamicBankGranularity列出的字段逐段求值后用::连接。Codex 支持的字段只有四个VALID_FIELDSagent配置项agentName缺省codex、projectcwd的目录基名空目录得unknown、session钩子输入的会话 ID、user环境变量HINDSIGHT_USER_ID未设得anonymous。注意源码里刻意省略了 channel 维度——Codex 是纯 CLI 工具不存在 Telegram/Discord 式多通道路由这个维度没有意义。对照 test_bank.py 可以确认边界行为agentNamemybot且 cwd 为/home/user/hindsight时派生出mybot::hindsight目录名含空格或 UTF-8测试里用了西里尔字母目录时原样保留不做 URL 编码cwd 为空时对应段是unknown。写进dynamicBankGranularity的非法字段不会中断流程只往 stderr 打一条警告。配置的加载顺序config.py 的load_config按四层合并、后写覆盖前写内置默认值 → 安装器写入的~/.hindsight/codex/settings.json→ 用户配置~/.hindsight/codex.json→ 环境变量覆盖。排障时记住这一点环境变量永远赢配置文件里改了的值可能被HINDSIGHT_*悄悄盖掉。三个触发点与失败降级hooks/hooks.json 注册了三个生命周期钩子超时各不相同钩子脚本超时动作SessionStartsession_start.py5s探活 Hindsight 服务器连不上就后台预启动本地 daemonUserPromptSubmitrecall.py45s召回相关记忆并注入上下文Stopretain.py30s把会话 transcript 写入长期记忆recall.py 的链路读 stdin 钩子输入 → prompt 不足 5 字符直接跳过 → 解析 API 地址注意此处不允许顺带拉起 daemon服务器没起来就安静退出→ 派生银行 ID 并补写 mission →recallContextTurns 1时读 transcript 组装多轮查询 → 按recallMaxQueryChars默认 800截断 → 调 recall默认 10 秒超时→ 结果过recallMinScores地板过滤缺失分数放行即 BM25-only 命中不会被误杀→ 用hindsight_memories包裹经hookSpecificOutput.additionalContext注入。无论发生什么异常退出码恒为 0——记忆系统故障永不阻塞你的对话。retain.py 的链路读 transcript → 按retainEveryNTurns做门控用本地 turn 计数器取模不满 N 轮直接跳过→chunked模式按N retainOverlapTurns取重叠窗口 → 组装 transcript → 派生银行 ID → 调 retain。文档 ID 默认取session_id同一会话重复 retain 是 upsert 而非新增chunked模式才追加毫秒时间戳区分文档。retainTags/retainMetadata支持{session_id}、{bank_id}、{timestamp}三个模板变量。另外bankMission只在银行首次使用时写入一次本地状态文件bank_missions.json记录已设置名单超过 1 万条自动裁半避免每次钩子都发一次写请求。4. 该往银行里放什么内容取舍分库的收益取决于库里存了什么。默认retainMode: full-session会在会话收尾时 retain 整份 transcript由 Hindsight 负责抽取事实——你不需要手动写记忆只需要让「值得说的内容」在会话里被说出来。回报最高的是四类仓库约定这个项目的真实规则。例如「SQL 统一走 sqlc 模板生成禁止 ORM 层」「前端包管理只用 pnpm Turborepo不手写 npm scripts」。每次新会话都要重新解释一遍的东西就该沉淀。已知脆弱区以反直觉方式坏掉的地方。例如「staging 重跑迁移前必须手动执行 0042 补丁脚本」「webhook 消费端上游有 3 秒超时重试逻辑必须幂等」。一条「内有恶龙」的备注能拦住 Codex 用踩坑的方式重新撞一遍。历史排障根因故事比修复动作更值钱。例如「网关 502 的根因是空闲连接耗尽调大 max_idle_conns 后解决」——复发性问题回来时一次召回就抵得上一轮完整 debug。工程决策为什么重试要指数退避、为什么消息队列选了 NATS 而不是 Kafka。决策从 diff 反推成本很高召回几乎零成本。反面清单同样明确一次性命令、临时草稿、跑通即弃的实验代码不值得占用召回预算。这四类取舍的实际用途是帮你识别一次有价值的会话——约定和决策真的被讨论出来的会话才配得上被整段保留。5. 进阶跨仓库规范用固定共享银行按仓库隔离是默认但有些知识天然跨边界组织级 commit 规范、共享 CI 流水线、安全评审要求、全员依赖的内部 SDK。把这类内容塞进某个仓库的动态银行里其他仓库永远召回不到正确做法是给它们一个固定银行。在共享场景的配置里关掉动态派生、写死银行名{ dynamicBankId: false, bankId: acme-platform }指向同一bankId的银行是共享的——一位同事的 Codex 往里 retain 的平台规范另一位同事的 Codex 会话可以直接召回。实用布局由此变成两层日常开发走动态派生的按仓库银行真正跨切的标准走一个具名共享银行。别贪心把动态银行也顺手指向共享名否则第 1 章讲的隔离墙就没了全共享的单一银行只适合「个人全局习惯」这种极少数场景不适合一组异质代码库。6. ✅ 验证序列与踩坑清单一套可复现的四步验证直接检验隔离是否成立在orders仓库里让 Codex 明确说出一个决策比如「为什么订单事件用 NATS」确保它被讲清楚了结束会话让 transcript 被 retainfull-session模式下这一步发生在会话收尾在同一仓库开新会话问同样的问题——应召回第 1 步的决策在dashboard仓库开新会话问同样问题——不应冒出orders的答案。第 3 步命中、第 4 步干净说明布局正确。诊断分岔第 3 步落空时两次运行大概率派生了不同银行 ID——把HINDSIGHT_DEBUGtrue打开对照 stderr 里Retaining to bank ...的实际值第 4 步泄漏时先确认dynamicBankId真的为true再检查是否有HINDSIGHT_BANK_ID环境变量在第四层覆盖掉了你的配置。高频踩坑点按出现频率排一直不拆库bankId默认codex不开动态派生时所有仓库共享它项目一多必然噪声召回团队规范放错层跨切约定只存在于某个仓库的银行里等于不存在该去固定共享银行反向期望跨库召回隔离是严格的设计目标orders的银行天生看不到dashboard的记忆不要试图「顺便」召回会话没收尾就验证full-session模式下中途去查transcript 还没落库retainEveryNTurns缺省是 10测试期可临时设为 1 让每轮 Stop 都触发 retain测完记得改回。7. ❓ FAQ必须用 Hindsight Cloud 吗不用。自托管hindsight-api或本地hindsight-embeddaemon 行为一致银行策略与后端解耦。自托管入口见 docker/docker-compose/ 与官方文档 hindsight-docs/docs/。按仓库银行和共享银行怎么选按用途分层项目私有的约定、排障、决策进动态派生的仓库银行必须跟着你走进每个仓库的平台规范进固定共享银行。两者不冲突可以并存于不同集成配置里。仓库银行的命名规则是什么开启dynamicBankId后由dynamicBankGranularity派生默认「代理名::目录基名」如codex::orders。想区分多个人在同一仓库的记忆把user加进粒度并设HINDSIGHT_USER_ID即可。哪些内容不该 retain临时草稿、一次性命令、跑完即弃的探索。它们不产生复利却会持续稀释召回精度。结语把dynamicBankId打开Codex 的每个仓库自动拥有私有记忆再为跨仓库规范配一个具名共享银行就是多仓库工作下最稳的记忆布局。隔离、沉淀、验证三步做完记忆系统才从「能跑」变成「可信」。延伸阅读hindsight-integrations/codex/README.md——完整配置表、默认值与排障hindsight-integrations/codex/scripts/lib/bank.py 与 tests/test_bank.py——银行 ID 派生逻辑及行为断言hindsight-integrations/codex/scripts/recall.py 与 hindsight-integrations/codex/scripts/retain.py——召回与保留钩子的完整链路hindsight-integrations/codex/scripts/lib/config.py——配置加载顺序与环境变量映射需要通读全部代码时可克隆仓库git clone https://gitcode.com/GitHub_Trending/hindsight2/hindsight【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考