Claude Platform Docs
Managed AgentsSandbox yang di-host sendiri

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 ant versi 1.33.0 atau lebih baru, atau EnvironmentWorker dari SDK Python, TypeScript, atau Go.
  • Sistem file POSIX: Host Windows tidak didukung, karena worker memerlukan O_NOFOLLOW saat 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/memory yang 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/memory

Jangan 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.

  1. Buat direktori di volume data

    Buat direktori memory dan jadikan pengguna worker sebagai pemiliknya. $USER adalah 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/memory

    Lokasi ini hanyalah salah satu opsi. Jika Anda menggunakan lokasi lain, ubah path di baris synthetic.conf agar sesuai. Anthropic hanya menguji /System/Volumes/Data/mnt.

  2. Tambahkan baris ke synthetic.conf

    Jalankan cat -et /etc/synthetic.conf, yang menampilkan setiap tab sebagai ^I dan 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 $, jalankan echo | sudo tee -a /etc/synthetic.conf untuk mengakhirinya.
    • Jika tidak ada yang ditampilkan atau muncul laporan No such file or directory, lanjutkan. Perintah printf akan 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.conf

    Perintah tersebut menampilkan baris yang ditambahkannya. Baris tersebut memetakan nama mnt ke direktori yang berisi memory. File memerlukan tab di antara kedua kolom, yang ditulis oleh \t.

  3. Buat tautan

    Jalankan apfs.util dengan opsi -t. Perintah ini membuat tautan dari baris yang Anda tambahkan, tanpa perlu restart.

    sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
  4. Periksa hasilnya

    Tampilkan daftar /mnt dan /mnt/memory.

    ls -ld /mnt /mnt/memory

    Baris 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:

  1. 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/.
  2. Membuka direktori tersebut untuk alat file. Agen bekerja dengan memori menggunakan alat file yang sama dengan yang digunakannya di direktori kerja.
  3. 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.
  4. 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.

PengaturanNilai
Default15 detik
Minimum5 detik
Contoh (10 detik)10
Menonaktifkan dukungan memoriNone

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.

NilaiPerilaku
"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 bash untuk 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?