Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vectorize-io/hindsight/llms.txt

Use this file to discover all available pages before exploring further.

The reflect endpoint generates a synthesized, grounded response to a query by running an agentic reasoning loop over a memory bank. Unlike recall — which returns raw facts — reflect retrieves memories autonomously using multiple tools, applies the bank’s disposition traits and directives to shape the reasoning style, and produces a final answer written by the LLM. Mental models are checked first during retrieval, followed by observations, then raw facts.
To learn about disposition-driven reasoning and the agentic loop in depth, see the Reflect Architecture guide.

​
Endpoint

POST /v1/{tenant}/banks/{bank_id}/reflect

​
Request parameters

​
path.tenant
string
required
Your tenant identifier. Use default for single-tenant deployments.
​
path.bank_id
string
required
The memory bank to reason over.
​
query
string
required
The question or prompt to reflect on. If you have situational context that should influence the answer, include it directly in the query rather than as a separate field.
​
budget
string
default:"low"
Controls how thoroughly the agent explores the memory bank before answering. Accepted values: low (shallow search, optimized for speed), mid (checks multiple sources when the question warrants it), high (deep exploration across all knowledge levels, uses multiple query variations to find indirect connections). Use high for complex questions that require synthesizing information from many sources.
​
max_tokens
integer
default:"4096"
Limits the length of the final generated response. Does not affect how much the agent can retrieve during the agentic loop — only the final answer length.
​
response_schema
object
An optional JSON Schema object. When provided, the LLM generates a response conforming to the schema and the response includes a structured_output field with the result parsed accordingly. The text field will be empty. Use this when you need to process the response programmatically rather than display it as prose.
​
tags
string[]
Filters which memories the agent can access during reflection. Works identically to recall tags — only memories matching the specified tags are considered.
​
tags_match
string
default:"any"
Controls tag filtering logic. Accepted values: any, all, any_strict, all_strict. Same semantics as the recall endpoint.
​
tag_groups
object[]
Compound boolean tag filters for advanced tag matching. Same structure as the recall endpoint’s tag_groups parameter.
​
fact_types
string[]
Optional list of fact types to include during retrieval: world, experience, observation. When omitted, all types are considered.
​
exclude_mental_models
boolean
default:"false"
When true, excludes all mental models from the agentic loop. The agent falls back to raw recall and observations.
​
exclude_mental_model_ids
string[]
Optional list of specific mental model IDs to exclude while allowing other mental models to be used.
​
include
object
Controls optional supplementary data returned alongside the main response.

​
Response fields

​
text
string
required
The synthesized answer as a well-formatted markdown string. This is the primary output of reflect. Empty when response_schema is provided — use structured_output instead.
​
structured_output
object
The LLM’s response parsed according to the response_schema provided in the request. Only present when response_schema was set. null otherwise.
​
based_on
object
The sources the agent used to construct the answer. Only present when include.facts was enabled.
​
usage
object
Token usage for all LLM calls made during the agentic loop.
​
trace
object
Full execution log of the agentic loop. Only present when include.tool_calls was enabled.

​
Examples

​
Basic reflect

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/reflect" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What should I know about Alice before our meeting today?"
  }'

​
Reflect with budget and source attribution

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/reflect" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize all architectural decisions made in Q1 2024 and their rationale.",
    "budget": "high",
    "include": {"facts": {}}
  }'

​
Structured output

curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/reflect" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are Alice'\''s top three priorities this week?",
    "response_schema": {
      "type": "object",
      "properties": {
        "priorities": {
          "type": "array",
          "items": {"type": "string"},
          "maxItems": 3
        }
      },
      "required": ["priorities"]
    }
  }'

​
Tag-scoped reflect

response = client.reflect(
    bank_id="my-bank",
    query="What does this user prefer?",
    tags=["user:alice"],
    tags_match="all_strict",
)
print(response.text)

​
Error codes

StatusCodeDescription
400invalid_requestMalformed request body or missing required fields.
401unauthorizedMissing or invalid API key.
404bank_not_foundThe specified bank does not exist.
422validation_errorOne or more parameters failed validation.
429rate_limitedToo many requests. Retry with exponential backoff.
500internal_errorServer error during the agentic loop.

Build docs developers (and LLMs) love

Get started for freeTalk to us