Memory stores em sandboxes auto-hospedados

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. Recomenda-se 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.
• Um diretório /mnt/memory gravável: Consulte Preparar o host.
• 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

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 os diretórios de cada store. O worker cria o diretório mount_path de cada store (por exemplo, /mnt/memory/user-preferences) quando uma sessão começa e o remove quando a sessão termina. Se algo já existir nesse caminho, o worker se recusa a iniciar o trabalho da sessão.

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 worker envia o conteúdo deles para o store antes de o sandbox encerrar.

Isolar sessões que compartilham um store

Duas sessões não podem montar o mesmo store em um host ao mesmo tempo, porque ambas precisam do mesmo caminho. Se suas sessões anexam o mesmo store, execute uma sessão por sistema de arquivos. Dar a cada sessão seu próprio sandbox atende a essa regra.

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 o 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. Reconcilia as alterações após chamadas de ferramentas, no máximo uma vez por intervalo de sincronização (15 segundos por padrão). Memórias que mudaram no store são gravadas em disco, e arquivos que o agente alterou são enviados para o store.
4. Executa uma sincronização final quando a sessão termina. Ele conclui quaisquer envios ainda pendentes por até 30 segundos e, em seguida, remove os diretórios que criou.

O memory store do lado da Anthropic continua sendo a fonte da verdade. Versões de memória, redação e a visualização ou edição de memórias no Console funcionam como nas sessões em nuvem. As leituras e gravações de memória do agente aparecem no fluxo de eventos como eventos de ferramenta comuns.

Como cada worker sincroniza em um intervalo, uma alteração gravada em uma sessão só se torna visível para outra sessão em execução depois que ambas tiverem sincronizado. Isso normalmente leva bem menos de um minuto no intervalo padrão. Sessões em sandboxes na nuvem veem as alterações umas das outras quase imediatamente.

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: o worker não sincroniza um diretório cujo marcador esteja ausente ou alterado.

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 com que frequência os stores anexados se reconciliam com o servidor enquanto a sessão é executada.

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.

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.

Por exemplo, para sincronizar a cada 10 segundos e apenas registrar em log as exclusões que o worker teria feito:

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

Stores somente leitura e conflitos

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 são sincronizadas com o store, e a próxima alteração remota nessa memória as sobrescreve. Se a própria cópia local precisar permanecer inalterada durante a sessão:

• Desative a ferramenta bash para esse agente e não forneça a ele nenhuma ferramenta personalizada que grave no sistema de arquivos do sandbox.
• Não monte o caminho do store como somente leitura. O próprio worker precisa criar o diretório e gravar nele as memórias baixadas.

Conflitos são resolvidos em favor do store. Suponha que o agente altere um arquivo de memória que também mudou no store desde a última sincronização da sessão. Na próxima sincronização, o worker mantém a versão do store, sobrescreve o arquivo local com ela e registra um aviso em log. As próprias ferramentas write e edit são bem-sucedidas e nenhum erro chega ao agente. Se a alteração do agente ainda for aplicável, ele pode reler o arquivo após a sincronização e fazer a alteração novamente.

Solução de problemas

Consulte Memory stores não são montados para ver as mensagens de log do worker e suas correções.