Memory store di sandbox self-hosted
Lampirkan memory store ke sesi Claude Managed Agents yang berjalan di sandbox self-hosted: siapkan host, konfigurasikan sinkronisasi, dan tangani store read-only serta konflik.
Sesi pada environment self-hosted melampirkan memory store persis seperti sesi pada environment cloud. Cantumkan store tersebut di resources saat Anda membuat sesi, seperti yang ditunjukkan di Melampirkan memory store ke sesi. Sebuah sesi menerima hingga 8 memory store.
Perbedaannya terletak pada siapa yang mewujudkan store tersebut. Pada environment self-hosted, worker Anda, bukan infrastruktur Anthropic, yang mengunduh setiap store ke dalam sandbox dan menyinkronkan kembali perubahan yang dibuat agen.
Persyaratan
- Worker yang me-mount memory store: Gunakan CLI
antversi 1.33.0 atau lebih baru, atauEnvironmentWorkerdari SDK Python, TypeScript, atau Go. - Sistem file POSIX: Host Windows tidak didukung, karena worker memerlukan
O_NOFOLLOWsaat membuka file memori. Sistem file yang peka huruf besar-kecil disarankan, agar path memori yang hanya berbeda dalam huruf besar-kecil tidak bertabrakan. Volume macOS secara default tidak peka huruf besar-kecil, sehingga path semacam itu bertabrakan di sana. - Direktori
/mnt/memoryyang dapat ditulisi: Lihat Menyiapkan host. Di macOS, lihat Menyiapkan host macOS. - Secret milik item pekerjaan: Jika kode Anda sendiri yang meluncurkan worker, teruskan secret item pekerjaan ke worker tersebut.
Menyiapkan host
Di macOS, lewati perintah berikutnya dan ikuti Menyiapkan host macOS sebagai gantinya.
Sebelum Anda memulai worker, buat direktori induk dan jadikan direktori tersebut dapat ditulis oleh pengguna yang menjalankan worker:
sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memoryJangan membuat direktori per-store sendiri. Worker membuat direktori mount_path untuk setiap store (misalnya, /mnt/memory/user-preferences) saat sesi dimulai dan menghapusnya saat sesi berakhir. Jika sudah ada sesuatu di path tersebut, worker menolak untuk memulai pekerjaan sesi.
Dalam pola sandbox-per-sesi, image sandbox memerlukan /mnt/memory yang dapat ditulis. Anda tidak perlu melakukan bind-mount direktori memori ke host, karena worker mengunggah isinya ke store sebelum sandbox keluar.
Menyiapkan host macOS
Di macOS, volume root bersifat hanya-baca, sehingga mkdir tidak dapat membuat /mnt. Sebagai gantinya, buat /System/Volumes/Data/mnt/memory di volume data, yang dapat ditulisi. Kemudian tambahkan satu baris ke /etc/synthetic.conf, sehingga macOS membuat /mnt sebagai tautan simbolik ke /System/Volumes/Data/mnt. Langkah-langkah ini memerlukan hak administrator.
Tanpa pengaturan ini, worker tidak dapat membuat direktori store, sehingga item pekerjaan gagal. Sesi kemudian tetap idle tanpa event error. Lihat Memory store gagal di-mount.
Buat direktori di volume data
Buat direktori
memorydan jadikan pengguna worker sebagai pemiliknya.$USERadalah nama pengguna Anda sendiri. Jika worker berjalan sebagai pengguna lain, ganti"$USER"dengan nama pengguna tersebut.sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memoryLokasi ini hanyalah salah satu opsi. Jika Anda menggunakan lokasi lain, ubah path di baris
synthetic.confagar sesuai. Anthropic hanya menguji/System/Volumes/Data/mnt.Tambahkan baris ke synthetic.conf
Jalankan
cat -et /etc/synthetic.conf, yang menampilkan setiap tab sebagai^Idan setiap akhir baris sebagai$.- Jika ada baris yang berbunyi
mnt^ISystem/Volumes/Data/mnt$, langkah ini sudah selesai. Lanjutkan ke langkah berikutnya. - Jika ada baris lain yang diawali dengan
mnt, berhenti. Sesuatu yang lain di Mac ini sudah mendefinisikan/mnt. - Jika baris terakhir tidak diakhiri dengan
$, jalankanecho | sudo tee -a /etc/synthetic.confuntuk mengakhirinya. - Jika tidak ada yang ditampilkan atau muncul laporan
No such file or directory, lanjutkan. Perintahprintfakan membuat file tersebut jika belum ada.
Kemudian tambahkan baris tersebut, kecuali salah satu dari dua kasus pertama berlaku. Jalankan perintah ini hanya sekali, karena setiap kali dijalankan akan menambahkan baris lain.
printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.confPerintah tersebut menampilkan baris yang ditambahkannya. Baris tersebut memetakan nama
mntke direktori yang berisimemory. File memerlukan tab di antara kedua kolom, yang ditulis oleh\t.- Jika ada baris yang berbunyi
Buat tautan
Jalankan
apfs.utildengan opsi-t. Perintah ini membuat tautan dari baris yang Anda tambahkan, tanpa perlu restart.sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -tPeriksa hasilnya
Tampilkan daftar
/mntdan/mnt/memory.ls -ld /mnt /mnt/memoryBaris pertama diakhiri dengan
/mnt -> System/Volumes/Data/mnt. Baris kedua menampilkan pengguna worker sebagai pemilik/mnt/memory. Sekarang Anda dapat memulai worker.
Anthropic telah menguji pengaturan ini di macOS 26.7.1 dengan worker ant CLI.
Mengisolasi sesi yang berbagi store
Dua sesi tidak dapat me-mount penyimpanan yang sama pada satu host secara bersamaan, karena keduanya memerlukan path yang sama. Jika sesi-sesi Anda melampirkan penyimpanan yang sama, jalankan satu sesi untuk setiap sistem file. Memberikan setiap sesi sandbox-nya sendiri memenuhi aturan ini.
Cara worker menangani memori
Saat worker mengklaim item pekerjaan yang sesinya memiliki memory store terlampir, worker akan:
- Mengunduh setiap store ke
mount_path-nya. Ini adalah direktori yang sama di bawah/mnt/memory/yang digunakan sesi cloud, dan prompt sistem sesi menjelaskannya kepada agen. Misalnya, store bernama “User Preferences” ditempatkan di/mnt/memory/user-preferences/. - Membuka direktori tersebut untuk alat file. Agen bekerja dengan memori menggunakan alat file yang sama dengan yang digunakannya di direktori kerja.
- Merekonsiliasi perubahan setelah pemanggilan alat, paling banyak sekali per interval sinkronisasi (15 detik secara default). Memori yang berubah di store ditulis ke disk, dan file yang diubah agen diunggah ke store.
- Menjalankan sinkronisasi akhir saat sesi berakhir. Worker menuntaskan unggahan yang masih tertunda hingga 30 detik, lalu menghapus direktori yang dibuatnya.
Penyimpanan memori di sisi Anthropic tetap menjadi sumber kebenaran. Versi memori, redaksi, serta melihat atau mengedit memori di Claude Console berfungsi seperti pada sesi cloud. Operasi baca dan tulis memori oleh agen muncul di aliran event sebagai event alat biasa.
Karena setiap worker melakukan sinkronisasi berdasarkan interval, perubahan yang ditulis dalam satu sesi baru terlihat oleh sesi lain yang sedang berjalan setelah keduanya melakukan sinkronisasi. Biasanya ini jauh di bawah satu menit pada interval default. Sesi pada sandbox cloud melihat perubahan satu sama lain hampir seketika.
Setiap direktori store berisi file penanda bernama .anthropic-memory-store yang mengaitkan direktori tersebut dengan store-nya. Biarkan file tersebut tetap ada: worker tidak menyinkronkan direktori yang penandanya hilang atau diubah.
Mengonfigurasi sinkronisasi
Dua opsi EnvironmentWorker mengontrol perilaku memori. Atur opsi tersebut di mana pun Anda membuat worker, termasuk di handler webhook. Worker CLI ant selalu menggunakan nilai default.
Interval sinkronisasi
memory_sync_interval mengatur seberapa sering store yang terlampir direkonsiliasi dengan server selama sesi berjalan.
| Pengaturan | Nilai |
|---|---|
| Default | 15 detik |
| Minimum | 5 detik |
| Contoh (10 detik) | 10 |
| Menonaktifkan dukungan memori | None |
Interval yang lebih pendek mempersempit jendela waktu di mana sesi lain melihat memori yang usang, dengan konsekuensi lebih banyak permintaan ke memory store.
Nonaktifkan dukungan memori hanya pada worker yang sesinya tidak melampirkan memory store. Worker yang dinonaktifkan tidak mengunduh maupun menyinkronkan store, sehingga sesi dengan store terlampir berjalan tanpa store tersebut meskipun prompt sistemnya masih menjelaskannya.
Selama dukungan memori diaktifkan, item pekerjaan yang tiba tanpa secret untuk sesi dengan store terlampir akan gagal alih-alih berjalan tanpa memori. Lihat Memory store gagal di-mount.
Penghapusan
memory_sync_deletions mengatur apakah file yang dihapus agen secara lokal juga dihapus dari store. Unggahan dan unduhan tidak terpengaruh.
| Nilai | Perilaku |
|---|---|
"enabled" (default) | Menghapus memori dari store setelah sinkronisasi berikutnya mengonfirmasi bahwa file tersebut masih tidak ada. |
"log_only" | Menjalankan pemeriksaan yang sama tetapi hanya mencatat apa yang akan dihapusnya. Gunakan mode ini untuk memantau apa yang akan dihapus worker Anda sebelum Anda memercayai mode yang diaktifkan. |
"disabled" | Tidak pernah menghapus dari store. |
Misalnya, untuk menyinkronkan setiap 10 detik dan hanya mencatat penghapusan yang akan dilakukan worker:
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
memory_sync_interval=10, # seconds
memory_sync_deletions="log_only",
)Store read-only dan konflik
Untuk store yang dilampirkan dengan access: "read_only", alat write dan edit menolak mengubah file di dalam direktorinya. Worker tidak pernah mengunggah apa pun dari direktori tersebut.
Perubahan yang dibuat melalui bash, atau melalui alat kustom atau server MCP yang Anda layani dari sandbox, tidak diblokir secara lokal. Perubahan tersebut tidak pernah disinkronkan ke store, dan perubahan jarak jauh berikutnya pada memori tersebut akan menimpanya. Jika salinan lokal itu sendiri harus tetap tidak berubah selama sesi:
- Nonaktifkan alat
bashuntuk agen tersebut, dan jangan berikan alat kustom apa pun yang menulis ke sistem file sandbox. - Jangan me-mount path store sebagai read-only. Worker sendiri harus membuat direktori tersebut dan menulis memori yang diunduh ke dalamnya.
Konflik diselesaikan dengan mengutamakan store. Misalkan agen mengubah file memori yang juga berubah di store sejak sesi terakhir kali menyinkronkannya. Pada sinkronisasi berikutnya, worker mempertahankan versi store, menimpa file lokal dengan versi tersebut, dan mencatat peringatan. Alat write dan edit itu sendiri berhasil dan tidak ada error yang sampai ke agen. Jika perubahan agen masih relevan, agen dapat membaca ulang file tersebut setelah sinkronisasi dan membuat perubahan itu lagi.
Pemecahan masalah
Lihat Memory store gagal di-mount untuk pesan log worker beserta perbaikannya.
Apakah halaman ini membantu?