Managed Agents Memory Stores

Avancé

What you'll learn

Ce qu'est un Memory Store — et en quoi il diffère de l'ancien outil memory côté client
Comment les stores se montent dans le sandbox de session à /mnt/memory/ et comment l'agent les utilise
La règle de header bêta qui fait tomber les gens (agent-memory-2026-07-22 vs managed-agents-2026-04-01)
Le cycle de vie complet : create → seed → attach → read/write → audit versions → redact
Les limites concrètes : 8 stores par session, 2 000 mémoires par store, 100 kB par mémoire

Si vous avez construit avec les Managed Agents, vous savez que chaque session démarre avec un contexte frais par défaut. Quand la session se termine, ce que l'agent a appris part avec. Les Memory Stores sont le correctif first-party : collections côté serveur, versionnées, de documents texte qui persistent entre sessions et se montent dans le sandbox de l'agent comme un répertoire ordinaire qu'il peut lire et écrire avec ses outils de fichiers.

Memory Stores vs l'outil memory côté client

Il y a maintenant deux primitives « memory » différentes dans la plateforme Claude. Ne les confondez pas.

	Memory Stores (cette page)	Outil memory côté client (page séparée)
Où vit la mémoire	Hébergé Anthropic, scope workspace	Votre propre stockage (Redis, Postgres, fichiers…)
Qui fait tourner la boucle	Managed Agents	Vous (Messages API + boucle d'outils)
Header bêta	`agent-memory-2026-07-22`	`context-management-2025-06-27` (outil memory)
Comment l'agent la lit	Montée à `/mnt/memory/` comme fichiers	Appels d'outils (`view`, `str_replace`, `create`…)
Piste d'audit	Versions immuables, endpoint redact	Ce que vous construisez

Même idée (état persistant) ; primitive différente. Tout ce qui suit concerne les Memory Stores — la version côté serveur, pour Managed Agents uniquement.

Le modèle mental

Un store est un dossier de petits fichiers Markdown/texte (mémoires), scopé à votre workspace. Quand vous l'attachez à une session, il apparaît comme un montage à l'intérieur du sandbox, et Claude le lit et l'écrit avec le toolset agent standard — les mêmes outils qu'il utilise pour le reste du système de fichiers.

Deux corollaires importants :

Une note sur chaque montage (nom, chemin de montage, mode d'accès, description et toutes instructions par session) est automatiquement insérée dans le prompt système. L'agent sait que le montage existe sans que vous le lui disiez.
Les écritures hors du chemin de montage — n'importe où ailleurs sous /mnt/memory/ — atterrissent dans un scratch local au conteneur et sont perdues à la fin de la session. Seules les écritures vers le chemin de montage persistent.

La règle du header bêta (le piège)

C'est là où les gens perdent 20 minutes.

Watch out

Les endpoints memory-store utilisent anthropic-beta: agent-memory-2026-07-22 — rien d'autre.
Les endpoints de session (y compris attacher un memory store à une session) utilisent encore managed-agents-2026-04-01.
Envoyer les deux sur une requête memory-store retourne HTTP 400. Si votre code définit les headers bêta explicitement, remplacez — n'ajoutez pas.

Si vous utilisez le SDK officiel, il définit le bon header automatiquement. Si vous êtes sur du HTTP brut, séparez vos sites d'appel :

Appel	Header
`POST /v1/memory_stores` (create)	`agent-memory-2026-07-22`
`POST /v1/memory_stores/{id}/memories` (create/list/update/delete une mémoire)	`agent-memory-2026-07-22`
`POST /v1/memory_stores/{id}/memory_versions/…/redact`	`agent-memory-2026-07-22`
`POST /v1/sessions` — attacher un store dans `resources[]`	`managed-agents-2026-04-01`

Le cycle de vie

Guided walkthrough1 of 5

POST /v1/memory_stores avec un nom et une description. La description est passée à l'agent, donc elle doit se lire comme un brief : 'Préférences par utilisateur et contexte projet'.

Créer un store et une première mémoire

Le nom et la description du store sont ce que l'agent voit — écrivez-les comme vous écririez un README de dossier.

Créer le store (curl, HTTP brut)

curl -s https://api.anthropic.com/v1/memory_stores \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: agent-memory-2026-07-22" \
-H "content-type: application/json" \
-d '{"name": "User Preferences", "description": "Per-user preferences and project context."}'
# -> {"id": "memstore_01Hx...", ...}

Amorcer une mémoire

curl -s "https://api.anthropic.com/v1/memory_stores/$store_id/memories" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: agent-memory-2026-07-22" \
-H "content-type: application/json" \
-d '{"path": "/formatting_standards.md", "content": "All reports use GAAP formatting. Dates are ISO-8601."}'

Attacher un store à une session

Notez que le header repasse à managed-agents-2026-04-01 — les endpoints de session, y compris attach, utilisent le header Managed Agents.

Attacher à la création de session (read_write)

curl -s https://api.anthropic.com/v1/sessions \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "resources": [{
    "type": "memory_store",
    "memory_store_id": "$STORE_ID",
    "access": "read_write",
    "instructions": "User preferences and project context. Check before starting any task."
  }]
}'

Le champ instructions est plafonné à 4 096 caractères et montré à l'agent aux côtés du name et de la description du store.

Modes d'accès et le risque d'injection

access vaut read_write par défaut. C'est le bon choix quand l'agent doit apprendre de la session. C'est le mauvais choix pour un store que vous ne voulez pas laisser modifier par qui (ou quoi) que ce soit.

Watch out

Un store read_write est en aval de tout risque d'injection de prompt dans la session. Si l'agent traite des entrées non fiables (prompts utilisateur, pages récupérées, sortie d'outil tiers), une injection réussie peut écrire du contenu malicieux dans le store. Les sessions ultérieures le lisent alors comme mémoire de confiance.
Règle du pouce : matériel de référence partagé (standards, glossaires, docs de domaine) s'attache en read_only. Seul l'état par utilisateur ou par session qui doit grandir s'attache en read_write.
Attachez les deux si nécessaire : un store référence read_only plus un store scratch read_write. Jusqu'à 8 par session.

Les limites concrètes

Toutes des docs officielles, toutes bonnes à mémoriser :

Limite	Valeur
Memory stores par session	8
Mémoires par store	2 000
Octets par mémoire	100 kB (~25k tokens)
Longueur `instructions` (par attach)	4 096 caractères
Rétention des versions	30 jours (versions récentes toujours gardées)

Quand un store atteint 2 000 mémoires, les écritures suivantes — appels API directs et les propres écritures de fichiers de l'agent — commencent à échouer. Le correctif recommandé des docs n'est pas « un seul store géant » : utilisez beaucoup de petits stores focalisés (un par utilisateur, un pour la référence partagée, un par projet), élaguez les entrées obsolètes avec memories.delete, ou lancez une session de rêve pour consolider.

Piste d'audit, versions et rollback

Chaque écriture sur une mémoire crée une version de mémoire immuable (memver_...). Les versions appartiennent au store, pas à la mémoire, donc elles survivent même après que la mémoire elle-même est supprimée — la piste d'audit reste complète.

Patterns pratiques :

Inspection point-in-time : GET /v1/memory_stores/{id}/memory_versions?memory_id=… pour voir qui a changé quoi, plus récent d'abord.
Rollback : il n'y a pas d'endpoint restore dédié. Récupérez la version que vous voulez et réécrivez son content avec memories.update (ou memories.create si la mémoire parente est partie).
Éditions concurrentes sûres : passez une précondition content_sha256 sur memories.update. Si le hash de tête ne matche plus, votre update est rejetée et vous relisez avant de retry — concurrence optimiste classique.

Conformité : rédiger une version

Quand une PII, un secret ou une demande de suppression utilisateur nécessite que le contenu disparaisse de l'historique, utilisez redact. Ça gratte le contenu mais préserve la piste d'audit (qui a fait quoi, quand).

Pro tip

Vous ne pouvez pas rédiger la tête courante d'une mémoire vivante. Écrivez d'abord une nouvelle version (ou supprimez la mémoire), puis rédigez l'ancienne version.
Parce que les versions survivent à leur mémoire parente, supprimer la mémoire n'efface pas automatiquement l'historique — vous rédigez encore par version.
La rétention des versions est de 30 jours minimum. Si vous avez besoin d'une rétention plus longue pour conformité, exportez les versions via l'API avant qu'elles vieillissent.

Erreurs courantes

Pro tip

Envoyer les deux headers bêta sur un appel memory-store — vous obtenez HTTP 400. Remplacez, n'ajoutez pas.
Essayer d'ajouter ou retirer un store d'une session en cours — pas supporté. Attach se passe à la création de session, point.
Attacher un store référence partagé en read_write — une injection plus tard, vos standards sont corrompus pour chaque session future.
Un store géant au lieu de beaucoup de focalisés — vous atteindrez le plafond des 2 000 et bloquerez les écritures ultérieures.
Écrire à /mnt/memory/scratch/ en espérant que ça persiste — tout hors du chemin de montage est local au conteneur et s'évapore à la fin de session.

Vérifiez-vous

0/5

Vous envoyez une requête create memory-store avec les deux anthropic-beta: agent-memory-2026-07-22 et anthropic-beta: managed-agents-2026-04-01. Que se passe-t-il ?
Où un memory store apparaît-il à l'intérieur du sandbox de session ?
Votre agent traite des emails d'utilisateurs externes. Quel mode d'accès est le plus sûr pour un store partagé 'standards & glossaire' ?
Vous devez supprimer un secret leaké de l'historique. Quelle séquence marche ?
Quels sont le plafond de taille par mémoire et le nombre de mémoires par store ?

Key takeaways

Les Memory Stores sont la primitive de mémoire persistante côté serveur pour Managed Agents — différente de l'outil memory côté client.
La règle du header : agent-memory-2026-07-22 sur les endpoints memory-store, managed-agents-2026-04-01 sur les endpoints de session. Jamais les deux.
Les stores s'attachent à la création de session et se montent à /mnt/memory/[store-slug]/ ; ajout/retrait en cours de session pas supporté.
Défaut read_only pour la référence partagée ; seule la croissance par utilisateur ou par session doit être read_write.
Chaque écriture crée une version immuable ; rollback est 'récupérer + réécrire' ; redact gratte l'historique pour la conformité.

Suite

Managed Agents — le concept parent : agents, sessions, environnements, vaults, déploiements
Building Agents on the API — si vous roulez votre propre boucle
Memory Tool & Context Editing (côté client) — l'autre primitive memory
Prompt Injection — pourquoi read_only compte sur les stores partagés
Agent Memory Architectures — les patterns de conception derrière les systèmes de mémoire persistante

Memory Stores vs l'outil memory côté client​

Le modèle mental​

La règle du header bêta (le piège)​

Le cycle de vie​

Créer un store et une première mémoire​

Créer le store (curl, HTTP brut)

Amorcer une mémoire

Attacher un store à une session​

Attacher à la création de session (read_write)

Modes d'accès et le risque d'injection​

Les limites concrètes​

Piste d'audit, versions et rollback​

Conformité : rédiger une version​

Erreurs courantes​

Vérifiez-vous​

Vérifiez-vous

Suite​

Memory Stores vs l'outil memory côté client

Le modèle mental

La règle du header bêta (le piège)

Le cycle de vie

Créer un store et une première mémoire

Attacher un store à une session

Modes d'accès et le risque d'injection

Les limites concrètes

Piste d'audit, versions et rollback

Conformité : rédiger une version

Erreurs courantes

Vérifiez-vous

Suite