Menggunakan memori agen

Setiap sesi Managed Agents dimulai dengan konteks baru secara default. Ketika sesi berakhir, semua state yang telah dibangun oleh agen akan hilang. "Memory store" (penyimpanan memori) memungkinkan agen membawa informasi di seluruh 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 sebuah 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 filesystem lainnya, dan catatan yang mendeskripsikan setiap mount secara otomatis ditambahkan ke prompt sistem, memberi tahu agen di mana harus mencari. Agent toolset diperlukan untuk interaksi ini; pastikan untuk mengaktifkannya selama pembuatan agen.

Setiap memory dalam sebuah store dialamatkan dengan path dan dapat dibaca serta diedit langsung melalui API atau Console, memungkinkan penyetelan, impor, dan ekspor.

Setiap perubahan pada memory membuat memory version 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 tersebut diteruskan ke agen, memberi tahu agen apa isi store tersebut.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

id memory store (memstore_...) adalah yang Anda berikan saat melampirkan store ke sesi.



Mengisi awal dengan konten (opsional)

Muat store terlebih dahulu dengan materi referensi sebelum agen dijalankan:

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null



Melampirkan memory store ke sesi

Memory store dilampirkan dalam array resources[] sesi saat sesi dibuat. Tidak seperti resource file dan repository, memory store hanya dapat dilampirkan pada saat pembuatan sesi; menambahkan atau menghapusnya dari sesi yang sedang berjalan tidak didukung.

Secara opsional sertakan instructions untuk memberikan panduan spesifik sesi tentang bagaimana agen harus menggunakan store ini. Instruksi ini ditampilkan kepada agen bersama dengan 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.

ant beta:sessions create <<YAML
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.
YAML

Maksimum 8 memory store didukung per sesi. Lampirkan beberapa store ketika bagian memory 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.
• Memetakan ke struktur produk Anda: satu store per pengguna akhir, per tim, atau per proyek, sambil berbagi satu konfigurasi agen.
• Siklus hidup yang berbeda: store yang bertahan lebih lama dari satu sesi, atau yang ingin Anda arsipkan dengan jadwalnya sendiri.



Bagaimana agen mengakses memory

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; rangkaian karakter non-alfanumerik menjadi 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; baca dari sana daripada menyusunnya sendiri. Agen membaca dan menulis store dengan agent toolset standar. Penulisan di bawah mount path dipersistenkan kembali ke store dan tetap sinkron di seluruh sesi yang membagikannya; penulisan ke path lain di bawah /mnt/memory/ masuk ke scratch lokal container dan hilang ketika sesi berakhir. Deskripsi singkat dari setiap mount (nama tampilan, mount path, mode akses, description store, dan instructions apa pun) secara otomatis ditambahkan ke prompt sistem.

access diberlakukan pada level filesystem: mount read_only menolak penulisan, sementara penulisan ke mount read_write menghasilkan memory version yang diatribusikan ke sesi.

Pembacaan dan penulisan agen muncul dalam event stream sebagai event agent.tool_use dan agent.tool_result biasa untuk alat mana pun yang menyentuh mount tersebut.



Melihat dan mengedit memory

Memory store dapat dikelola langsung melalui API. Gunakan ini untuk membangun alur kerja peninjauan, memperbaiki memory yang buruk, atau mengisi store sebelum sesi apa pun dijalankan.



Membuat daftar memory

Buat daftar memory dalam sebuah store, secara opsional difilter dengan path_prefix untuk menelusuri path seperti direktori:

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/" --order-by path --depth 2

Lihat referensi List memories untuk parameter lengkap dan skema respons.



Membaca memory

Mengambil memory individual mengembalikan konten lengkap.

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Lihat referensi Retrieve a memory untuk parameter lengkap dan skema respons.



Membuat memory

memories.create membuat memory pada path tertentu. Create tidak menimpa; untuk mengubah memory yang sudah ada, gunakan memories.update.

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

Lihat referensi Create a memory untuk parameter lengkap dan skema respons.



Memperbarui memory

memories.update memodifikasi memory yang sudah ada berdasarkan ID. Anda dapat mengubah content, path (penggantian nama), atau keduanya. Contoh berikut mengganti nama memory ke path arsip:

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

Lihat referensi Update a memory untuk parameter lengkap dan skema respons.



Edit konten yang aman (optimistic concurrency)

Untuk menghindari menimpa penulisan yang terjadi bersamaan, berikan prasyarat content_sha256. Pembaruan hanya diterapkan jika hash konten yang tersimpan masih cocok dengan yang Anda baca; jika tidak cocok, baca ulang memory dan coba lagi terhadap state yang baru.

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null



Menghapus memory

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

Lihat referensi Delete a memory untuk parameter lengkap dan skema respons.



Audit perubahan memory

Setiap mutasi pada memory membuat memory version yang tidak dapat diubah (memver_...). Gunakan endpoint version untuk mengaudit siapa yang mengubah apa dan kapan, untuk memeriksa atau memulihkan snapshot sebelumnya, dan untuk menghapus konten sensitif dari riwayat dengan redact.

Version dimiliki oleh store (bukan memory individual) dan tetap ada bahkan setelah memory itu sendiri dihapus, sehingga jejak audit tetap lengkap. Version disimpan selama 30 hari; namun, version terbaru selalu disimpan terlepas dari usianya, sehingga memory yang jarang berubah mungkin mempertahankan riwayat lebih dari 30 hari. Panggilan memories.retrieve langsung selalu mengembalikan version terbaru; endpoint version memberi Anda riwayat yang disimpan.

Tidak ada endpoint restore khusus; untuk melakukan rollback, ambil version yang Anda inginkan dan tulis kembali content-nya dengan memories.update (atau memories.create jika memory induk telah dihapus, karena version bertahan lebih lama dari induknya).

Memory version lama mungkin dihapus setelah 30 hari. Untuk mempertahankan riwayat memory lebih lama, ekspor version melalui API.



Membuat daftar version

Buat daftar riwayat version untuk sebuah store, yang terbaru lebih dulu. Contoh berikut memfilter ke riwayat satu memory:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

Lihat referensi List memory versions untuk parameter lengkap dan skema respons.



Mengambil version

Mengambil version individual mengembalikan field yang sama seperti respons list ditambah isi content lengkap.

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Lihat referensi Retrieve a memory version untuk parameter lengkap dan skema respons.



Meredaksi version

Redact menghapus konten dari version historis sambil mempertahankan jejak audit (siapa melakukan apa, kapan). Gunakan ini untuk alur kerja kepatuhan seperti menghapus rahasia yang bocor, PII, atau permintaan penghapusan pengguna.

Version yang merupakan head saat ini dari memory yang aktif tidak dapat diredaksi. Tulis version baru terlebih dahulu (atau hapus memory), lalu redaksi yang lama.

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Lihat referensi Redact a memory version untuk parameter lengkap dan skema respons.



Mengelola memory store

Selain create, memory store mendukung retrieve, update, list, archive, dan delete.



Membuat daftar store

Buat daftar store dalam workspace. Store yang diarsipkan dikecualikan secara default; berikan include_archived: true untuk menyertakannya.

ant beta:memory-stores list --include-archived

Lihat referensi List memory stores 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 unarchive.

ant beta:memory-stores archive --memory-store-id "$store_id"

Lihat referensi Archive a memory store untuk parameter lengkap dan skema respons.

Untuk menghapus store secara permanen beserta semua memory dan version-nya, gunakan memory_stores.delete.



Praktik terbaik untuk manajemen memory

Ketika sebuah store mencapai batas 2.000 memory, penulisan ke memory baru akan gagal: baik panggilan memories.create langsung maupun penulisan file agen ke path yang belum dipetakan. Memory 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. Daripada satu store besar serbaguna, gunakan store yang lebih kecil dan dibuat untuk tujuan tertentu — satu per pengguna, satu untuk pengetahuan domain bersama, dan satu untuk konteks spesifik proyek. Setiap store memiliki batas 2.000 memory sendiri, sehingga menjaga store tetap terbatas cakupannya mengurangi kemungkinan salah satunya penuh.

• Padatkan atau pangkas sebelum store penuh. Hapus memory yang usang atau redundan dengan memories.delete. Anda juga dapat menjalankan dreaming session, yang mengonsolidasikan konten yang terfragmentasi ke dalam store output baru yang terpisah daripada memodifikasi yang asli. Alihkan sesi Anda ke store output tersebut, lalu arsipkan atau hapus yang asli.

• Lampirkan store baru jika diperlukan. Jika sebuah store telah berkembang melampaui cakupan yang berguna, lampirkan store baru untuk konten baru dan lampirkan yang asli dengan akses read_only. Agen dapat membaca dari keduanya sambil hanya menulis ke yang baru.

• Batasi akses tulis jika sesuai. Sesi yang hanya membaca materi referensi bersama tidak memerlukan read_write. Menjaga akses tulis terbatas pada sesi yang benar-benar menambahkan memory baru memudahkan pelacakan dari mana pertumbuhan berasal.