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 construido desaparece. Los almacenes de memoria permiten que el agente transporte información entre sesiones: preferencias del usuario, convenciones del proyecto, errores previos y contexto del dominio.



Descripción general

Un memory store (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 una nota que describe cada montaje se agrega automáticamente 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 memory (memoria) en un almacén se direcciona mediante una ruta y puede leerse y editarse directamente a través de la API o la Console, lo que permite ajustar, importar y exportar.

Cada cambio en una memoria crea una memory version (versión de memoria) 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.



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



Inicialízalo 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



Adjunta 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 y repositorios, los almacenes de memoria solo pueden adjuntarse en el momento de la creación de la sesión; agregar o eliminar uno de una sesión en ejecución no está soportado.

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. Su valor predeterminado es read_write (mostrado explícitamente en el siguiente ejemplo), pero read_only también está soportado.

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.
• Mapeo a 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 no alfanuméricas 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 en cualquier otra ruta bajo /mnt/memory/ terminan en el 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 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.



Visualiza y edita 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 inicializar almacenes antes de que se ejecute cualquier sesión.



Lista memorias

Lista las memorias en 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 va 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 los parámetros completos y el esquema de respuesta.



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



Crea una memoria

memories.create crea una memoria en un path dado. Create 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.



Actualiza una memoria

memories.update modifica una memoria existente por ID. Puedes cambiar content, path (un renombrado), o ambos. El ejemplo renombra 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 de contenido seguras (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 todavía 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



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



Audita los cambios de memoria

Cada mutación de una memoria crea una memory version (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 elimine, 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 los 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 de restauración dedicado; para revertir, recupera la versión que deseas y escribe su content de vuelta con memories.update (o memories.create si la memoria padre ha sido eliminada, porque las versiones sobreviven a su padre).

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.



Lista versiones

Lista el historial de versiones de un almacén, de más reciente a más antiguo. 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)
# `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 los parámetros completos y el esquema de respuesta.



Recupera 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 los parámetros completos y el esquema de respuesta.



Redacta una versión

Redact elimina el contenido de una versión histórica mientras preserva 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 solicitudes de eliminación de usuarios.

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

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



Gestiona almacenes de memoria

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



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



Archiva un almacén

Archivar hace que un almacén sea de solo lectura y evita que se adjunte a nuevas sesiones. El archivado es unidireccional; no hay desarchivado.

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 en nuevas memorias fallan: tanto las llamadas directas a memories.create como las escrituras de archivos del agente en rutas no mapeadas. 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 con elegancia si lo alcanzas.

• Usa almacenes enfocados. En lugar de un gran almacén de propósito general, usa almacenes más pequeños construidos para un propósito específico: uno por usuario, uno para conocimiento de dominio compartido 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 acotados reduce la probabilidad de que alguno se llene.

• Condensa o poda 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 el 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 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 donde sea apropiado. Las sesiones que solo leen material de referencia compartido no necesitan read_write. Mantener el acceso de escritura acotado a las sesiones que realmente agregan nuevas memorias facilita rastrear de dónde proviene el crecimiento.