Memory stores in self-hosted sandboxes

Sessions on a self-hosted environment attach memory stores exactly as sessions on cloud environments do. List them in resources when you create the session, as shown in Attach a memory store to a session. A session accepts up to 8 memory stores.

The difference is who materializes the store. On a self-hosted environment your worker, rather than Anthropic's infrastructure, downloads each store into the sandbox and syncs the agent's changes back.

Requirements

• A worker that mounts memory stores: Use ant CLI 1.33.0 or later, or EnvironmentWorker from the Python, TypeScript, or Go SDK.
• A POSIX filesystem: Windows hosts are not supported, because the worker requires O_NOFOLLOW when it opens memory files. A case-sensitive filesystem is recommended, so that memory paths that differ only in case do not collide.
• A writable /mnt/memory directory: See Prepare the host.
• The work item's secret: If your own code launches the worker, forward the work item's secret to it.

Prepare the host

Before you start the worker, create the parent directory and make it writable by the user the worker runs as:

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

Do not create the per-store directories yourself. The worker creates each store's mount_path directory (for example, /mnt/memory/user-preferences) when a session starts and removes it when the session ends. If something already exists at that path, the worker refuses to start the session's work.

In the sandbox-per-session pattern, the sandbox image needs a writable /mnt/memory. You don't need to bind-mount the memory directories to the host, because the worker uploads their contents to the store before the sandbox exits.

Isolate sessions that share a store

Two sessions cannot mount the same store on one host at the same time, because both need the same path. If your sessions attach the same store, run one session per filesystem. Giving each session its own sandbox satisfies this rule.

How the worker handles memory

When the worker claims a work item whose session has memory stores attached, it:

1. Downloads each store to its mount_path. This is the same directory under /mnt/memory/ that cloud sessions use, and the session's system prompt describes it to the agent. For example, a store named "User Preferences" lands at /mnt/memory/user-preferences/.
2. Opens those directories to the file tools. The agent works on memories with the same file tools it uses in the working directory.
3. Reconciles changes after tool calls, at most once per sync interval (15 seconds by default). Memories that changed in the store are written to disk, and files the agent changed are uploaded to the store.
4. Runs a final sync when the session ends. It flushes any uploads still pending for up to 30 seconds, then removes the directories it created.

The memory store on Anthropic's side remains the source of truth. Memory versions, redaction, and viewing or editing memories in the Console work as they do for cloud sessions. The agent's memory reads and writes appear in the event stream as ordinary tool events.

Because each worker syncs on an interval, a change written in one session becomes visible to another running session only after both have synced. That is typically well under a minute at the default interval. Sessions on cloud sandboxes see each other's changes almost immediately.

Each store directory contains a marker file named .anthropic-memory-store that ties the directory to its store. Leave it in place: the worker does not sync a directory whose marker is missing or altered.

Configure sync

Two EnvironmentWorker options control memory behavior. Set them wherever you construct the worker, including in a webhook handler. The ant CLI worker always uses the defaults.

Sync interval

memory_sync_interval sets how often attached stores reconcile with the server while the session runs.

A shorter interval narrows the window in which another session sees stale memories, at the cost of more memory store requests.

Disable memory support only on workers whose sessions attach no memory stores. A disabled worker neither downloads nor syncs stores, so a session with stores attached runs without them even though its system prompt still describes them.

While memory support is enabled, a work item that arrives without a secret for a session with attached stores fails rather than running without memory. See Memory stores fail to mount.

Deletions

memory_sync_deletions sets whether a file the agent deletes locally is also deleted from the store. Uploads and downloads are unaffected.

For example, to sync every 10 seconds and only log the deletes the worker would have made:

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

Read-only stores and conflicts

For a store attached with access: "read_only", the write and edit tools refuse to change files inside its directory. The worker never uploads anything from it.

Changes made through bash, or through a custom tool or MCP server you serve from the sandbox, are not blocked locally. They are never synced to the store, and the next remote change to that memory overwrites them. If the local copy itself must stay unchanged during the session:

• Disable the bash tool for that agent, and give it no custom tool that writes to the sandbox's filesystem.
• Do not mount the store path read-only. The worker itself must create the directory and write the downloaded memories into it.

Conflicts resolve in favor of the store. Suppose the agent changes a memory file that also changed in the store since the session last synced it. At the next sync, the worker keeps the store's version, overwrites the local file with it, and logs a warning. The write and edit tools themselves succeed and no error reaches the agent. If the agent's change still applies, it can re-read the file after the sync and make the change again.

Troubleshooting

See Memory stores fail to mount for the worker's log messages and their fixes.