Se usó la API de Cloud Translation para traducir esta página.

Revisiones de memoria

En esta página, se describe cómo se crean y administran los recursos de revisión de memoria para el banco de memoria de Vertex AI Agent Engine.

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 un recuerdo, se guarda automáticamente una nueva revisión inmutable. Esto te brinda transparencia sobre cómo evolucionó un recuerdo y (para la generación de recuerdos) 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 la memoria están habilitadas de forma predeterminada. Para inhabilitar las revisiones de la memoria, consulta Cómo inhabilitar las revisiones de la 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 recuerdos, se crea un recuerdo si no hay recuerdos existentes que abarquen información similar para el mismo alcance:

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

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

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

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, los recuerdos se actualizan de forma dinámica cuando el proceso de consolidación decide que la información nueva es duplicada, complementaria o contradictoria con todos los recuerdos 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=agent_engine_name, ...)

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

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 crear directamente con DeleteMemory o de forma dinámica con GenerateMemories. Con la generación de recuerdos, 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=agent_engine_name, ...)

Cuando se borra un recuerdo, se borra el recurso Memory existente y se crea un nuevo recurso secundario MemoryRevision. 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 del menor solo están disponibles hasta 48 horas después de que se borra la memoria de la madre o el padre. 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 la memoria y revertir una memoria 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 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.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 formato projects/.../locations/.../reasoningEngines/.../memories/.../revisions/....

Cómo volver a 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 formato projects/.../locations/.../reasoningEngines/.../memories/....
REVISION_ID: Es el 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 memoria incluye una referencia a la revisión anterior (previous_revision) para cada memoria actualizada o borrada:

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 la 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:

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 la 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 su inspección ni para revertir los cambios.

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
)

Revisiones de memoria Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Ciclo de vida de un recuerdo y sus revisiones

Creación de recuerdos

Actualización de la memoria

Borrado de recuerdos

Operaciones de revisión de memoria

Enumera las revisiones

Obtén una revisión

Cómo volver a un recuerdo

Cómo inhabilitar las revisiones de memoria

Generar

Crear

Actualizar

Vencimiento de la revisión

TTL

Vencimiento

Revisiones de memoria