---
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
  zdr:
    eligibility: not-eligible
    note: 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.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
---

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 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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). Sur macOS, consultez [Préparer un hôte macOS](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-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-per-session#forward-the-work-items-secret).

## Préparer l’hôte

Sur macOS, ignorez la commande suivante et suivez plutôt [Préparer un hôte macOS](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host).

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 vous-même le répertoire d’aucun 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`, 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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-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 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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount).

<Steps>
  <Step title="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.

    ```bash
    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`.
  </Step>

  <Step title="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.

    ```bash
    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.
  </Step>

  <Step title="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.

    ```bash
    sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
    ```
  </Step>

  <Step title="Vérifier le résultat">
    Listez `/mnt` et `/mnt/memory`.

    ```bash
    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.
  </Step>
</Steps>

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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-per-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` (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. **Se synchronise après les appels d’outils.** Le worker se synchronise après un appel d’outil si l’[intervalle de synchronisation](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#sync-interval) (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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-reference#when-the-worker-finishes-with-a-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](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 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](https://platform.claude.com/docs/fr/managed-agents/events-and-streaming) 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.

<Warning>
  Si vous arrêtez proprement un worker pendant une session ou si vous [arrêtez l’élément de travail de la session](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully), le worker téléverse tout de même les fichiers nouveaux et modifiés. Il supprime également les répertoires de magasin. Il n’envoie aucune suppression, de sorte qu’une mémoire que l’agent a supprimée reste dans le magasin, sauf si une synchronisation antérieure l’a déjà supprimée du magasin. 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).
</Warning>

## 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 le délai minimal entre deux synchronisations 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`) |

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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-memory#how-the-worker-handles-memory). 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` (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 ou à se synchroniser](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 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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-sandboxes-workers#run-an-always-on-worker) indique comment créer le répertoire et quoi utiliser sur macOS.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Un worker est un processus de longue durée, et non une simple requête HTTP. Pour modifier les paramètres de synchronisation, utilisez `EnvironmentWorker` dans le SDK Python, TypeScript ou Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Le worker de la CLI `ant` utilise toujours les paramètres de synchronisation par défaut. Pour les modifier, utilisez `EnvironmentWorker` dans le SDK Python, TypeScript ou Go.
  </CodeGroupItem>

  ```python Python
  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())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });
  const controller = new AbortController();
  process.once("SIGINT", () => controller.abort());
  process.once("SIGTERM", () => controller.abort());

  const worker = new EnvironmentWorker({
    client,
    environmentId,
    environmentKey,
    workdir: "/workspace",
    signal: controller.signal,
    memorySyncIntervalMs: 10_000,
    memorySyncDeletions: "log_only"
  });
  await worker.run();
  ```

  <CodeGroupItem language="C#">
    Le SDK C# ne dispose pas de `EnvironmentWorker`.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"
  	"time"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		EnvironmentID:       environmentID,
  		EnvironmentKey:      environmentKey,
  		Workdir:             "/workspace",
  		MemorySyncInterval:  10 * time.Second,
  		MemorySyncDeletions: environments.MemorySyncDeletionsLogOnly,
  	})
  	if err := worker.Run(ctx); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Le SDK Java ne dispose pas de `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    Le SDK PHP ne dispose pas de `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Le SDK Ruby ne dispose pas de `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## 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 magasin | Dans la sandbox | Résultat |
| ----- | ----- | ----- |
| Modifiée | Modifiée | La version du magasin écrase le fichier. |
| Modifiée | Supprimée | Le worker réécrit la version du magasin dans la sandbox. |
| Supprimée | Modifiée | Le 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](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.

## Disponibilité

Magasins de mémoire dans les sandboxes auto-hébergées sont en bêta sur tous les modèles.

### Prise en charge de l’API

#### [Managed Agents](https://platform.claude.com/docs/fr/managed-agents/overview)

* Disponibilité : Disponible

| Statut | Plateformes cloud |
| ----- | ----- |
| Bêta | Claude API |

### En-têtes bêta requis

[Présentation des en-têtes bêta](https://platform.claude.com/docs/fr/api/beta-headers)

Les en-têtes bêta vous permettent d’accéder à des fonctionnalités expérimentales et à de nouvelles capacités des modèles avant qu’elles ne fassent partie de l’API standard.

* `managed-agents-2026-04-01`

### Traitement des données

[Présentation du traitement des données](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention#feature-eligibility)

| Élément | Zéro conservation des données | HIPAA |
| ----- | ----- | ----- |
| Statut | Non éligible | Non éligible |
| Détails | 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](https://platform.claude.com/docs/fr/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | Non éligible à HIPAA. S’applique à toutes les sous-fonctionnalités de Managed Agents. |

Points de terminaison concernés :

* `/v1/agents`
* `/v1/sessions`
* `/v1/environments`
