Uso de la memoria del agente

Cada sesión de Managed Agents comienza con un contexto nuevo de forma predeterminada. Cuando una sesión termina, cualquier estado que el agente haya acumulado desaparece. Los "memory stores" (almacenes de memoria) permiten que el agente conserve información entre sesiones: preferencias del usuario, convenciones del proyecto, errores previos y contexto del dominio.

Descripción general

Un almacén de memoria es una colección de documentos de texto con alcance de espacio de trabajo, optimizada para Claude. Cuando adjuntas un almacén a una sesión, se monta como un directorio dentro del sandbox de la sesión. El agente lo lee y escribe con las mismas herramientas de archivos que usa para el resto del sistema de archivos, y se agrega automáticamente a la indicación del sistema una nota que describe cada montaje, indicándole al agente dónde buscar. El conjunto de herramientas del agente es necesario para estas interacciones; asegúrate de habilitarlo durante la creación del agente. En sandboxes autoalojados, ese directorio no es un montaje en vivo. En su lugar, el worker de entorno del SDK descarga cada almacén adjunto en tu sandbox antes de que se ejecuten las herramientas del agente y mantiene esa copia sincronizada con el almacén.

Cada memoria en un almacén se direcciona mediante una ruta y puede leerse y editarse directamente a través de la API o de Claude Console, lo que permite ajustarla, importarla y exportarla.

Cada cambio en una memoria crea una versión de memoria ("memory version") inmutable, lo que te brinda un registro de auditoría y recuperación a un punto en el tiempo para todo lo que el agente escribe.

Crear un almacén de memoria

Dale al almacén un name y una description. La descripción se pasa al agente, indicándole qué contiene el almacén.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

El id del almacén de memoria (memstore_...) es lo que pasas al adjuntar el almacén a una sesión.

Inicializarlo con contenido (opcional)

Precarga un almacén con material de referencia antes de que se ejecute cualquier agente:

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null

Adjuntar un almacén de memoria a una sesión

Los almacenes de memoria se adjuntan en el arreglo resources[] de la sesión cuando se crea la sesión. A diferencia de los recursos de archivos, los almacenes de memoria solo pueden adjuntarse en el momento de creación de la sesión; no se admite agregar ni quitar uno de una sesión en ejecución. Los almacenes de memoria se adjuntan de la misma manera para sesiones en la nube y en entornos autoalojados; los entornos autoalojados solo aceptan recursos memory_store.

Opcionalmente, incluye instructions para proporcionar orientación específica de la sesión sobre cómo el agente debe usar este almacén. Se muestra al agente junto con el name y la description del almacén, y tiene un límite de 4,096 caracteres.

También puedes configurar access. El valor predeterminado es read_write (mostrado explícitamente en el siguiente ejemplo), pero también se admite read_only.

ant beta:sessions create <<YAML
agent: $agent_id
environment_id: $environment_id
resources:
  - type: memory_store
    memory_store_id: $store_id
    access: read_write
    instructions: User preferences and project context. Check before starting any task.
YAML

Se admite un máximo de 8 almacenes de memoria por sesión. Adjunta varios almacenes cuando distintas partes de la memoria tengan distintos propietarios o reglas de acceso. Razones comunes:

• Material de referencia compartido: un almacén de solo lectura adjunto a muchas sesiones (estándares, convenciones, conocimiento del dominio), separado del almacén de lectura y escritura propio de cada sesión.
• Correspondencia con la estructura de tu producto: un almacén por usuario final, por equipo o por proyecto, compartiendo una única configuración de agente.
• Ciclos de vida diferentes: un almacén que sobrevive a cualquier sesión individual, o uno que quieras archivar según su propio calendario.

Cómo accede el agente a la memoria

Cada almacén adjunto se monta dentro del sandbox de la sesión como un directorio bajo /mnt/memory/. El nombre del directorio es el nombre visible del almacén saneado a un slug seguro para el sistema de archivos (en minúsculas; las secuencias de caracteres no alfanuméricos se convierten en un solo guion), por lo que un almacén llamado "Demo Memory" se monta en /mnt/memory/demo-memory/. La ruta exacta se devuelve en el campo mount_path del recurso de almacén de memoria de la sesión; léela desde ahí en lugar de construirla tú mismo. El agente lee y escribe el almacén con el conjunto de herramientas del agente estándar. Las escrituras bajo la ruta de montaje se persisten de vuelta en el almacén y se mantienen sincronizadas entre las sesiones que lo comparten; las escrituras en cualquier otra ruta bajo /mnt/memory/ fallan, porque el sandbox monta ese directorio padre como solo lectura. Se agrega automáticamente a la indicación del sistema una breve descripción de cada montaje (nombre visible, ruta de montaje, modo de acceso, description del almacén y cualquier instructions).

access se aplica a nivel del sistema de archivos: un montaje read_only rechaza las escrituras, mientras que las escrituras en un montaje read_write producen versiones de memoria atribuidas a la sesión.

Las lecturas y escrituras del agente aparecen en el flujo de eventos como eventos ordinarios agent.tool_use y agent.tool_result de la herramienta que haya tocado el montaje.

Ver y editar memorias

Los almacenes de memoria pueden administrarse directamente a través de la API. Usa esto para crear flujos de trabajo de revisión, corregir memorias incorrectas o inicializar almacenes antes de que se ejecute cualquier sesión.

Listar memorias

Lista las memorias de un almacén. Los resultados se devuelven en un orden estable definido por el servidor.

• path_prefix limita la lista a un directorio. Debe terminar con / y coincide con segmentos de ruta completos, por lo que path_prefix=/notes/ devuelve /notes/todo.md pero no /notes-archive/todo.md.
• depth controla qué tan profundo llega el listado por debajo de path_prefix: omítelo (o pasa 0) para listar todo el subárbol, o pasa 1 para listar solo los hijos inmediatos. Otros valores devuelven un error 400.

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/"

Consulta la referencia de Listar memorias para ver todos los parámetros y el esquema de respuesta.

Leer una memoria

Obtener una memoria individual devuelve el contenido completo.

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Consulta la referencia de Recuperar una memoria para ver todos los parámetros y el esquema de respuesta.

Crear una memoria

memories.create crea una memoria en una path dada. Crear no sobrescribe; para cambiar una memoria existente, usa memories.update.

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

Consulta la referencia de Crear una memoria para ver todos los parámetros y el esquema de respuesta.

Actualizar una memoria

memories.update modifica una memoria existente por ID. Puedes cambiar content, path (un cambio de nombre) o ambos. El ejemplo cambia el nombre de una memoria a una ruta de archivo:

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

Consulta la referencia de Actualizar una memoria para ver todos los parámetros y el esquema de respuesta.

Ediciones de contenido seguras (concurrencia optimista)

Para evitar pisar una escritura concurrente, pasa una precondición content_sha256. La actualización solo se aplica si el hash del contenido almacenado aún coincide con el que leíste; si no coincide, vuelve a leer la memoria y reintenta contra el estado actualizado.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null

Eliminar una memoria

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

Consulta la referencia de Eliminar una memoria para ver todos los parámetros y el esquema de respuesta.

Auditar cambios en la memoria

Cada mutación de una memoria crea una versión de memoria inmutable (memver_...). Usa los endpoints de versiones para auditar quién cambió qué y cuándo, para inspeccionar o restaurar una instantánea anterior, y para eliminar contenido sensible del historial mediante redacción.

Las versiones pertenecen al almacén (no a la memoria individual) y no se eliminan cuando se elimina la memoria en sí, por lo que el registro de auditoría también cubre las memorias eliminadas, sujeto a la retención descrita a continuación. Las versiones se conservan durante 30 días después de escribirse; sin embargo, las versiones recientes de una memoria activa siempre se conservan independientemente de su antigüedad, por lo que las memorias que cambian con poca frecuencia podrían conservar historial más allá de los 30 días. La llamada memories.retrieve en vivo siempre devuelve la versión más reciente; los endpoints de versiones te dan el historial conservado.

No existe un endpoint dedicado de restauración; para revertir, recupera la versión que quieras y escribe su content de vuelta con memories.update (o memories.create si la memoria padre ha sido eliminada, siempre que la versión que quieres aún se conserve).

Las versiones de memoria pasadas podrían eliminarse después de 30 días. Para preservar el historial de memoria por más tiempo, exporta las versiones a través de la API.

Listar versiones

Lista el historial de versiones de un almacén, de la más reciente a la más antigua. El ejemplo filtra el historial de una sola memoria:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
# `list --format json` emite un objeto JSON por elemento.
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

Consulta la referencia de Listar versiones de memoria para ver todos los parámetros y el esquema de respuesta.

Recuperar una versión

Obtener una versión individual devuelve los mismos campos que la respuesta de listado más el cuerpo completo de content.

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consulta la referencia de Recuperar una versión de memoria para ver todos los parámetros y el esquema de respuesta.

Redactar una versión

Redactar elimina el contenido de una versión histórica preservando el registro de auditoría (quién hizo qué y cuándo). Úsalo para flujos de trabajo de cumplimiento, como eliminar secretos filtrados, PII o atender solicitudes de eliminación de usuarios.

Una versión que es la cabeza actual de una memoria activa no puede redactarse. Escribe primero una nueva versión (o elimina la memoria) y luego redacta la anterior.

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consulta la referencia de Redactar una versión de memoria para ver todos los parámetros y el esquema de respuesta.

Administrar almacenes de memoria

Además de create, los almacenes de memoria admiten retrieve, update, list, archive y delete.

Listar almacenes

Lista los almacenes del espacio de trabajo. Los almacenes archivados se excluyen de forma predeterminada; pasa include_archived: true para incluirlos.

ant beta:memory-stores list --include-archived

Consulta la referencia de Listar almacenes de memoria para ver todos los parámetros y el esquema de respuesta.

Archivar un almacén

Archivar hace que un almacén sea de solo lectura e impide que se adjunte a nuevas sesiones. Archivar es irreversible; no existe la opción de desarchivar.

ant beta:memory-stores archive --memory-store-id "$store_id"

Consulta la referencia de Archivar un almacén de memoria para ver todos los parámetros y el esquema de respuesta.

Para eliminar permanentemente un almacén junto con todas sus memorias y versiones, usa memory_stores.delete.

Mejores prácticas para la administración de memoria

Cuando un almacén alcanza su límite de 10,000 memorias, las escrituras de nuevas memorias fallan: tanto las llamadas directas a memories.create como las escrituras de archivos del agente en rutas no asignadas. Las memorias existentes siguen siendo legibles y editables. Las siguientes prácticas te ayudan a mantenerte muy por debajo del límite y a recuperarte sin problemas si lo alcanzas.

• Usa almacenes enfocados. En lugar de un único almacén grande de propósito general, usa almacenes más pequeños diseñados para un propósito específico: uno por usuario, uno para conocimiento del dominio compartido y uno para contexto específico del proyecto. Cada almacén tiene su propio límite de 10,000 memorias, por lo que mantener los almacenes con un alcance definido reduce la probabilidad de que alguno se llene.

• Condensa o depura antes de que el almacén se llene. Elimina memorias obsoletas o redundantes con memories.delete. También puedes ejecutar una sesión de sueño, que consolida el contenido fragmentado en un nuevo almacén de salida independiente en lugar de modificar el original. Cambia tus sesiones a ese almacén de salida y luego archiva o elimina el original.

• Adjunta un nuevo almacén cuando tenga sentido. Si un almacén ha crecido más allá de su alcance útil, adjunta uno nuevo para el contenido nuevo y adjunta el original con acceso read_only. El agente puede leer de ambos mientras solo escribe en el nuevo.

• Limita el acceso de escritura cuando corresponda. Las sesiones que solo leen material de referencia compartido no necesitan read_write. Mantener el acceso de escritura limitado a las sesiones que realmente agregan nuevas memorias facilita rastrear de dónde proviene el crecimiento.