Generar recuerdos

Agent Platform Memory Bank te permite construir memorias a largo plazo a partir de las conversaciones entre el usuario y tu agente. Este proceso se produce automáticamente cuando se activa, y extrae información valiosa para interacciones futuras.

En este documento, se explica cómo funciona la generación de recuerdos, cómo personalizar la extracción de recuerdos con temas y cómo activar solicitudes de generación de recuerdos.

Para obtener información sobre cómo configurar tu entorno, consulta Configura Memory Bank.

Información sobre la generación de memoria

Memory Bank extrae memorias de los datos de origen y selecciona automáticamente memorias para una colección específica de memorias (definida por un scope) agregando, actualizando y quitando memorias con el tiempo.

Cuando activas la generación de memoria, Memory Bank realiza las siguientes operaciones:

  • Extracción: Extrae información sobre el usuario a partir de sus conversaciones con el agente. Solo se conservará la información que coincida con al menos uno de los temas de memoria de tu instancia.

  • Consolidación: Identifica si los recuerdos existentes con el mismo alcance se deben borrar o actualizar según la información extraída. Memory Bank verifica que las memorias nuevas no sean duplicadas ni contradictorias antes de combinarlas con las existentes. Si los recuerdos existentes no se superponen con la información nueva, se creará un recuerdo nuevo.

Algoritmo de generación
de memoria

Puedes inspeccionar los pasos intermedios de la generación de memoria y ver cómo cambia una memoria en varias solicitudes con las revisiones de memoria. Cada revisión incluye el resultado intermedio del paso de extracción (extracted_memories) y el paso de consolidación final (fact) para cada solicitud de generación de memoria.

list(client.memory_banks.memories.revisions.list(
  name="projects/.../locations/.../reasoningEngines/.../memories/.../revisions/..."))

"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is the output of extraction for a single request.'
      ),
    ],
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    extracted_memories=[
      IntermediateExtractedMemory(
        fact='This is my original fact.'
      ),
    ],
    ...
  )
]
"""

Temas de las memorias

Los "temas de memoria" identifican qué información Memory Bank considera significativa y, por lo tanto, debe conservarse como recuerdos generados. Memory Bank admite dos tipos de temas de memoria:

  • Temas administrados: Memory Bank define la etiqueta y las instrucciones. Solo debes proporcionar el nombre del tema administrado. Por ejemplo:

    Diccionario

    memory_topic = {
        "managed_memory_topic": {
            "managed_topic_enum": "USER_PERSONAL_INFO"
        }
    }
    

    Basada en clases

    from agentplatform.types import ManagedTopicEnum
    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
    
    memory_topic = MemoryTopic(
        managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
        )
    )
    
  • Temas personalizados: Tú defines la etiqueta y las instrucciones cuando configuras tu instancia de Memory Bank. Se usarán en la instrucción para el paso de extracción de Memory Bank. Por ejemplo:

    Diccionario

    memory_topic = {
        "custom_memory_topic": {
            "label": "business_feedback",
            "description": """Specific user feedback about their experience
            at the coffee shop. This includes opinions on drinks, food,
            pastries, ambiance, staff friendliness, service speed,
            cleanliness, and any suggestions for improvement."""
        }
    }
    

    Basada en clases

    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
    from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
    
    memory_topic = MemoryTopic(
        custom_memory_topic=CustomMemoryTopic(
            label="business_feedback",
            description="""Specific user feedback about their experience at
            the coffee shop. This includes opinions on drinks, food,
            pastries, ambiance, staff friendliness, service speed,
            cleanliness, and any suggestions for improvement."""
        )
    )
    

    Cuando uses temas personalizados, también se recomienda proporcionar algunos ejemplos para demostrar cómo se deben extraer los recuerdos de tu conversación.

De forma predeterminada, Memory Bank conserva todos los siguientes temas administrados:

  • Información del usuario (USER_PERSONAL_INFO): Información importante sobre el usuario, como nombres, relaciones, pasatiempos y fechas importantes. Por ejemplo, "Trabajo en Google" o "Mi aniversario de bodas es el 31 de diciembre".

  • Preferencias del usuario (USER_PREFERENCES): Gustos, aversiones, estilos o patrones preferidos explícitos o implícitos. Por ejemplo, "Prefiero el asiento del medio".

  • Eventos clave de la conversación y resultados de las tareas (KEY_CONVERSATION_DETAILS): Son hitos o conclusiones importantes dentro del diálogo. Por ejemplo, "Reservé boletos de avión para un viaje de ida y vuelta entre JFK y SFO. Me voy el 1 de junio de 2025 y regreso el 7 de junio de 2025".

  • Instrucciones explícitas para recordar o borrar (EXPLICIT_INSTRUCTIONS): Información que el usuario le pide explícitamente al agente que recuerde o borre. Por ejemplo, si el usuario dice "Recuerda que uso principalmente Python", el banco de memoria genera una memoria como "Uso principalmente Python".

Esto equivale a usar el siguiente conjunto de temas de memoria administrada:

Diccionario

  memory_topics = [
      {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
      {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
      {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
      {"managed_memory_topic": {"managed_topic_enum": "EXPLICIT_INSTRUCTIONS"}},
  ]

Basada en clases

from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topics = [
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
  MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS)),
]

Si quieres personalizar los temas que conserva Memory Bank, establece los temas de memoria en tu configuración de personalización cuando configures Memory Bank.

Usa metadatos durante la consolidación

Puedes adjuntar metadatos a los recuerdos generados. Los metadatos te permiten almacenar información estructurada (strings, dobles, booleanos o marcas de tiempo) junto con un hecho de la memoria. Esto es útil para filtrar o administrar los ciclos de vida de los recuerdos.

Diccionario

import datetime

client.memory_banks.memories.generate(
    ...,
    config={
        "metadata": {
            "my_string_key": {"string_value": "my_string_value"},
            "my_double_key": {"double_value": 123.456},
            "my_boolean_key": {"bool_value": True},
            "my_timestamp_key": {
                "timestamp_value": datetime.datetime(
                    2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
                )
            }
        },
        "metadata_merge_strategy": "MERGE"
    },
)

Basada en clases

import datetime

from agentplatform import types

client.memory_banks.memories.generate(
    ...,
    config=types.GenerateMemoriesConfig(
        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
                )
            ),
        },
        metadata_merge_strategy=types.MemoryMetadataMergeStrategy.MERGE,
    )
)

Con un metadata_merge_strategy, puedes controlar cómo interactúan los metadatos nuevos con los recuerdos existentes durante la consolidación:

  • MERGE: (Predeterminado) Combina los metadatos nuevos con los existentes. Si ya existe una clave, el valor nuevo reemplaza al anterior.

  • OVERWRITE: Reemplaza los metadatos de los recuerdos actualizados por los metadatos nuevos.

  • REQUIRE_EXACT_MATCH: Restringe la consolidación a los recuerdos que tienen exactamente los mismos metadatos que la solicitud. Si un recuerdo no tiene los mismos metadatos, no es apto para la consolidación y no se actualizará.

Generación de recuerdos para un subconjunto de temas

De forma predeterminada, la generación de memoria extrae datos de todos los temas de memoria que configuraste cuando configuraste tu instancia de Memory Bank. Para una solicitud GenerateMemories específica, puedes restringir la extracción a un subconjunto de temas configurados. Para configurar los temas permitidos, usa el campo allowed_topics.

Diccionario

client.memory_banks.memories.generate(
    ...,
    config={
        "allowed_topics": [
            {"managed_memory_topic": "USER_PERSONAL_INFO"},
            {"custom_memory_topic_label": "business_feedback"}
        ]
    },
)

Basada en clases

from agentplatform import types

client.memory_banks.memories.generate(
    ...,
    config=types.GenerateMemoriesConfig(
        allowed_topics=[
            types.MemoryTopicId(
                managed_memory_topic=types.ManagedTopicEnum.USER_PERSONAL_INFO
            ),
            types.MemoryTopicId(
                custom_memory_topic_label="business_feedback"
            )
        ]
    )
)

Activando la generación de memoria

Puedes activar la generación de recuerdos con uno de los siguientes métodos:

  • GenerateMemories: Transfiere datos a Memory Bank y activa la generación de memoria de inmediato. Este método es útil cuando quieres generar recuerdos en un momento específico, como al final de una sesión o a intervalos regulares dentro de una sesión.
  • IngestEvents: Transfiere datos al banco de memoria de forma continua y deja que el banco de memoria los procese cuando se cumplan los criterios de activación. Este método es útil cuando tienes un flujo continuo de eventos y quieres que Memory Bank controle automáticamente el almacenamiento en búfer y active la generación de memoria según el volumen o el tiempo. Para obtener más información, consulta Transferencia de eventos.

La generación de memorias extrae el contexto clave de las conversaciones de origen y lo combina con las memorias existentes para el mismo permiso. Por ejemplo, puedes crear memorias a nivel de la sesión con un permiso como {"user_id": "123", "session_id": "456"}. Las memorias con el mismo permiso se pueden consolidar y recuperar juntas.

GenerateMemories es una operación de larga duración. Una vez que se completa la operación, GenerateMemoriesOperation contiene una lista de recuerdos generados, si se genera alguno:

GenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="CREATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="UPDATED",
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action="DELETED",
      ),
    ]
  )
)

Cada memoria generada incluye la action que se realizó en esa memoria:

  • CREATED: Indica que se agregó una memoria nueva, que representa un concepto nuevo que no se capturó en las memorias existentes.

  • UPDATED: Indica que se actualizó un recuerdo existente, lo que sucede si el recuerdo abarcaba conceptos similares a los de la información extraída recientemente. El hecho de la memoria puede actualizarse con información nueva o permanecer igual.

  • DELETED: Indica que se borró la memoria existente porque su información era contradictoria con la información nueva extraída de la conversación.

Para los recuerdos CREATED o UPDATED, puedes usar GetMemories para recuperar el contenido completo del recuerdo. Cuando se recuperan recuerdos de DELETED, se produce un error 404.

Generando recuerdos en segundo plano

GenerateMemories es una operación de larga duración. De forma predeterminada, client.memory_banks.memories.generate es una función de bloqueo que sondea la operación hasta que se completa. Ejecutar la generación de memoria como una operación de bloqueo es útil cuando quieres inspeccionar de forma manual las memorias generadas o notificar a los usuarios finales sobre qué memorias se generaron.

Sin embargo, para los agentes de producción, por lo general, querrás ejecutar la generación de memoria en segundo plano como un proceso asíncrono. En la mayoría de los casos, el cliente no necesita usar el resultado de la ejecución actual, por lo que no es necesario incurrir en una latencia adicional mientras se espera una respuesta. Si deseas que la generación de memoria se ejecute en segundo plano, establece wait_for_completion en False:

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

Como alternativa a llamar a GenerateMemories de forma asíncrona, puedes usar IngestEvents, que separa la transferencia de eventos de la generación de memoria y procesa los eventos en segundo plano de forma predeterminada.

Fuentes de datos

Existen varias formas de proporcionar datos de origen para la generación de recuerdos:

Cuando proporcionas eventos directamente en la carga útil o usas sesiones, la información se extrae de la conversación y se consolida con las memorias existentes. Si solo quieres extraer información de estas fuentes de datos, puedes inhabilitar la consolidación:

client.memory_banks.memories.generate(
    ...
    config={
        "disable_consolidation": True
    }
)

Usa eventos en la carga útil como fuente de datos

Usa direct_contents_source cuando quieras generar recuerdos con eventos proporcionados directamente en la carga útil. Se extrae información significativa de estos eventos y se consolida con la información existente para el mismo alcance. Este enfoque se puede usar si utilizas un almacenamiento de sesiones diferente al de Agent Platform Sessions.

Diccionario

Los eventos deben incluir diccionarios Content.

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I work with LLM agents!"}
      ]
    }
  }
]

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": EVENTS
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Reemplaza lo siguiente:

  • SCOPE: Es un diccionario que representa el alcance de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"} Solo se consideran para la consolidación las memorias con el mismo permiso.

Basada en clases

Los eventos deben incluir objetos Content.

from google import genai
from agentplatform import types

events = [
  types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="I work with LLM agents!")
      ]
    )
  )
]

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_contents_source={
      "events": events
    },
    # For example, `scope={"user_id": "123"}`.
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

Reemplaza lo siguiente:

  • SCOPE: Es un diccionario que representa el alcance de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"} Solo se consideran para la consolidación las memorias con el mismo permiso.

Usa sesiones de Agent Platform como fuente de datos

Con Sessions, Memory Bank usa los eventos de sesión como la conversación de origen para la generación de memoria.

Para definir el alcance de las memorias generadas, Memory Bank extrae y usa el ID de usuario de la sesión de forma predeterminada. Por ejemplo, el alcance de los recuerdos se almacena como {"user_id": "123"} si el user_id de la sesión es "123". También puedes proporcionar un scope directamente, lo que anula el uso del user_id de la sesión como alcance.

Diccionario

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source={
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      "session": "SESSION_NAME"
  },
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

Reemplaza lo siguiente:

  • SESSION_NAME: Es el nombre de la sesión completamente calificado.

  • SCOPE (opcional): Es un diccionario que representa el alcance de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"} Solo se consideran para la consolidación las memorias con el mismo permiso. Si no se proporciona, se usa {"user_id": session.user_id}.

Basada en clases

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
      # For example, projects/.../locations/.../reasoningEngines/.../sessions/...
      session="SESSION_NAME"
  ),
  # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

De manera opcional, puedes proporcionar un período que indique qué eventos de la sesión se deben incluir. Si no se proporciona, se incluyen todos los eventos de la sesión.

Diccionario

import datetime

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source={
      "session": "SESSION_NAME",
      # Extract memories from the last hour of events.
      "start_time": datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      "end_time": datetime.datetime.now(tz=datetime.timezone.utc)
  },
  scope=SCOPE
)

Basada en clases

import datetime

from agentplatform import types

client.memory_banks.memories.generate(
  name=memory_bank.name,
  vertex_session_source=types.GenerateMemoriesRequestVertexSessionSource(
      session="SESSION_NAME",
      # Extract memories from the last hour of events.
      start_time=datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(seconds=24 * 60),
      end_time=datetime.datetime.now(tz=datetime.timezone.utc)
  ),
  scope=SCOPE
)

Consolidación de memorias extraídas previamente

Como alternativa al uso del proceso de extracción automática de Memory Bank, puedes proporcionar directamente recuerdos extraídos previamente. Las memorias de fuentes directas se consolidarán con las memorias existentes para el mismo permiso. Esto puede ser útil cuando quieres que tu agente o un humano con intervención humana sea responsable de extraer recuerdos, pero aún quieres aprovechar la consolidación de Memory Bank para asegurarte de que no haya recuerdos duplicados o contradictorios.

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Reemplaza lo siguiente:

  • FACT: Es el hecho extraído previamente que se debe consolidar con los recuerdos existentes. Puedes proporcionar hasta 5 datos extraídos previamente en una lista como la siguiente:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
    
  • SCOPE: Es un diccionario que representa el alcance de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se consideran para la consolidación las memorias con el mismo permiso.

Usa entradas multimodales

Puedes extraer recuerdos de entradas multimodales. Sin embargo, los recuerdos solo se extraen del texto, los archivos intercalados y los datos de archivos del contenido de origen. Todo el resto del contenido, incluidas las llamadas a funciones y las respuestas, se ignora cuando se generan recuerdos.

Los recuerdos se pueden extraer de imágenes, videos y audios que proporcione el usuario. Si Memory Bank considera que el contexto proporcionado por la entrada multimodal es significativo para interacciones futuras, se puede crear una memoria textual que incluya información extraída de la entrada. Por ejemplo, si el usuario proporciona una imagen de un golden retriever con el texto "Este es mi perro", Memory Bank genera un recuerdo como "Mi perro es un golden retriever".

Por ejemplo, puedes proporcionar una imagen y un contexto para la imagen en la carga útil:

Diccionario

with open(file_name, "rb") as f:
    inline_data = f.read()

events =  [
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "This is my dog"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": inline_data
          }
        },
        {
          "file_data": {
            "file_uri": "gs://cloud-samples-data/generative-ai/image/dog.jpg",
            "mime_type": "image/jpeg"
          }
        },
      ]
    }
  }
]

Basada en clases

from google import genai
from agentplatform import types

with open(file_name, "rb") as f:
    inline_data = f.read()

events = [
  types.GenerateMemoriesRequestDirectContentsSourceEvent(
    content=genai.types.Content(
      role="user",
      parts=[
        genai.types.Part.from_text(text="This is my dog"),
        genai.types.Part.from_bytes(
          data=inline_data,
          mime_type="image/jpeg",
        ),
        genai.types.Part.from_uri(
          file_uri="gs://cloud-samples-data/generative-ai/image/dog.jpg",
          mime_type="image/jpeg",
        )
      ]
    )
  )
]

¿Qué sigue?

Guía

Aprende a recuperar recuerdos generados y subidos.

Guía

Obtén más información para configurar Memory Bank.

Guía

Obtén información para inspeccionar las revisiones de la memoria.