Memory Store per Managed Agents

Avanzato

What you'll learn

• Cos'è un Memory Store — e in cosa differisce dal precedente memory tool client-side
• Come i store si montano nella sandbox della sessione in /mnt/memory/ e come l'agente li usa
• La regola del beta header che frega tutti (agent-memory-2026-07-22 vs managed-agents-2026-04-01)
• Il ciclo di vita completo: create → seed → attach → read/write → audit delle versioni → redact
• I limiti concreti: 8 store per sessione, 2.000 memorie per store, 100 kB per memoria

Ultima verifica: 2026-07-30.

I Memory Store sono in public beta dal 22 luglio 2026. Endpoint, stringhe degli header e limiti cambiano durante la beta — verifica contro il riferimento ufficiale prima di andare in produzione.

Conferma confrontando con la fonte ufficiale.

Se hai lavorato con i Managed Agents, sai che di default ogni sessione parte con un contesto pulito. Quando la sessione finisce, tutto quello che l'agente ha imparato se ne va con lei. I Memory Store sono la soluzione first-party: collezioni versionate di documenti di testo, gestite server-side, che persistono tra sessioni e si montano nella sandbox dell'agente come una normale directory che può leggere e scrivere con i suoi file tool.

Memory Store vs il memory tool client-side

Nella piattaforma Claude esistono ora due primitive "memory" diverse. Non confonderle.

	Memory Store (questa pagina)	Memory tool client-side (pagina separata)
Dove vive la memoria	Ospitata da Anthropic, scope di workspace	Il tuo storage (Redis, Postgres, file…)
Chi guida il loop	Managed Agents	Tu (Messages API + tool loop)
Beta header	agent-memory-2026-07-22	context-management-2025-06-27 (memory tool)
Come l'agente la legge	Montata come file in /mnt/memory/	Chiamate a tool (view, str_replace, create…)
Audit trail	Versioni immutabili, endpoint di redact	Quello che costruisci tu

Stessa idea (stato persistente); primitiva diversa. Tutto quello che segue riguarda i Memory Store — quelli server-side, solo per Managed Agents.

Il modello mentale

Un store è una cartella di piccoli file Markdown/testo (memorie), con scope di workspace. Quando lo colleghi a una sessione, appare come un mount dentro la sandbox, e Claude lo legge e ci scrive con il toolset agente standard — gli stessi tool che usa per il resto del filesystem.

Due corollari importanti:

• Una nota su ogni mount (nome, mount path, access mode, descrizione e le eventuali instructions per la sessione) viene inserita automaticamente nel system prompt. L'agente sa che il mount esiste senza che tu debba dirglielo.
• Le scritture fuori dal mount path — ovunque altro sotto /mnt/memory/ — finiscono in scratch container-locale e si perdono quando la sessione termina. Persistono solo le scritture al mount path.

La regola del beta header (l'inghippo)

Qui la gente perde 20 minuti.

Watch out

• Gli endpoint dei memory store usano anthropic-beta: agent-memory-2026-07-22 — nient'altro.
• Gli endpoint delle sessioni (compreso il collegare un memory store a una sessione) usano ancora managed-agents-2026-04-01.
• Inviare entrambi in una richiesta a un memory store restituisce HTTP 400. Se il tuo codice imposta beta header espliciti, sostituisci — non aggiungere.

Se usi l'SDK ufficiale, imposta l'header corretto in automatico. Se sei su HTTP raw, separa i call site:

Chiamata	Header
POST /v1/memory_stores (create)	agent-memory-2026-07-22
POST /v1/memory_stores/{id}/memories (create/list/update/delete di una memoria)	agent-memory-2026-07-22
POST /v1/memory_stores/{id}/memory_versions/…/redact	agent-memory-2026-07-22
POST /v1/sessions — collegare uno store in resources[]	managed-agents-2026-04-01

Il ciclo di vita

Guided walkthrough1 of 5

1. POST /v1/memory_stores con un nome e una descrizione. La descrizione viene passata all'agente, quindi dovrebbe leggersi come un brief: 'Preferenze per-utente e contesto del progetto'.

Crea uno store e una prima memoria

Nome e descrizione dello store sono ciò che l'agente vede — scrivili come scriveresti il README di una cartella.

Crea lo store (curl, HTTP raw)

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...", ...}

Fai il seed di una memoria

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."}'

Collega uno store a una sessione

Nota che l'header ritorna a managed-agents-2026-04-01 — gli endpoint di sessione, incluso l'attach, usano l'header dei Managed Agents.

Attach alla creazione della sessione (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."
  }]
}'

Il campo instructions ha un tetto di 4.096 caratteri ed è mostrato all'agente insieme a name e description dello store.

Modalità di accesso e rischio di injection

access di default è read_write. È la scelta giusta quando l'agente deve imparare dalla sessione. È la scelta sbagliata per uno store che non vuoi che nessuno (o niente) modifichi.

Watch out

• Uno store read_write è a valle di qualsiasi rischio di prompt injection nella sessione. Se l'agente elabora input non fidato (prompt utente, pagine scaricate, output di tool di terze parti), una injection andata a segno può scrivere contenuto malevolo nello store. Sessioni successive lo rileggeranno come memoria fidata.
• Regola pratica: materiale di riferimento condiviso (standard, glossari, doc di dominio) si collega come read_only. Solo lo stato per-utente o per-sessione che deve crescere si collega read_write.
• Collegane due se serve: uno store di riferimento read_only più uno scratch read_write. Fino a 8 per sessione.

I limiti concreti

Tutti presi dai docs ufficiali, tutti da tenere a mente:

Limite	Valore
Memory store per sessione	8
Memorie per store	2.000
Byte per memoria	100 kB (~25k token)
Lunghezza instructions (per attach)	4.096 caratteri
Retention delle versioni	30 giorni (le versioni recenti restano sempre)

Quando uno store raggiunge le 2.000 memorie, le scritture successive — chiamate API dirette e le scritture di file dell'agente — iniziano a fallire. Il fix consigliato dai docs non è "uno store gigante": usa tanti store piccoli e focalizzati (uno per utente, uno per il riferimento condiviso, uno per progetto), pota le voci obsolete con memories.delete, o lancia una dreaming session per consolidare.

Audit trail, versioni e rollback

Ogni scrittura su una memoria crea una memory version immutabile (memver_...). Le versioni appartengono allo store, non alla memoria, quindi sopravvivono anche dopo che la memoria stessa viene cancellata — l'audit trail resta completo.

Pattern utili:

• Ispezione point-in-time: GET /v1/memory_stores/{id}/memory_versions?memory_id=… per vedere chi ha cambiato cosa, dal più recente.
• Rollback: non c'è un endpoint di restore dedicato. Recupera la versione che vuoi e riscrivi il suo content con memories.update (o memories.create se la memoria genitrice non c'è più).
• Edit concorrenti sicuri: passa una precondizione content_sha256 su memories.update. Se l'hash della head non corrisponde più, il tuo update viene rifiutato e rileggi prima di riprovare — classica optimistic concurrency.

Compliance: redact di una versione

Quando PII, un segreto o una richiesta di cancellazione utente richiedono che il contenuto sia sparito dalla history, usa redact. Cancella il contenuto ma preserva l'audit trail (chi ha fatto cosa, quando).

Pro tip

• Non puoi fare redact della head corrente di una memoria viva. Prima scrivi una nuova versione (o cancella la memoria), poi fai redact della versione vecchia.
• Poiché le versioni sopravvivono alla memoria genitrice, cancellare la memoria non cancella automaticamente la history — devi comunque fare redact per versione.
• La retention delle versioni è di 30 giorni minimo. Se ti serve una retention più lunga per compliance, esporta le versioni via API prima che scadano.

Errori comuni

Pro tip

• Inviare entrambi i beta header su una chiamata memory store — ottieni HTTP 400. Sostituisci, non aggiungere.
• Provare ad aggiungere o rimuovere uno store da una sessione in corso — non supportato. L'attach avviene alla creazione della sessione, punto.
• Collegare uno store di riferimento condiviso come read_write — una injection dopo, i tuoi standard sono corrotti per tutte le sessioni future.
• Uno store gigante invece di tanti focalizzati — ti scontri con il cap di 2.000 e blocchi le scritture successive.
• Scrivere in /mnt/memory/scratch/ sperando che persista — qualsiasi cosa fuori dal mount path è container-locale ed evapora a fine sessione.

Verifica

Verifica

0/5

1. 1Invii una richiesta di creazione memory store con entrambi anthropic-beta: agent-memory-2026-07-22 e anthropic-beta: managed-agents-2026-04-01. Cosa succede?
2. 2Dove appare un memory store dentro la sandbox della sessione?
3. 3Il tuo agente elabora email da utenti esterni. Quale access mode è più sicuro per uno store condiviso di 'standard e glossario'?
4. 4Devi cancellare un segreto trapelato dalla history. Quale sequenza funziona?
5. 5Qual è il cap di dimensione per memoria e il conteggio di memorie per store?

Key takeaways

• I Memory Store sono la primitiva server-side di memoria persistente per i Managed Agents — diversa dal memory tool client-side.
• La regola degli header: agent-memory-2026-07-22 sugli endpoint memory store, managed-agents-2026-04-01 sugli endpoint sessione. Mai entrambi.
• Gli store si collegano alla creazione della sessione e si montano in /mnt/memory/[store-slug]/; aggiungere/rimuovere in corso non è supportato.
• Default a read_only per il riferimento condiviso; solo la crescita per-utente o per-sessione deve essere read_write.
• Ogni scrittura crea una versione immutabile; il rollback è 'recupera + riscrivi'; redact cancella la history per la compliance.

Prossimi passi

• Managed Agents — il concetto padre: agenti, sessioni, environment, vault, deployment
• Costruire agenti sull'API — se ti gestisci il loop
• Memory Tool & Context Editing (client-side) — l'altra primitiva di memoria
• Prompt Injection — perché read_only conta sugli store condivisi
• Architetture di Agent Memory — i design pattern dietro i sistemi di memoria persistente