Buscar recordações

O Memory Bank permite recuperar memórias armazenadas usando diferentes operações, dependendo das suas necessidades. É possível buscar uma única memória, listar todas as memórias ou realizar a recuperação com base no escopo usando a pesquisa de similaridade.

Este documento explica como usar essas operações de busca usando o SDK da Agent Platform.

Se você usa o Kit de Desenvolvimento de Agente (ADK), o agente pode orquestrar essas chamadas automaticamente. Consulte o Guia de início rápido com o ADK.

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 memórias geradas:

  • Receber memória: receba o conteúdo completo de uma única memória usando o SDK da Agent Platform.

  • Recuperar memórias: usando o SDK da Agent Platform, recupere memórias usando a recuperação de memória com base no escopo. Recupere memórias usando a pesquisa de similaridade ou todas as memórias no escopo.

  • Listar memórias: liste memórias usando o SDK da Agent Platform.

Receber memória

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

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

Substitua:

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

Buscar memórias usando a recuperação com base no escopo

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

O escopo de uma memória é definido quando ela é gerada ou criada e é imutável.

É possível usar RetrieveMemories para realizar as seguintes operações em um escopo específico:

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

As memórias retornadas são classificadas da mais semelhante (distância euclidiana mais curta) à menos semelhante (maior distância euclidiana):

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

results.page

"""
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 a qual realizar a pesquisa de similaridade. Por exemplo, é possível usar a última vez que o usuário conversou como a 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 memórias

Se nenhum parâmetro de pesquisa de similaridade for fornecido, RetrieveMemories retornará todas as memórias que têm o escopo fornecido, independente da similaridade com a conversa atual.

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.

results.page

"""
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 da recuperação. Por exemplo, {"user_id": "123"}. Somente as memórias com o mesmo escopo da solicitação são retornadas.

Listar memórias

Use ListMemories para memórias do Memory Bank sem filtragem com base no escopo. Para recuperação com base no escopo, use RetrieveMemories em vez disso. ListMemories não é recomendado para recuperação de baixa latência.

pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
  print(page)

Filtrar memórias

Esta seção descreve como usar filtros para restringir quais memórias são buscadas. É possível filtrar por:

  • Metadados usando o filter_groups atributo para recuperação com base no escopo.

  • Campos do sistema usando filter. Os campos do sistema incluem topics, create_time, update_time e fact das memórias.

A filtragem de metadados e campos do sistema pode ser usada na mesma solicitação.

Filtrar por metadados

Ao criar, atualizar ou gerar memórias, é possível aplicar metadados estruturados às memórias armazenadas:

import datetime

from agentplatform 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.memory_banks.memories.create(
  ...,
  config={"metadata": metadata}
)

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

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

É possível filtrar esses metadados ao recuperar memórias usando o atributo filter_groups. Os filtros de metadados são definidos na forma normal disjuntiva (DNF), que é uma expressão lógica de ORs de ANDs.

Por exemplo, a solicitação a seguir vai recuperar memórias que incluem os metadados ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) OR {"my_string_key": {"string_value": "other"}}.

Dicionário

results = client.memory_banks.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 na classe

from agentplatform import types

results = client.memory_banks.memories.retrieve(
  ...,
  config=types.RetrieveMemoriesConfig(
    # 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 filter atributo, que espera um valor de string usando a EBNF 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) usam uma string entre aspas duplas que representa a data e hora ISO 8601 ou um campo numérico que representa microssegundos da época Unix.

Por exemplo, o filtro a seguir pode ser usado para buscar memórias em que o fact inclui a substring "allergies" e update_time foi depois de 1º de janeiro de 2026.

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

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

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

Filtrar por temas

As memórias geradas são rotuladas automaticamente com o tema de memória relevante.

Para filtrar 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 temas personalizados, use topics.custom_memory_topic_label como o nome do campo e o rótulo do tema esperado como o 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.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

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