Claude Platform Docs
Managed AgentsSandboxes auto-hébergées

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

Attachez des magasins de mémoire aux sessions Claude Managed Agents qui s’exécutent dans des sandboxes auto-hébergées : préparez l’hôte, configurez la synchronisation et gérez les magasins en lecture seule et les conflits.

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 exige O_NOFOLLOW lorsqu’il ouvre les fichiers de mémoire. Anthropic recommande un système de fichiers sensible à la casse, afin que les chemins de mémoire qui ne diffèrent que par la casse n’entrent pas en collision. Les volumes macOS sont insensibles à la casse par défaut, de sorte que de tels chemins y entrent en collision.
  • Un répertoire /mnt/memory accessible en écriture : Consultez Préparer l’hôte. Sur macOS, consultez Préparer un hôte macOS.
  • 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

Sur macOS, ignorez la commande suivante et suivez plutôt Préparer un hôte macOS.

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 vous-même le répertoire d’aucun magasin. Le worker crée le répertoire mount_path de chaque magasin, par exemple /mnt/memory/user-preferences, lorsqu’il réclame une session et le supprime lorsqu’il en a terminé avec cette session. Si quoi que ce soit existe déjà à ce chemin, même un répertoire vide, le worker fait échouer l’élément de travail.

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 magasin conserve la copie durable de chaque mémoire.

Préparer un hôte macOS

Sur macOS, le volume racine est en lecture seule, donc mkdir ne peut pas créer /mnt. Créez plutôt /System/Volumes/Data/mnt/memory sur le volume de données, qui est accessible en écriture. Ajoutez ensuite une ligne à /etc/synthetic.conf, afin que macOS crée /mnt sous la forme d’un lien symbolique vers /System/Volumes/Data/mnt. Ces étapes nécessitent des droits d’administrateur.

Sans cette configuration, le worker ne peut pas créer le répertoire d’un magasin, et il fait donc échouer l’élément de travail. La session reste alors inactive sans aucun événement d’erreur. Consultez Les magasins de mémoire ne parviennent pas à se monter ou à se synchroniser.

  1. Créer le répertoire sur le volume de données

    Créez le répertoire memory et faites de l’utilisateur du worker son propriétaire. $USER est votre propre nom d’utilisateur. Si le worker s’exécute sous un autre utilisateur, remplacez "$USER" par le nom de cet utilisateur.

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

    Cet emplacement n’est qu’une option parmi d’autres. Si vous en utilisez un autre, modifiez le chemin dans la ligne de synthetic.conf en conséquence. Anthropic n’a testé que /System/Volumes/Data/mnt.

  2. Ajouter une ligne à synthetic.conf

    Exécutez cat -et /etc/synthetic.conf, qui affiche chaque tabulation sous la forme ^I et chaque fin de ligne sous la forme $.

    • Si une ligne indique mnt^ISystem/Volumes/Data/mnt$, cette étape est déjà effectuée. Passez à l’étape suivante.
    • Si une autre ligne commence par mnt, arrêtez-vous. Un autre élément sur ce Mac définit déjà /mnt.
    • Si la dernière ligne ne se termine pas par $, exécutez echo | sudo tee -a /etc/synthetic.conf pour la terminer. Ajoutez ensuite la ligne.
    • Si la commande n’affiche rien ou signale No such file or directory, ajoutez la ligne. La commande suivante crée le fichier s’il est absent.
    • Sinon, ajoutez la ligne.

    Pour ajouter la ligne, exécutez cette commande. Ne l’exécutez qu’une seule fois, car chaque exécution ajoute une nouvelle ligne.

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

    La commande affiche la ligne qu’elle ajoute. Cette ligne associe le nom mnt au répertoire qui contient memory. Le fichier nécessite une tabulation entre les deux colonnes, que \t écrit.

  3. Créer le lien

    Exécutez apfs.util avec l’option -t. Elle crée le lien à partir de la ligne que vous avez ajoutée, sans redémarrage.

    sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
  4. Vérifier le résultat

    Listez /mnt et /mnt/memory.

    ls -ld /mnt /mnt/memory

    La première ligne se termine par /mnt -> System/Volumes/Data/mnt. La deuxième ligne indique l’utilisateur du worker comme propriétaire de /mnt/memory. Vous pouvez maintenant démarrer le worker.

Anthropic a testé cette configuration sur macOS 26.7.1 avec le worker du CLI ant.

Isoler les sessions qui partagent un magasin

Deux sessions ne peuvent pas monter le même magasin sur un même système de fichiers en même temps, car toutes deux ont besoin du même chemin. Pour exécuter côte à côte des sessions qui partagent un magasin, donnez à chaque session son propre système de fichiers. Si vous utilisez une sandbox par session, chaque session obtient automatiquement son propre système de fichiers. Consultez Exécuter une sandbox par session. Un même hôte peut exécuter de nombreuses sandboxes de ce type.

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. Se synchronise après les appels d’outils. Le worker se synchronise après un appel d’outil si l’intervalle de synchronisation (15 secondes par défaut) s’est écoulé depuis sa dernière synchronisation. Chaque synchronisation écrit sur le disque les mémoires modifiées dans le magasin et téléverse les fichiers que l’agent a modifiés.
  4. Exécute une synchronisation finale lorsque la session se termine ou reste inactive pendant la durée de l’« idle limit » (limite d’inactivité) du worker. La synchronisation finale peut prendre jusqu’à 60 secondes. Les modifications non téléversées d’ici là sont perdues. Le worker supprime ensuite les répertoires qu’il a créés.

La limite d’inactivité est de 60 secondes par défaut. Quand le worker en a terminé avec une session indique ce que couvre cette limite et comment la modifier.

Les outils write et edit de l’agent ne modifient que la copie locale, et le worker téléverse ces modifications lors de sa prochaine synchronisation. Les chemins sous /mnt/memory/ situés en dehors des répertoires de magasin ne constituent pas un « scratch space » (espace de travail temporaire). Les outils de fichiers du worker refusent d’y écrire, et tout ce qu’une commande shell y écrit n’est jamais synchronisé vers un magasin.

Les versions de mémoire, le caviardage, ainsi que la consultation ou la modification des mémoires dans la Claude 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.

Chaque répertoire de magasin contient un fichier marqueur nommé .anthropic-memory-store qui lie le répertoire à son magasin. Laissez-le en place. Si le marqueur est manquant ou altéré et que le répertoire contient encore des fichiers, le worker ne synchronise pas le répertoire. Il ne supprime pas non plus le répertoire lorsqu’il en a terminé avec la session.

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 le délai minimal entre deux synchronisations pendant l’exécution de la session.

ParamètreValeur
Par défaut15 secondes
Minimum5 secondes
Exemple (10 secondes)10
Désactiver la prise en charge de la mémoireNone

Le worker ne se synchronise pas selon un minuteur. Il vérifie l’intervalle après chaque appel à un outil qui s’exécute dans votre sandbox, comme bash, read ou un outil personnalisé. L’appel n’a pas besoin de toucher à la mémoire. Sans appels d’outils, rien n’est synchronisé jusqu’à la synchronisation finale. Une modification dans une session n’atteint une autre session en cours d’exécution qu’une fois que les deux se sont synchronisées, de sorte que l’attente n’a pas de durée fixe.

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 ou à se synchroniser.

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.

ValeurComportement
"enabled" (par défaut)Supprime la mémoire du magasin une fois qu’une synchronisation ultérieure confirme que le fichier a toujours disparu.
"log_only"Exécute les mêmes vérifications mais se contente de journaliser ce qu’il aurait supprimé. Utilisez-le pour observer ce que vos workers supprimeraient avant de faire confiance au mode activé.
"disabled"Ne supprime jamais rien du magasin.

Par exemple, pour synchroniser au plus une fois toutes les 10 secondes et seulement journaliser les suppressions que le worker aurait effectuées, utilisez l’exemple suivant. L’exemple utilise /workspace comme répertoire de travail, qui doit exister avant le démarrage du worker. Exécuter un worker toujours actif indique comment créer le répertoire et quoi utiliser sur 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())

Magasins en lecture seule et conflits

Magasins en lecture seule

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 n’atteignent jamais le magasin. Un fichier modifié reste modifié jusqu’à ce que l’un des événements suivants se produise :

  • Cette mémoire reçoit une nouvelle version dans le magasin. La prochaine synchronisation du worker écrase le fichier avec cette version.
  • Le worker en a terminé avec la session. Il supprime le répertoire.

Pour que la copie locale reste elle aussi inchangée, désactivez l’outil bash pour cet agent. Ne lui donnez pas non plus d’outils personnalisés ni de serveurs MCP qui écrivent dans le système de fichiers de la sandbox. Ne montez pas de volume en lecture seule au chemin du magasin. Le montage place un répertoire à ce chemin, et le worker fait échouer l’élément de travail si quoi que ce soit y existe déjà.

Conflits

Un conflit est une mémoire qui a été modifiée à la fois dans le magasin et dans la sandbox depuis la synchronisation précédente. Une suppression compte comme une modification. Pour un magasin attaché avec access: "read_write", le worker résout le conflit lors de la synchronisation suivante :

Dans le magasinDans la sandboxRésultat
ModifiéeModifiéeLa version du magasin écrase le fichier.
ModifiéeSuppriméeLe worker réécrit la version du magasin dans la sandbox.
SuppriméeModifiéeLe worker recrée la mémoire à partir du fichier.

Dans les deux premières lignes, la modification ou la suppression de l’agent est perdue, même si l’appel d’outil a réussi. Rien n’en informe l’agent, et le seul signe de la perte est un avertissement dans le journal du worker. Dans la dernière ligne, la suppression dans le magasin est annulée.

Dépannage

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

Disponibilité

Magasins de mémoire dans les sandboxes auto-hébergées
Statut
Bêta
API
  • Managed Agents
En-tête bêta
Nécessite
Modèles
  • Tous les modèles

Points de terminaison concernés

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Zéro conservation des donnéesNon éligible

Non éligible à la ZDR, sauf pour Managed Agents auto-hébergé. Les sessions sont des ressources avec état ; les transcriptions persistent jusqu’à ce que vous les supprimiez. En savoir plus

HIPAANon éligible

Non éligible à HIPAA. S’applique à toutes les sous-fonctionnalités de Managed Agents.

Cette page vous a-t-elle été utile ?