VEvectorize
Memory

Reflect and generate answer

Changed on

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
post/v1/default/banks/{bank_id}/reflect

Request

Path parameters

bank_idstring required

Headers

authorizationstring nullable

Request body

reflect_search_observations_max_tokensinteger 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_entitiesboolean 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_tokensinteger 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).

querystring required
budget'low' | 'mid' | 'high'

Budget levels for recall/reflect operations.

contextstring 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_tokensinteger

Maximum tokens for the response

response_schemaobject 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.

tagsstring[] 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.

apply_all_directivesboolean

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_typesstring[] nullable

Filter which fact types are retrieved during reflect. None means all types (world, experience, observation).

exclude_mental_modelsboolean

If true, exclude all mental models from the reflect loop (skip search_mental_models tool).

exclude_mental_model_idsstring[] nullable

Exclude specific mental models by ID from the reflect loop.

Example request

{
  "budget": "low",
  "include": {
    "facts": {}
  },
  "max_tokens": 4096,
  "query": "What do you think about artificial intelligence?",
  "response_schema": {
    "properties": {
      "summary": {
        "type": "string"
      },
      "key_points": {
        "items": {
          "type": "string"
        },
        "type": "array"
      }
    },
    "required": [
      "summary",
      "key_points"
    ],
    "type": "object"
  },
  "tags": [
    "user_a"
  ],
  "tags_match": "any"
}

Response

Successful Response

textstring required

The reflect response as well-formatted markdown (headers, lists, bold/italic, code blocks, etc.)

structured_outputobject nullable

Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request.

structured_output_errorstring 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.

Example response

{
  "based_on": {
    "memories": [
      {
        "id": "123",
        "text": "AI is used in healthcare",
        "type": "world"
      },
      {
        "id": "456",
        "text": "I discussed AI applications last week",
        "type": "experience"
      }
    ]
  },
  "structured_output": {
    "key_points": [
      "Used in healthcare",
      "Discussed recently"
    ],
    "summary": "AI is transformative"
  },
  "text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
  "trace": {
    "llm_calls": [
      {
        "duration_ms": 1200,
        "scope": "agent_1"
      }
    ],
    "observations": [
      {
        "id": "obs-1",
        "name": "AI Technology",
        "subtype": "structural",
        "type": "concept"
      }
    ],
    "tool_calls": [
      {
        "duration_ms": 150,
        "input": {
          "query": "AI"
        },
        "tool": "recall"
      }
    ]
  },
  "usage": {
    "input_tokens": 1500,
    "output_tokens": 500,
    "total_tokens": 2000
  }
}

Changes

  • 45e711cd0897Revision changes
    • info

      added the new optional request property

  • 4fda98b75f63Revision changes
    • warning

      removed the optional property // from the response with the status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property ////

    • info

      added the new optional request property ///////

    • info

      added the new optional request property //////////

    • info

      added the new optional request property ////////////

    • info

      added the new optional request property /////////

    • info

      added the new optional request property ///////

    • info

      added the new optional request property /////////

    • info

      added the new optional request property //////

    • info

      added the new exact enum value to the request property ////

    • info

      added the new exact enum value to the request property ///////

    • info

      added the new exact enum value to the request property //////////

    • info

      added the new exact enum value to the request property ////////////

    • info

      added the new exact enum value to the request property /////////

    • info

      added the new exact enum value to the request property ///////

    • info

      added the new exact enum value to the request property /////////

    • info

      added the new exact enum value to the request property //////

    • info

      added the new exact enum value to the request property

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status