Generar recuerdos

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 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 borrar o actualizar los recuerdos existentes con el mismo alcance en función de 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.

  • De forma predeterminada, Memory Bank tendrá en cuenta todos los recuerdos existentes para el mismo alcance durante la consolidación. Si deseas restringir qué recuerdos son aptos para la consolidación de forma más detallada con metadatos, usa la estrategia de combinación de metadatos REQUIRE_EXACT_MATCH.

  • De forma predeterminada, solo se usa la revisión más reciente de una memoria para la comparación. Para identificar mejor las tendencias a largo plazo y corroborar los datos, puedes aumentar revisions_per_candidate_count cuando crees tu instancia de Agent Platform para incluir más revisiones históricas en la lógica de consolidación.

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 considera Memory Bank que es significativa y, por lo tanto, debe persistir como recuerdos generados. Memory Bank admite dos tipos de temas de memoria:

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

  Diccionario

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

  Basado 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."""
      }
  }
  

  Basado 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 significativa sobre el usuario, como nombres, relaciones, pasatiempos y fechas importantes. Por ejemplo, "Trabajo en Google" o "Mi aniversario de boda es el 31 de diciembre".

• Preferencias del usuario (USER_PREFERENCES): Gustos, aversiones, estilos preferidos o patrones 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 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 olvidar (EXPLICIT_INSTRUCTIONS): Es la información que el usuario le pide explícitamente al agente que recuerde o olvide. Por ejemplo, si el usuario dice "Recuerda que uso principalmente Python", Memory Bank genera una memoria como "Uso principalmente Python".

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

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

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.

Uso de metadatos durante la consolidación

Puedes adjuntar metadatos a los recuerdos generados. Los metadatos te permiten almacenar información estructurada (cadenas, números de punto flotante de doble precisión, valores 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.

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

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

Si usas un metadata_merge_strategy, puedes controlar cómo los metadatos nuevos interactúan 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á.

Genera 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.

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

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 memoria con uno de los siguientes métodos:

• GenerateMemories: Ingresa datos en 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 en intervalos regulares dentro de una sesión.
• IngestEvents: Ingresa datos en Memory Bank de forma continua y permite que Memory Bank los procese cuando se cumplan tus criterios de activación. Este método es útil cuando tienes un flujo continuo de eventos y deseas 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 memoria extrae el contexto clave de las conversaciones fuente y lo combina con las memorias existentes para el mismo permiso. Por ejemplo, puedes crear recuerdos a nivel de la sesión con un alcance 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 es que se generó 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 ella:

• CREATED: Indica que se agregó un recuerdo nuevo, que representa un concepto novedoso que no se capturó en los recuerdos existentes.

• UPDATED: Indica que se actualizó una memoria existente, lo que sucede si la memoria abarcaba conceptos similares a la información recién extraída. 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.

En el caso de los recuerdos de 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 recuerdos como una operación de bloqueo es útil cuando deseas inspeccionar manualmente los recuerdos generados o notificar a los usuarios finales qué recuerdos se generaron.

Sin embargo, para los agentes de producción, generalmente 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 latencia adicional esperando una respuesta. Si quieres 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 desacopla 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:

• Proporciona eventos directamente en la carga útil.

• Proporciona eventos con Agent Platform Sessions.

• Proporciona hechos preextraídos para consolidarlos con las memorias existentes para el mismo permiso.

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

Usar 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. De estos eventos se extrae información significativa 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.

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

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

Cómo usar Agent Platform Sessions como fuente de datos

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

Para definir el alcance de las memorias generadas, Memory Bank extrae y usa el ID del 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.

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

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.

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
)

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 memorias extraídas 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 se encarguen 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 hechos preextraídos 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.

Cómo usar la entrada multimodal

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 fuente. Todo el resto del contenido, incluidas las llamadas a funciones y las respuestas, se ignoran cuando se generan recuerdos.

Se pueden extraer recuerdos de las imágenes, los videos y el audio que proporciona el usuario. Si Memory Bank considera que el contexto proporcionado por la entrada multimodal es significativo para interacciones futuras, es posible que se cree 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:

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

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?