Memory store di sandbox self-hosted

Sesi pada environment self-hosted melampirkan memory store persis seperti sesi pada environment cloud. Cantumkan memory 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 (case-sensitive) direkomendasikan, agar path memori yang hanya berbeda dalam huruf besar-kecil tidak bertabrakan.
• Direktori /mnt/memory yang dapat ditulis: Lihat Menyiapkan host.
• Secret milik work item: Jika kode Anda sendiri yang meluncurkan worker, teruskan secret milik work item ke worker tersebut.

Menyiapkan host

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.

Mengisolasi sesi yang berbagi store

Dua sesi tidak dapat me-mount store yang sama pada satu host secara bersamaan, karena keduanya memerlukan path yang sama. Jika sesi-sesi Anda melampirkan store yang sama, jalankan satu sesi per sistem file. Memberikan setiap sesi sandbox-nya sendiri memenuhi aturan ini.

Cara worker menangani memori

Saat worker mengklaim work item 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.

Memory store di sisi Anthropic tetap menjadi sumber kebenaran. Versi memori, redaksi, serta melihat atau mengedit memori di Console berfungsi sama seperti pada sesi cloud. Pembacaan dan penulisan 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.

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, work item 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.

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.