---
title: Magasins de mémoire dans les sandboxes auto-hébergées
url: https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory
description: "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."
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
Les sessions sur un environnement auto-hébergé attachent des [magasins de mémoire](https://platform.claude.com/docs/fr/managed-agents/memory) exactement comme le font les sessions sur des environnements cloud. Listez-les dans `resources` (csharp, go: `Resources`) lorsque vous créez la session, comme indiqué dans [Attacher un magasin de mémoire à une session](https://platform.claude.com/docs/fr/managed-agents/memory#attach-a-memory-store-to-a-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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#prepare-the-host).
* **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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret).
Les magasins de mémoire ne peuvent pas être attachés aux sessions sur des environnements auto-hébergés sur [Claude Platform on AWS](https://platform.claude.com/docs/fr/build-with-claude/claude-platform-on-aws).
## 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 :
```bash
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` (java, php: `mountPath`; csharp, go: `MountPath`) 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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session) 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` (java, php: `mountPath`; csharp, go: `MountPath`).** 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](https://platform.claude.com/docs/fr/managed-agents/memory#audit-memory-changes), 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](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming) 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é.
Un worker qui est tué plutôt qu'arrêté n'exécute aucun nettoyage, de sorte que les modifications non synchronisées sont perdues et que les répertoires de magasin restent en place. Consultez [Arrêter les workers proprement](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations#stop-workers-gracefully).
## 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` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) définit la fréquence à laquelle les magasins attachés se réconcilient avec le serveur pendant l'exécution de la session.
| Paramètre | Valeur |
| ------------------------------------------- | --------------------------------------------------- |
| Par défaut | 15 secondes |
| Minimum | 5 secondes |
| Exemple (10 secondes) | `10` (typescript: `10_000`; go: `10 * time.Second`) |
| Désactiver la prise en charge de la mémoire | `None` (typescript: `null`; go: `-1`) |
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` (csharp, go: `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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount).
### Suppressions
`memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) 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.
| Valeur | Comportement |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"enabled"` (go: `environments.MemorySyncDeletionsEnabled`) (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"` (go: `environments.MemorySyncDeletionsLogOnly`) | 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"` (go: `environments.MemorySyncDeletionsDisabled`) | Ne supprime jamais rien du magasin. |
Par exemple, pour synchroniser toutes les 10 secondes et seulement journaliser les suppressions que le worker aurait effectuées :
```python Python
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
memory_sync_interval=10, # seconds
memory_sync_deletions="log_only",
)
```
```typescript TypeScript
const worker = new EnvironmentWorker({
client,
environmentId,
environmentKey,
workdir: "/workspace",
memorySyncIntervalMs: 10_000,
memorySyncDeletions: "log_only"
});
```
Le SDK C# ne dispose pas de `EnvironmentWorker`.
```go Go
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
EnvironmentID: environmentID,
EnvironmentKey: environmentKey,
Workdir: "/workspace",
MemorySyncInterval: 10 * time.Second,
MemorySyncDeletions: environments.MemorySyncDeletionsLogOnly,
})
```
Le SDK Java ne dispose pas de `EnvironmentWorker`.
Le SDK PHP ne dispose pas de `EnvironmentWorker`.
Le SDK Ruby ne dispose pas de `EnvironmentWorker`.
## 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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount) pour les messages de journal du worker et leurs correctifs.