Almacenes de memoria en sandboxes autoalojados
Adjunta almacenes de memoria a sesiones de Claude Managed Agents que se ejecutan en sandboxes autoalojados: prepara el host, configura la sincronización y gestiona los almacenes de solo lectura y los conflictos.
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
ant1.33.0 o posterior, oEnvironmentWorkerdel SDK de Python, TypeScript o Go. - Un sistema de archivos POSIX: Los hosts Windows no son compatibles, porque el worker requiere
O_NOFOLLOWcuando abre archivos de memoria. Anthropic 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. Los volúmenes de macOS no distinguen entre mayúsculas y minúsculas de forma predeterminada, por lo que esas rutas colisionan allí. - Un directorio
/mnt/memorycon permisos de escritura: Consulta Preparar el host. En macOS, consulta Preparar un host macOS. - 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
En macOS, omite el siguiente comando y sigue en su lugar Preparar un host macOS.
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/memoryNo crees tú mismo el directorio de ningún almacén. El worker crea el directorio mount_path de cada almacén, como /mnt/memory/user-preferences, cuando reclama una sesión y lo elimina cuando termina con esa sesión. Si ya existe algo en esa ruta, incluso un directorio vacío, el worker marca el elemento de trabajo como fallido.
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 almacén conserva la copia duradera de cada memoria.
Preparar un host macOS
En macOS, el volumen raíz es de solo lectura, por lo que mkdir no puede crear /mnt. En su lugar, crea /System/Volumes/Data/mnt/memory en el volumen de datos, que tiene permisos de escritura. Luego agrega una línea a /etc/synthetic.conf, para que macOS cree /mnt como un enlace simbólico a /System/Volumes/Data/mnt. Estos pasos requieren derechos de administrador.
Sin esta configuración, el worker no puede crear el directorio de un almacén, por lo que marca el elemento de trabajo como fallido. La sesión entonces permanece inactiva sin ningún evento de error. Consulta Los almacenes de memoria no se montan o no se sincronizan.
Crea el directorio en el volumen de datos
Crea el directorio
memoryy haz que el usuario del worker sea su propietario.$USERes tu propio nombre de usuario. Si el worker se ejecuta como otro usuario, reemplaza"$USER"con el nombre de ese usuario.sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memoryEsta ubicación es solo una opción. Si usas otra, cambia la ruta en la línea de
synthetic.confpara que coincida. Anthropic solo ha probado/System/Volumes/Data/mnt.Agrega una línea a synthetic.conf
Ejecuta
cat -et /etc/synthetic.conf, que muestra cada tabulación como^Iy cada fin de línea como$.- Si una línea dice
mnt^ISystem/Volumes/Data/mnt$, este paso ya está hecho. Ve al siguiente paso. - Si otra línea comienza con
mnt, detente. Algo más en esta Mac ya define/mnt. - Si la última línea no termina con
$, ejecutaecho | sudo tee -a /etc/synthetic.confpara terminarla. Luego, agrega la línea. - Si no imprime nada o informa
No such file or directory, agrega la línea. El siguiente comando crea el archivo si no existe. - De lo contrario, agrega la línea.
Para agregar la línea, ejecuta este comando. Ejecútalo solo una vez, porque cada ejecución agrega otra línea.
printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.confEl comando imprime la línea que agrega. La línea asigna el nombre
mntal directorio que contienememory. El archivo necesita una tabulación entre las dos columnas, que\tescribe.- Si una línea dice
Crea el enlace
Ejecuta
apfs.utilcon la opción-t. Crea el enlace a partir de la línea que agregaste, sin reiniciar.sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -tComprueba el resultado
Lista
/mnty/mnt/memory.ls -ld /mnt /mnt/memoryLa primera línea termina con
/mnt -> System/Volumes/Data/mnt. La segunda línea muestra al usuario del worker como propietario de/mnt/memory. Ahora puedes iniciar el worker.
Anthropic ha probado esta configuración en macOS 26.7.1 con el worker de la CLI ant.
Aislar sesiones que comparten un almacén
Dos sesiones no pueden montar el mismo almacén en un sistema de archivos al mismo tiempo porque ambas necesitan la misma ruta. Para ejecutar en paralelo sesiones que comparten un almacén, da a cada sesión su propio sistema de archivos. Si usas un sandbox por sesión, cada sesión obtiene automáticamente su propio sistema de archivos. Consulta Ejecutar un sandbox por sesión. Un host puede ejecutar muchos de esos sandboxes.
Cómo gestiona el worker la memoria
Cuando el worker reclama un elemento de trabajo cuya sesión tiene almacenes de memoria adjuntos:
- Descarga cada almacén en su
mount_path. 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/. - 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.
- Sincroniza después de las llamadas a herramientas. El worker sincroniza después de una llamada a herramienta si ha pasado el intervalo de sincronización (15 segundos de forma predeterminada) desde su última sincronización. Cada sincronización escribe en el disco las memorias modificadas del almacén y sube los archivos que el agente modificó.
- Ejecuta una sincronización final cuando la sesión termina o permanece inactiva durante el límite de inactividad del worker. La sincronización final puede tardar hasta 60 segundos. Los cambios que no se hayan subido para entonces se pierden. Luego, el worker elimina los directorios que creó.
El límite de inactividad es de 60 segundos de forma predeterminada. Cuándo termina el worker con una sesión explica qué cubre el límite y cómo cambiarlo.
Las herramientas write y edit del agente solo cambian la copia local, y el worker sube esos cambios en su siguiente sincronización. Las rutas bajo /mnt/memory/ fuera de los directorios de los almacenes no son “scratch space” (espacio de trabajo temporal). Las herramientas de archivos del worker se niegan a escribir en ellas, y todo lo que un comando de shell escriba allí nunca se sincroniza con un almacén.
Las versiones de memoria, la eliminación de su contenido (redact) y la visualización o edición de memorias en Claude 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.
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. Si el marcador falta o ha sido alterado y el directorio aún contiene archivos, el worker no sincroniza el directorio. Tampoco elimina el directorio cuando termina con la sesión.
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 el tiempo mínimo entre dos sincronizaciones mientras se ejecuta la sesión.
| Configuración | Valor |
|---|---|
| Predeterminado | 15 segundos |
| Mínimo | 5 segundos |
| Ejemplo (10 segundos) | 10 |
| Desactivar la compatibilidad con memoria | None |
El worker no sincroniza según un temporizador. Comprueba el intervalo después de cada llamada a una herramienta que se ejecuta en tu sandbox, como bash, read o una herramienta personalizada. La llamada no tiene que afectar a la memoria. Sin llamadas a herramientas, nada se sincroniza hasta la sincronización final. Un cambio en una sesión llega a otra sesión en ejecución solo después de que ambas se hayan sincronizado, por lo que la espera no tiene una duración fija.
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 o no se sincronizan.
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.
| Valor | Comportamiento |
|---|---|
"enabled" (predeterminado) | Elimina la memoria del almacén una vez que una sincronización posterior confirma que el archivo sigue sin existir. |
"log_only" | Ejecuta las mismas comprobaciones, pero solo registra lo que habría eliminado. Úsalo para observar lo que tus workers eliminarían antes de confiar en el modo activado. |
"disabled" | Nunca elimina del almacén. |
Por ejemplo, para sincronizar como máximo una vez cada 10 segundos y solo registrar las eliminaciones que el worker habría realizado, usa el siguiente ejemplo. El ejemplo usa /workspace como directorio de trabajo, que debe existir antes de que se inicie el worker. Ejecuta un worker siempre activo explica cómo crear el directorio y qué usar en macOS.
import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
memory_sync_interval=10, # seconds
memory_sync_deletions="log_only",
)
task = asyncio.create_task(worker.run())
loop = asyncio.get_running_loop()
for signum in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(signum, task.cancel)
with contextlib.suppress(asyncio.CancelledError):
await task
asyncio.run(main())Almacenes de solo lectura y conflictos
Almacenes de solo lectura
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 llegan al almacén. Un archivo modificado permanece modificado hasta que ocurre una de estas cosas:
- Esa memoria obtiene una nueva versión en el almacén. La siguiente sincronización del worker sobrescribe el archivo con esa versión.
- El worker termina con la sesión. Elimina el directorio.
Para mantener también sin cambios la copia local, desactiva la herramienta bash para ese agente. Además, no le des herramientas personalizadas ni servidores MCP que escriban en el sistema de archivos del sandbox. No montes un volumen de solo lectura en la ruta del almacén. El montaje coloca un directorio en esa ruta, y el worker marca el elemento de trabajo como fallido si ya existe algo allí.
Conflictos
Un conflicto es una memoria que cambió tanto en el almacén como en el sandbox desde la sincronización anterior. Una eliminación cuenta como un cambio. Para un almacén adjuntado con access: "read_write", el worker resuelve el conflicto en la siguiente sincronización:
| En el almacén | En el sandbox | Resultado |
|---|---|---|
| Modificada | Modificada | La versión del almacén sobrescribe el archivo. |
| Modificada | Eliminada | El worker vuelve a escribir la versión del almacén en el sandbox. |
| Eliminada | Modificada | El worker vuelve a crear la memoria a partir del archivo. |
En las dos primeras filas, el cambio o la eliminación del agente se pierde, aunque la llamada a la herramienta se haya ejecutado correctamente. Nada se lo comunica al agente, y la única señal de la pérdida es una advertencia en el registro del worker. En la última fila, la eliminación en el almacén se deshace.
Solución de problemas
Consulta Los almacenes de memoria no se montan o no se sincronizan para ver los mensajes del registro del worker y sus soluciones.
Disponibilidad
Claude API
- Estado
- Beta
- API
- Managed Agents
- Encabezado beta
- Requiere
- Modelos
- Todos los modelos
Manejo de datos
Descripción general del manejo de datosEndpoints aplicables
/v1/agents/v1/sessions/v1/environments
No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas. Más información
No es elegible para HIPAA. Se aplica a todas las subfunciones de Managed Agents.
¿Te resultó útil esta página?