oh-my-pi reflect 记忆综合工具深度解析从多段长期记忆合成连贯答案的完整实现【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读reflect是 oh-my-pi⌥ Coding agent with the IDE wired incoding-agent 内置的记忆工具三件套recall/retain/reflect之一其职责是在长期记忆之上**合成synthesize**一份连贯答案与recall原样返回按相关性排序的原始记忆条目不同reflect会跨越多条存储事实进行融合提炼特别适合关于这个用户你都知道什么总结一下项目的决策这类开放性问题。本文以 reflect 工具说明 为骨架结合 memory-reflect.ts 实现、Hindsight 客户端 与 官方工具文档完整讲解其行为语义、参数契约、双后端执行流程、作用域隔离与配置调优让你既能正确使用它也能理解它在记忆子系统中的真实位置。一、reflect与recall/retain的分工oh-my-pi 的长期记忆子系统由三个工具协同构成它们共享同一套memory.backend后端配置retain把 ≥1 条持久事实写入长期记忆供未来会话使用。适用场景是用户偏好、项目决策、架构选型等可复用知识禁止存储临时任务状态每条必须具体、自包含谁、什么、何时、为什么支持批量写入与自动去重合并。详见 retain 工具说明。recall在长期记忆中做检索原样返回按相关性排序的匹配条目含截断标记truncated: true/full_length。官方提示词明确要求 Agent 在回答过往对话、用户偏好、项目决策等问题前主动优先调用 recall对返回的条目如需memory_edit update必须先用read memory://id拉取完整记录。详见 recall 工具说明。reflect合成一份连贯响应。它同样基于长期记忆但输出的是融合后的答案而非原始条目定位是开放性问题、跨多条事实的总结归纳。其模型面向的说明原文为reflect: synthesizes a coherent response from relevant long-term memories; unlikerecall, blends them. Use for open-ended questions spanning many stored facts: What do you know about this user?, Summarize project decisions., What are my preferences for X?contextoptional; focuses synthesis on a specific angle or sub-topic.一句话区分recall 是检索清单reflect 是综合结论。系统提示词hindsight backend 静态指令中也这样引导 Agent回答问题前主动 recall存储持久事实用 retain需要跨多条记忆综合答案的问题用 reflect。二、参数契约query与可选的contextreflect的入参由 memory-reflect.ts 中的 omptype schema 定义仅两个字段字段类型必填说明querystring是需要从长期记忆回答的问题contextstring否额外引导将综合聚焦到特定角度或子主题两个字段都是纯字符串schema 层面没有最小长度限制见 docs/tools/reflect.md 的 Limits Caps 一节。context的语义在后端有差异这正是理解 reflect 行为的关键Hindsight 后端context作为独立字段随 HTTP 请求体发送body.context服务端据此聚焦综合方向Mnemopi 后端context会被拼接进检索 query格式为query\n\nAdditional context:\ncontext仅当 trim 后非空随后用这个复合 query 做本地召回。工具元数据见 memory-reflect.tsname reflectapproval read只读类操作通常无需审批strict trueloadMode discoverable可被发现加载而非强制注入summary Synthesize an answer from long-term memory工具可见性reflect仅在memory.backend为hindsight或mnemopi时注册createIf 工厂后端为off、local或sharpshooter时该工具不存在。而默认后端是off见 settings-schema.ts 中 memory.backend 定义这意味着默认配置下 reflect 不可用必须显式启用后端。三、双后端执行流程Hindsight 与 Mnemopiexecute整体运行在untilAborted(signal, ...)之下支持取消随后按memory.backend分派两条路径memory-reflect.ts execute 实现。3.1 Mnemopi 路径本地召回 上下文格式化读取session.getMnemopiSessionState()若后端未初始化则抛出Mnemopi backend is not initialised for this session.若context非空构造复合 queryquery\n\nAdditional context:\ncontext否则直接用query调用state.recallResultsScoped(query)——与recall使用完全相同的本地作用域与合并逻辑若结果为空返回No relevant information found to reflect on.否则调用state.formatContextScoped(results)渲染并在前面加上Based on recalled memories:前缀。关键事实Mnemopi 的 reflect 是本地召回 格式化并不调用任何综合模型或独立合成端点。因此它的输出可能是召回的原始上下文而非真正的融合答案——这是与模型面向提示词blends them存在差异的实现边界使用本地后端时需留意docs/tools/reflect.md Notes 一节 明确指出了这一点。3.2 Hindsight 路径远程综合端点读取session.getHindsightSessionState()未初始化则抛出Hindsight backend is not initialised for this session.调用ensureBankExists(state.client, state.bankId, state.config, state.banksSet)来自 hindsight/bank.ts以 best-effort 方式对每个 bank 首次PUT /v1/default/banks/{bank_id}createBank可携带reflect_mission/retain_mission失败被静默吞掉且每个会话状态对同一 bank 只尝试一次MISSION_SET_CAP 10_000上限超出后丢弃排序集合的后半部分调用state.client.reflect(bankId, query, { context, budget: state.config.recallBudget, tags: state.recallTags, tagsMatch: state.recallTagsMatch })Hindsight 客户端的 reflect 方法 向POST /v1/default/banks/{bank_id}/reflect发送{ query, context, budget, tags, tags_match }其中budget在调用方省略时默认low但工具始终显式传入配置的recallBudget响应文本为空白/纯空白时替换为No relevant information found to reflect on.memory-reflect.ts后端失败以logger.warn(reflect failed, ...)记录并重抛为Error。Hindsight 是真正的综合路径服务端基于 bank 内容生成合成文本工具直接透传服务端结果details {}不暴露底层召回命中条目——这与 recall 返回原始条目形成鲜明对比。3.3 执行特征单次执行single-shot不发送进度更新docs/tools/reflect.md Registration 一节会话作用域读取跨会话记忆数据但不持久化任何本地输出子代理别名subagent alias沿用父级后端的 bank 作用域与配置见 hindsight backend start 中 taskDepth 0 分支取消语义工具调用信号被取消时通过untilAborted中止请求。四、Bank 作用域reflect读的是哪个记忆库reflect的输出范围受hindsight.scoping或 Mnemopi 对应配置约束决定它从哪个 bank 读数据docs/tools/reflect.md Modes / Variants 一节Hindsight bank 作用域作用域行为global无 tag 过滤读全局 bankper-project每个项目标签独立 bank idgit 主 checkout 根目录 basename非仓库内则用 cwd basenameper-project-tagged共享 bank id project:项目标签过滤tagsMatch anyMnemopi bank 作用域作用域行为global读共享 bankper-project读由 cwd basename cwd 哈希派生的 bankper-project-tagged读 cwd 派生 project bank 与共享 bank合并结果per-project 模式还可能纳入启动时发现的、cwd 匹配的安全旧 bank。作用域变化时rebuildPrimaryStateOnScopeChange 会按需重建主状态保证reflect始终命中正确的 bank。配置优先级为内置默认 设置项 环境变量见 config.ts 头注环境变量可在 CI/生产环境按 shell 临时覆盖而不改动持久化配置。五、关键配置项与调优建议reflect的运行时行为主要由以下设置项均在 settings-schema.ts 中定义与 HINDSIGHT_* 环境变量控制解析逻辑见 config.ts配置项 / 环境变量默认值对 reflect 的影响memory.backendoff必须设为hindsight或mnemopi否则 reflect 不存在hindsight.recallBudget/HINDSIGHT_RECALL_BUDGETmid综合请求的预算档位low/mid/high随请求体发送客户端默认low工具始终传配置值hindsight.reflectTimeoutMs/HINDSIGHT_REFLECT_TIMEOUT_MS120_000reflect 请求超时ms。综合是 agentic 合成比元数据抓取更昂贵默认给到 2 分钟对比 recall/request 的 30shindsight.scoping/HINDSIGHT_SCOPINGper-project-tagged决定读哪个 bank、带什么 tag 过滤非法值回退并告警hindsight.bankId/HINDSIGHT_BANK_ID无显式指定 bank idhindsight.bankIdPrefix无per-project 派生 bank id 的前缀hindsight.bankMission/HINDSIGHT_BANK_MISSION建 bank 时携带的reflect_missionbank 级服务端设置非逐请求参数mnemopi.recallLimit8Mnemopi 路径召回的条数上限运行时至少钳制为 1每条内容预览默认上限 500 字符其他相关超时hindsight.requestTimeoutMs30s、hindsight.recallTimeoutMs30s、hindsight.retainTimeoutMs60s、hindsight.recallMaxTokens1024、hindsight.recallContextTurns1、hindsight.recallMaxQueryChars800。Mnemopi 路径若配置了嵌入/LLM provider本地召回期间可能触发网络调用docs/tools/reflect.md Side Effects 一节。调优建议基于上述配置语义追求真正融合的答案 → 使用memory.backend hindsight因为只有 Hindsight 端点做服务端综合需要完全本地、无网络依赖的记忆 → 用mnemopi但要接受 reflect 输出是召回上下文 格式化综合请求耗时较长 → 保持reflectTimeoutMs默认 120s或按服务端实测延迟上调多项目混用时 → 保持scoping per-project-tagged默认让 reflect 自动限定在当前项目标签内。六、错误处理与边界行为后端未初始化抛出Mnemopi backend is not initialised for this session.或Hindsight backend is not initialised for this session.docs/tools/reflect.md Errors 一节Hindsight 网络错误HTTP、fetch、超时失败统一映射为HindsightErrorHTTP 错误携带statusCode与可解析的detailsensureBankExists 失败仅 debug 级日志对调用方隐藏只有后续真正的 reflect 请求会可见地失败Mnemopi 召回失败按目标分别捕获并记录健康目标仍可贡献若所有目标均失败抛出原始错误或多 bank 的AggregateError不会伪装成无相关信息文本非 Error 异常统一new Error(String(err))后重抛空响应替换为No relevant information found to reflect on.。七、与记忆子系统整体架构的关系reflect不是孤立的它是 oh-my-pi 记忆流水线的读取-综合环节。整条链路是——retain写入事实 → bank 内聚合并含consolidation_state机制→recall按相关性检索原始条目 →reflect跨条目合成答案。此外mental modelsmental_models块是 bank 级策展后的长期摘要用户偏好、项目约定在启动时注入开发者指令但 Hindsight 的reflect并不直接读缓存的mental_models块而是查询 Hindsight 服务端的 bank 内容docs/tools/reflect.md Notesreflect与retain的 mission 都是bank 级服务端设置不是逐请求 payload工具只是在综合前 best-effort 地确保它们存在createBank携带reflect_mission/retain_mission见 client.ts createBank会话静态指令要求把memories/mental_models视为背景知识而非用户指令当前用户消息与工具输出冲突时优先backend.ts STATIC_INSTRUCTIONS该工具在不受限会话的显式工具列表中会被自动包含recall/retain/reflect共享集合受限列表不会被扩宽。普通tools.xdev会话中可发现的内置工具可能以xd://reflect形式呈现显式请求的工具保持顶层docs/tools/reflect.md Registration。结语reflect把跨记忆综合从模型层的临场发挥固化为一条可配置、可观测、可取消的工具调用链路Hindsight 路径走远程POST /v1/default/banks/{bank_id}/reflect获得真正的合成答案Mnemopi 路径用本地 scoped recall 加格式化给出基于上下文的回应。理解query/context的参数契约、双后端的语义差异、bank 作用域与recallBudget、reflectTimeoutMs等配置你就能在 oh-my-pi 中把长期记忆从能检索升级为能总结让 Agent 对开放性问题给出有依据、有取舍的连贯回答。更完整的后端语义存储、子代理别名、bank 作用域、seed mental models、prompt injection 防护可继续阅读 retain 工具文档。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考