Utilizzo della memoria dell'agente

Ogni sessione di Managed Agents inizia con un contesto nuovo per impostazione predefinita. Quando una sessione termina, qualsiasi stato accumulato dall'agente viene perso. I "memory store" (archivi di memoria) consentono all'agente di trasferire 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 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 prompt di sistema, indicando all'agente dove cercare. Il toolset dell'agente è necessario per queste interazioni; assicurati di abilitarlo durante la creazione dell'agente.

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

Ogni modifica a una memoria crea una memory version (versione di memoria) immutabile, fornendoti una traccia di audit e il ripristino a un punto nel tempo per tutto ciò che l'agente scrive.



Creare 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.



Precaricare contenuti (opzionale)

Precarica uno store con materiale di riferimento prima di qualsiasi esecuzione dell'agente:

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



Collegare 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 e repository, i memory store possono essere collegati solo al momento della creazione della sessione; l'aggiunta o la rimozione da una sessione in esecuzione non è supportata.

Opzionalmente 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 anche configurare 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

Sono supportati 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 di sola lettura collegato a molte sessioni (standard, convenzioni, conoscenza di dominio), tenuto separato dallo store di lettura-scrittura proprio di ciascuna sessione.
• Mappatura alla struttura del tuo prodotto: uno store per utente finale, per team o per progetto, condividendo al contempo una singola configurazione dell'agente.
• Cicli di vita diversi: uno store che sopravvive a qualsiasi singola sessione, o uno che vuoi archiviare secondo una pianificazione propria.



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 compatibile con il filesystem (minuscolo; 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 sulla 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/ finiscono nello spazio temporaneo locale del container e vengono perse quando la sessione termina. 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 nello stream di eventi come normali eventi agent.tool_use e agent.tool_result per qualsiasi strumento abbia toccato il mount.



Visualizzare e modificare le memorie

I memory store possono essere gestiti direttamente tramite l'API. Usa questa funzionalità per creare flussi di revisione, correggere memorie errate o precaricare store prima di qualsiasi esecuzione di sessione.



Elencare le memorie

Elenca le memorie in uno store, opzionalmente filtrate per path_prefix per esplorare un percorso come una directory:

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

Consulta il riferimento List memories per i parametri completi e lo schema di risposta.



Leggere 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 Retrieve a memory per i parametri completi e lo schema di risposta.



Creare 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 Create a memory per i parametri completi e lo schema di risposta.



Aggiornare 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 Update a memory per i parametri completi e lo schema di 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 con lo 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



Eliminare una memoria

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

Consulta il riferimento Delete a memory per i parametri completi e lo schema di risposta.



Verificare 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 la redazione.

Le versioni appartengono allo store (non alla singola memoria) e sopravvivono anche dopo che la memoria stessa viene eliminata, quindi la traccia di audit rimane completa. Le versioni vengono conservate per 30 giorni; tuttavia, le versioni recenti 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 la versione più recente; gli endpoint delle versioni ti forniscono la cronologia conservata.

Non esiste un endpoint di ripristino dedicato; per eseguire il rollback, recupera la versione desiderata e riscrivi il suo content con memories.update (o memories.create se la memoria padre è stata eliminata, poiché le versioni sopravvivono al loro padre).

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



Elencare le versioni

Elenca la cronologia delle versioni per 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)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

Consulta il riferimento List memory versions per i parametri completi e lo schema di risposta.



Recuperare 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 Retrieve a memory version per i parametri completi e lo schema di risposta.



Redigere una versione

La redazione rimuove il contenuto da una versione storica preservando la traccia di audit (chi ha fatto cosa, quando). Usala per flussi di lavoro di conformità come la rimozione di segreti trapelati, PII o richieste di cancellazione utente.

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

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

Consulta il riferimento Redact a memory version per i parametri completi e lo schema di risposta.



Gestire i memory store

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



Elencare 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 List memory stores per i parametri completi e lo schema di risposta.



Archiviare uno store

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

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

Consulta il riferimento Archive a memory store per i parametri completi e lo schema di risposta.

Per rimuovere permanentemente 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 limite di 2.000 memorie, le scritture su nuove memorie falliscono: sia le chiamate dirette 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 agevolmente se lo raggiungi.

• Usa store mirati. Invece di un unico grande store generico, usa store più piccoli e specifici — 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 2.000 memorie, quindi mantenere gli store circoscritti riduce la probabilità che uno di essi si riempia.

• Condensa o elimina prima che lo store si riempia. Elimina le memorie obsolete o ridondanti con memories.delete. Puoi anche eseguire una dreaming session, che consolida i contenuti frammentati in un nuovo store di output separato invece di modificare l'originale. Passa le tue sessioni a quello store di output, poi 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.