Menggunakan memori

Sesi API Managed Agents bersifat sementara secara default. Ketika sesi berakhir, apa pun yang dipelajari agen hilang. Penyimpan memori memungkinkan agen membawa pembelajaran di seluruh sesi: preferensi pengguna, konvensi proyek, kesalahan sebelumnya, dan konteks domain.

Gambaran Umum

Penyimpan memori adalah koleksi dokumen teks yang dibatasi ruang kerja dan dioptimalkan untuk Claude. Ketika satu atau lebih penyimpan memori dilampirkan ke sesi, agen secara otomatis memeriksa penyimpan sebelum memulai tugas dan menulis pembelajaran yang tahan lama setelah selesai - tidak perlu prompting atau konfigurasi tambahan dari pihak Anda.

Setiap memori dalam penyimpan dapat diakses dan diedit langsung melalui API atau Console, memungkinkan penyetelan, impor, dan ekspor memori.

Setiap perubahan pada memori membuat memory_version yang tidak dapat diubah untuk mendukung audit dan rollback perubahan memori.

Buat penyimpan memori

Berikan penyimpan nama name dan description. Deskripsi dilewatkan ke agen, memberi tahu apa yang berisi penyimpan.

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

id penyimpan memori (memstore_...) adalah apa yang Anda lewatkan saat melampirkan penyimpan ke sesi.

Isi dengan konten (opsional)

Pra-muat penyimpan dengan materi referensi sebelum agen apa pun berjalan:

Lampirkan memori ke sesi

Penyimpan memori dilampirkan dalam array resources[] sesi.

Secara opsional sertakan prompt jika Anda ingin memberikan instruksi khusus sesi kepada Claude tentang cara menggunakan penyimpan memori ini. Ini disediakan kepada Claude selain name dan description penyimpan memori, dan dibatasi pada 4.096 karakter.

Anda juga dapat mengonfigurasi access. Defaultnya adalah read_write, tetapi read_only juga didukung (ditampilkan secara eksplisit dalam contoh di bawah).

Maksimal 8 penyimpan memori didukung per sesi. Lampirkan beberapa penyimpan ketika bagian berbeda dari memori memiliki pemilik atau aturan akses yang berbeda. Alasan umum:

• Materi referensi bersama - satu penyimpan read-only dilampirkan ke banyak sesi (standar, konvensi, pengetahuan domain), dipisahkan dari pembelajaran read-write sesi masing-masing.
• Pemetaan ke struktur produk Anda - satu penyimpan per pengguna akhir, per-tim, atau per-proyek, sambil berbagi konfigurasi agen tunggal.
• Siklus hidup berbeda - penyimpan yang bertahan lebih lama dari sesi apa pun, atau yang ingin Anda arsipkan sesuai jadwal Anda sendiri.

Alat memori

Ketika penyimpan memori dilampirkan ke sesi, agen secara otomatis mendapatkan akses ke alat memori. Interaksi agen dengan penyimpan memori terdaftar sebagai acara agent.tool_use dalam aliran acara.

Inspeksi dan perbaiki memori

Penyimpan memori dapat dikelola langsung melalui API. Gunakan ini untuk membangun alur kerja tinjauan, memperbaiki memori buruk, atau menyemai penyimpan sebelum sesi apa pun berjalan.

Daftar memori

Daftar tidak mengembalikan konten memori, hanya metadata objek. Gunakan path_prefix untuk daftar yang dibatasi direktori (sertakan garis miring trailing: /notes/ cocok dengan /notes/a.md tetapi bukan /notes_backup/old.md).

Baca memori

Mengambil memori individual mengembalikan konten dokumen lengkap.

Tulis dokumen

Gunakan memories.write untuk upsert dokumen berdasarkan jalur. Jika tidak ada yang ada di jalur, itu dibuat; jika dokumen sudah ada di sana, kontennya diganti. Untuk mutasi dokumen yang ada berdasarkan ID mem_... (misalnya, untuk mengganti nama jalurnya atau dengan aman menerapkan edit konten), gunakan memories.update sebagai gantinya (lihat Update di bawah).

Buat hanya jika jalur bebas

Lewatkan precondition={"type": "not_exists"} ke memories.write untuk menjadikannya penjaga create-only. Jika dokumen sudah ada di jalur, penulisan mengembalikan 409 memory_precondition_failed alih-alih menggantinya. Gunakan ini saat menyemai penyimpan dan Anda ingin menghindari menimpa konten yang ada.

Untuk dengan aman mengedit dokumen yang ada (baca, ubah, tulis kembali tanpa menimpa perubahan bersamaan), gunakan memories.update dengan kondisi awal content_sha256 sebagai gantinya. Lihat Update di bawah.

Update

memories.update() memodifikasi dokumen yang ada berdasarkan ID mem_... nya. Anda dapat mengubah content, path (penggantian nama), atau keduanya dalam satu panggilan.

Mengganti nama ke jalur yang ditempati mengembalikan 409 conflict. Pemanggil harus menghapus atau mengganti nama pemblokir terlebih dahulu, atau meneruskan precondition={"type": "not_exists"} untuk membuat penggantian nama menjadi no-op jika ada yang sudah ada di target.

Contoh di bawah mengganti nama dokumen ke jalur arsip:

Edit konten yang aman (keselarasan optimis)

Untuk mengedit konten dokumen tanpa menimpa penulisan bersamaan, lewatkan kondisi awal content_sha256. Pembaruan hanya berlaku jika hash yang disimpan masih cocok dengan yang Anda baca; pada ketidakcocokan itu mengembalikan 409 memory_precondition_failed, di mana titik Anda membaca ulang dokumen dan mencoba lagi terhadap status segar.

Hapus dokumen

Secara opsional lewatkan expected_content_sha256 untuk penghapusan bersyarat.

Versi memori

Setiap mutasi ke memori membuat memory version yang tidak dapat diubah (memver_...). Versi terakumulasi untuk seumur hidup memori induk dan membentuk permukaan audit dan rollback di bawahnya. Panggilan memories.retrieve langsung selalu mengembalikan kepala saat ini; titik akhir versi memberi Anda riwayat lengkap.

Versi baru ditulis pada setiap mutasi:

• memories.write pertama ke jalur membuat versi dengan operation: "created".
• memories.update yang mengubah content, path, atau keduanya membuat versi dengan operation: "modified".
• memories.delete membuat versi dengan operation: "deleted".

Gunakan titik akhir versi untuk mengaudit pengguna atau agen mana yang mengubah apa dan kapan, untuk memeriksa atau mengembalikan snapshot sebelumnya, dan untuk menghapus konten sensitif dari riwayat dengan redact.

Daftar versi

Daftar metadata versi yang dipaginasi untuk sebuah toko, terbaru terlebih dahulu. Filter berdasarkan memory_id, operation (created, modified, atau deleted), session_id, api_key_id, atau rentang waktu created_at_gte/created_at_lte. Respons daftar tidak menyertakan badan content; ambil versi individual dengan retrieve ketika Anda memerlukan konten lengkap.

Ambil sebuah versi

Mengambil versi individual mengembalikan bidang yang sama dengan respons daftar ditambah badan content lengkap.

Redaksi sebuah versi

Redaksi menghapus konten dari versi historis sambil mempertahankan jejak audit (siapa yang melakukan apa, kapan). Gunakan untuk alur kerja kepatuhan seperti menghapus rahasia yang bocor, PII, atau permintaan penghapusan pengguna. Redaksi dengan keras menghapus content, content_sha256, content_size_bytes, dan path; semua bidang lainnya, termasuk aktor dan stempel waktu, dipertahankan.