oh-my-pi/docs/tools/reflect.md

reflect

Ask the Hindsight server to synthesize an answer over the active memory bank.

Source

• Entry: packages/coding-agent/src/tools/hindsight-reflect.ts
• Model-facing prompt: packages/coding-agent/src/prompts/tools/reflect.md
• Key collaborators:
  • packages/coding-agent/src/hindsight/bank.ts — best-effort bank mission initialization.
  • packages/coding-agent/src/hindsight/state.ts — session state, shared bank scope, recall/reflect config.
  • packages/coding-agent/src/hindsight/client.ts — HTTP reflect call and error mapping.
  • docs/tools/retain.md — shared backend, storage, seeding, and mental-model bootstrap.

Inputs

Field	Type	Required	Description
query	string	Yes	Question to answer from long-term memory.
context	string	No	Extra guidance sent to the Hindsight reflect endpoint.

Outputs

Returns a single-shot tool result:

• content[0].type = "text"
• content[0].text = response.text?.trim() || "No relevant information found to reflect on."
• details = {}

The tool returns the Hindsight server's synthesized text directly; it does not expose raw recall hits.

Flow

1. HindsightReflectTool.createIf(...) only exposes the tool when memory.backend == "hindsight".
2. execute(...) runs under untilAborted(...).
3. It reads the active HindsightSessionState; missing state throws Hindsight backend is not initialised for this session.
4. Before reflecting, it calls ensureBankMission(...) with the current bankId, config, and process-local missionsSet.
5. ensureBankMission(...) best-effort PUTs /v1/default/banks/{bank_id} with reflect_mission and optional retain_mission exactly once per bank/process; failures are swallowed.
6. It calls state.client.reflect(...) with the model query, optional context, configured recall budget, and bank-scope tag filters.
7. HindsightApi.reflect(...) POSTs /v1/default/banks/{bank_id}/reflect and defaults its own budget to "low" when callers omit one; this tool always passes the configured budget.
8. Blank or whitespace-only responses are replaced with No relevant information found to reflect on.
9. Failures are logged with logger.warn("reflect failed", ...) and rethrown.

Modes / Variants

• Tool path: one reflect request, optionally focused by context.
• Bank scoping is inherited from the active HindsightSessionState:
  • global — no tag filter.
  • per-project — separate bank id per cwd basename.
  • per-project-tagged — shared bank id plus project:<cwd basename> filter with tagsMatch = "any".
• Session scope: reads cross-session server-side memories, but does not persist local output.

Side Effects

• Network
  • Optional PUT /v1/default/banks/{bank_id} from ensureBankMission(...).
  • POST /v1/default/banks/{bank_id}/reflect via packages/coding-agent/src/hindsight/client.ts.
• Session state (transcript, memory, jobs, checkpoints, registries)
  • Reads session-held bank scope and config only. Does not update lastRecallSnippet, the mental-model cache, or the retain queue.
• Background work / cancellation
  • Aborts through untilAborted(...) if the tool call signal is cancelled.

Limits & Caps

• Tool-level params: only query is required; context is optional.
• Default budget setting comes from hindsight.recallBudget in packages/coding-agent/src/config/settings-schema.ts; default "mid".
• reflect itself has no client-side token cap parameter here; unlike recall, the tool does not pass maxTokens.
• Mission initialization tracks up to MISSION_SET_CAP = 10_000 bank ids in packages/coding-agent/src/hindsight/bank.ts, then drops the oldest half of the sorted set.

Errors

• Throws Hindsight backend is not initialised for this session. when no state exists.
• HTTP and fetch failures become HindsightError from packages/coding-agent/src/hindsight/client.ts with statusCode and parsed details when available.
• ensureBankMission(...) failures are silent to the tool caller; only the later reflect request can fail visibly.
• Non-Error failures are normalized to new Error(String(err)) before rethrow.

Notes

• Shared backend details are in docs/tools/retain.md: server-side storage, subagent aliasing, bank scoping, seed mental models from packages/coding-agent/src/hindsight/seeds.json, and mental-model prompt injection.
• reflect does not read the cached <mental_models> block directly. It queries the Hindsight server over the bank contents. The same session may also have separate mental-model context injected into its developer instructions.
• Reflect mission and retain mission are bank-level server settings, not per-request payload. The tool just ensures they are present best-effort before reflecting.