Method: memories.retrieve

Full name: projects.locations.reasoningEngines.memories.retrieve

Retrieve memories.

Endpoint

post https://aiplatform.googleapis.com/v1beta1/{parent}/memories:retrieve

Path parameters

parent string

Required. The resource name of the ReasoningEngine to retrieve memories from. Format: projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}

Request body

The request body contains data with the following structure:

Fields
scope map (key: string, value: string)

Required. The scope of the memories to retrieve. A memory must have exactly the same scope (Memory.scope) as the scope provided here to be retrieved (same keys and values). Order does not matter, but it is case-sensitive.

filter string

Optional. The standard list filter that will be applied to the retrieved memories. More detail in AIP-160.

Supported fields: * fact * createTime * updateTime * topics (i.e. topics.custom_memory_topic_label: "example topic" OR topics.managed_memory_topic: USER_PREFERENCES)

filterGroups[] object (MemoryConjunctionFilter)

Optional. metadata filters that will be applied to the retrieved memories' metadata using OR logic. Filters are defined using disjunctive normal form (OR of ANDs).

For example: filterGroups: [{filters: [{key: "author", value: {stringValue: "agent 123"}, op: EQUAL}]}, {filters: [{key: "label", value: {stringValue: "travel"}, op: EQUAL}, {key: "author", value: {stringValue: "agent 321"}, op: EQUAL}]}]

would be equivalent to the logical expression: (metadata.author = "agent 123" OR (metadata.label = "travel" AND metadata.author = "agent 321")).

retrieval_params Union type
Parameters for retrieval. retrieval_params can be only one of the following:
similaritySearchParams object (SimilaritySearchParams)

Parameters for semantic similarity search based retrieval.

simpleRetrievalParams object (SimpleRetrievalParams)

Parameters for simple (non-similarity search) retrieval.

Response body

Response message for MemoryBankService.RetrieveMemories.

If successful, the response body contains data with the following structure:

Fields
retrievedMemories[] object (RetrievedMemory)

The retrieved memories.

nextPageToken string

A token that can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages. This token is not set if similarity search was used for retrieval.

JSON representation 
{
  "retrievedMemories": [
    {
      object (RetrievedMemory)
    }
  ],
  "nextPageToken": string
}

SimilaritySearchParams

Parameters for semantic similarity search based retrieval.

Fields
searchQuery string

Required. Query to use for similarity search retrieval. If provided, then the parent ReasoningEngine must have ReasoningEngineContextSpec.MemoryBankConfig.SimilaritySearchConfig set.

topK integer

Optional. The maximum number of memories to return. The service may return fewer than this value. If unspecified, at most 3 memories will be returned. The maximum value is 100; values above 100 will be coerced to 100.

JSON representation 
{
  "searchQuery": string,
  "topK": integer
}

SimpleRetrievalParams

Parameters for simple (non-similarity search) retrieval.

Fields
pageSize integer

Optional. The maximum number of memories to return. The service may return fewer than this value. If unspecified, at most 3 memories will be returned. The maximum value is 100; values above 100 will be coerced to 100.

pageToken string

Optional. A page token, received from a previous memories.retrieve call. Provide this to retrieve the subsequent page.

JSON representation 
{
  "pageSize": integer,
  "pageToken": string
}

MemoryConjunctionFilter

A conjunction of filters that will be combined using AND logic.

Fields
filters[] object (MemoryFilter)

Filters that will combined using AND logic.

JSON representation 
{
  "filters": [
    {
      object (MemoryFilter)
    }
  ]
}

MemoryFilter

Filter to apply when retrieving memories.

Fields
key string

Key of the filter. For example, "author" would apply to metadata entries with the key "author".

op enum (Operator)

Operator to apply to the filter. If not set, then EQUAL will be used.

value object (MemoryMetadataValue)

value to compare to.

negate boolean

If true, the filter will be negated.

JSON representation 
{
  "key": string,
  "op": enum (Operator),
  "value": {
    object (MemoryMetadataValue)
  },
  "negate": boolean
}

Operator

Operator to apply to the filter.

Enums
OPERATOR_UNSPECIFIED Unspecified operator. Defaults to EQUAL.
EQUAL Equal to.
GREATER_THAN Greater than.
LESS_THAN Less than.

RetrievedMemory

A retrieved memory.

Fields
memory object (Memory)

The retrieved Memory.

distance number

The distance between the query and the retrieved Memory. Smaller values indicate more similar memories. This is only set if similarity search was used for retrieval.

JSON representation 
{
  "memory": {
    object (Memory)
  },
  "distance": number
}