Usare la memoria degli agenti

Ogni sessione di Managed Agents inizia per impostazione predefinita con un contesto nuovo. Quando una sessione termina, qualsiasi stato che l'agente ha costruito va perso. I "memory store" (archivi di memoria) consentono all'agente di trasportare informazioni tra le sessioni: preferenze dell'utente, convenzioni di progetto, errori precedenti e contesto di dominio.

Panoramica

Un memory store è una raccolta di documenti di testo con ambito a livello di workspace, ottimizzata per Claude. Quando colleghi uno store a una sessione, viene montato come directory all'interno della sandbox della sessione. L'agente lo legge e lo scrive con gli stessi strumenti per file che usa per il resto del filesystem, e una nota che descrive ciascun mount viene aggiunta automaticamente al "system prompt" (prompt di sistema), indicando all'agente dove cercare. Il toolset dell'agente è necessario per queste interazioni; assicurati di abilitarlo durante la creazione dell'agente. Nelle sandbox self-hosted, quella directory non è un mount live. Invece, l'environment worker dell'SDK scarica ogni store collegato nella tua sandbox prima che gli strumenti dell'agente vengano eseguiti e mantiene quella copia sincronizzata con lo store.

Ogni memory (memoria) in uno store è indirizzata da un percorso e può essere letta e modificata direttamente tramite l'API o la Claude Console, consentendo messa a punto, importazione ed esportazione.

Ogni modifica a una memoria crea una memory version (versione della memoria) immutabile, fornendoti una traccia di audit e un ripristino point-in-time per tutto ciò che l'agente scrive.

Crea un memory store

Assegna allo store un name e una description. La descrizione viene passata all'agente, indicandogli cosa contiene lo store.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

L'id del memory store (memstore_...) è ciò che passi quando colleghi lo store a una sessione.

Popolalo con contenuti (opzionale)

Precarica uno store con materiale di riferimento prima che qualsiasi agente venga eseguito:

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null

Collega un memory store a una sessione

I memory store vengono collegati nell'array resources[] della sessione quando la sessione viene creata. A differenza delle risorse file, i memory store possono essere collegati solo al momento della creazione della sessione; aggiungerne o rimuoverne uno da una sessione in esecuzione non è supportato. Colleghi i memory store nello stesso modo per le sessioni su cloud e sugli ambienti self-hosted; gli ambienti self-hosted accettano solo risorse memory_store.

Facoltativamente includi instructions per fornire indicazioni specifiche della sessione su come l'agente dovrebbe usare questo store. Viene mostrato all'agente insieme al name e alla description dello store, ed è limitato a 4.096 caratteri.

Puoi configurare anche access. Il valore predefinito è read_write (mostrato esplicitamente nell'esempio seguente), ma è supportato anche read_only.

ant beta:sessions create <<YAML
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.
YAML

È supportato un massimo di 8 memory store per sessione. Collega più store quando parti diverse della memoria hanno proprietari o regole di accesso differenti. Motivi comuni:

• Materiale di riferimento condiviso: uno store in sola lettura collegato a molte sessioni (standard, convenzioni, conoscenza di dominio), tenuto separato dallo store in lettura-scrittura proprio di ciascuna sessione.
• Mappatura sulla struttura del tuo prodotto: uno store per utente finale, per team o per progetto, condividendo una singola configurazione dell'agente.
• Cicli di vita diversi: uno store che sopravvive a qualsiasi singola sessione, o uno che vuoi archiviare secondo una propria pianificazione.

Come l'agente accede alla memoria

Ogni store collegato viene montato all'interno della sandbox della sessione come directory sotto /mnt/memory/. Il nome della directory è il nome visualizzato dello store sanificato in uno slug sicuro per il filesystem (in minuscolo; le sequenze di caratteri non alfanumerici diventano un singolo trattino), quindi uno store chiamato "Demo Memory" viene montato in /mnt/memory/demo-memory/. Il percorso esatto viene restituito nel campo mount_path della risorsa memory-store della sessione; leggilo da lì invece di costruirlo tu stesso. L'agente legge e scrive lo store con il toolset dell'agente standard. Le scritture sotto il percorso di mount vengono persistite nello store e rimangono sincronizzate tra le sessioni che lo condividono; le scritture su qualsiasi altro percorso sotto /mnt/memory/ falliscono, perché la sandbox monta quella directory padre in sola lettura. Una breve descrizione di ciascun mount (nome visualizzato, percorso di mount, modalità di accesso, description dello store ed eventuali instructions) viene aggiunta automaticamente al prompt di sistema.

access viene applicato a livello di filesystem: un mount read_only rifiuta le scritture, mentre le scritture su un mount read_write producono memory version attribuite alla sessione.

Le letture e scritture dell'agente appaiono nel flusso di eventi come normali eventi agent.tool_use e agent.tool_result per qualunque strumento abbia toccato il mount.

Visualizza e modifica le memorie

I memory store possono essere gestiti direttamente tramite l'API. Usalo per costruire flussi di revisione, correggere memorie errate o popolare gli store prima che qualsiasi sessione venga eseguita.

Elenca le memorie

Elenca le memorie in uno store. I risultati vengono restituiti in un ordine stabile definito dal server.

• path_prefix limita l'elenco a una directory. Deve terminare con / e corrisponde a segmenti di percorso interi, quindi path_prefix=/notes/ restituisce /notes/todo.md ma non /notes-archive/todo.md.
• depth controlla quanto in profondità va l'elenco sotto path_prefix: omettilo (o passa 0) per elencare l'intero sottoalbero, oppure passa 1 per elencare solo i figli immediati. Altri valori restituiscono un errore 400.

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/"

Consulta il riferimento Elenca memorie per i parametri completi e lo schema della risposta.

Leggi una memoria

Il recupero di una singola memoria restituisce il contenuto completo.

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Consulta il riferimento Recupera una memoria per i parametri completi e lo schema della risposta.

Crea una memoria

memories.create crea una memoria in un determinato path. La creazione non sovrascrive; per modificare una memoria esistente, usa memories.update.

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

Consulta il riferimento Crea una memoria per i parametri completi e lo schema della risposta.

Aggiorna una memoria

memories.update modifica una memoria esistente tramite ID. Puoi cambiare content, path (una ridenominazione) o entrambi. L'esempio rinomina una memoria in un percorso di archivio:

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

Consulta il riferimento Aggiorna una memoria per i parametri completi e lo schema della risposta.

Modifiche sicure del contenuto (concorrenza ottimistica)

Per evitare di sovrascrivere una scrittura concorrente, passa una precondizione content_sha256. L'aggiornamento viene applicato solo se l'hash del contenuto memorizzato corrisponde ancora a quello che hai letto; in caso di mancata corrispondenza, rileggi la memoria e riprova rispetto allo stato aggiornato.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null

Elimina una memoria

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

Consulta il riferimento Elimina una memoria per i parametri completi e lo schema della risposta.

Verifica le modifiche alla memoria

Ogni mutazione di una memoria crea una memory version immutabile (memver_...). Usa gli endpoint delle versioni per verificare chi ha cambiato cosa e quando, per ispezionare o ripristinare uno snapshot precedente, e per rimuovere contenuti sensibili dalla cronologia con redact.

Le versioni appartengono allo store (non alla singola memoria) e non vengono eliminate quando la memoria stessa viene eliminata, quindi la traccia di audit copre anche le memorie eliminate, nel rispetto della conservazione descritta di seguito. Le versioni vengono conservate per 30 giorni dopo la loro scrittura; tuttavia, le versioni recenti di una memoria attiva vengono sempre mantenute indipendentemente dall'età, quindi le memorie che cambiano raramente potrebbero conservare la cronologia oltre i 30 giorni. La chiamata live memories.retrieve restituisce sempre l'ultima versione; gli endpoint delle versioni ti forniscono la cronologia conservata.

Non esiste un endpoint di ripristino dedicato; per tornare indietro, recupera la versione desiderata e riscrivi il suo content con memories.update (o memories.create se la memoria padre è stata eliminata, a condizione che la versione desiderata sia ancora conservata).

Le versioni passate delle memorie potrebbero essere eliminate dopo 30 giorni. Per preservare la cronologia della memoria più a lungo, esporta le versioni tramite l'API.

Elenca le versioni

Elenca la cronologia delle versioni di uno store, dalla più recente. L'esempio filtra la cronologia di una singola memoria:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
# `list --format json` emette un oggetto JSON per ogni elemento.
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

Consulta il riferimento Elenca versioni della memoria per i parametri completi e lo schema della risposta.

Recupera una versione

Il recupero di una singola versione restituisce gli stessi campi della risposta di elenco più il corpo completo di content.

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consulta il riferimento Recupera una versione della memoria per i parametri completi e lo schema della risposta.

Oscura una versione

Redact (oscuramento) rimuove il contenuto da una versione storica preservando la traccia di audit (chi ha fatto cosa, quando). Usalo per flussi di conformità come la rimozione di segreti trapelati, PII o richieste di cancellazione degli utenti.

Una versione che è l'attuale head di una memoria attiva non può essere oscurata. Scrivi prima una nuova versione (o elimina la memoria), poi oscura quella vecchia.

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Consulta il riferimento Oscura una versione della memoria per i parametri completi e lo schema della risposta.

Gestisci i memory store

Oltre a create, i memory store supportano retrieve, update, list, archive e delete.

Elenca gli store

Elenca gli store nel workspace. Gli store archiviati sono esclusi per impostazione predefinita; passa include_archived: true per includerli.

ant beta:memory-stores list --include-archived

Consulta il riferimento Elenca memory store per i parametri completi e lo schema della risposta.

Archivia uno store

L'archiviazione rende uno store di sola lettura e impedisce che venga collegato a nuove sessioni. L'archiviazione è irreversibile; non esiste un'operazione di disarchiviazione.

ant beta:memory-stores archive --memory-store-id "$store_id"

Consulta il riferimento Archivia un memory store per i parametri completi e lo schema della risposta.

Per rimuovere definitivamente uno store insieme a tutte le sue memorie e versioni, usa memory_stores.delete.

Best practice per la gestione della memoria

Quando uno store raggiunge il suo limite di 10.000 memorie, le scritture di nuove memorie falliscono: sia le chiamate dirette a memories.create sia le scritture di file dell'agente su percorsi non mappati. Le memorie esistenti rimangono leggibili e modificabili. Le seguenti pratiche ti aiutano a rimanere ben al di sotto del limite e a recuperare senza problemi se lo raggiungi.

• Usa store mirati. Invece di un unico grande store generico, usa store più piccoli costruiti per uno scopo specifico: uno per utente, uno per la conoscenza di dominio condivisa e uno per il contesto specifico del progetto. Ogni store ha il proprio limite di 10.000 memorie, quindi mantenere gli store circoscritti riduce la probabilità che uno di essi si riempia.

• Condensa o sfoltisci prima che lo store si riempia. Elimina le memorie obsolete o ridondanti con memories.delete. Puoi anche eseguire una sessione di dreaming, che consolida i contenuti frammentati in un nuovo store di output separato invece di modificare l'originale. Sposta le tue sessioni su quello store di output, quindi archivia o elimina l'originale.

• Collega un nuovo store quando ha senso. Se uno store è cresciuto oltre il suo ambito utile, collegane uno nuovo per i nuovi contenuti e collega l'originale con accesso read_only. L'agente può leggere da entrambi scrivendo solo su quello nuovo.

• Limita l'accesso in scrittura dove appropriato. Le sessioni che leggono solo materiale di riferimento condiviso non hanno bisogno di read_write. Mantenere l'accesso in scrittura limitato alle sessioni che effettivamente aggiungono nuove memorie rende più facile tracciare da dove proviene la crescita.