VEvectorize
Memory

Recall memory

Changed on

Recall memory using semantic similarity and spreading activation.

The types parameter is optional and may contain any of:

  • world: General knowledge about people, places, events, and things that happen
  • experience: Memories about experience, conversations, actions taken, and tasks performed
  • observation: Consolidated knowledge synthesized from facts

If types is omitted, all fact types are recalled.

post/v1/default/banks/{bank_id}/memories/recall

Request

Path parameters

bank_idstring required

Headers

authorizationstring nullable

Request body

querystring required
typesstring[] nullable

List of fact types to recall: 'world', 'experience', 'observation'. Defaults to all fact types if not specified.

prefer_observationsboolean nullable

When recalling raw facts ('world'/'experience') together with 'observation', drop any raw fact that an observation in the results was consolidated from, so the observation supersedes it and you don't get duplicate content. The freed slots are backfilled with the next results, keeping the result count at the requested budget. When omitted, uses the bank/global recall_prefer_observations config (false unless configured). No effect unless 'observation' and at least one raw type are both requested.

budget'low' | 'mid' | 'high'

Budget levels for recall/reflect operations.

max_tokensinteger
traceboolean
query_timestampstring nullable

ISO format date string (e.g., '2023-05-30T23:40:00'). Used as the query-time anchor for relative temporal expressions and recency scoring.

tagsstring[] nullable

Filter memories by tags. If not specified, all memories are returned. Omitting tags (or passing []) together with tags_match='exact' filters to untagged/global observations only (the scope written by observation_scopes='shared').

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), 'exact' (set-equality on the full scope, excludes untagged). With 'exact' and no tags (or []), the empty global scope is selected and only untagged memories match.

Example request

{
  "budget": "mid",
  "include": {
    "entities": {
      "max_tokens": 500
    }
  },
  "max_tokens": 4096,
  "query": "What did Alice say about machine learning?",
  "query_timestamp": "2023-05-30T23:40:00",
  "tags": [
    "user_a"
  ],
  "tags_match": "any",
  "temporal_window": {
    "end": "2023-06-30T23:59:59Z",
    "start": "2023-04-01T00:00:00Z"
  },
  "trace": true,
  "types": [
    "world",
    "experience"
  ]
}

Response

Successful Response

traceobject nullable
entitiesobject nullable

Entity states for entities mentioned in results

chunksobject nullable

Chunks for facts, keyed by chunk_id

source_factsobject nullable

Source facts for observation-type results, keyed by fact ID

source_facts_truncatedboolean nullable

Whether the source_facts map was cut short by the token budget. When true, some IDs in results[].source_fact_ids have no entry in source_facts — the budget ran out, the references are not dangling. Only set when source facts were requested.

Example response

{
  "chunks": {
    "456e7890-e12b-34d5-a678-901234567890": {
      "chunk_index": 0,
      "id": "456e7890-e12b-34d5-a678-901234567890",
      "text": "Alice works at Google on the AI team. She's been there for 3 years..."
    }
  },
  "entities": {
    "Alice": {
      "canonical_name": "Alice",
      "entity_id": "123e4567-e89b-12d3-a456-426614174001",
      "observations": [
        {
          "mentioned_at": "2024-01-15T10:30:00Z",
          "text": "Alice works at Google on the AI team"
        }
      ]
    }
  },
  "results": [
    {
      "chunk_id": "456e7890-e12b-34d5-a678-901234567890",
      "context": "work info",
      "entities": [
        "Alice",
        "Google"
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "occurred_end": "2024-01-15T10:30:00Z",
      "occurred_start": "2024-01-15T10:30:00Z",
      "text": "Alice works at Google on the AI team",
      "type": "world"
    }
  ],
  "trace": {
    "num_results": 1,
    "query": "What did Alice say about machine learning?",
    "time_seconds": 0.123
  }
}

Changes

  • 45e711cd0897Revision changes
    • info

      added the new optional request property

    • info

      the request property default value false was removed

    • info

      request property list-of-types was widened by adding types null to media type application/json

  • 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