Buscar recordações

Esta página descreve como buscar recordações geradas e enviadas do Banco de recordações. Para conferir todo o fluxo de trabalho de configuração, geração e uso do Memory Bank, consulte o guia de início rápido com a API REST.

Antes de começar

Para concluir as etapas desta página, primeiro conclua as etapas em Configurar o Memory Bank.

Operações de busca

Você tem as seguintes opções para buscar recordações geradas:

Receber memória: receba o conteúdo completo de uma única memória usando o SDK da Vertex AI.
Listar memórias: liste memórias usando o SDK da Vertex AI ou o console Google Cloud .
Recuperar memórias: usando o SDK da Vertex AI, recupere memórias com base no escopo. Recupere recordações usando a pesquisa por similaridade ou todas as recordações no escopo.

Receber recordação

Use GetMemories para acessar o conteúdo completo de uma única memória:

memory = client.agent_engines.memories.get(
    name="MEMORY_NAME")

Substitua:

MEMORY_NAME: um nome de memória totalmente qualificado no formato "projects/.../locations/.../reasoningEngines/.../memories...".

Listar recordações

Console

Para agentes implantados, use o console Google Cloud para listar todas as memórias associadas à sua instância do Agent Engine:

No console Google Cloud , acesse a página Vertex AI Agent Engine.

Acessar o Agent Engine

As instâncias do Agent Engine que fazem parte do projeto selecionado aparecem na lista. Use o campo Filtro para filtrar a lista pela coluna especificada.
Clique no nome da sua instância do Agent Engine.
Clique na guia Recordações. Uma lista de recordações é exibida por ID.

SDK da Vertex AI

Use ListMemories para buscar todas as recordações no seu Banco de Memórias.

pager = client.agent_engines.memories.list(name=agent_engine.api_resource.name)
for page in pager:
  print(page)

Extrair recordações usando a recuperação baseada em escopo

Você pode usar RetrieveMemories para recuperar recordações de um escopo específico. Somente as memórias que têm o mesmo escopo (independente da ordem) da solicitação de recuperação são retornadas. Por exemplo, é possível recuperar todas as recordações de um usuário específico usando {"user_id": "123"}. Se nenhuma recordação for retornada, a central de recordações não terá nenhuma para o escopo fornecido.

O escopo de uma recordação é definido quando ela é gerada ou criada e é imutável.

Você pode usar RetrieveMemories para realizar as seguintes operações em um escopo específico:

Recuperar recordações usando a pesquisa por similaridade
Recuperar todas as recordações

Recuperar recordações usando a pesquisa de similaridade

Para casos em que você tem muitas memórias para um escopo específico, use a pesquisa por similaridade para recuperar apenas as mais semelhantes fornecendo parâmetros de pesquisa por similaridade. O Memory Bank só considera as recordações que têm exatamente o mesmo escopo da solicitação ao realizar a pesquisa de similaridade. A pesquisa por similaridade compara os vetores de embedding entre os fatos das recordações e a consulta de pesquisa da solicitação.

As recordações retornadas são classificadas da mais semelhante (menor distância euclidiana) para a menos semelhante (maior distância euclidiana):

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all memories.
list(results)

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      },
      distance=0.5
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      },
      distance=0.7
    ),
]
"""

Substitua:

QUERY: a consulta para realizar a pesquisa de similaridade. Por exemplo, você pode usar a última vez que o usuário falou na conversa como consulta.
SCOPE: um dicionário que representa o escopo da pesquisa de similaridade. Por exemplo, {"user_id": "123"}. Somente as memórias com o mesmo escopo da solicitação são consideradas.

Recuperar todas as recordações

Se nenhum parâmetro de pesquisa de similaridade for fornecido, RetrieveMemories vai retornar todas as recordações que têm o escopo fornecido, independente da similaridade com a conversa atual.

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all pages' memories.
list(results)

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      }
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      }
    ),
]
"""

Substitua:

SCOPE: um dicionário que representa o escopo para recuperação. Por exemplo, {"user_id": "123"}. Apenas as recordações com o mesmo escopo da solicitação são retornadas.

Filtrar recordações

Esta seção descreve como usar filtros para restringir quais recordações são buscadas. É possível filtrar por:

Metadados usando o atributo filter_groups para recuperação baseada em escopo.
Campos do sistema usando filter. Os campos do sistema incluem topics, create_time, update_time e fact das recordações.

Os filtros de metadados e de campos do sistema podem ser usados na mesma solicitação.

Filtrar por metadados

Ao criar, atualizar ou gerar recordações, é possível aplicar metadados estruturados a elas:

import datetime

from vertexai import types

metadata = {
    "my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
    "my_double_key": types.MemoryMetadataValue(double_value=123.456),
    "my_boolean_key": types.MemoryMetadataValue(bool_value=True),
    "my_timestamp_key": types.MemoryMetadataValue(
        timestamp_value=datetime.datetime(
            2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
        )
    ),
}

client.agent_engines.memories.create(
  ...,
  config={"metadata": metadata}
)

client.agent_engines.memories.update(
  ...,
  config={"metadata": metadata}
)

client.agent_engines.memories.generate(
  ...,
  config={"metadata": metadata}
)

É possível filtrar esses metadados ao recuperar recordações usando o atributo filter_groups. Os filtros de metadados são definidos na forma normal disjuntiva (DNF), que é uma expressão lógica de operadores OR de operadores AND.

Por exemplo, a solicitação a seguir vai recuperar recordações que incluem os metadados ({"my_string_key": {"string_value": "my_value"}} E {"my_double_key": {"double": 1.23}}) OU {"my_string_key": {"string_value": "other"}}.

Dicionário

results = client.agent_engines.memories.retrieve(
  ...,
  config={
    # Each element of `filter_groups` is combined using OR logic.
    "filter_groups": [
      {
        # Each element of `filters` is combined using AND logic.
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "my_value"}
          },
          {
            "key": "my_double_key",
            "value": {"double_value": 1.23}
          }
        ]
      },
      {
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "other"}
          }
        ]
      }
    ]
  }
)

Com base em classes

from vertexai import types

results = client.agent_engines.memories.retrieve(
  ...,
  config=types.RetrieveAgentEngineMemoriesConfig(
    # Each element of `filter_groups` is combined using OR logic.
    filter_groups=[
      types.MemoryConjunctionFilter(
        # Each element of `filters` is combined using AND logic.
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="my_value")
          ),
          types.MemoryFilter(
            key="my_double_key",
            value=types.MemoryMetadataValue(double_value=1.23)
          )
        ]
      ),
      types.MemoryConjunctionFilter(
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="other")
          )
        ]
      )
    ]
  )
)

Filtrar por campos do sistema

É possível filtrar campos do sistema usando o atributo filter, que espera um valor de string usando a sintaxe EBNF. Os campos do sistema incluem create_time, update_time, fact e topics.

A sintaxe EBNF tem os seguintes requisitos ao construir uma string de filtro:

Para combinar filtros, use AND e OR.
A string precisa usar aspas duplas ".
Os campos de data e hora (como create_time) devem usar uma string entre aspas duplas que represente a data e hora ISO 8601 ou um campo numérico que represente microssegundos desde a época Unix.

Por exemplo, o filtro a seguir pode ser usado para buscar recordações em que o fact inclui a substring "alergias" e update_time foi depois de 1º de janeiro de 2026.

filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"''

client.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)

Filtrar por temas

As recordações geradas são rotuladas automaticamente com o tema da recordação relevante.

Para filtrar por temas gerenciados, use topics.managed_memory_topic como o nome do campo e o ManagedTopicEnum esperado como o valor, como topics.managed_memory_topic: USER_PREFERENCES.

Para filtrar por tópicos personalizados, use topics.custom_memory_topic_label como nome do campo e o rótulo do tópico esperado como valor, como topics.custom_memory_topic_label: custom-label.

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)

Buscar recordações Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Operações de busca

Receber recordação

Listar recordações

Console

SDK da Vertex AI

Extrair recordações usando a recuperação baseada em escopo

Recuperar recordações usando a pesquisa de similaridade

Recuperar todas as recordações

Filtrar recordações

Filtrar por metadados

Dicionário

Com base em classes

Filtrar por campos do sistema

Filtrar por temas

Buscar recordações