Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Ogni sessione di Managed Agents inizia per impostazione predefinita con un contesto nuovo. Quando una sessione termina, qualsiasi stato che l'agente ha accumulato 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.
Un memory store è una raccolta di documenti di testo con ambito 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.
Ogni memoria in uno store è indirizzata da un percorso e può essere letta e modificata direttamente tramite l'API o la Claude Console, consentendo ottimizzazione, importazione ed esportazione.
Ogni modifica a una memoria crea una versione di memoria immutabile, fornendoti una traccia di audit e un ripristino point-in-time per tutto ciò che l'agente scrive.
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.
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/nullI 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.
Facoltativamente includi instructions per fornire indicazioni specifiche della sessione su come l'agente dovrebbe usare questo store. Viene mostrato all'agente insieme a name e description dello store, e ha un limite di 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:
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 non alfanumeriche 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 restano 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 versioni di memoria attribuite alla sessione.
Le letture e le scritture dell'agente compaiono nel flusso di eventi come normali eventi agent.tool_use e agent.tool_result per qualsiasi strumento abbia toccato il mount.
I memory store possono essere gestiti direttamente tramite l'API. Usa questa possibilità per costruire flussi di revisione, correggere memorie errate o popolare gli store prima che qualsiasi sessione venga eseguita.
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.
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.
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.
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/nullConsulta il riferimento Aggiorna una memoria per i parametri completi e lo schema della risposta.
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/nullant beta:memory-stores:memories delete \
--memory-store-id "$store_id" \
--memory-id "$mem_id" \
> /dev/nullConsulta il riferimento Elimina una memoria per i parametri completi e lo schema della risposta.
Ogni mutazione di una memoria crea una versione di memoria 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 tramite redact.
Le versioni appartengono allo store (non alla singola memoria) e sopravvivono anche dopo che la memoria stessa viene eliminata, così la traccia di audit resta 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 tornare indietro, 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.
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 di memoria per i parametri completi e lo schema della risposta.
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 di memoria per i parametri completi e lo schema della risposta.
Redact 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 live 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 di memoria per i parametri completi e lo schema della risposta.
Oltre a create, i memory store supportano retrieve, update, list, archive e delete.
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-archivedConsulta il riferimento Elenca memory store per i parametri completi e lo schema della risposta.
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.
Quando uno store raggiunge il limite di 2.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 restano leggibili e modificabili. Le seguenti pratiche ti aiutano a restare 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 2.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, 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.
Was this page helpful?