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 workspace 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 una nota que describe cada montaje a la indicación del sistema, 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.

Cada memoria en un almacén se direcciona mediante una ruta y puede leerse y editarse directamente a través de la API o la Consola, lo que permite ajustar, importar y exportar.

Cada cambio en una memoria crea una versión de memoria inmutable, lo que te proporciona 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

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



Precargarlo 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 esta se crea. A diferencia de los recursos de archivos y repositorios, los almacenes de memoria solo pueden adjuntarse en el momento de creación de la sesión; no se admite agregar o eliminar uno de una sesión en ejecución.

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 múltiples almacenes cuando diferentes partes de la memoria tengan diferentes 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), mantenido separado del almacén de lectura-escritura propio de cada sesión.
• Correspondencia con la estructura de tu producto: un almacén por usuario final, por equipo o por proyecto, mientras se comparte una única configuración de agente.
• Diferentes ciclos de vida: un almacén que sobrevive a cualquier sesión individual, o uno que deseas 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 para mostrar del almacén convertido 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 allí 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 al almacén y se mantienen sincronizadas entre las sesiones que lo comparten; las escrituras a cualquier otra ruta bajo /mnt/memory/ van a un espacio temporal local del contenedor y se pierden cuando la sesión termina. Una breve descripción de cada montaje (nombre para mostrar, ruta de montaje, modo de acceso, description del almacén y cualquier instructions) se agrega automáticamente a la indicación del sistema.

access se aplica a nivel del sistema de archivos: un montaje read_only rechaza escrituras, mientras que las escrituras a 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 para cualquier herramienta que haya tocado el montaje.



Ver y editar memorias

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



Listar memorias

Lista las memorias en un almacén, opcionalmente filtradas por path_prefix para explorar una ruta como un directorio:

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

Consulta la referencia de Listar memorias para ver los parámetros completos 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 los parámetros completos 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 los parámetros completos 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 los parámetros completos y el esquema de respuesta.



Ediciones seguras de contenido (concurrencia optimista)

Para evitar sobrescribir 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 con 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 los parámetros completos y el esquema de respuesta.



Auditar cambios de memoria

Cada mutación a 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 con redact.

Las versiones pertenecen al almacén (no a la memoria individual) y sobreviven incluso después de que la memoria misma se elimina, por lo que el registro de auditoría permanece completo. Las versiones se retienen durante 30 días; sin embargo, las versiones recientes siempre se conservan independientemente de su antigüedad, por lo que las memorias que cambian con poca frecuencia podrían retener historial más allá de 30 días. La llamada en vivo memories.retrieve siempre devuelve la versión más reciente; los endpoints de versiones te dan el historial retenido.

No hay un endpoint dedicado de restauración; para revertir, recupera la versión que deseas y escribe su content de vuelta con memories.update (o memories.create si la memoria principal ha sido eliminada, porque las versiones sobreviven a su memoria principal).

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, las más recientes primero. El ejemplo filtra al historial de una sola memoria:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

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



Recuperar una versión

Obtener una versión individual devuelve los mismos campos que la respuesta de lista 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 los parámetros completos y el esquema de respuesta.



Censurar una versión

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

Una versión que es la cabeza actual de una memoria activa no puede censurarse. Escribe una nueva versión primero (o elimina la memoria), luego censura la antigua.

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

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



Gestionar almacenes de memoria

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



Listar almacenes

Lista los almacenes en el workspace. 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 los parámetros completos 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 unidireccional; no hay forma de desarchivar.

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

Consulta la referencia de Archivar un almacén de memoria para ver los parámetros completos 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 gestión de memoria

Cuando un almacén alcanza su límite de 2,000 memorias, las escrituras a nuevas memorias fallan: tanto las llamadas directas a memories.create como las escrituras de archivos del agente a rutas no mapeadas. Las memorias existentes permanecen 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 almacén grande de propósito general, usa almacenes más pequeños con propósitos específicos: uno por usuario, uno para conocimiento compartido del dominio y uno para contexto específico del proyecto. Cada almacén tiene su propio límite de 2,000 memorias, por lo que mantener los almacenes con alcance limitado 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 dreaming, que consolida contenido fragmentado en un nuevo almacén de salida separado en lugar de modificar el original. Cambia tus sesiones a ese almacén de salida, 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 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 sea apropiado. 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 el seguimiento de dónde proviene el crecimiento.