Menggunakan memori agen
Berikan agen Anda memori persisten yang bertahan lintas sesi menggunakan memory store.
Setiap sesi Managed Agents dimulai dengan konteks baru secara default. Ketika sebuah sesi berakhir, semua state yang telah dibangun agen akan hilang. Memory store (penyimpanan memori) memungkinkan agen membawa informasi lintas sesi: preferensi pengguna, konvensi proyek, kesalahan sebelumnya, dan konteks domain.
Ikhtisar
Memory store adalah kumpulan dokumen teks dengan cakupan workspace yang dioptimalkan untuk Claude. Ketika Anda melampirkan store ke sesi, store tersebut di-mount sebagai direktori di dalam sandbox sesi. Agen membaca dan menulisnya dengan alat file yang sama yang digunakannya untuk bagian lain dari filesystem, dan catatan yang menjelaskan setiap mount secara otomatis ditambahkan ke prompt sistem, memberi tahu agen di mana harus mencari. Toolset agen diperlukan untuk interaksi ini; pastikan untuk mengaktifkannya selama pembuatan agen. Pada sandbox self-hosted, direktori tersebut bukan mount langsung. Sebagai gantinya, environment worker Anda mengunduh setiap store yang dilampirkan ke sandbox Anda sebelum alat agen berjalan dan menjaga salinan tersebut tetap sinkron dengan store.
Setiap memori dalam sebuah store dialamatkan dengan sebuah path dan dapat dibaca serta diedit langsung melalui API atau Claude Console, sehingga memungkinkan penyetelan, impor, dan ekspor.
Setiap perubahan pada memori menciptakan versi memori yang tidak dapat diubah (immutable), memberi Anda jejak audit dan pemulihan point-in-time untuk semua yang ditulis agen.
Membuat memory store
Berikan store sebuah name dan description. Deskripsi diteruskan ke agen, memberi tahu apa isi store tersebut.
ant apply memory_store.yaml# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.id memory store (memstore_...) adalah yang Anda teruskan saat melampirkan store ke sesi.
Mengisinya dengan konten awal (opsional)
Muat store terlebih dahulu dengan materi referensi sebelum agen apa pun berjalan:
client.beta.memory_stores.memories.create(
store.id,
path="/formatting_standards.md",
content="All reports use GAAP formatting. Dates are ISO-8601...",
)Melampirkan memory store ke sesi
Memory store dilampirkan dalam array resources sesi saat sesi dibuat. Tidak seperti resource file, memory store hanya dapat dilampirkan pada saat pembuatan sesi; menambahkan atau menghapusnya dari sesi yang sedang berjalan tidak didukung. Anda melampirkan memory store dengan cara yang sama untuk sesi di environment cloud maupun environment self-hosted; environment self-hosted hanya menerima resource memory_store.
Secara opsional, sertakan instructions untuk memberikan panduan khusus sesi tentang bagaimana agen harus menggunakan store ini. Instruksi ini ditampilkan kepada agen bersama name dan description store, dan dibatasi hingga 4.096 karakter.
Anda juga dapat mengonfigurasi access. Nilai default-nya adalah read_write (ditampilkan secara eksplisit dalam contoh berikut), tetapi read_only juga didukung.
session = client.beta.sessions.create(
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.",
}
],
)Maksimal 8 memory store didukung untuk setiap sesi. Lampirkan beberapa store ketika bagian memori yang berbeda memiliki pemilik atau aturan akses yang berbeda. Alasan umum:
- Materi referensi bersama: satu store read-only yang dilampirkan ke banyak sesi (standar, konvensi, pengetahuan domain), dipisahkan dari store read-write milik setiap sesi
- Pemetaan ke struktur produk Anda: satu store untuk setiap pengguna akhir, tim, atau proyek, sambil berbagi satu konfigurasi agen
- Siklus hidup yang berbeda: store yang bertahan lebih lama dari satu sesi mana pun, atau store yang ingin Anda arsipkan sesuai jadwalnya sendiri
Bagaimana agen mengakses memori
Setiap store yang dilampirkan di-mount di dalam sandbox sesi sebagai direktori di bawah /mnt/memory/. Nama direktori adalah nama tampilan store yang disanitasi menjadi slug yang aman untuk filesystem (huruf kecil, dengan setiap rangkaian karakter non-alfanumerik diganti dengan satu tanda hubung), sehingga store bernama “Demo Memory” di-mount di /mnt/memory/demo-memory/. Path yang tepat dikembalikan dalam field mount_path pada resource memory-store sesi; bacalah dari sana alih-alih menyusunnya sendiri. Agen membaca dan menulis store dengan toolset agen standar. Penulisan di bawah path mount disimpan kembali ke store dan tetap sinkron di seluruh sesi yang berbagi store tersebut; penulisan ke path lain mana pun di bawah /mnt/memory/ akan gagal, karena sandbox me-mount direktori induk tersebut sebagai read-only. Deskripsi singkat dari setiap mount (nama tampilan, path mount, mode akses, description store, dan instructions apa pun) secara otomatis ditambahkan ke prompt sistem.
access diberlakukan di tingkat filesystem: mount read_only menolak penulisan, sedangkan penulisan ke mount read_write menghasilkan versi memori yang diatribusikan ke sesi.
Pembacaan dan penulisan agen muncul dalam aliran event sebagai event agent.tool_use dan agent.tool_result biasa untuk alat mana pun yang menyentuh mount tersebut.
Melihat dan mengedit memori
Memory store dapat dikelola langsung melalui API. Gunakan ini untuk membangun alur kerja peninjauan, memperbaiki memori yang buruk, atau mengisi store sebelum sesi apa pun berjalan.
Mendaftar memori
Daftar memori dalam sebuah store. Hasil dikembalikan dalam urutan yang stabil dan ditentukan server.
path_prefixmembatasi daftar ke satu direktori. Nilainya harus diakhiri dengan/dan mencocokkan segmen path utuh, sehinggapath_prefix=/notes/mengembalikan/notes/todo.mdtetapi tidak/notes-archive/todo.md.depthmengontrol seberapa dalam daftar menjangkau di bawahpath_prefix: hilangkan (atau teruskan0) untuk mendaftar seluruh subtree, atau teruskan1untuk hanya mendaftar anak langsung. Nilai lain mengembalikan error400.
page = client.beta.memory_stores.memories.list(
store.id,
path_prefix="/",
)
for item in page.data:
print(item.type, item.path)Lihat referensi Mendaftar memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Membaca memori
Mengambil memori individual mengembalikan konten lengkapnya.
retrieved = client.beta.memory_stores.memories.retrieve(
mem.id,
memory_store_id=store.id,
)
print(retrieved.content)Lihat referensi Mengambil memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Membuat memori
client.beta.memory_stores.memories.create() membuat memori pada path tertentu. Create tidak menimpa; untuk memperbarui memori yang sudah ada, gunakan client.beta.memory_stores.memories.update().
mem = client.beta.memory_stores.memories.create(
store.id,
path="/preferences/formatting.md",
content="Always use tabs, not spaces.",
)Lihat referensi Membuat memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Memperbarui memori
client.beta.memory_stores.memories.update() memodifikasi memori yang sudah ada berdasarkan ID. Anda dapat mengubah content, path (penggantian nama), atau keduanya. Contoh berikut mengganti nama memori ke path arsip:
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md",
)Lihat referensi Memperbarui memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Pengeditan konten yang aman (konkurensi optimistis)
Untuk menghindari penimpaan penulisan yang terjadi secara bersamaan, teruskan prekondisi content_sha256. Pembaruan hanya diterapkan jika hash konten yang tersimpan masih cocok dengan yang Anda baca; jika tidak cocok, baca ulang memori dan coba lagi terhadap state terbaru.
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},
)Menghapus memori
client.beta.memory_stores.memories.delete(
mem.id,
memory_store_id=store.id,
)Lihat referensi Menghapus memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Mengaudit perubahan memori
Setiap mutasi pada memori menciptakan versi memori yang tidak dapat diubah (memver_...). Gunakan endpoint versi untuk mengaudit siapa yang mengubah apa dan kapan, untuk memeriksa atau memulihkan snapshot sebelumnya, dan untuk membersihkan konten sensitif dari riwayat dengan redact.
Versi dimiliki oleh store (bukan memori individual) dan tidak dihapus ketika memori itu sendiri dihapus, sehingga jejak audit juga mencakup memori yang telah dihapus, dengan tunduk pada retensi yang dijelaskan nanti. Versi disimpan selama 30 hari setelah ditulis; namun, versi terbaru dari memori yang aktif selalu disimpan tanpa memandang usianya, sehingga memori yang jarang berubah mungkin menyimpan riwayat lebih dari 30 hari. Panggilan client.beta.memory_stores.memories.retrieve() langsung selalu mengembalikan versi terbaru; endpoint versi memberi Anda riwayat yang disimpan.
Tidak ada endpoint pemulihan khusus; untuk melakukan rollback, ambil versi yang Anda inginkan dan tulis kembali content-nya dengan client.beta.memory_stores.memories.update() (atau client.beta.memory_stores.memories.create() jika memori induk telah dihapus, asalkan versi yang Anda inginkan masih disimpan).
Versi memori lama mungkin dihapus setelah 30 hari. Untuk mempertahankan riwayat memori lebih lama, ekspor versi melalui API.
Mendaftar versi
Daftar riwayat versi untuk sebuah store, yang terbaru lebih dulu. Contoh berikut memfilter ke riwayat satu memori:
versions = client.beta.memory_stores.memory_versions.list(
store.id,
memory_id=mem.id,
)
for version in versions:
print(f"{version.id}: {version.operation}")
version_id = versions.data[1].idLihat referensi Mendaftar versi memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Mengambil versi
Mengambil versi individual mengembalikan field yang sama dengan respons daftar ditambah isi content lengkap.
version = client.beta.memory_stores.memory_versions.retrieve(
version_id,
memory_store_id=store.id,
)
print(version.content)Lihat referensi Mengambil versi memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Meredaksi versi
Redact membersihkan konten dari versi historis sambil mempertahankan jejak audit (siapa melakukan apa, kapan). Gunakan untuk alur kerja kepatuhan seperti menghapus rahasia atau PII yang bocor, atau memenuhi permintaan penghapusan dari pengguna.
Versi yang merupakan head saat ini dari memori yang masih aktif tidak dapat diredaksi. Tulis versi baru terlebih dahulu (atau hapus memorinya), lalu redaksi versi lama.
client.beta.memory_stores.memory_versions.redact(
version_id,
memory_store_id=store.id,
)Lihat referensi Me-redact versi memoriPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Mengelola memory store
Selain createPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali., memory store mendukung retrievePratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali., updatePratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali., listPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali., archivePratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali., dan deletePratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali..
Mendaftar store
Daftar store di workspace. Store yang diarsipkan dikecualikan secara default; atur include_archived ke true untuk menyertakannya.
for memory_store in client.beta.memory_stores.list(include_archived=True):
print(memory_store.id, memory_store.name, memory_store.archived_at)Lihat referensi Mendaftar memory storePratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Mengarsipkan store
Pengarsipan membuat store menjadi read-only dan mencegahnya dilampirkan ke sesi baru. Pengarsipan bersifat satu arah; tidak ada pembatalan arsip.
client.beta.memory_stores.archive(store.id)Lihat referensi Mengarsipkan memory storePratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. untuk parameter lengkap dan skema respons.
Untuk menghapus store secara permanenPratinjau dengan tautan ke referensi API tersedia — tekan Tab hingga fokus masuk ke kartu, Escape untuk kembali. beserta semua memori dan versinya, panggil client.beta.memory_stores.delete().
Praktik terbaik untuk pengelolaan memori
Ketika sebuah store mencapai batas 10.000 memori, penulisan ke memori baru akan gagal: baik panggilan client.beta.memory_stores.memories.create() langsung maupun penulisan file oleh agen ke path yang belum dipetakan. Memori yang sudah ada tetap dapat dibaca dan diedit. Praktik berikut membantu Anda tetap jauh di bawah batas dan pulih dengan baik jika Anda mencapainya.
-
Gunakan store yang terfokus. Alih-alih satu store besar serba guna, gunakan store yang lebih kecil dan dibuat untuk tujuan tertentu: satu untuk setiap pengguna, satu untuk pengetahuan domain bersama, dan satu untuk konteks khusus proyek. Setiap store memiliki batas 10.000 memorinya sendiri, sehingga menjaga cakupan store mengurangi kemungkinan salah satunya penuh.
-
Ringkas atau pangkas sebelum store penuh. Hapus memori yang usang atau redundan dengan
client.beta.memory_stores.memories.delete(). Anda juga dapat menjalankan sesi dreaming, yang mengonsolidasikan konten yang terfragmentasi ke dalam store output baru yang terpisah alih-alih memodifikasi store asli. Alihkan sesi Anda ke store output tersebut, lalu arsipkan atau hapus store asli. -
Lampirkan store baru bila masuk akal. Jika sebuah store telah tumbuh melampaui cakupan kegunaannya, lampirkan store baru untuk konten baru dan lampirkan store asli dengan akses
read_only. Agen dapat membaca dari keduanya sambil hanya menulis ke store yang baru. -
Batasi akses tulis bila sesuai. Sesi yang hanya membaca materi referensi bersama tidak memerlukan
read_write. Menjaga akses tulis terbatas pada sesi yang benar-benar menambahkan memori baru memudahkan pelacakan dari mana pertumbuhan berasal.
Ketersediaan
Claude API
- Status
- Beta
- API
- Managed Agents
- Header beta
- Memerlukan
- Model
- Semua model
- Catatan
Mengirim
managed-agents-2026-04-01bersamaagent-memory-2026-07-22pada panggilan memory store akan menghasilkan error 400.
Claude Platform on AWS
- Status
- Beta
- API
- Managed Agents
- Header beta
- Memerlukan
- Model
- Semua model
- Catatan
Di Claude Platform on AWS, sesi pada environment yang di-host sendiri tidak dapat melampirkan memory store. Mengirim
managed-agents-2026-04-01bersamaagent-memory-2026-07-22pada panggilan memory store akan menghasilkan error 400.
Claude Models on Google Cloud (Anthropic managed)
- Status
- Beta
- API
- Managed Agents
- Header beta
- Memerlukan
- Model
- Semua model
- Catatan
Di Claude Models on Google Cloud (Anthropic managed), memory store tidak didukung untuk sesi pada environment yang di-host sendiri. Mengirim
managed-agents-2026-04-01bersamaagent-memory-2026-07-22pada panggilan memory store akan menghasilkan error 400.
Penanganan data
Ikhtisar penanganan dataEndpoint yang berlaku
/v1/agents/v1/sessions/v1/environments
Tidak memiliki kelayakan ZDR, kecuali untuk Managed Agents yang di-host sendiri. Sesi adalah sumber daya stateful; transkrip tetap tersimpan hingga Anda menghapusnya. Pelajari lebih lanjut
Tidak memiliki kelayakan HIPAA. Berlaku untuk semua subfitur Managed Agents.
Apakah halaman ini membantu?