Claude Platform Docs
Managed AgentsSandboxes auto-hospedados

Memory stores em sandboxes auto-hospedados

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.

Sessões em um ambiente auto-hospedado anexam memory stores exatamente como as sessões em ambientes de nuvem. Liste-os em resources ao criar a sessão, conforme mostrado em Anexar um memory store a uma sessão. 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. No macOS, consulte Preparar um host macOS.
  • O segredo do item de trabalho: Se o seu próprio código inicia o worker, encaminhe o segredo do item de trabalho para ele.

Preparar o host

No macOS, pule o próximo comando e siga Preparar um host macOS 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:

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

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

    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.

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

    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.

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

    sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
  4. Verificar o resultado

    Liste /mnt e /mnt/memory.

    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.

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. 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. 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 (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 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, 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 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.

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 define o tempo mínimo entre duas sincronizações enquanto a sessão é executada.

ConfiguraçãoValor
Padrão15 segundos
Mínimo5 segundos
Exemplo (10 segundos)10
Desativar o suporte a memóriaNone

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

Exclusões

memory_sync_deletions define se um arquivo que o agente exclui localmente também é excluído do store. Envios e downloads não são afetados.

ValorComportamento
"enabled" (padrão)Exclui a memória do store assim que uma sincronização posterior confirma que o arquivo continua ausente.
"log_only"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"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 explica como criar o diretório e o que usar no 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())

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 storeNo sandboxResultado
AlteradaAlteradaA versão do store sobrescreve o arquivo.
AlteradaExcluídaO worker grava a versão do store de volta no sandbox.
ExcluídaAlteradaO 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 para ver as mensagens de log do worker e suas correções.

Disponibilidade

Memory stores em sandboxes auto-hospedados
Status
Beta
API
  • Managed Agents
Cabeçalho beta
Requer
Modelos
  • Todos os modelos

Endpoints aplicáveis

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Retenção zero de dadosNão elegível

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

HIPAANão elegível

Não é elegível para HIPAA. Aplica-se a todos os sub-recursos do Managed Agents.

Esta página foi útil?