---
title: Memory stores em sandboxes auto-hospedados
url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory
description: "Anexe memory stores a sessões do Claude Managed Agents executadas em sandboxes auto-hospedados: prepare o host, configure a sincronização e lide com stores somente leitura e conflitos."
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: Não é elegível para ZDR, exceto o Managed Agents auto-hospedado. Sessões são recursos com estado; as transcrições persistem até que você as exclua.
  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
---

Sessões em um ambiente auto-hospedado anexam [memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/memory) exatamente como as sessões em ambientes de nuvem. Liste-os em `resources` (csharp, go: `Resources`) ao criar a sessão, conforme mostrado em [Anexar um memory store a uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/memory#attach-a-memory-store-to-a-session). Uma sessão aceita até 8 memory stores.

A diferença está em quem materializa o store. Em um ambiente auto-hospedado, é o seu worker, e não a infraestrutura da Anthropic, que baixa cada store para o sandbox e sincroniza de volta as alterações do agente.

## Requisitos

* **Um worker que monta memory stores:** Use a CLI `ant` 1.33.0 ou posterior, ou o `EnvironmentWorker` do SDK de Python, TypeScript ou Go.
* **Um sistema de arquivos POSIX:** Hosts Windows não são suportados, porque o worker exige `O_NOFOLLOW` ao abrir arquivos de memória. A Anthropic recomenda um sistema de arquivos que diferencie maiúsculas de minúsculas, para que caminhos de memória que diferem apenas em maiúsculas/minúsculas não colidam. Volumes do macOS não diferenciam maiúsculas de minúsculas por padrão, então esses caminhos colidem lá.
* **Um diretório `/mnt/memory` gravável:** Consulte [Preparar o host](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). No macOS, consulte [Preparar um host macOS](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host).
* **O segredo do item de trabalho:** Se o seu próprio código inicia o worker, [encaminhe o segredo do item de trabalho](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret) para ele.

## Preparar o host

No macOS, pule o próximo comando e siga [Preparar um host macOS](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host) em vez disso.

Antes de iniciar o worker, crie o diretório pai e torne-o gravável pelo usuário com o qual o worker é executado:

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

Não crie você mesmo o diretório de nenhum store. O worker cria o diretório `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) de cada store, como `/mnt/memory/user-preferences`, quando reivindica uma sessão e o remove quando termina de atender a essa sessão. Se algo já existir nesse caminho, mesmo um diretório vazio, o worker marca o item de trabalho como falho.

No [padrão de um sandbox por sessão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session), a imagem do sandbox precisa de um `/mnt/memory` gravável. Você não precisa fazer bind-mount dos diretórios de memória no host, porque o store mantém a cópia duradoura de cada memória.

### Preparar um host macOS

No macOS, o volume raiz é somente leitura, então o `mkdir` não consegue criar `/mnt`. Em vez disso, crie `/System/Volumes/Data/mnt/memory` no volume de dados, que é gravável. Em seguida, adicione uma linha a `/etc/synthetic.conf`, para que o macOS crie `/mnt` como um link simbólico para `/System/Volumes/Data/mnt`. Essas etapas exigem direitos de administrador.

Sem essa configuração, o worker não consegue criar o diretório de um store, então ele marca o item de trabalho como falho. A sessão então permanece ociosa sem nenhum evento de erro. Consulte [Memory stores não são montados ou sincronizados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount).

<Steps>
  <Step title="Criar o diretório no volume de dados">
    Crie o diretório `memory` e torne o usuário do worker seu proprietário. `$USER` é o seu próprio nome de usuário. Se o worker for executado como outro usuário, substitua `"$USER"` pelo nome desse usuário.

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

    Este local é apenas uma opção. Se você usar outro, altere o caminho na linha do `synthetic.conf` para corresponder. A Anthropic testou apenas `/System/Volumes/Data/mnt`.
  </Step>

  <Step title="Adicionar uma linha ao synthetic.conf">
    Execute `cat -et /etc/synthetic.conf`, que mostra cada tabulação como `^I` e cada fim de linha como `$`.

    * Se uma linha diz `mnt^ISystem/Volumes/Data/mnt$`, esta etapa já foi concluída. Vá para a próxima etapa.
    * Se outra linha começa com `mnt`, pare. Algo mais neste Mac já define `/mnt`.
    * Se a última linha não termina com `$`, execute `echo | sudo tee -a /etc/synthetic.conf` para finalizá-la. Em seguida, adicione a linha.
    * Se não imprimir nada ou relatar `No such file or directory`, adicione a linha. O comando a seguir cria o arquivo se ele estiver ausente.
    * Caso contrário, adicione a linha.

    Para adicionar a linha, execute este comando. Execute-o apenas uma vez, porque cada execução acrescenta outra linha.

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

    O comando imprime a linha que adiciona. A linha mapeia o nome `mnt` para o diretório que contém `memory`. O arquivo precisa de uma tabulação entre as duas colunas, que o `\t` escreve.
  </Step>

  <Step title="Criar o link">
    Execute o `apfs.util` com a opção `-t`. Ele cria o link a partir da linha que você adicionou, sem reiniciar.

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

  <Step title="Verificar o resultado">
    Liste `/mnt` e `/mnt/memory`.

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

    A primeira linha termina com `/mnt -> System/Volumes/Data/mnt`. A segunda linha mostra o usuário do worker como proprietário de `/mnt/memory`. Agora você pode iniciar o worker.
  </Step>
</Steps>

A Anthropic testou esta configuração no macOS 26.7.1 com o worker do `ant` CLI.

### Isolar sessões que compartilham um store

Duas sessões não podem montar o mesmo store em um sistema de arquivos ao mesmo tempo porque ambas precisam do mesmo caminho. Para executar lado a lado sessões que compartilham um store, dê a cada sessão seu próprio sistema de arquivos. Se você usar um sandbox para cada sessão, cada sessão recebe automaticamente seu próprio sistema de arquivos. Consulte [Executar um sandbox por sessão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session). Um host pode executar muitos desses sandboxes.

## Como o worker lida com a memória

Quando o worker reivindica um item de trabalho cuja sessão tem memory stores anexados, ele:

1. **Baixa cada store para seu `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`).** Este é o mesmo diretório em `/mnt/memory/` que as sessões em nuvem usam, e o prompt do sistema da sessão o descreve para o agente. Por exemplo, um store chamado “User Preferences” fica em `/mnt/memory/user-preferences/`.
2. **Abre esses diretórios para as ferramentas de arquivo.** O agente trabalha com as memórias usando as mesmas ferramentas de arquivo que usa no diretório de trabalho.
3. **Sincroniza após chamadas de ferramentas.** O worker sincroniza após uma chamada de ferramenta se o [intervalo de sincronização](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#sync-interval) (15 segundos por padrão) tiver passado desde sua última sincronização. Cada sincronização grava em disco as memórias que mudaram no store e envia os arquivos que o agente alterou.
4. **Executa uma sincronização final quando a sessão termina ou permanece ociosa pelo “idle limit” (limite de ociosidade) do worker.** A sincronização final pode levar até 60 segundos. Alterações não enviadas até lá são perdidas. Em seguida, o worker remove os diretórios que criou.

O limite de ociosidade é de 60 segundos por padrão. [Quando o worker termina de atender a uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference#when-the-worker-finishes-with-a-session) explica o que o limite abrange e como alterá-lo.

As ferramentas `write` e `edit` do agente alteram apenas a cópia local, e o worker envia essas alterações na sua próxima sincronização. Caminhos em `/mnt/memory/` fora dos diretórios dos stores não são “scratch space” (espaço temporário). As ferramentas de arquivo do worker se recusam a gravar neles, e qualquer coisa que um comando de shell grave ali nunca é sincronizada com um store.

[Versões de memória](https://platform.claude.com/docs/pt-BR/managed-agents/memory#audit-memory-changes), a remoção do conteúdo de versões (redact) e a visualização ou edição de memórias no Claude Console funcionam como nas sessões na nuvem. As leituras e gravações de memória do agente aparecem no [fluxo de eventos](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming) como eventos de ferramenta comuns.

Cada diretório de store contém um arquivo marcador chamado `.anthropic-memory-store` que vincula o diretório ao seu store. Mantenha-o no lugar. Se o marcador estiver ausente ou alterado e o diretório ainda contiver arquivos, o worker não sincroniza o diretório. Ele também não remove o diretório quando termina de atender à sessão.

<Warning>
  Se você parar um worker de forma controlada durante uma sessão ou [parar o item de trabalho da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully), o worker ainda envia arquivos novos e alterados. Ele também remove os diretórios dos stores. Ele não envia exclusões, então uma memória que o agente excluiu permanece no store, a menos que uma sincronização anterior já a tenha excluído do store. Um worker que é encerrado à força, em vez de parado, não executa nenhuma finalização, então edições não sincronizadas são perdidas e os diretórios dos stores permanecem. Consulte [Parar workers de forma controlada](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations#stop-workers-gracefully).
</Warning>

## Configurar a sincronização

Duas opções do `EnvironmentWorker` controlam o comportamento da memória. Defina-as onde quer que você construa o worker, inclusive em um handler de webhook. O worker da CLI `ant` sempre usa os padrões.

### Intervalo de sincronização

`memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) define o tempo mínimo entre duas sincronizações enquanto a sessão é executada.

| Configuração | Valor |
| ----- | ----- |
| Padrão | 15 segundos |
| Mínimo | 5 segundos |
| Exemplo (10 segundos) | `10` (typescript: `10_000`; go: `10 * time.Second`) |
| Desativar o suporte a memória | `None` (typescript: `null`; go: `-1`) |

O worker não sincroniza com base em um temporizador. Ele verifica o intervalo após cada chamada a uma ferramenta que é executada no seu sandbox, como `bash`, `read` ou uma ferramenta personalizada. A chamada não precisa envolver a memória. Sem chamadas de ferramentas, nada é sincronizado até a [sincronização final](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#how-the-worker-handles-memory). Uma alteração em uma sessão só chega a outra sessão em execução depois que ambas tiverem sincronizado, então a espera não tem duração fixa.

Um intervalo menor reduz a janela em que outra sessão vê memórias desatualizadas, ao custo de mais requisições ao memory store.

Desative o suporte a memória apenas em workers cujas sessões não anexam memory stores. Um worker com o suporte desativado não baixa nem sincroniza stores, então uma sessão com stores anexados é executada sem eles, mesmo que seu prompt do sistema ainda os descreva.

Enquanto o suporte a memória estiver ativado, um item de trabalho que chega sem um `secret` (csharp, go: `Secret`) para uma sessão com stores anexados falha, em vez de ser executado sem memória. Consulte [Memory stores não são montados ou sincronizados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount).

### Exclusões

`memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) define se um arquivo que o agente exclui localmente também é excluído do store. Envios e downloads não são afetados.

| Valor | Comportamento |
| ----- | ----- |
| `"enabled"` (go: `environments.MemorySyncDeletionsEnabled`) (padrão) | Exclui a memória do store assim que uma sincronização posterior confirma que o arquivo continua ausente. |
| `"log_only"` (go: `environments.MemorySyncDeletionsLogOnly`) | Executa as mesmas verificações, mas apenas registra em log o que teria excluído. Use-o para observar o que seus workers excluiriam antes de confiar no modo ativado. |
| `"disabled"` (go: `environments.MemorySyncDeletionsDisabled`) | Nunca exclui do store. |

Por exemplo, para sincronizar no máximo uma vez a cada 10 segundos e apenas registrar em log as exclusões que o worker teria feito, use o exemplo a seguir. O exemplo usa `/workspace` como diretório de trabalho, que precisa existir antes de o worker iniciar. [Executar um worker sempre ativo](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#run-an-always-on-worker) explica como criar o diretório e o que usar no macOS.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Um worker é um processo de longa duração, não uma única requisição HTTP. Para alterar as configurações de sincronização, use o `EnvironmentWorker` no SDK de Python, TypeScript ou Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    O worker da CLI `ant` sempre usa as configurações de sincronização padrão. Para alterá-las, use o `EnvironmentWorker` no SDK de Python, TypeScript ou 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#">
    O SDK C# não tem `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">
    O SDK Java não tem `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    O SDK PHP não tem `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    O SDK Ruby não tem `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## Stores somente leitura e conflitos

### Stores somente leitura

Para um store anexado com `access: "read_only"`, as ferramentas `write` e `edit` se recusam a alterar arquivos dentro do seu diretório. O worker nunca envia nada a partir dele.

Alterações feitas por meio de `bash` ou de uma ferramenta personalizada ou servidor MCP que você disponibiliza a partir do sandbox não são bloqueadas localmente. Elas nunca chegam ao store. Um arquivo alterado permanece alterado até que uma destas coisas aconteça:

* **Essa memória recebe uma nova versão no store.** A próxima sincronização do worker sobrescreve o arquivo com essa versão.
* **O worker termina de atender à sessão.** Ele remove o diretório.

Para manter também a cópia local inalterada, desative a ferramenta `bash` para esse agente. Além disso, não forneça a ele nenhuma ferramenta personalizada ou servidor MCP que grave no sistema de arquivos do sandbox. Não monte um volume somente leitura no caminho do store. A montagem coloca um diretório nesse caminho, e o worker marca o item de trabalho como falho se algo já existir ali.

### Conflitos

Um conflito é uma memória que mudou tanto no store quanto no sandbox desde a sincronização anterior. Uma exclusão conta como uma alteração. Para um store anexado com `access: "read_write"`, o worker resolve o conflito na próxima sincronização:

| No store | No sandbox | Resultado |
| ----- | ----- | ----- |
| Alterada | Alterada | A versão do store sobrescreve o arquivo. |
| Alterada | Excluída | O worker grava a versão do store de volta no sandbox. |
| Excluída | Alterada | O worker cria a memória novamente a partir do arquivo. |

Nas duas primeiras linhas, a alteração ou exclusão do agente é perdida, mesmo que a chamada de ferramenta tenha sido bem-sucedida. Nada avisa o agente, e o único sinal da perda é um aviso no log do worker. Na última linha, a exclusão no store é desfeita.

## Solução de problemas

Consulte [Memory stores não são montados ou sincronizados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount) para ver as mensagens de log do worker e suas correções.

## Disponibilidade

Memory stores em sandboxes auto-hospedados estão em beta em todos os modelos.

### Suporte da API

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

* Disponibilidade: Disponível

| Status | Plataformas de nuvem |
| ----- | ----- |
| Beta | Claude API |

### Cabeçalhos beta obrigatórios

[Visão geral dos cabeçalhos beta](https://platform.claude.com/docs/pt-BR/api/beta-headers)

Os cabeçalhos beta permitem que você acesse recursos experimentais e novas capacidades de modelos antes que eles se tornem parte da API padrão.

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

### Tratamento de dados

[Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility)

| Item | Retenção zero de dados | HIPAA |
| ----- | ----- | ----- |
| Status | Não elegível | Não elegível |
| Detalhes | Não é elegível para ZDR, exceto o Managed Agents auto-hospedado. Sessões são recursos com estado; as transcrições persistem até que você as exclua. [Saiba mais](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | Não é elegível para HIPAA. Aplica-se a todos os sub-recursos do Managed Agents. |

Endpoints aplicáveis:

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