Хранилища памяти в самостоятельно размещаемых песочницах

Сеансы в самостоятельно размещаемой среде подключают хранилища памяти точно так же, как сеансы в облачных средах. Перечислите их в resources при создании сеанса, как показано в разделе Подключение хранилища памяти к сессии. Сеанс принимает до 8 хранилищ памяти.

Разница в том, кто материализует хранилище. В самостоятельно размещаемой среде ваш «worker» (воркер), а не инфраструктура Anthropic, загружает каждое хранилище в песочницу и синхронизирует изменения агента обратно.

Требования

• Воркер, который монтирует хранилища памяти: используйте ant CLI версии 1.33.0 или новее либо EnvironmentWorker из Python, TypeScript или Go SDK.
• Файловая система POSIX: хосты Windows не поддерживаются, поскольку воркеру требуется O_NOFOLLOW при открытии файлов памяти. Рекомендуется файловая система с учётом регистра, чтобы пути памяти, различающиеся только регистром, не конфликтовали.
• Доступный для записи каталог /mnt/memory: см. раздел Подготовка хоста.
• Секрет элемента работы: если вы запускаете воркер из собственного кода, передайте ему секрет элемента работы.

Подготовка хоста

Перед запуском воркера создайте родительский каталог и сделайте его доступным для записи пользователю, от имени которого работает воркер:

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

Не создавайте каталоги для отдельных хранилищ самостоятельно. Воркер создаёт каталог mount_path каждого хранилища (например, /mnt/memory/user-preferences) при запуске сеанса и удаляет его при завершении сеанса. Если по этому пути уже что-то существует, воркер отказывается начинать работу сеанса.

В шаблоне «одна песочница на сеанс» образу песочницы нужен доступный для записи /mnt/memory. Вам не нужно монтировать каталоги памяти на хост через bind-mount, поскольку воркер загружает их содержимое в хранилище до завершения песочницы.

Изоляция сеансов, использующих общее хранилище

Два сеанса не могут одновременно монтировать одно и то же хранилище на одном хосте, поскольку обоим нужен один и тот же путь. Если ваши сеансы подключают одно и то же хранилище, запускайте по одному сеансу на файловую систему. Предоставление каждому сеансу собственной песочницы удовлетворяет этому правилу.

Как воркер обрабатывает память

Когда воркер забирает элемент работы, к сеансу которого подключены хранилища памяти, он:

1. Загружает каждое хранилище в его mount_path. Это тот же каталог в /mnt/memory/, который используют облачные сеансы, и системная подсказка сеанса описывает его агенту. Например, хранилище с именем «User Preferences» размещается в /mnt/memory/user-preferences/.
2. Открывает эти каталоги для файловых инструментов. Агент работает с памятью с помощью тех же файловых инструментов, которые он использует в рабочем каталоге.
3. Согласовывает изменения после вызовов инструментов не чаще одного раза за интервал синхронизации (по умолчанию 15 секунд). Записи памяти, изменившиеся в хранилище, записываются на диск, а файлы, изменённые агентом, загружаются в хранилище.
4. Выполняет финальную синхронизацию при завершении сеанса. В течение не более 30 секунд он завершает все ещё ожидающие загрузки, а затем удаляет созданные им каталоги.

Хранилище памяти на стороне Anthropic остаётся источником истины. Версии памяти, редактирование конфиденциальных данных, а также просмотр и изменение памяти в Console работают так же, как для облачных сеансов. Операции чтения и записи памяти агентом отображаются в потоке событий как обычные события инструментов.

Поскольку каждый воркер синхронизируется с определённым интервалом, изменение, записанное в одном сеансе, становится видимым другому работающему сеансу только после того, как оба выполнят синхронизацию. При интервале по умолчанию это обычно занимает значительно меньше минуты. Сеансы в облачных песочницах видят изменения друг друга почти мгновенно.

Каждый каталог хранилища содержит файл-маркер с именем .anthropic-memory-store, который связывает каталог с его хранилищем. Не удаляйте его: воркер не синхронизирует каталог, маркер которого отсутствует или изменён.

Настройка синхронизации

Поведением памяти управляют два параметра EnvironmentWorker. Задавайте их везде, где вы создаёте воркер, в том числе в обработчике вебхуков. Воркер ant CLI всегда использует значения по умолчанию.

Интервал синхронизации

memory_sync_interval задаёт, как часто подключённые хранилища согласуются с сервером во время работы сеанса.

Более короткий интервал сужает окно, в течение которого другой сеанс видит устаревшую память, ценой большего числа запросов к хранилищу памяти.

Отключайте поддержку памяти только на воркерах, сеансы которых не подключают хранилища памяти. Воркер с отключённой поддержкой не загружает и не синхронизирует хранилища, поэтому сеанс с подключёнными хранилищами работает без них, хотя его системная подсказка по-прежнему их описывает.

Пока поддержка памяти включена, элемент работы, поступивший без secret для сеанса с подключёнными хранилищами, завершается ошибкой, а не выполняется без памяти. См. раздел Хранилища памяти не монтируются.

Удаления

memory_sync_deletions определяет, удаляется ли из хранилища файл, который агент удалил локально. На загрузку и скачивание это не влияет.

Например, чтобы синхронизировать каждые 10 секунд и только записывать в журнал удаления, которые выполнил бы воркер:

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

Хранилища только для чтения и конфликты

Для хранилища, подключённого с access: "read_only", инструменты write и edit отказываются изменять файлы в его каталоге. Воркер никогда ничего из него не выгружает.

Изменения, внесённые через bash или через пользовательский инструмент либо сервер MCP, который вы обслуживаете из песочницы, локально не блокируются. Они никогда не синхронизируются с хранилищем, и следующее удалённое изменение этой записи памяти перезаписывает их. Если сама локальная копия должна оставаться неизменной в течение сеанса:

• Отключите инструмент bash для этого агента и не предоставляйте ему пользовательских инструментов, которые записывают в файловую систему песочницы.
• Не монтируйте путь хранилища в режиме только для чтения. Воркер должен сам создать каталог и записать в него загруженные записи памяти.

Конфликты разрешаются в пользу хранилища. Предположим, агент изменяет файл памяти, который также изменился в хранилище с момента последней синхронизации сеанса. При следующей синхронизации воркер сохраняет версию из хранилища, перезаписывает ею локальный файл и записывает предупреждение в журнал. Сами инструменты write и edit выполняются успешно, и агент не получает никакой ошибки. Если изменение агента по-прежнему актуально, он может повторно прочитать файл после синхронизации и внести изменение снова.

Устранение неполадок

Сообщения журнала воркера и способы устранения проблем см. в разделе Хранилища памяти не монтируются.