Utilizzo della memoria

Le sessioni dell'API Managed Agents sono effimere per impostazione predefinita. Quando una sessione termina, tutto ciò che l'agente ha imparato scompare. Gli archivi di memoria consentono all'agente di portare gli insegnamenti tra le sessioni: preferenze dell'utente, convenzioni di progetto, errori precedenti e contesto di dominio.

Panoramica

Un archivio di memoria è una raccolta di documenti di testo con ambito workspace ottimizzata per Claude. Quando uno o più archivi di memoria sono allegati a una sessione, l'agente controlla automaticamente gli archivi prima di iniziare un'attività e scrive gli insegnamenti durevoli al termine - non è necessaria alcuna richiesta aggiuntiva o configurazione da parte tua.

Ogni memoria in un archivio può essere accessibile e modificata direttamente tramite l'API o Console, consentendo l'ottimizzazione, l'importazione e l'esportazione di memorie.

Ogni modifica a una memoria crea una memory_version immutabile per supportare l'audit e il rollback delle modifiche di memoria.

Creare un archivio di memoria

Assegna all'archivio un name e una description. La descrizione viene passata all'agente, indicandogli cosa contiene l'archivio.

store=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -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" \
  --data @- <<EOF
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...

L'id dell'archivio di memoria (memstore_...) è quello che passi quando alleghi l'archivio a una sessione.

Seminalo con contenuto (facoltativo)

Pre-carica un archivio con materiale di riferimento prima di qualsiasi esecuzione dell'agente:

Allegare memoria a una sessione

Gli archivi di memoria sono allegati nell'array resources[] della sessione.

Facoltativamente includi un prompt se desideri fornire istruzioni specifiche della sessione a Claude su come utilizzare questo archivio di memoria. Viene fornito a Claude in aggiunta al name e alla description dell'archivio di memoria, ed è limitato a 4.096 caratteri.

Puoi anche configurare access. Per impostazione predefinita è read_write, ma è supportato anche read_only (mostrato esplicitamente nell'esempio seguente).

Un massimo di 8 archivi di memoria sono supportati per sessione. Allega più archivi quando diverse parti della memoria hanno proprietari o regole di accesso diversi. Motivi comuni:

• Materiale di riferimento condiviso - un archivio di sola lettura allegato a molte sessioni (standard, convenzioni, conoscenza di dominio), mantenuto separato dagli insegnamenti di lettura-scrittura propri di ogni sessione.
• Mappatura alla struttura del tuo prodotto - un archivio per utente finale, per team o per progetto, mentre si condivide una singola configurazione di agente.
• Cicli di vita diversi - un archivio che sopravvive a qualsiasi singola sessione, o uno che desideri archiviare secondo il tuo programma.

Strumenti di memoria

Quando gli archivi di memoria sono allegati a una sessione, l'agente ottiene automaticamente accesso agli strumenti di memoria. Le interazioni dell'agente con gli archivi di memoria sono registrate come eventi agent.tool_use nel flusso di eventi.

Ispezionare e correggere la memoria

Gli archivi di memoria possono essere gestiti direttamente tramite l'API. Usalo per costruire flussi di lavoro di revisione, correggere memorie errate o seminare archivi prima di qualsiasi esecuzione di sessione.

Elenca memorie

L'elenco non restituisce il contenuto della memoria, solo i metadati dell'oggetto. Usa path_prefix per elenchi con ambito directory (includi una barra finale: /notes/ corrisponde a /notes/a.md ma non a /notes_backup/old.md).

Leggi una memoria

Il recupero di una singola memoria restituisce il contenuto completo del documento.

Scrivi un documento

Usa memories.write per eseguire un upsert di un documento per percorso. Se non esiste nulla al percorso, viene creato; se un documento esiste già lì, il suo contenuto viene sostituito. Per mutare un documento esistente per mem_... ID (ad esempio, per rinominare il suo percorso o applicare in sicurezza una modifica del contenuto), usa invece memories.update (vedi Update di seguito).

Crea solo se il percorso è libero

Passa precondition={"type": "not_exists"} a memories.write per renderlo una guardia di creazione-solo. Se un documento esiste già al percorso, la scrittura restituisce 409 memory_precondition_failed invece di sostituirlo. Usalo quando semini un archivio e desideri evitare di sovrascrivere il contenuto esistente.

Per modificare in sicurezza un documento esistente (leggere, modificare, scrivere di nuovo senza sovrascrivere una modifica concorrente), usa memories.update con una precondizione content_sha256 invece. Vedi Update di seguito.

Update

memories.update() modifica un documento esistente per il suo mem_... ID. Puoi modificare content, path (una ridenominazione), o entrambi in una sola chiamata.

La ridenominazione su un percorso occupato restituisce 409 conflict. Il chiamante deve eliminare o rinominare il blocco prima, o passare precondition={"type": "not_exists"} per rendere la ridenominazione un'operazione nulla se qualcosa esiste già al target.

L'esempio seguente rinomina un documento a un percorso di archivio:

Modifiche di contenuto sicure (concorrenza ottimistica)

Per modificare il contenuto di un documento senza sovrascrivere una scrittura concorrente, passa una precondizione content_sha256. L'aggiornamento si applica solo se l'hash memorizzato corrisponde ancora a quello che hai letto; in caso di mancata corrispondenza restituisce 409 memory_precondition_failed, a quel punto rileggi il documento e riprova con lo stato fresco.

Elimina un documento

Facoltativamente passa expected_content_sha256 per un'eliminazione condizionale.

Versioni di memoria

Ogni mutazione a una memoria crea una memory version immutabile (memver_...). Le versioni si accumulano per la durata della memoria padre e formano la superficie di audit e rollback sottostante. La chiamata memories.retrieve dal vivo restituisce sempre l'head corrente; gli endpoint della versione ti danno la cronologia completa.

Una nuova versione viene scritta ad ogni mutazione:

• Il primo memories.write a un percorso crea una versione con operation: "created".
• memories.update che modifica content, path, o entrambi crea una versione con operation: "modified".
• memories.delete crea una versione con operation: "deleted".

Usa gli endpoint della versione per controllare quale utente o agente ha modificato cosa e quando, per ispezionare o ripristinare uno snapshot precedente, e per rimuovere il contenuto sensibile dalla cronologia con redact.

Elencare versioni

Elencare i metadati delle versioni impaginati per un archivio, dal più recente al meno recente. Filtrare per memory_id, operation (created, modified, o deleted), session_id, api_key_id, o un intervallo di tempo created_at_gte/created_at_lte. La risposta dell'elenco non include il corpo content; recuperare le versioni individuali con retrieve quando hai bisogno del contenuto completo.

Recuperare una versione

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

Redarre una versione

Redarre cancella il contenuto da una versione storica preservando la traccia di controllo (chi ha fatto cosa, quando). Utilizzalo per flussi di lavoro di conformità come la rimozione di segreti trapelati, dati personali identificabili o richieste di eliminazione dell'utente. Redarre cancella completamente content, content_sha256, content_size_bytes e path; tutti gli altri campi, inclusi l'attore e i timestamp, vengono preservati.