Generar recuerdos

Memory Bank te permite crear recuerdos a largo plazo a partir de las conversaciones entre el usuario y tu agente. En esta página se describe cómo funciona la generación de recuerdos, cómo puedes personalizar la forma en que se extraen y cómo activar la generación de recuerdos.

Para completar los pasos que se muestran en esta guía, primero debes seguir los pasos de Configuración de Memory Bank.

Información sobre la generación de recuerdos

Memory Bank extrae recuerdos de datos de origen y los organiza automáticamente en una colección específica (definida por un scope) añadiendo, actualizando y eliminando recuerdos con el tiempo.

Cuando activas la generación de recuerdos, 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 se deben eliminar o actualizar los recuerdos que ya existen con el mismo ámbito en función de la información extraída. Banca de recuerdos comprueba que los recuerdos nuevos no sean duplicados ni contradictorios antes de combinarlos con los que ya tienes. Si los recuerdos que ya tienes no se solapan con la información nueva, se creará un nuevo recuerdo.

Temas de recuerdos

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

  • Temas gestionados: la etiqueta y las instrucciones las define Memory Bank. Solo tienes que proporcionar el nombre del tema gestionado. Por ejemplo:

    Diccionario

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

    Basado en clases

    from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.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 al configurar tu instancia de Memory Bank. Se usarán en la petición del 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."""
    }
}

    Basado en clases

    from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.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 se usan temas personalizados, se recomienda proporcionar ejemplos con pocos ejemplos para demostrar cómo se deben extraer los recuerdos de la conversación.

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

  • Información personal (USER_PERSONAL_INFO): información personal importante sobre el usuario, como nombres, relaciones, aficiones y fechas importantes. Por ejemplo, "Trabajo en Google" o "Mi aniversario de boda es el 31 de diciembre".
  • Preferencias de los usuarios (USER_PREFERENCES): gustos, rechazos, estilos o patrones preferidos, ya sean 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): hitos o conclusiones importantes de la conversación. Por ejemplo, "He reservado billetes de avión de ida y vuelta entre JFK y SFO. Me voy el 1 de junio del 2025 y vuelvo el 7 de junio del 2025".
  • Instrucciones explícitas para recordar o olvidar (EXPLICIT_INSTRUCTIONS): información que el usuario pide explícitamente al agente que recuerde o que olvide. Por ejemplo, si el usuario dice "Recuerda que uso principalmente Python", Memory Bank genera un recuerdo como "Uso principalmente Python".

Es lo mismo que usar el siguiente conjunto de temas de memoria gestionada:

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

Basado en clases

from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.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, define los temas de la memoria en tu configuración de personalización al configurar Memory Bank.

Activar la generación de recuerdos

Puedes activar la generación de recuerdos con GenerateMemories al final de una sesión o a intervalos regulares durante una sesión. La generación de recuerdos extrae el contexto clave de las conversaciones de origen y lo combina con los recuerdos existentes del mismo ámbito. Por ejemplo, puedes crear recuerdos a nivel de sesión usando un ámbito como {"user_id": "123", "session_id": "456"}. Los recuerdos con el mismo ámbito se pueden consolidar y recuperar juntos.

GenerateMemories es una operación de larga duración. Una vez completada la operación, el AgentEngineGenerateMemoriesOperation contiene una lista de los recuerdos generados, si se ha generado alguno:

AgentEngineGenerateMemoriesOperation(
  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 recuerdo generado incluye la action que se ha realizado en él:

  • CREATED: indica que se ha añadido un nuevo recuerdo, que representa un concepto nuevo que no se había captado en los recuerdos anteriores.
  • UPDATED: indica que se ha actualizado una memoria, lo que ocurre si la memoria abarca conceptos similares a la información recién extraída. El dato de la memoria puede actualizarse con información nueva o seguir siendo el mismo.
  • DELETED: indica que se ha eliminado la memoria porque su información era contradictoria con la nueva información extraída de la conversación.

En el caso de los recuerdos CREATED o UPDATED, puedes usar GetMemories para recuperar todo el contenido del recuerdo. Al recuperar recuerdos de DELETED, se produce un error 404.

Generar recuerdos en segundo plano

GenerateMemories es una operación de larga duración. De forma predeterminada, client.agent_engines.generate_memories es una función de bloqueo que sondea la operación hasta que se completa. Ejecutar la generación de recuerdos como una operación de bloqueo es útil cuando quieres inspeccionar manualmente los recuerdos generados o notificar a los usuarios finales qué recuerdos se han generado.

Sin embargo, en el caso de los agentes de producción, lo habitual es 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 esperando una respuesta. Si quieres que la generación de memoria se ejecute en segundo plano, define wait_for_completion como False:

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

Fuentes de datos

Hay varias formas de proporcionar datos de origen para generar memoria:

Cuando proporcionas eventos directamente en la carga útil o usas sesiones de Vertex AI Agent Engine, se extrae información de la conversación y se consolida con los recuerdos existentes. Si solo quiere extraer información de estas fuentes de datos, puede inhabilitar la consolidación:

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

Usar eventos en la carga útil como fuente de datos

Usa direct_contents_source cuando quieras generar recuerdos a partir de eventos proporcionados directamente en la carga útil. Se extrae información útil de estos eventos y se consolida con la información existente del mismo ámbito. Este enfoque se puede usar si utilizas un almacenamiento de sesiones diferente al de las sesiones de Vertex AI Agent Engine.

Diccionario

Los eventos deben incluir diccionarios Content.

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

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

Haz los cambios siguientes:

  • SCOPE: diccionario que representa el ámbito de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se tienen en cuenta para la consolidación los recuerdos que tengan el mismo ámbito.

Basado en clases

Los eventos deben incluir objetos Content.

from google import genai
import vertexai

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

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

Haz los cambios siguientes:

  • SCOPE: diccionario que representa el ámbito de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se tienen en cuenta para la consolidación los recuerdos que tengan el mismo ámbito.

Usar sesiones de Vertex AI Agent Engine como fuente de datos

Con las sesiones de Agent Engine, Memory Bank usa los eventos de sesión como conversación de origen para generar la memoria.

Para acotar las memorias generadas, Memory Bank extrae y usa el ID de usuario de la sesión de forma predeterminada. Por ejemplo, el ámbito 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 ámbito.

Diccionario

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

Haz los cambios siguientes:

  • SESSION_NAME: el nombre de la sesión completo.

  • (Opcional) SCOPE: un diccionario que representa el ámbito de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se tienen en cuenta para la consolidación los recuerdos que tengan el mismo ámbito. Si no se proporciona, se usa {"user_id": session.user_id}.

Basado en clases

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

También puede proporcionar un intervalo de tiempo 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.agent_engines.memories.generate(
  name=agent_engine.api_resource.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
)

Basado en clases

import datetime

client.agent_engines.memories.generate(
  name=agent_engine.api_resource.name,
  vertex_session_source=vertexai.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
)

Consolidar recuerdos preextraídos

Como alternativa al proceso de extracción automática de Recuerdos, puedes proporcionar directamente los recuerdos ya extraídos. Los recuerdos de fuentes directas se combinarán con los recuerdos que ya haya del mismo ámbito. Esto puede ser útil cuando quieras que tu agente o un humano sea responsable de extraer recuerdos, pero sigas queriendo aprovechar la consolidación de Memory Bank para asegurarte de que no haya recuerdos duplicados o contradictorios.

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

Haz los cambios siguientes:

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

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE: diccionario que representa el ámbito de los recuerdos generados. Por ejemplo, {"session_id": "MY_SESSION"}. Solo se tienen en cuenta para la consolidación los recuerdos que tengan el mismo ámbito.

Usar la entrada multimodal

Puedes extraer recuerdos a partir de entradas multimodales. Sin embargo, las memorias solo se extraen del texto, los archivos insertados y los datos de archivos del contenido de origen. El resto del contenido, incluidas las llamadas a funciones y las respuestas, se ignora al generar recuerdos.

Los recuerdos se pueden extraer de imágenes, vídeos y audios proporcionados por el usuario. Si Memory Bank considera que el contexto proporcionado por la entrada multimodal es significativo para futuras interacciones, 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 el contexto de 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"
          }
        },
      ]
    }
  }
]

Basado en clases

from google import genai
import vertexai

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

events = [
  vertexai.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",
        )
      ]
    )
  )
]

Cuando se usan las sesiones de Vertex AI Agent Engine como fuente de datos, el contenido multimodal se proporciona directamente en los eventos de la sesión.

Siguientes pasos