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. Anthropic menyarankan sistem file yang peka huruf besar-kecil, 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 store mana pun sendiri. Worker membuat direktori mount_path untuk setiap store, seperti /mnt/memory/user-preferences, saat mengklaim sesi dan menghapusnya saat selesai menangani sesi tersebut. Jika sudah ada sesuatu di path tersebut, bahkan direktori kosong, worker menggagalkan item pekerjaan.

Dalam pola sandbox-per-sesi, image sandbox memerlukan /mnt/memory yang dapat ditulis. Anda tidak perlu melakukan bind-mount direktori memori ke host, karena store menyimpan salinan permanen dari setiap memori.

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 atau disinkronkan.

  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. Kemudian, tambahkan baris tersebut.
    • Jika tidak ada yang ditampilkan atau muncul laporan No such file or directory, tambahkan baris tersebut. Perintah berikut akan membuat file tersebut jika belum ada.
    • Jika tidak, tambahkan baris tersebut.

    Untuk menambahkan baris tersebut, jalankan perintah ini. Jalankan 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 store yang sama pada satu sistem file secara bersamaan, karena keduanya memerlukan path yang sama. Untuk menjalankan sesi-sesi yang berbagi store secara berdampingan, berikan setiap sesi sistem file-nya sendiri. Jika Anda menggunakan sandbox untuk setiap sesi, setiap sesi otomatis mendapatkan sistem file-nya sendiri. Lihat Menjalankan satu sandbox per sesi. Satu host dapat menjalankan banyak sandbox semacam itu.

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. Melakukan sinkronisasi setelah pemanggilan alat. Worker melakukan sinkronisasi setelah pemanggilan alat jika interval sinkronisasi (15 detik secara default) telah berlalu sejak sinkronisasi terakhirnya. Setiap sinkronisasi menulis memori yang berubah dari store ke disk dan mengunggah file yang diubah agen.
  4. Menjalankan sinkronisasi akhir saat sesi berakhir atau tetap idle selama batas idle worker. Sinkronisasi akhir dapat memakan waktu hingga 60 detik. Perubahan yang belum diunggah hingga saat itu akan hilang. Worker kemudian menghapus direktori yang dibuatnya.

Batas idle secara default adalah 60 detik. Saat worker selesai menangani sesi menjelaskan apa yang dicakup batas tersebut dan cara mengubahnya.

Alat write dan edit milik agen hanya mengubah salinan lokal, dan worker mengunggah perubahan tersebut pada sinkronisasi berikutnya. Path di bawah /mnt/memory/ di luar direktori store bukanlah “scratch space” (ruang kerja sementara). Alat file worker menolak menulis ke path tersebut, dan apa pun yang ditulis perintah shell di sana tidak pernah disinkronkan ke store.

Versi memori, penghapusan kontennya (redact), 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.

Setiap direktori store berisi file penanda bernama .anthropic-memory-store yang mengaitkan direktori tersebut dengan store-nya. Biarkan file tersebut tetap ada. Jika penanda hilang atau diubah dan direktori masih berisi file, worker tidak menyinkronkan direktori tersebut. Worker juga tidak menghapus direktori tersebut saat selesai menangani sesi.

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 waktu terpendek antara dua sinkronisasi selama sesi berjalan.

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

Worker tidak melakukan sinkronisasi berdasarkan timer. Worker memeriksa interval setelah setiap pemanggilan alat yang berjalan di sandbox Anda, seperti bash, read, atau alat kustom. Pemanggilan tersebut tidak harus menyentuh memori. Tanpa pemanggilan alat, tidak ada yang disinkronkan hingga sinkronisasi akhir. Perubahan dalam satu sesi baru sampai ke sesi lain yang sedang berjalan setelah keduanya melakukan sinkronisasi, sehingga waktu tunggunya tidak memiliki durasi yang pasti.

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 atau disinkronkan.

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 paling banyak sekali setiap 10 detik dan hanya mencatat penghapusan yang akan dilakukan worker, gunakan contoh berikut. Contoh ini menggunakan /workspace sebagai direktori kerja, yang harus sudah ada sebelum worker dimulai. Menjalankan worker always-on menjelaskan cara membuat direktori tersebut dan apa yang digunakan di macOS.

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        worker = EnvironmentWorker(
            client,
            environment_id=environment_id,
            environment_key=environment_key,
            workdir="/workspace",
            memory_sync_interval=10,  # seconds
            memory_sync_deletions="log_only",
        )
        task = asyncio.create_task(worker.run())
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

Store read-only dan konflik

Store read-only

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 sampai ke store. File yang diubah tetap berubah hingga salah satu hal berikut terjadi:

  • Memori tersebut mendapatkan versi baru di store. Sinkronisasi worker berikutnya menimpa file tersebut dengan versi itu.
  • Worker selesai menangani sesi. Worker menghapus direktori tersebut.

Agar salinan lokal juga tetap tidak berubah, nonaktifkan alat bash untuk agen tersebut. Selain itu, jangan berikan alat kustom atau server MCP apa pun yang menulis ke sistem file sandbox. Jangan me-mount volume read-only di path store. Mount tersebut menempatkan direktori di path itu, dan worker menggagalkan item pekerjaan jika sudah ada sesuatu di sana.

Konflik

Konflik adalah memori yang berubah baik di store maupun di sandbox sejak sinkronisasi sebelumnya. Penghapusan dihitung sebagai perubahan. Untuk store yang dilampirkan dengan access: "read_write", worker menyelesaikan konflik pada sinkronisasi berikutnya:

Di storeDi sandboxHasil
BerubahBerubahVersi store menimpa file.
BerubahDihapusWorker menulis kembali versi store ke sandbox.
DihapusBerubahWorker membuat ulang memori dari file tersebut.

Pada dua baris pertama, perubahan atau penghapusan oleh agen akan hilang, meskipun pemanggilan alat berhasil. Tidak ada yang memberi tahu agen, dan satu-satunya tanda kehilangan tersebut adalah peringatan di log worker. Pada baris terakhir, penghapusan di store dibatalkan.

Pemecahan masalah

Lihat Memory store gagal di-mount atau disinkronkan untuk pesan log worker beserta perbaikannya.

Ketersediaan

Memory store di sandbox self-hosted
Status
Beta
API
  • Managed Agents
Header beta
Memerlukan
Model
  • Semua model

Endpoint yang berlaku

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Retensi data nolTidak layak

Tidak memiliki kelayakan ZDR, kecuali untuk Managed Agents yang di-host sendiri. Sesi adalah sumber daya stateful; transkrip tetap tersimpan hingga Anda menghapusnya. Pelajari lebih lanjut

HIPAATidak layak

Tidak memiliki kelayakan HIPAA. Berlaku untuk semua subfitur Managed Agents.

Apakah halaman ini membantu?