---
title: Almacenes de memoria en sandboxes autoalojados
url: https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory
description: "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."
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: No es elegible para ZDR, excepto Managed Agents autoalojado. Las sesiones son recursos con estado; las transcripciones persisten hasta que las eliminas.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
---

Las sesiones en un entorno autoalojado adjuntan [almacenes de memoria](https://platform.claude.com/docs/es/managed-agents/memory) exactamente igual que las sesiones en entornos en la nube. Enuméralos en `resources` (csharp, go: `Resources`) cuando crees la sesión, como se muestra en [Adjuntar un almacén de memoria a una sesión](https://platform.claude.com/docs/es/managed-agents/memory#attach-a-memory-store-to-a-session). 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. 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/memory` con permisos de escritura:** Consulta [Preparar el host](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). En macOS, consulta [Preparar un host macOS](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host).
* **El secreto del elemento de trabajo:** Si tu propio código inicia el worker, [reenvíale el secreto del elemento de trabajo](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret).

## Preparar el host

En macOS, omite el siguiente comando y sigue en su lugar [Preparar un host macOS](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-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:

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

No crees tú mismo el directorio de ningún almacén. El worker crea el directorio `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session), 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount).

<Steps>
  <Step title="Crea el directorio en el volumen de datos">
    Crea el directorio `memory` y haz que el usuario del worker sea su propietario. `$USER` es tu propio nombre de usuario. Si el worker se ejecuta como otro usuario, reemplaza `"$USER"` con el nombre de ese usuario.

    ```bash
    sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memory
    ```

    Esta ubicación es solo una opción. Si usas otra, cambia la ruta en la línea de `synthetic.conf` para que coincida. Anthropic solo ha probado `/System/Volumes/Data/mnt`.
  </Step>

  <Step title="Agrega una línea a synthetic.conf">
    Ejecuta `cat -et /etc/synthetic.conf`, que muestra cada tabulación como `^I` y 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 `$`, ejecuta `echo | sudo tee -a /etc/synthetic.conf` para 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.

    ```bash
    printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.conf
    ```

    El comando imprime la línea que agrega. La línea asigna el nombre `mnt` al directorio que contiene `memory`. El archivo necesita una tabulación entre las dos columnas, que `\t` escribe.
  </Step>

  <Step title="Crea el enlace">
    Ejecuta `apfs.util` con la opción `-t`. Crea el enlace a partir de la línea que agregaste, sin reiniciar.

    ```bash
    sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
    ```
  </Step>

  <Step title="Comprueba el resultado">
    Lista `/mnt` y `/mnt/memory`.

    ```bash
    ls -ld /mnt /mnt/memory
    ```

    La 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.
  </Step>
</Steps>

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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-per-session). 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:

1. **Descarga cada almacén en su `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`).** 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. **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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#sync-interval) (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ó.
4. **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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-reference#when-the-worker-finishes-with-a-session) 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](https://platform.claude.com/docs/es/managed-agents/memory#audit-memory-changes), 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](https://platform.claude.com/docs/es/managed-agents/events-and-streaming) 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.

<Warning>
  Si detienes un worker de forma ordenada durante una sesión o [detienes el elemento de trabajo de la sesión](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully), el worker aun así sube los archivos nuevos y modificados. También elimina los directorios de los almacenes. No envía eliminaciones, por lo que una memoria que el agente eliminó permanece en el almacén a menos que una sincronización anterior ya la haya eliminado del almacén. Un worker que se termina a la fuerza en lugar de detenerse no ejecuta ninguna limpieza, por lo que las ediciones no sincronizadas se pierden y los directorios de los almacenes permanecen. Consulta [Detener workers de forma ordenada](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations#stop-workers-gracefully).
</Warning>

## 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` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) 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` (typescript: `10_000`; go: `10 * time.Second`) |
| Desactivar la compatibilidad con memoria | `None` (typescript: `null`; go: `-1`) |

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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-memory#how-the-worker-handles-memory). 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` (csharp, go: `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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount).

### Eliminaciones

`memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) 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"` (go: `environments.MemorySyncDeletionsEnabled`) (predeterminado) | Elimina la memoria del almacén una vez que una sincronización posterior confirma que el archivo sigue sin existir. |
| `"log_only"` (go: `environments.MemorySyncDeletionsLogOnly`) | 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"` (go: `environments.MemorySyncDeletionsDisabled`) | 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-workers#run-an-always-on-worker) explica cómo crear el directorio y qué usar en macOS.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Un worker es un proceso de larga duración, no una única solicitud HTTP. Para cambiar la configuración de sincronización, usa `EnvironmentWorker` en el SDK de Python, TypeScript o Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    El worker de la CLI `ant` siempre usa la configuración de sincronización predeterminada. Para cambiarla, usa `EnvironmentWorker` en el SDK de Python, TypeScript o Go.
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });
  const controller = new AbortController();
  process.once("SIGINT", () => controller.abort());
  process.once("SIGTERM", () => controller.abort());

  const worker = new EnvironmentWorker({
    client,
    environmentId,
    environmentKey,
    workdir: "/workspace",
    signal: controller.signal,
    memorySyncIntervalMs: 10_000,
    memorySyncDeletions: "log_only"
  });
  await worker.run();
  ```

  <CodeGroupItem language="C#">
    El SDK de C# no tiene `EnvironmentWorker`.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"
  	"time"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		EnvironmentID:       environmentID,
  		EnvironmentKey:      environmentKey,
  		Workdir:             "/workspace",
  		MemorySyncInterval:  10 * time.Second,
  		MemorySyncDeletions: environments.MemorySyncDeletionsLogOnly,
  	})
  	if err := worker.Run(ctx); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    El SDK de Java no tiene `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    El SDK de PHP no tiene `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    El SDK de Ruby no tiene `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount) para ver los mensajes del registro del worker y sus soluciones.

## Disponibilidad

Estado de Almacenes de memoria en sandboxes autoalojados: en beta en todos los modelos.

### Compatibilidad con la API

#### [Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview)

* Disponibilidad: Disponible

| Estado | Plataformas en la nube |
| ----- | ----- |
| Beta | Claude API |

### Encabezados beta requeridos

[Descripción general de los encabezados beta](https://platform.claude.com/docs/es/api/beta-headers)

Los encabezados beta te permiten acceder a funciones experimentales y nuevas capacidades de los modelos antes de que formen parte de la API estándar.

* `managed-agents-2026-04-01`

### Manejo de datos

[Descripción general del manejo de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention#feature-eligibility)

| Elemento | Retención de datos cero | HIPAA |
| ----- | ----- | ----- |
| Estado | No elegible | No elegible |
| Detalles | 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](https://platform.claude.com/docs/es/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | No es elegible para HIPAA. Se aplica a todas las subfunciones de Managed Agents. |

Endpoints aplicables:

* `/v1/agents`
* `/v1/sessions`
* `/v1/environments`
