---
title: "Reflect and generate answer"
method: POST
path: "/v1/default/banks/{bank_id}/reflect"
tags: ["Memory"]
---

# Reflect and generate answer

`POST /v1/default/banks/{bank_id}/reflect`

## Request

- Base URL: `https://hindsight.vectorize.io` (the document declares no server; this is the origin it was published from)
- URL: `https://hindsight.vectorize.io/v1/default/banks/{bank_id}/reflect`
- Auth: none declared
- TypeScript: <https://skmtc.dev/vectorize/apis/hindsight-http-api/docs/v1/default/banks/:bank_id/reflect/post.ts> (a function with typed inputs; its response is checked against the schema)

Reflect and formulate an answer using bank identity, world facts, observations, and mental models.

This endpoint:
1. Retrieves experience (conversations and events)
2. Retrieves world facts relevant to the query
3. Retrieves observations and mental models (bank's synthesized perspectives)
4. Uses LLM to formulate a contextual answer
5. Returns plain text answer and the facts used

## Path parameters

- `bank_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- ReflectRequest: Request model for reflect endpoint.
  - `reflect_search_observations_max_tokens` integer, nullable: Token budget for reflect's search_observations tool when the model names none. Observation evidence is often the largest contributor to the reflect context; lowering it trades the lowest-ranked observations for a smaller LLM context. None means use the shipped default (5000).
  - `reflect_search_observations_include_entities` boolean, nullable: Whether search_observations attaches resolved entity names to each observation. Entities can be more than half the serialized tool payload; turning them off keeps the same observations and ranking with a much smaller context. None means enabled.
  - `reflect_search_mental_models_max_tokens` integer, nullable: Token budget for the mental models search_mental_models returns in full, packed in rank order. The best-ranked one is always in full; the others that do not fit come back as a snippet the model can read with read_mental_models. Raise it for banks with long pages or answers spread across pages; lower it to cut the reflect context. None means use the shipped default (16000).
  - `query` string, required
  - `budget` 'low' | 'mid' | 'high': Budget levels for recall/reflect operations.
  - `context` string, nullable: DEPRECATED: Additional context is now concatenated with the query. Pass context directly in the query field instead. If provided, it will be appended to the query for backward compatibility.
  - `max_tokens` integer: Maximum tokens for the response
  - `include` ReflectIncludeOptions: Options for including additional data in reflect results.
    - `facts` FactsIncludeOptions: Options for including facts (based_on) in reflect results.
    - `tool_calls` ToolCallsIncludeOptions: Options for including tool calls in reflect results.
      - `output` boolean: Include tool outputs in the trace. Set to false to only include inputs (smaller payload).
  - `response_schema` object, nullable: Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema.
  - `tags` string[], nullable: Scope raw facts, observations, mental models, and tagged directives during reflection. With no tags, memory retrieval is unfiltered while only untagged/global directives are loaded. Use tags=[] with tags_match='exact' to select the untagged/global scope.
  - `tags_match` 'any' | 'all' | 'any_strict' | 'all_strict' | 'exact': How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged), or 'exact' (set equality). Untagged directives remain global in every mode.
  - `tag_groups` union[], nullable: Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}. Mutually exclusive with tags. A leaf may set resolve='fuzzy' to match its tags against the bank's tags by trigram similarity instead of literally, so a query that says 'typsecript' still reaches memories tagged 'typescript'.
    - union
      - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode.
        - `tags` string[], required
        - `match` 'any' | 'all' | 'any_strict' | 'all_strict' | 'exact'
        - `resolve` 'exact' | 'fuzzy'
      - TagGroupAndInput: Compound AND group: all child filters must match.
        - `and` union[], required
          - union
            - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode.
              - …
            - TagGroupAndInput (recursive)
            - TagGroupOrInput: Compound OR group: at least one child filter must match.
              - …
            - TagGroupNotInput: Compound NOT group: child filter must NOT match.
              - …
      - TagGroupOrInput: Compound OR group: at least one child filter must match.
        - `or` union[], required
          - union
            - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode.
              - …
            - TagGroupAndInput: Compound AND group: all child filters must match.
              - …
            - TagGroupOrInput (recursive)
            - TagGroupNotInput: Compound NOT group: child filter must NOT match.
              - …
      - TagGroupNotInput: Compound NOT group: child filter must NOT match.
        - `not` union, required
          - TagGroupLeaf: A leaf tag filter: matches memories by tag list and match mode.
            - `tags` string[], required
            - `match` 'any' | 'all' | 'any_strict' | 'all_strict' | 'exact'
            - `resolve` 'exact' | 'fuzzy'
          - TagGroupAndInput: Compound AND group: all child filters must match.
            - `and` union[], required
              - …
          - TagGroupOrInput: Compound OR group: at least one child filter must match.
            - `or` union[], required
              - …
          - TagGroupNotInput (recursive)
  - `apply_all_directives` boolean: Apply every active directive regardless of tags. By default directives are scoped like memories: untagged directives always apply, and tagged directives apply only when the request's tags match them. Set true to apply all active directives, ignoring tag scope.
  - `fact_types` string[], nullable: Filter which fact types are retrieved during reflect. None means all types (world, experience, observation).
  - `exclude_mental_models` boolean: If true, exclude all mental models from the reflect loop (skip search_mental_models tool).
  - `exclude_mental_model_ids` string[], nullable: Exclude specific mental models by ID from the reflect loop.

## Response `200`

Successful Response

- ReflectResponse: Response model for think endpoint.
  - `text` string, required: The reflect response as well-formatted markdown (headers, lists, bold/italic, code blocks, etc.)
  - `based_on` ReflectBasedOn: Evidence the response is based on: memories, mental models, and directives.
    - `memories` ReflectFact[]: Memory facts used to generate the response
      - `id` string, nullable
      - `text` string, required: Fact text. When type='observation', this contains markdown-formatted consolidated knowledge
      - `type` string, nullable
      - `context` string, nullable
      - `occurred_start` string, nullable
      - `occurred_end` string, nullable
      - `mentioned_at` string, nullable
      - `document_id` string, nullable
      - `chunk_id` string, nullable
      - `tags` string[], nullable
      - `metadata` object, nullable
      - `attachments` ChunkAttachment[], nullable: Attachments this memory was drawn from — the same per-fact edge recall reports. An observation reports those of the facts it was consolidated from. Omitted when there are none.
        - `id` string, required: The id inside the text's placeholder; a prefix of the bytes' sha256.
        - `hash` string, required: Full sha256 of the attachment bytes.
        - `kind` string, required: 'image' or 'file', as the caller sent it.
        - `media_type` string, required: MIME type of the attachment.
        - `byte_size` integer, required: Size of the attachment in bytes.
        - `filename` string, nullable: Original filename, when the caller supplied one.
        - `url` string, required: Bank-scoped API path serving the bytes. Requires the same authorization as the bank.
    - `mental_models` ReflectMentalModel[]: Mental models used during reflection
      - `id` string, required: Mental model ID
      - `text` string, required: Mental model content
      - `context` string, nullable: Additional context
    - `directives` ReflectDirective[]: Directives applied during reflection
      - `id` string, required: Directive ID
      - `name` string, required: Directive name
      - `content` string, required: Directive content
  - `structured_output` object, nullable: Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request.
  - `structured_output_error` string, nullable: Why structured output could not be produced. Present only when a response_schema was given and the extraction call failed (provider error, timeout, unparseable output). A missing structured_output *without* this field means the answer held nothing matching the schema — the reflect itself still succeeded either way.
  - `usage` TokenUsage: Token usage metrics for LLM calls. Tracks input/output tokens for a single request to enable per-request cost tracking and monitoring.
    - `input_tokens` integer: Number of input/prompt tokens consumed
    - `output_tokens` integer: Number of visible output/completion tokens generated (excludes reasoning/thoughts)
    - `total_tokens` integer: Total tokens (input + output, excludes thoughts)
    - `cached_tokens` integer: Cached/cache-read prompt tokens, when reported by the provider
    - `thoughts_tokens` integer: Reasoning/thinking tokens generated by the model. Billed at the output rate by some providers (e.g. Gemini 2.5+ family) but not surfaced in the visible response.
  - `trace` ReflectTrace: Execution trace of LLM and tool calls during reflection.
    - `tool_calls` ReflectToolCall[]: Tool calls made during reflection
      - `tool` string, required: Tool name: lookup, recall, learn, expand
      - `input` object, required: Tool input parameters
      - `output` object, nullable: Tool output (only included when include.tool_calls.output is true)
      - `duration_ms` integer, required: Execution time in milliseconds
      - `iteration` integer: Iteration number (1-based) when this tool was called
    - `llm_calls` ReflectLLMCall[]: LLM calls made during reflection
      - `scope` string, required: Call scope: agent_1, agent_2, final, etc.
      - `duration_ms` integer, required: Execution time in milliseconds

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-07** `45e711cd0897`: 1 info
  - added the new optional request property `reflect_search_mental_models_max_tokens`
- **2026-10-04** `4fda98b75f63`: 1 warning, 29 info
  - removed the optional property `detail/items/url` from the response with the `422` status
  - added the new optional request property `apply_all_directives`
  - added the new optional request property `reflect_search_observations_include_entities`
  - added the new optional request property `reflect_search_observations_max_tokens`
  - …26 more
- **2026-05-15** `0d08f271b9db`: 1 breaking, 4 info
  - removed `#/components/schemas/TagGroupAnd, #/components/schemas/TagGroupOr, #/components/schemas/TagGroupNot` from the `tag_groups/anyOf[subschema #1]/items/` request property `anyOf` list
  - added `#/components/schemas/TagGroupAnd-Input, #/components/schemas/TagGroupOr-Input, #/components/schemas/TagGroupNot-Input` to the `tag_groups/anyOf[subschema #1]/items/` request property `anyOf` list
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
  - …1 more

[Operation history](https://skmtc.dev/vectorize/apis/hindsight-http-api/changes/v1/default/banks/:bank_id/reflect/post.md)

---

[API](https://skmtc.dev/vectorize/apis/hindsight-http-api.md) - [All operations](https://skmtc.dev/vectorize/apis/hindsight-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vectorize/apis/hindsight-http-api/revisions/45e711cd0897?raw)