Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Ogni sessione di Managed Agents inizia con un contesto nuovo per impostazione predefinita. Quando una sessione termina, qualsiasi stato costruito dall'agente viene perso. I memory store consentono all'agente di trasferire informazioni tra le sessioni: preferenze dell'utente, convenzioni del progetto, errori precedenti e contesto di dominio.
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, questo viene montato come directory all'interno della sandbox della sessione. L'agente lo legge e lo scrive con gli stessi strumenti per i file che utilizza per il resto del filesystem, e una nota che descrive ogni mount viene aggiunta automaticamente al prompt di sistema, indicando all'agente dove cercare. L'agent toolset è 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 Console, consentendo la messa a punto, l'importazione e l'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 dell'esecuzione di qualsiasi 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/nullI memory store vengono collegati nell'array resources[] della sessione al momento della creazione della sessione. A differenza delle risorse di tipo 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.
Facoltativamente includi instructions per fornire indicazioni specifiche per la sessione su come l'agente dovrebbe utilizzare questo store. Viene mostrato all'agente insieme al name e alla 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 di caratteri non alfanumerici diventano un singolo trattino), quindi uno store denominato "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 l'agent toolset standard. Le scritture sotto il percorso di mount vengono persistite nello store e rimangono sincronizzate tra le sessioni che lo condividono; le scritture in qualsiasi altro percorso sotto /mnt/memory/ finiscono nello spazio temporaneo locale del container e vengono perse quando la sessione termina. Una breve descrizione di ogni mount (nome visualizzato, percorso di mount, modalità di accesso, description dello store e qualsiasi 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 appaiono nel flusso di eventi come normali eventi agent.tool_use e agent.tool_result per lo strumento che ha interagito con il mount.
I memory store possono essere gestiti direttamente tramite l'API. Usa questa funzionalità per creare flussi di lavoro di revisione, correggere memorie errate o popolare gli store prima dell'esecuzione di qualsiasi sessione.
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 completi, quindi path_prefix=/notes/ restituisce /notes/todo.md ma non /notes-archive/todo.md.depth controlla la profondità dell'elenco al di sotto di 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 per elencare le memorie per i parametri completi e lo schema di 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 per recuperare una memoria per i parametri completi e lo schema di 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 per creare una memoria per i parametri completi e lo schema di risposta.
memories.update modifica una memoria esistente tramite ID. Puoi modificare content, path (una rinomina) 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 per aggiornare una memoria per i parametri completi e lo schema di 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 sullo 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 per eliminare una memoria per i parametri completi e lo schema di risposta.
Ogni mutazione di una memoria crea una versione di memoria immutabile (memver_...). Usa gli endpoint delle versioni per verificare chi ha modificato 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 l'eliminazione della memoria stessa, 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 l'ultima versione; gli endpoint delle versioni ti forniscono la cronologia conservata.
Non esiste un endpoint dedicato per il ripristino; per tornare indietro, recupera la versione desiderata e riscrivi il suo content con memories.update (o memories.create se la memoria padre è stata eliminata, perché 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 per elencare le versioni di memoria per i parametri completi e lo schema di risposta.
Il recupero di una singola versione restituisce gli stessi campi della risposta dell'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 per recuperare una versione di memoria per i parametri completi e lo schema di risposta.
La redazione rimuove il contenuto da una versione storica preservando la traccia di audit (chi ha fatto cosa e quando). Usala per flussi di lavoro di conformità come la rimozione di segreti trapelati, PII o richieste di cancellazione da parte degli utenti.
Una versione che è l'attuale head di una memoria attiva non può essere redatta. Scrivi prima una nuova versione (o elimina la memoria), quindi redigi quella vecchia.
ant beta:memory-stores:memory-versions redact \
--memory-store-id "$store_id" \
--memory-version-id "$version_id"Consulta il riferimento per redigere una versione di memoria per i parametri completi e lo schema di 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 per elencare i memory store per i parametri completi e lo schema di risposta.
L'archiviazione rende uno store di sola lettura e ne impedisce il collegamento a nuove sessioni. L'archiviazione è unidirezionale; non esiste la disarchiviazione.
ant beta:memory-stores archive --memory-store-id "$store_id"Consulta il riferimento per archiviare un memory store per i parametri completi e lo schema di 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 rimangono leggibili e modificabili. Le seguenti pratiche ti aiutano a rimanere ben al di sotto del limite e a recuperare in modo controllato 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 con un ambito ristretto 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 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 sul 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?