Cómo recuperar recuerdos

En esta página, se describe cómo recuperar los recuerdos generados y subidos desde Memory Bank. Para conocer todo el flujo de trabajo de configuración, generación y uso de Memory Bank, consulta la Guía de inicio rápido con la API de REST.

Antes de comenzar

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

Operaciones de recuperación

Tienes las siguientes opciones para recuperar los recuerdos generados:

Obtener memoria: Obtén el contenido completo de una sola memoria con el SDK de Vertex AI.
Enumera recuerdos: Enumera recuerdos con el SDK de Vertex AI o la consola de Google Cloud .
Recupera recuerdos: Con el SDK de Vertex AI, recupera recuerdos con la recuperación de recuerdos basada en el alcance. Recupera recuerdos con la búsqueda por similitud o todos los recuerdos dentro del alcance.

Obtener memoria

Usa GetMemories para obtener el contenido completo de un solo recuerdo:

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

Reemplaza lo siguiente:

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

Lista de recuerdos

Console

En el caso de los agentes implementados, puedes usar la consola de Google Cloud para enumerar todos los recuerdos asociados con tu instancia de Agent Engine:

En la consola de Google Cloud , ve a la página Vertex AI Agent Engine.

Ir a Agent Engine

Las instancias de Agent Engine que forman parte del proyecto seleccionado aparecen en la lista. Puedes usar el campo Filtro para filtrar la lista según la columna que especifiques.
Haz clic en el nombre de tu instancia de Agent Engine.
Haz clic en la pestaña Recuerdos. Se muestra una lista de recuerdos por ID.

SDK de Vertex AI

Usa ListMemories para recuperar todos los recuerdos de tu banco de recuerdos.

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

Recupera recuerdos con la recuperación basada en el alcance

Puedes usar RetrieveMemories para recuperar recuerdos de un alcance en particular. Solo se devuelven los recuerdos que tienen exactamente el mismo alcance (independientemente del orden) que la solicitud de recuperación. Por ejemplo, puedes recuperar todos los recuerdos que se limitan a un usuario en particular con {"user_id": "123"}. Si no se devuelven recuerdos, significa que Memory Bank no tiene recuerdos para el alcance proporcionado.

El alcance de un recuerdo se define cuando se genera o crea el recuerdo, y es inmutable.

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

Cómo recuperar recuerdos con la búsqueda por similitud
Recupera todos los recuerdos

Recupera recuerdos con la búsqueda por similitud

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

Los recuerdos devueltos se ordenan de más similar (distancia euclidiana más corta) a menos similar (distancia euclidiana más grande):

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

Reemplaza lo siguiente:

QUERY: Es la búsqueda para la que se realizará la búsqueda por similitud. Por ejemplo, puedes usar el último turno del usuario en la conversación como la búsqueda.
SCOPE: Es un diccionario que representa el alcance de la búsqueda de similitud. Por ejemplo, {"user_id": "123"} Solo se consideran los recuerdos con el mismo alcance que la solicitud.

Recupera todos los recuerdos

Si no se proporcionan parámetros de búsqueda de similitud, RetrieveMemories devuelve todos los recuerdos que tienen el alcance proporcionado, independientemente de su similitud con la conversación actual.

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

Reemplaza lo siguiente:

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

Cómo filtrar recuerdos

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

Son los metadatos que usan el atributo filter_groups para la recuperación basada en el alcance.
Campos del sistema que usan filter. Los campos del sistema incluyen topics, create_time, update_time y fact de los recuerdos.

Se pueden usar los filtros de metadatos y de campos del sistema en la misma solicitud.

Filtrar por metadatos

Cuando creas, actualizas o generas recuerdos, puedes aplicar metadatos estructurados a los recuerdos almacenados:

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

Puedes filtrar en función de estos metadatos cuando recuperes recuerdos 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á los recuerdos que incluyan 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.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"}
          }
        ]
      }
    ]
  }
)

Basado en clases

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

Cómo filtrar por campos del sistema

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

La sintaxis de 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) deben usar una cadena entre comillas dobles que represente la fecha y hora ISO 8601 o un campo numérico que represente microsegundos desde la época de Unix.

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

Los recuerdos generados se etiquetan automáticamente con el tema de recuerdo pertinente.

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

Para filtrar por temas personalizados, usa topics.custom_memory_topic_label como nombre del campo y la etiqueta del tema esperado como el 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}
)

Cómo recuperar recuerdos Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Operaciones de recuperación

Obtener memoria

Lista de recuerdos

Console

SDK de Vertex AI

Recupera recuerdos con la recuperación basada en el alcance

Recupera recuerdos con la búsqueda por similitud

Recupera todos los recuerdos

Cómo filtrar recuerdos

Filtrar por metadatos

Diccionario

Basado en clases

Cómo filtrar por campos del sistema

Filtrar por temas

Cómo recuperar recuerdos