Menggunakan memori agen

Sesi Managed Agents API 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.

Ikhtisar

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 versi memori yang tidak dapat diubah untuk mendukung audit dan pengembalian perubahan memori.

Buat penyimpan memori

Berikan penyimpan name dan description. Deskripsi dilewatkan ke agen, memberitahunya apa yang berisi penyimpan.

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(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:

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...",
)

Lampirkan penyimpan 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).

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.",
        }
    ],
)

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.

Lihat dan edit 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 di belakang: /notes/ cocok dengan /notes/a.md tetapi bukan /notes_backup/old.md).

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]})"
    )

Baca memori

Mengambil memori individual mengembalikan konten lengkap.

mem = client.beta.memory_stores.memories.retrieve(
    memory_id,
    memory_store_id=store.id,
)
print(mem.content)

Buat memori

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

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

Penulisan aman (keselarasan optimis)

Lewatkan precondition={"type": "not_exists"} ke memories.write untuk menjadikannya penjaga create-only. Jika memori 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.

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"},
)

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

Perbarui memori

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

Penggantian 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 memori ke jalur arsip:

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

Edit konten aman (keselarasan optimis)

Untuk mengedit konten memori 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 memori dan mencoba lagi terhadap status segar.

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},
)

Hapus memori

client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id=store.id,
)

Secara opsional lewatkan expected_content_sha256 untuk penghapusan bersyarat.

Audit perubahan memori

Setiap mutasi ke memori membuat versi memori 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.

for v in client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
):
    print(f"{v.id}: {v.operation}")

Ambil sebuah versi

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

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

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.

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)