# recall

> Search the active Hindsight bank and return raw matching memories.

## Source
- Entry: `packages/coding-agent/src/tools/hindsight-recall.ts`
- Model-facing prompt: `packages/coding-agent/src/prompts/tools/recall.md`
- Key collaborators:
  - `packages/coding-agent/src/hindsight/state.ts` — session state, recall query defaults, prompt-side auto-recall.
  - `packages/coding-agent/src/hindsight/content.ts` — result formatting and UTC timestamp formatting.
  - `packages/coding-agent/src/hindsight/client.ts` — HTTP `recall` call and error mapping.
  - `packages/coding-agent/src/hindsight/bank.ts` — bank id and tag-filter scoping.
  - `docs/tools/retain.md` — shared backend, storage, seeding, and mental-model bootstrap.

## Inputs

| Field | Type | Required | Description |
|---|---|---:|---|
| `query` | `string` | Yes | Natural-language search query. The tool passes it through unchanged. |

## Outputs
Returns a single-shot tool result.

When matches exist:
- `content[0].type = "text"`
- `content[0].text = "Found <n> relevant memories (as of YYYY-MM-DD HH:MM UTC):\n\n<bullet list>"`
- each bullet is `- <text> [<type>] (<mentioned_at>)`; the type and timestamp suffixes appear only when those fields are present
- `details = {}`

When no matches exist:
- `content[0].text = "No relevant memories found."`
- `details = {}`

## Flow
1. `HindsightRecallTool.createIf(...)` only exposes the tool when `memory.backend == "hindsight"`.
2. `execute(...)` wraps the whole operation in `untilAborted(...)` from `@oh-my-pi/pi-utils`.
3. It reads the active `HindsightSessionState`; missing state throws `Hindsight backend is not initialised for this session.`
4. It calls `state.client.recall(...)` with:
   - `bankId` from session bootstrap,
   - the model-supplied `query`,
   - `budget`, `maxTokens`, and `types` from `HindsightConfig`,
   - tag filters from the bank scope (`recallTags`, `recallTagsMatch`).
5. `HindsightApi.recall(...)` POSTs `/v1/default/banks/{bank_id}/memories/recall`.
6. Results are formatted into a plain-text list with `formatMemories(...)`; empty results map to the fixed no-match string.
7. Failures are logged with `logger.warn("recall failed", ...)` and rethrown.

## Modes / Variants
- Tool path: explicit query-only recall. The tool does not compose context from recent turns; that richer path is reserved for backend auto-recall in `HindsightSessionState.beforeAgentStartPrompt(...)` / `maybeRecallOnAgentStart(...)`.
- 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"`, so project-tagged and untagged global memories can both surface.
- Session scope: reads cross-session server-side memories, but uses per-session cached config and scope.

## Side Effects
- Network
  - `POST /v1/default/banks/{bank_id}/memories/recall` via `packages/coding-agent/src/hindsight/client.ts`.
- Session state (transcript, memory, jobs, checkpoints, registries)
  - None on success. Unlike backend auto-recall, this tool does not update `lastRecallSnippet` or refresh the system prompt.
- Background work / cancellation
  - Aborts through `untilAborted(...)` if the tool call signal is cancelled.

## Limits & Caps
- Client default budget for raw `HindsightApi.recall(...)` is `"mid"`; this tool overrides from config in `packages/coding-agent/src/hindsight/state.ts`.
- Default recall settings from `packages/coding-agent/src/config/settings-schema.ts`:
  - `hindsight.recallBudget = "mid"`
  - `hindsight.recallMaxTokens = 1024`
  - `hindsight.recallTypes = ["world", "experience"]`
- The explicit tool path does not apply `hindsight.recallContextTurns` or `hindsight.recallMaxQueryChars`; those caps only affect backend auto-recall query composition.

## 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.
- 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, mission setup, and mental-model bootstrap.
- Mental models are not fetched by this tool. They may still already be present in the agent's developer instructions because the backend caches a `<mental_models>` block separately from recall results.
- The tool returns raw memory hits; it does not synthesize across them. Use `reflect` for that path.