Magasins de mémoire dans les sandboxes auto-hébergées

Les sessions sur un environnement auto-hébergé attachent des magasins de mémoire exactement comme le font les sessions sur des environnements cloud. Listez-les dans resources lorsque vous créez la session, comme indiqué dans Attacher un magasin de mémoire à une session. Une session accepte jusqu'à 8 magasins de mémoire.

La différence tient à qui matérialise le magasin. Sur un environnement auto-hébergé, c'est votre worker, et non l'infrastructure d'Anthropic, qui télécharge chaque magasin dans la sandbox et synchronise en retour les modifications de l'agent.

Prérequis

• Un worker qui monte les magasins de mémoire : Utilisez la CLI ant 1.33.0 ou une version ultérieure, ou EnvironmentWorker du SDK Python, TypeScript ou Go.
• Un système de fichiers POSIX : Les hôtes Windows ne sont pas pris en charge, car le worker requiert O_NOFOLLOW lorsqu'il ouvre les fichiers de mémoire. Un système de fichiers sensible à la casse est recommandé, afin que les chemins de mémoire qui ne diffèrent que par la casse n'entrent pas en collision.
• Un répertoire /mnt/memory accessible en écriture : Consultez Préparer l'hôte.
• Le secret de l'élément de travail : Si votre propre code lance le worker, transmettez-lui le secret de l'élément de travail.

Préparer l'hôte

Avant de démarrer le worker, créez le répertoire parent et rendez-le accessible en écriture par l'utilisateur sous lequel le worker s'exécute :

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

Ne créez pas vous-même les répertoires propres à chaque magasin. Le worker crée le répertoire mount_path de chaque magasin (par exemple, /mnt/memory/user-preferences) au démarrage d'une session et le supprime à la fin de la session. Si quelque chose existe déjà à ce chemin, le worker refuse de démarrer le travail de la session.

Dans le modèle une sandbox par session, l'image de la sandbox a besoin d'un /mnt/memory accessible en écriture. Vous n'avez pas besoin de monter les répertoires de mémoire sur l'hôte (bind mount), car le worker téléverse leur contenu vers le magasin avant que la sandbox ne se termine.

Isoler les sessions qui partagent un magasin

Deux sessions ne peuvent pas monter le même magasin sur un même hôte en même temps, car elles ont toutes deux besoin du même chemin. Si vos sessions attachent le même magasin, exécutez une session par système de fichiers. Donner à chaque session sa propre sandbox satisfait cette règle.

Comment le worker gère la mémoire

Lorsque le worker réclame un élément de travail dont la session a des magasins de mémoire attachés, il :

1. Télécharge chaque magasin vers son mount_path. Il s'agit du même répertoire sous /mnt/memory/ que celui utilisé par les sessions cloud, et l'invite système de la session le décrit à l'agent. Par exemple, un magasin nommé « User Preferences » se retrouve dans /mnt/memory/user-preferences/.
2. Ouvre ces répertoires aux outils de fichiers. L'agent travaille sur les mémoires avec les mêmes outils de fichiers que ceux qu'il utilise dans le répertoire de travail.
3. Réconcilie les modifications après les appels d'outils, au plus une fois par intervalle de synchronisation (15 secondes par défaut). Les mémoires modifiées dans le magasin sont écrites sur le disque, et les fichiers modifiés par l'agent sont téléversés vers le magasin.
4. Exécute une synchronisation finale à la fin de la session. Il vide les téléversements encore en attente pendant 30 secondes au maximum, puis supprime les répertoires qu'il a créés.

Le magasin de mémoire côté Anthropic reste la source de vérité. Les versions de mémoire, le caviardage, ainsi que la consultation ou la modification des mémoires dans la Console fonctionnent comme pour les sessions cloud. Les lectures et écritures de mémoire de l'agent apparaissent dans le flux d'événements sous forme d'événements d'outils ordinaires.

Comme chaque worker se synchronise selon un intervalle, une modification écrite dans une session ne devient visible pour une autre session en cours d'exécution qu'une fois que les deux se sont synchronisées. Cela prend généralement bien moins d'une minute avec l'intervalle par défaut. Les sessions sur des sandboxes cloud voient les modifications des autres presque immédiatement.

Chaque répertoire de magasin contient un fichier marqueur nommé .anthropic-memory-store qui lie le répertoire à son magasin. Laissez-le en place : le worker ne synchronise pas un répertoire dont le marqueur est manquant ou altéré.

Configurer la synchronisation

Deux options de EnvironmentWorker contrôlent le comportement de la mémoire. Définissez-les partout où vous construisez le worker, y compris dans un gestionnaire de webhook. Le worker de la CLI ant utilise toujours les valeurs par défaut.

Intervalle de synchronisation

memory_sync_interval définit la fréquence à laquelle les magasins attachés se réconcilient avec le serveur pendant l'exécution de la session.

Un intervalle plus court réduit la fenêtre pendant laquelle une autre session voit des mémoires obsolètes, au prix d'un plus grand nombre de requêtes vers le magasin de mémoire.

Ne désactivez la prise en charge de la mémoire que sur les workers dont les sessions n'attachent aucun magasin de mémoire. Un worker désactivé ne télécharge ni ne synchronise les magasins, de sorte qu'une session avec des magasins attachés s'exécute sans eux, même si son invite système les décrit toujours.

Tant que la prise en charge de la mémoire est activée, un élément de travail qui arrive sans secret pour une session avec des magasins attachés échoue plutôt que de s'exécuter sans mémoire. Consultez Les magasins de mémoire ne parviennent pas à se monter.

Suppressions

memory_sync_deletions détermine si un fichier que l'agent supprime localement est également supprimé du magasin. Les téléversements et les téléchargements ne sont pas affectés.

Par exemple, pour synchroniser toutes les 10 secondes et seulement journaliser les suppressions que le worker aurait effectuées :

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

Magasins en lecture seule et conflits

Pour un magasin attaché avec access: "read_only", les outils write et edit refusent de modifier les fichiers de son répertoire. Le worker n'en téléverse jamais rien.

Les modifications effectuées via bash, ou via un outil personnalisé ou un serveur MCP que vous servez depuis la sandbox, ne sont pas bloquées localement. Elles ne sont jamais synchronisées vers le magasin, et la prochaine modification distante de cette mémoire les écrase. Si la copie locale elle-même doit rester inchangée pendant la session :

• Désactivez l'outil bash pour cet agent, et ne lui donnez aucun outil personnalisé qui écrit dans le système de fichiers de la sandbox.
• Ne montez pas le chemin du magasin en lecture seule. Le worker lui-même doit créer le répertoire et y écrire les mémoires téléchargées.

Les conflits sont résolus en faveur du magasin. Supposons que l'agent modifie un fichier de mémoire qui a également été modifié dans le magasin depuis la dernière synchronisation de la session. Lors de la synchronisation suivante, le worker conserve la version du magasin, écrase le fichier local avec celle-ci et journalise un avertissement. Les outils write et edit eux-mêmes réussissent et aucune erreur ne parvient à l'agent. Si la modification de l'agent reste pertinente, il peut relire le fichier après la synchronisation et effectuer à nouveau la modification.

Dépannage

Consultez Les magasins de mémoire ne parviennent pas à se monter pour les messages de journal du worker et leurs correctifs.