Memory store nelle sandbox self-hosted

Le sessioni su un ambiente self-hosted collegano i memory store esattamente come fanno le sessioni sugli ambienti cloud. Elencali in resources quando crei la sessione, come mostrato in Collega un memory store a una sessione. Una sessione accetta fino a 8 memory store.

La differenza sta in chi materializza lo store. In un ambiente self-hosted è il tuo worker, anziché l'infrastruttura di Anthropic, a scaricare ogni store nella sandbox e a sincronizzare le modifiche dell'agente.

Requisiti

• Un worker che monta i memory store: Usa la CLI ant 1.33.0 o successiva, oppure EnvironmentWorker dall'SDK Python, TypeScript o Go.
• Un filesystem POSIX: Gli host Windows non sono supportati, perché il worker richiede O_NOFOLLOW quando apre i file di memoria. È consigliato un filesystem case-sensitive, in modo che i percorsi di memoria che differiscono solo per maiuscole e minuscole non entrino in conflitto.
• Una directory /mnt/memory scrivibile: Consulta Preparare l'host.
• Il segreto dell'elemento di lavoro: Se è il tuo codice ad avviare il worker, inoltragli il segreto dell'elemento di lavoro.

Preparare l'host

Prima di avviare il worker, crea la directory padre e rendila scrivibile dall'utente con cui viene eseguito il worker:

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

Non creare tu stesso le directory dei singoli store. Il worker crea la directory mount_path di ogni store (ad esempio, /mnt/memory/user-preferences) all'avvio di una sessione e la rimuove al termine della sessione. Se in quel percorso esiste già qualcosa, il worker si rifiuta di avviare il lavoro della sessione.

Nel pattern sandbox-per-sessione, l'immagine della sandbox necessita di una /mnt/memory scrivibile. Non è necessario eseguire il bind-mount delle directory di memoria sull'host, perché il worker carica il loro contenuto nello store prima che la sandbox termini.

Isolare le sessioni che condividono uno store

Due sessioni non possono montare lo stesso store su un host contemporaneamente, perché entrambe necessitano dello stesso percorso. Se le tue sessioni collegano lo stesso store, esegui una sessione per filesystem. Assegnare a ogni sessione la propria sandbox soddisfa questa regola.

Come il worker gestisce la memoria

Quando il worker acquisisce un elemento di lavoro la cui sessione ha memory store collegati:

1. Scarica ogni store nel relativo mount_path. Si tratta della stessa directory sotto /mnt/memory/ usata dalle sessioni cloud, e il prompt di sistema della sessione la descrive all'agente. Ad esempio, uno store chiamato "User Preferences" finisce in /mnt/memory/user-preferences/.
2. Rende accessibili quelle directory agli strumenti per i file. L'agente lavora sulle memorie con gli stessi strumenti per i file che usa nella directory di lavoro.
3. Riconcilia le modifiche dopo le chiamate agli strumenti, al massimo una volta per intervallo di sincronizzazione (15 secondi per impostazione predefinita). Le memorie modificate nello store vengono scritte su disco, e i file modificati dall'agente vengono caricati nello store.
4. Esegue una sincronizzazione finale al termine della sessione. Completa gli upload ancora in sospeso per un massimo di 30 secondi, quindi rimuove le directory che ha creato.

Il memory store lato Anthropic rimane la fonte di verità. Le versioni della memoria, la redazione e la visualizzazione o modifica delle memorie nella Console funzionano come per le sessioni cloud. Le letture e scritture di memoria dell'agente compaiono nello stream di eventi come normali eventi degli strumenti.

Poiché ogni worker si sincronizza a intervalli, una modifica scritta in una sessione diventa visibile a un'altra sessione in esecuzione solo dopo che entrambe si sono sincronizzate. Con l'intervallo predefinito, ciò richiede in genere ben meno di un minuto. Le sessioni su sandbox cloud vedono le modifiche reciproche quasi immediatamente.

Ogni directory di store contiene un file marcatore chiamato .anthropic-memory-store che lega la directory al suo store. Lascialo al suo posto: il worker non sincronizza una directory il cui marcatore è mancante o alterato.

Configurare la sincronizzazione

Due opzioni di EnvironmentWorker controllano il comportamento della memoria. Impostale ovunque costruisci il worker, anche in un handler di webhook. Il worker della CLI ant usa sempre i valori predefiniti.

Intervallo di sincronizzazione

memory_sync_interval imposta la frequenza con cui gli store collegati si riconciliano con il server durante l'esecuzione della sessione.

Un intervallo più breve restringe la finestra in cui un'altra sessione vede memorie obsolete, al costo di un maggior numero di richieste al memory store.

Disabilita il supporto della memoria solo sui worker le cui sessioni non collegano alcun memory store. Un worker disabilitato non scarica né sincronizza gli store, quindi una sessione con store collegati viene eseguita senza di essi anche se il suo prompt di sistema continua a descriverli.

Mentre il supporto della memoria è abilitato, un elemento di lavoro che arriva senza un secret per una sessione con store collegati fallisce anziché essere eseguito senza memoria. Consulta Il montaggio dei memory store non riesce.

Eliminazioni

memory_sync_deletions stabilisce se un file che l'agente elimina localmente viene eliminato anche dallo store. Upload e download non sono interessati.

Ad esempio, per sincronizzare ogni 10 secondi e registrare soltanto le eliminazioni che il worker avrebbe effettuato:

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

Store di sola lettura e conflitti

Per uno store collegato con access: "read_only", gli strumenti write ed edit si rifiutano di modificare i file all'interno della sua directory. Il worker non carica mai nulla da essa.

Le modifiche apportate tramite bash, o tramite uno strumento personalizzato o un server MCP che servi dalla sandbox, non vengono bloccate localmente. Non vengono mai sincronizzate con lo store, e la successiva modifica remota a quella memoria le sovrascrive. Se la copia locale stessa deve rimanere invariata durante la sessione:

• Disabilita lo strumento bash per quell'agente e non fornirgli alcuno strumento personalizzato che scriva nel filesystem della sandbox.
• Non montare il percorso dello store in sola lettura. È il worker stesso che deve creare la directory e scrivervi le memorie scaricate.

I conflitti si risolvono a favore dello store. Supponi che l'agente modifichi un file di memoria che è cambiato anche nello store dall'ultima sincronizzazione della sessione. Alla sincronizzazione successiva, il worker mantiene la versione dello store, sovrascrive con essa il file locale e registra un avviso. Gli strumenti write ed edit di per sé hanno esito positivo e nessun errore raggiunge l'agente. Se la modifica dell'agente è ancora pertinente, l'agente può rileggere il file dopo la sincronizzazione e apportare di nuovo la modifica.

Risoluzione dei problemi

Consulta Il montaggio dei memory store non riesce per i messaggi di log del worker e le relative soluzioni.