Recupera recuerdos

Memory Bank te permite recuperar memorias almacenadas con diferentes operaciones según tus necesidades. Puedes recuperar una sola memoria, enumerar todas las memorias o realizar una recuperación basada en el alcance con la búsqueda de similitud.

En este documento, se explica cómo usar estas operaciones de recuperación con el SDK de Agent Platform.

Si usas el Kit de desarrollo de agentes (ADK), tu agente puede organizar automáticamente estas llamadas por ti. Consulta la guía de inicio rápido con ADK.

Antes de comenzar

Para completar los pasos de esta página, primero debes completar los pasos de Configuración para Memory Bank.

Operaciones de recuperación

Tienes las siguientes opciones para recuperar memorias generadas:

  • Obtener memoria: Obtén el contenido completo de una sola memoria con el SDK de Agent Platform.

  • Recuperar memorias: Con el SDK de Agent Platform, recupera memorias con la recuperación de memoria basada en el alcance. Recupera memorias con la búsqueda de similitud o todas las memorias dentro del alcance.

  • Enumerar memorias: Enumera memorias con el SDK de Agent Platform.

Obtener memoria

Usa GetMemories para obtener el contenido completo de una sola memoria:

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

Reemplaza lo siguiente:

  • MEMORY_NAME: Es un nombre de memoria completamente calificado en el formato "projects/.../locations/.../reasoningEngines/.../memories...".

Recupera memorias con la recuperación basada en el alcance

Puedes usar RetrieveMemories para recuperar memorias de un alcance en particular. Solo se muestran las memorias que tienen exactamente el mismo alcance (independientemente del orden) que la solicitud de recuperación. Por ejemplo, puedes recuperar todas las memorias que están dentro del alcance de un usuario en particular con {"user_id": "123"}. Si no se muestran memorias, Memory Bank no tiene ninguna memoria para el alcance proporcionado.

El alcance de una memoria se define cuando se genera o crea la memoria, y es inmutable.

Puedes usar RetrieveMemories para realizar las siguientes operaciones para un alcance en particular:

En los casos en los que tienes muchas memorias para un alcance en particular, puedes usar la búsqueda de similitud para recuperar solo las memorias más similares. Para ello, proporciona parámetros de búsqueda de similitud. Memory Bank solo considera las memorias que tienen exactamente el mismo alcance que la solicitud cuando realiza la búsqueda de similitud. La búsqueda de similitud compara los vectores de incorporación entre los hechos de las memorias y la consulta de búsqueda de la solicitud.

Las memorias que se muestran se ordenan de la más similar (distancia euclidiana más corta) a la menos similar (distancia euclidiana más grande):

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
    ),
]
"""

Reemplaza lo siguiente:

  • QUERY: Es la consulta para la que se realizará la búsqueda de similitud. Por ejemplo, puedes usar el último turno de usuario de la conversación como la consulta.

  • SCOPE: Es un diccionario que representa el alcance de la búsqueda de similitud. Por ejemplo, {"user_id": "123"}. Solo se consideran las memorias con el mismo alcance que la solicitud.

Recupera todas las memorias

Si no se proporcionan parámetros de búsqueda de similitud, RetrieveMemories muestra todas las memorias que tienen el alcance proporcionado, independientemente de su similitud con la conversación actual.

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."
      }
    ),
]
"""

Reemplaza lo siguiente:

  • SCOPE: Es un diccionario que representa el alcance de la recuperación. Por ejemplo, {"user_id": "123"}. Solo se muestran las memorias con el mismo alcance que la solicitud.

Enumera memorias

Usa ListMemories para memorias de tu Memory Bank sin filtrado basado en el alcance. Para la recuperación basada en el alcance, usa RetrieveMemories en su lugar. No se recomienda ListMemories para la recuperación de latencia baja.

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

Filtra memorias

En esta sección, se describe cómo usar filtros para restringir las memorias que se recuperan. Puedes aplicar los siguientes filtros:

  • Metadatos con el atributo filter_groups para la recuperación basada en el alcance.

  • Campos del sistema con filter Los campos del sistema incluyen topics, create_time, update_time y fact de las memorias.

El filtrado de metadatos y campos del sistema se puede usar en la misma solicitud.

Filtrar por metadatos

Cuando creas, actualizas o generas memorias, puedes aplicar metadatos estructurados a las memorias almacenadas:

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}
)

Puedes filtrar estos metadatos cuando recuperas memorias con el atributo filter_groups. Los filtros de metadatos se definen en forma normal disyuntiva (DNF), que es una expresión lógica de OR de AND.

Por ejemplo, la siguiente solicitud recuperará memorias que incluyen los metadatos ({"my_string_key": {"string_value": "my_value"}} Y {"my_double_key": {"double": 1.23}}) O {"my_string_key": {"string_value": "other"}}.

Diccionario

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"}
          }
        ]
      }
    ]
  }
)

Basado en clases

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 del sistema

Puedes filtrar los campos del sistema con el atributo filter, que espera un valor de cadena con la sintaxis EBNF. Los campos del sistema incluyen create_time, update_time, fact, y topics.

La sintaxis EBNF tiene los siguientes requisitos cuando se construye una cadena de filtro:

  • Para combinar filtros, usa AND y OR.
  • La cadena debe usar comillas dobles ".
  • Los campos de fecha y hora (como create_time) usan una cadena entre comillas dobles que representa la fecha y hora ISO 8601 o un campo numérico que representa microsegundos desde la época de Unix.

Por ejemplo, el siguiente filtro se puede usar para recuperar memorias en las que fact incluye la subcadena "allergies" y update_time fue posterior al 1 de enero 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

Las memorias generadas se etiquetan automáticamente con el tema de memoria pertinente.

Para filtrar temas administrados, usa topics.managed_memory_topic como nombre de campo y el ManagedTopicEnum esperado como valor, como topics.managed_memory_topic: USER_PREFERENCES.

Para filtrar temas personalizados, usa topics.custom_memory_topic_label como nombre de campo y la etiqueta del tema 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.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

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