Revisiones de memoria

Memory Bank mantiene automáticamente un historial de versiones de tus recuerdos a través de recursos de revisión de la memoria. Cada vez que se crea o modifica un recuerdo, 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 los recuerdos y sus revisiones, y se describen operaciones como la enumeración, la obtención y la reversión de 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 directamente (con CreateMemory, UpdateMemory o DeleteMemory, respectivamente) o de forma dinámica (con GenerateMemories). Los recursos de revisión de recuerdos proporcionan un historial completo de versiones 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ó un recuerdo y (en el caso de la generación de memoria) 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 de 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 principal. Cada revisión es una instantánea de la memoria en un evento de mutación. Si se modificó un recuerdo 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 del recuerdo.

    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 Cómo inhabilitar 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 memoria, se crea una memoria si no hay memorias existentes que abarquen información similar para el mismo alcance:

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

# Dynamic creation using GenerateMemory
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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.agent_engines.memories.update(name=memory_name, ...)

# Dynamic update using GenerateMemories
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

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

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

list(client.agent_engines.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 recuerdos

Los recuerdos se pueden recuperar 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.agent_engines.memories.delete(name=memory_name, ...)

# Dynamic delete using GenerateMemories
client.agent_engines.memories.generate_memories(name=memory_bank_name, ...)

Cuando se borra un recuerdo, 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.agent_engines.memories.get(name=memory_name)
"""
404 Not Found.
"""

list(client.agent_engines.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",
    ...
  )
]
"""

Las revisiones de la memoria secundaria solo son accesibles hasta 48 horas después de que se borra la memoria principal. Durante este período de recuperación, puedes seguir inspeccionando las revisiones de tu 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 recuerdos y revertir un recuerdo a una revisión anterior.

Enumera las revisiones

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

list(client.agent_engines.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 generes recuerdos, puedes proporcionar etiquetas de revisión que se apliquen a las revisiones afiliadas. Las etiquetas son pares clave-valor arbitrarios. Por ejemplo, puedes etiquetar 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.agent_engines.memories.generate(
    ...,
    config={
        "revision_labels": {
            "data_source": "321"
        }
    }
)

list(client.agent_engines.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.agent_engines.memories.revisions.get(name=MEMORY_REVISION_NAME)

Reemplaza lo siguiente:

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

Revertir un recuerdo

Usa RollbackMemory para revertir un recuerdo a una revisión anterior.

client.agent_engines.memories.rollback(
    name=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: ID de la revisión a la que se debe revertir. 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 que GenerateMemories realizó en un recuerdo, revierte el recuerdo a la revisión anterior al cambio. La respuesta de generación de recuerdos incluye una referencia a la revisión anterior (previous_revision) para cada recuerdo actualizado o borrado:

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

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

Cómo inhabilitar 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 inhabilitar las revisiones de memoria para todas las solicitudes a tu instancia de Memory Bank cuando la configures:

memory_bank = client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": {
        "disable_memory_revisions": True
      }
    }
  }
)

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

Generar

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

Crear

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

Actualizar

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

Vencimiento de la revisión

Las revisiones de memoria no se conservan para siempre. Debes establecer la fecha de vencimiento de las revisiones o usar la fecha de vencimiento predeterminada. 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 inspección ni reversiones.

Puedes configurar el TTL para todas las solicitudes a tu instancia de Memory Bank cuando la configures:

client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_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 la 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.agent_engines.memories.create(
  ...,
  config=config
)

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

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

Vencimiento

import datetime

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

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

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

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