Almacenes de memoria en sandboxes autoalojados

Las sesiones en un entorno autoalojado adjuntan almacenes de memoria exactamente igual que las sesiones en entornos en la nube. Enuméralos en resources cuando crees la sesión, como se muestra en Adjuntar un almacén de memoria a una sesión. Una sesión acepta hasta 8 almacenes de memoria.

La diferencia está en quién materializa el almacén. En un entorno autoalojado, tu worker, en lugar de la infraestructura de Anthropic, descarga cada almacén en el sandbox y sincroniza de vuelta los cambios del agente.

Requisitos

• Un worker que monte almacenes de memoria: Usa la CLI ant 1.33.0 o posterior, o EnvironmentWorker del SDK de Python, TypeScript o Go.
• Un sistema de archivos POSIX: Los hosts Windows no son compatibles, porque el worker requiere O_NOFOLLOW cuando abre archivos de memoria. Se recomienda un sistema de archivos que distinga entre mayúsculas y minúsculas, para que las rutas de memoria que solo difieren en mayúsculas y minúsculas no colisionen.
• Un directorio /mnt/memory con permisos de escritura: Consulta Preparar el host.
• El secreto del elemento de trabajo: Si tu propio código inicia el worker, reenvíale el secreto del elemento de trabajo.

Preparar el host

Antes de iniciar el worker, crea el directorio padre y haz que el usuario con el que se ejecuta el worker pueda escribir en él:

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

No crees tú mismo los directorios de cada almacén. El worker crea el directorio mount_path de cada almacén (por ejemplo, /mnt/memory/user-preferences) cuando se inicia una sesión y lo elimina cuando la sesión termina. Si ya existe algo en esa ruta, el worker se niega a iniciar el trabajo de la sesión.

En el patrón de un sandbox por sesión, la imagen del sandbox necesita un /mnt/memory con permisos de escritura. No necesitas hacer un bind-mount de los directorios de memoria al host, porque el worker sube su contenido al almacén antes de que el sandbox termine.

Aislar sesiones que comparten un almacén

Dos sesiones no pueden montar el mismo almacén en un mismo host al mismo tiempo, porque ambas necesitan la misma ruta. Si tus sesiones adjuntan el mismo almacén, ejecuta una sesión por sistema de archivos. Dar a cada sesión su propio sandbox cumple esta regla.

Cómo gestiona el worker la memoria

Cuando el worker reclama un elemento de trabajo cuya sesión tiene almacenes de memoria adjuntos:

1. Descarga cada almacén en su mount_path. Este es el mismo directorio bajo /mnt/memory/ que usan las sesiones en la nube, y la indicación del sistema de la sesión se lo describe al agente. Por ejemplo, un almacén llamado "User Preferences" queda en /mnt/memory/user-preferences/.
2. Abre esos directorios a las herramientas de archivos. El agente trabaja con las memorias usando las mismas herramientas de archivos que usa en el directorio de trabajo.
3. Concilia los cambios después de las llamadas a herramientas, como máximo una vez por intervalo de sincronización (15 segundos de forma predeterminada). Las memorias que cambiaron en el almacén se escriben en el disco, y los archivos que el agente cambió se suben al almacén.
4. Ejecuta una sincronización final cuando la sesión termina. Vacía las subidas que aún estén pendientes durante un máximo de 30 segundos y luego elimina los directorios que creó.

El almacén de memoria del lado de Anthropic sigue siendo la fuente de verdad. Las versiones de memoria, la redacción y la visualización o edición de memorias en la Console funcionan igual que en las sesiones en la nube. Las lecturas y escrituras de memoria del agente aparecen en el flujo de eventos como eventos de herramientas normales.

Como cada worker sincroniza en un intervalo, un cambio escrito en una sesión se vuelve visible para otra sesión en ejecución solo después de que ambas se hayan sincronizado. Normalmente eso tarda bastante menos de un minuto con el intervalo predeterminado. Las sesiones en sandboxes en la nube ven los cambios de las demás casi de inmediato.

Cada directorio de almacén contiene un archivo marcador llamado .anthropic-memory-store que vincula el directorio con su almacén. Déjalo en su lugar: el worker no sincroniza un directorio cuyo marcador falte o haya sido alterado.

Configurar la sincronización

Dos opciones de EnvironmentWorker controlan el comportamiento de la memoria. Establécelas dondequiera que construyas el worker, incluso en un controlador de webhook. El worker de la CLI ant siempre usa los valores predeterminados.

Intervalo de sincronización

memory_sync_interval establece con qué frecuencia los almacenes adjuntos se concilian con el servidor mientras se ejecuta la sesión.

Un intervalo más corto reduce la ventana en la que otra sesión ve memorias desactualizadas, a costa de más solicitudes al almacén de memoria.

Desactiva la compatibilidad con memoria solo en workers cuyas sesiones no adjunten almacenes de memoria. Un worker con la memoria desactivada no descarga ni sincroniza almacenes, por lo que una sesión con almacenes adjuntos se ejecuta sin ellos aunque su indicación del sistema todavía los describa.

Mientras la compatibilidad con memoria está activada, un elemento de trabajo que llega sin un secret para una sesión con almacenes adjuntos falla en lugar de ejecutarse sin memoria. Consulta Los almacenes de memoria no se montan.

Eliminaciones

memory_sync_deletions establece si un archivo que el agente elimina localmente también se elimina del almacén. Las subidas y descargas no se ven afectadas.

Por ejemplo, para sincronizar cada 10 segundos y solo registrar las eliminaciones que el worker habría realizado:

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

Almacenes de solo lectura y conflictos

Para un almacén adjuntado con access: "read_only", las herramientas write y edit se niegan a cambiar archivos dentro de su directorio. El worker nunca sube nada desde él.

Los cambios realizados mediante bash, o mediante una herramienta personalizada o un servidor MCP que sirvas desde el sandbox, no se bloquean localmente. Nunca se sincronizan con el almacén, y el siguiente cambio remoto en esa memoria los sobrescribe. Si la copia local en sí debe permanecer sin cambios durante la sesión:

• Desactiva la herramienta bash para ese agente y no le des ninguna herramienta personalizada que escriba en el sistema de archivos del sandbox.
• No montes la ruta del almacén como de solo lectura. El propio worker debe crear el directorio y escribir en él las memorias descargadas.

Los conflictos se resuelven a favor del almacén. Supón que el agente cambia un archivo de memoria que también cambió en el almacén desde la última vez que la sesión lo sincronizó. En la siguiente sincronización, el worker conserva la versión del almacén, sobrescribe con ella el archivo local y registra una advertencia. Las herramientas write y edit en sí se ejecutan correctamente y ningún error llega al agente. Si el cambio del agente sigue siendo aplicable, puede volver a leer el archivo después de la sincronización y hacer el cambio de nuevo.

Solución de problemas

Consulta Los almacenes de memoria no se montan para ver los mensajes del log del worker y sus soluciones.