Menggunakan memori agen

Setiap sesi Managed Agents dimulai dengan konteks baru secara default. Ketika sesi berakhir, semua state yang dibangun agen akan hilang. Memory store 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 store ke sebuah sesi, store tersebut dipasang (mount) sebagai direktori di dalam sandbox sesi. Agen membaca dan menulisnya dengan alat file yang sama yang digunakan untuk sisa 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.

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

Setiap perubahan pada memori membuat 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 tersebut diteruskan ke agen, memberi tahu 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 teruskan saat melampirkan store ke sebuah sesi.



Mengisinya dengan konten (opsional)

Muat store terlebih dahulu dengan materi referensi sebelum agen apa pun berjalan:

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 sumber daya file dan repositori, 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 khusus sesi tentang bagaimana agen harus menggunakan store ini. Ini ditampilkan kepada agen bersama dengan name dan description store, dan dibatasi hingga 4.096 karakter.

Anda juga dapat mengonfigurasi access. Nilai defaultnya 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 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 masing-masing sesi.
• Pemetaan 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 mana pun, atau yang ingin Anda arsipkan dengan jadwalnya sendiri.



Bagaimana agen mengakses memori

Setiap store yang dilampirkan dipasang 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), jadi store bernama "Demo Memory" dipasang di /mnt/memory/demo-memory/. Path yang tepat dikembalikan dalam field mount_path pada sumber daya memory-store sesi; baca dari sana alih-alih membangunnya sendiri. Agen membaca dan menulis store dengan toolset agen 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 di tingkat filesystem: mount read_only menolak penulisan, sementara penulisan ke mount read_write menghasilkan versi memori yang diatribusikan ke sesi tersebut.

Pembacaan dan penulisan agen muncul di event stream 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

Daftarkan memori dalam sebuah store. Hasil dikembalikan dalam urutan stabil yang ditentukan server.

• path_prefix membatasi daftar ke satu direktori. Harus diakhiri dengan / dan mencocokkan segmen path utuh, jadi path_prefix=/notes/ mengembalikan /notes/todo.md tetapi tidak /notes-archive/todo.md.
• depth mengontrol seberapa dalam daftar berjalan di bawah path_prefix: hilangkan (atau berikan 0) untuk mendaftar seluruh subtree, atau berikan 1 untuk mendaftar hanya anak langsung. Nilai lain mengembalikan error 400.

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

Lihat referensi List memories untuk parameter lengkap dan skema respons.



Membaca memori

Mengambil memori 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 memori

memories.create membuat memori pada path tertentu. Create tidak menimpa; untuk mengubah memori 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 memori

memories.update memodifikasi memori yang sudah ada berdasarkan ID. Anda dapat mengubah content, path (penggantian nama), atau keduanya. Contoh ini mengganti nama memori 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.



Pengeditan konten yang aman (optimistic concurrency)

Untuk menghindari menimpa penulisan yang bersamaan, berikan prasyarat 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 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 memori

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 memori

Setiap mutasi pada memori membuat versi memori yang tidak dapat diubah (memver_...). Gunakan endpoint versi untuk mengaudit siapa 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 tetap ada bahkan setelah memori itu sendiri dihapus, sehingga jejak audit tetap lengkap. Versi disimpan selama 30 hari; namun, versi terbaru selalu disimpan terlepas dari usianya, jadi memori yang jarang berubah mungkin mempertahankan riwayat lebih dari 30 hari. Panggilan 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 memories.update (atau memories.create jika memori induknya telah dihapus, karena versi bertahan lebih lama dari induknya).

Versi memori lama mungkin dihapus setelah 30 hari. Untuk mempertahankan riwayat memori lebih lama, ekspor versi melalui API.



Mendaftar versi

Daftarkan riwayat versi untuk sebuah store, yang terbaru lebih dulu. Contoh ini memfilter ke riwayat satu memori:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
# `list --format json` menghasilkan satu objek JSON per item.
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

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



Mengambil versi

Mengambil versi individual mengembalikan field yang sama dengan respons daftar 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 versi

Redact membersihkan konten dari versi historis sambil mempertahankan jejak audit (siapa melakukan apa, kapan). Gunakan untuk alur kerja kepatuhan seperti menghapus rahasia yang bocor, PII, atau permintaan penghapusan 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 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.



Mendaftar store

Daftarkan 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 memori dan versinya, gunakan memory_stores.delete.



Praktik terbaik untuk manajemen memori

Ketika sebuah store mencapai batas 2.000 memorinya, penulisan ke memori baru akan gagal: baik panggilan memories.create langsung maupun penulisan file 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 serbaguna, gunakan store yang lebih kecil dan dibuat untuk tujuan tertentu: satu per pengguna, satu untuk pengetahuan domain bersama, dan satu untuk konteks khusus proyek. Setiap store memiliki batas 2.000 memorinya sendiri, jadi menjaga store tetap terbatas cakupannya mengurangi kemungkinan salah satunya penuh.

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

• Lampirkan store baru ketika masuk akal. Jika sebuah store telah tumbuh melampaui cakupan yang berguna, lampirkan yang 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 memori baru memudahkan pelacakan dari mana pertumbuhan berasal.