Revisiones de memoria

Agent Platform Memory Bank mantiene automáticamente un historial de versiones de tus recuerdos a través de recursos de revisión de memoria. Cada vez que se crea o modifica una memoria, se guarda una nueva revisión inmutable, lo que proporciona transparencia sobre cómo evoluciona la información y qué se extrajo en cada paso.

En este documento, se explica el ciclo de vida de las memorias y sus revisiones, y se describen operaciones como enumerar, obtener y revertir revisiones.

Para obtener más información sobre cómo generar recuerdos, consulta Genera recuerdos.

Ciclo de vida de un recuerdo y sus revisiones

Fuentes de datos y revisiones de la memoria

Los recuerdos se pueden crear, actualizar o borrar de forma directa (con CreateMemory, UpdateMemory o DeleteMemory, respectivamente) o de forma dinámica (con GenerateMemories). Los recursos de revisión de recuerdos proporcionan un historial de versiones completo de un recurso de recuerdo en todas las operaciones de mutación. Cada vez que se crea o modifica la memoria, se guarda automáticamente una revisión nueva e inmutable. Esto te brinda transparencia sobre cómo evolucionó una memoria y (para la generación de memorias) qué información específica se extrajo y consolidó en cada paso.

Cada recurso de memoria tiene uno o más recursos de revisión de memoria secundarios asociados:

  • Los recursos Memory siempre reflejan el estado actual y consolidado de la información. Una sola memoria puede reflejar datos derivados de varias solicitudes y fuentes de datos.

    Memory(
        create_time=datetime.datetime(...),
        fact='This is my current memory content after consolidation',
        name='projects/.../locations/.../reasoningEngines/../memories/...',
        scope={
          'my_scope_key': 'my_scope_value'
        },
        topics=[
          MemoryTopicId(
            managed_memory_topic=<ManagedTopicEnum.USER_PERSONAL_INFO: 'USER_PERSONAL_INFO'>
          ),
        ],
        update_time=datetime.datetime(...)
    )
    
  • Los recursos MemoryRevisions representan los estados históricos de la memoria superior. Cada revisión es una instantánea de la memoria en un evento de mutación. Si se modificó una memoria con GenerateMemories, la revisión también incluye la información que se extrajo de la fuente de datos (extracted_memories) antes de que se consolidara con el contenido existente de la memoria.

    MemoryRevision(
        create_time=datetime.datetime(...),
        expire_time=datetime.datetime(...),
        extracted_memories=[
          IntermediateExtractedMemory(
            fact='This information was extracted from my data source'
          ),
        ],
        fact='This is my current memory content after consolidation',
        name='projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...'
    )
    

    Las revisiones de memoria están habilitadas de forma predeterminada. Para inhabilitar las revisiones de memoria, consulta Inhabilita las revisiones de memoria.

Creación de recuerdos

Los recuerdos se pueden crear directamente con CreateMemory o de forma dinámica con GenerateMemories. Con la generación de memorias, se crea una memoria si no hay memorias existentes que cubran información similar para el mismo permiso:

# Direct creation using CreateMemory
client.memory_banks.memories.create(name=memory_bank_name, ...)

# Dynamic creation using GenerateMemory
client.memory_banks.memories.generate(name=memory_bank_name, ...)

Cuando se crea una memoria, se crean un solo recurso Memory y un MemoryRevision secundario:

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my original fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Actualización de la memoria

Los recuerdos se pueden actualizar directamente con UpdateMemory o de forma dinámica con GenerateMemories. Con la generación de memoria, las memorias se actualizan de forma dinámica cuando el proceso de consolidación decide que la información nueva es duplicada, complementaria o contradictoria con todas las memorias existentes para el mismo alcance.

# Direct update using UpdateMemory
client.memory_banks.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

Cuando se actualiza una memoria, se actualiza el recurso Memory existente y se crea un nuevo MemoryRevision secundario.

client.memory_banks.memories.get(name=memory_name)
"""
Memory(
  name="projects/123/locations/us-central1/reasoningEngines/456/memories/789",
  fact="This is my updated fact.",
  ...
)
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Borrado de memoria

Los recuerdos se pueden usar directamente con DeleteMemory o de forma dinámica con GenerateMemories. Con la generación de memoria, los recuerdos se borran de forma dinámica cuando el proceso de consolidación decide que la información nueva invalida la información existente para el mismo alcance.

# Direct deletion using UpdateMemory
client.memory_banks.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.memory_banks.memories.generate(name=memory_bank_name, ...)

Cuando se borra una memoria, se borra el recurso Memory existente y se crea un nuevo MemoryRevision secundario. El fact en la revisión de memoria más reciente está vacío porque refleja una mutación de eliminación.

client.memory_banks.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.memory_banks.memories.revisions.list(name=memory_name))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/789",
    fact="",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/456",
    fact="This is my updated fact",
    ...
  ),
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    fact="This is my original fact",
    ...
  )
]
"""

Solo se puede acceder a las revisiones de la memoria secundaria durante un máximo de 48 horas después de que se borre la memoria principal. Durante este período de recuperación, puedes seguir inspeccionando tus revisiones de memoria y recuperarla revirtiéndola a una revisión anterior.

Operaciones de revisión de memoria

En esta sección, se describe cómo puedes inspeccionar las revisiones de la memoria y revertir una memoria a una revisión anterior.

Enumera las revisiones

Puedes inspeccionar las revisiones de memoria en la consola de Google Cloud o con el SDK de Agent Platform.

Console

Para ver las revisiones de memoria en la consola de Google Cloud , se requiere el permiso aiplatform.memoryRevisions.list (incluido en roles/aiplatform.memoryViewer y roles/aiplatform.memoryUser) y no está disponible en el modo Exprés.

  1. Abre tu instancia en la consola de Google Cloud :

    • Instancia de Memory Bank independiente: Ve a la página Memory Bank de Agent Platform y haz clic en tu instancia.

      Ir a Memory Bank

    • Agente implementado en Agent Runtime: Ve a la página Implementaciones de Agent Platform y haz clic en tu agente.

      Ir a Implementaciones

  2. Abre la pestaña Recuerdos:

    • Recuerdos no estructurados: En una fila de recuerdos, haz clic en el menú de más acciones () > Ver revisiones.
    • Perfiles estructurados (instancias independientes): Selecciona Estructurado, elige un alcance completo, haz clic en Ver en una fila de perfil para abrir Detalles de la memoria y haz clic en Ver revisiones para ver un hecho de la memoria.

    En el panel de revisiones, se enumeran los campos Creado, Vence, Hecho y Contexto de cada revisión.

SDK de Agent Platform

Usa ListMemoryRevisions para mostrar todas las revisiones de memoria que pertenecen a una memoria.

list(client.memory_banks.memories.revisions.list(name=MEMORY_NAME))

Reemplaza lo siguiente:

  • MEMORY_NAME: Es el nombre del recurso de la memoria en el formato: projects/.../locations/.../reasoningEngines/.../memories/...

Cuando generas recuerdos, puedes proporcionar etiquetas de revisión que se aplican a las revisiones afiliadas. Las etiquetas son pares clave-valor arbitrarios. Por ejemplo, puedes etiquetar las revisiones con un ID de la fuente de datos que se usó para generar la memoria y, luego, filtrar las revisiones por esta etiqueta:

response = client.memory_banks.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.memory_banks.memories.revisions.list(
    name=MEMORY_NAME,
    config={
      "filter": "labels.data_source=\"321\""
    }
))
"""
[
  MemoryRevision(
    name="projects/123/locations/us-central1/reasoningEngines/456/memories/789/revision/123",
    labels={
      "data_source": "123"
    }
    ...
  )
]
"""

Obtén una revisión

Usa GetMemoryRevision para recuperar una revisión de memoria individual.

client.memory_banks.memories.revisions.get(name=MEMORY_REVISION_NAME)

Reemplaza lo siguiente:

  • MEMORY_REVISION_NAME: Es el nombre del recurso de la revisión de la memoria que se recuperará en el siguiente formato: projects/.../locations/.../reasoningEngines/.../memories/.../revisions/...

Revierte un recuerdo

Usa RollbackMemory para revertir una memoria a una revisión anterior.

client.memory_banks.memories.rollback(
    name="MEMORY_NAME",
    target_revision_id="REVISION_ID"
)

Reemplaza lo siguiente:

  • MEMORY_NAME: Es el nombre del recurso de la memoria que se actualizará en el siguiente formato: projects/.../locations/.../reasoningEngines/.../memories/...

  • REVISION_ID: Es el ID de la revisión a la que se debe revertir. Este es el último segmento del nombre del recurso de revisión de memoria, como 789 en projects/MyProject/locations/us-central1/reasoningEngines/123/memories/456/revisions/789.

Si quieres deshacer un cambio en una memoria realizado por GenerateMemories, revierte la memoria a su revisión anterior al cambio. La respuesta de generación de memoria incluye una referencia a la revisión anterior (previous_revision) para cada memoria actualizada o borrada:

operation = client.memory_banks.memories.generate(
  ...
)

# Rollback the first generated memory to the previous revision.
client.memory_banks.memories.rollback(
    name=operation.response.generated_memories[0].memory.name,
    target_revision_id=operation.response.generated_memories[0].previous_revision
)

Inhabilitando las revisiones de memoria

Las revisiones de memoria están habilitadas de forma predeterminada. Puedes inhabilitar las revisiones de memoria para todas las solicitudes a tu instancia de Memory Bank o para cada solicitud individual. Si las revisiones de memoria están inhabilitadas, no se crea una revisión de memoria cuando se muta la memoria.

Puedes desactivar las revisiones de memoria para todas las solicitudes a tu instancia de Memory Bank en la consola de Google Cloud (en Configuración > Retención o Configuración del servicio > Memory Bank para los agentes implementados) o con el SDK de Agent Platform:

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "disable_memory_revisions": True
  }
)

Puedes inhabilitar las revisiones de memoria a nivel de la solicitud cuando la envíes:

Generar

client.memory_banks.memories.generate(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Crear

client.memory_banks.memories.create(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Actualizar

client.memory_banks.memories.update(
  ...,
  "config": {
    "disable_memory_revisions": True
  }
)

Vencimiento de la revisión

Las revisiones de memoria no se conservan para siempre. Debes establecer el vencimiento de las revisiones o usar el vencimiento predeterminado. El tiempo de actividad (TTL) predeterminado es de 365 días. Puedes configurar el vencimiento para todas las solicitudes a tu instancia de Memory Bank o para cada solicitud individual. Una vez que vence una revisión de memoria, no está disponible para inspecciones ni reversiones.

Puedes configurar el TTL del historial de revisiones para todas las solicitudes a tu instancia de Memory Bank en la consola de Google Cloud (en Configuración > Retención o Configuración del servicio > Memory Bank para los agentes implementados) o con el SDK de Agent Platform:

client.memory_banks.create(
  managed_semantic_memory_config={
    "ttl_config": {
      # Persist memory revisions for 30 days after they're created.
      "revision_ttl": f"{30 * 60 * 60 * 24}s"
    }
  }
)

Para configurar el TTL de cada revisión de memoria a nivel de solicitud, incluye revision_expire_time o revision_ttl en tu solicitud:

TTL

config = {
    # Persist memory revisions for 30 days after they're created.
    "revision_ttl": f"{30 * 60 * 60 * 24}s"
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)

Vencimiento

import datetime

config = {
    "revision_expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(weeks=3)
}

client.memory_banks.memories.create(
  ...,
  config=config
)

client.memory_banks.memories.update(
  ...,
  config=config
)

client.memory_banks.memories.generate(
  ...,
  config=config
)