Utilizzo della memoria dell'agente

Utilizzo della memoria

Agent Memory è una funzione in Research Preview. Richiedi accesso per provarla.

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 da una sessione all'altra: preferenze dell'utente, convenzioni di progetto, errori precedenti e contesto di dominio.

Tutte le richieste dell'API Managed Agents richiedono l'intestazione beta managed-agents-2026-04-01. Un'intestazione beta aggiuntiva è necessaria per le funzioni in anteprima di ricerca. L'SDK imposta automaticamente queste intestazioni beta.

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 versione di memoria immutabile per supportare il controllo e il ripristino delle modifiche di memoria.

Crea un archivio di memoria

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

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

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

Popola con contenuto (facoltativo)

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

Le singole memorie all'interno dell'archivio sono limitate a 100KB (~25K token). Struttura la memoria come molti file piccoli e focalizzati, non pochi file grandi.

Allega un archivio di 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 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.

Strumento	Descrizione
`memory_list`	Elenca le memorie in un archivio, facoltativamente filtrate per prefisso di percorso.
`memory_search`	Ricerca full-text nei contenuti della memoria.
`memory_read`	Leggi i contenuti di una memoria.
`memory_write`	Crea o sovrascrivi una memoria in un percorso.
`memory_edit`	Modifica una memoria esistente.
`memory_delete`	Rimuovi una memoria.

Visualizza e modifica le memorie

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

Elenca le 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.

Crea una memoria

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

Scritture sicure (concorrenza ottimistica)

Passa precondition={"type": "not_exists"} a memories.write per renderla una protezione di sola creazione. Se una memoria esiste già al percorso, la scrittura restituisce 409 memory_precondition_failed invece di sostituirla. Usalo quando popoli un archivio e desideri evitare di sovrascrivere il contenuto esistente.

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

Aggiorna una memoria

memories.update() modifica una memoria esistente per il suo mem_... ID. Puoi cambiare 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 no-op se qualcosa esiste già al target.

L'esempio seguente rinomina una memoria a un percorso di archivio:

Modifiche di contenuto sicure (concorrenza ottimistica)

Per modificare il contenuto di una memoria 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 la memoria e riprova con lo stato aggiornato.

Elimina una memoria

Facoltativamente passa expected_content_sha256 per un'eliminazione condizionale.

Controlla le modifiche della memoria

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

Una nuova versione viene scritta su ogni mutazione:

Il primo memories.write a un percorso crea una versione con operation: "created".
memories.update che cambia 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 cambiato cosa e quando, per ispezionare o ripristinare uno snapshot precedente, e per eliminare il contenuto sensibile dalla cronologia con redact.

Elencare versioni

Elencare i metadati della versione paginati per un archivio, dal più recente al più vecchio. 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 audit (chi ha fatto cosa, quando). Usalo per flussi di lavoro di conformità come la rimozione di segreti trapelati, PII, o richieste di cancellazione 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.

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

mem = client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)