Использование памяти агента

Каждая сессия Managed Agents по умолчанию начинается с чистого контекста. Когда сессия завершается, всё состояние, накопленное агентом, исчезает. Хранилища памяти позволяют агенту переносить информацию между сессиями: предпочтения пользователя, соглашения проекта, прошлые ошибки и контекст предметной области.

Обзор

Хранилище памяти («memory store») — это коллекция текстовых документов в рамках рабочего пространства, оптимизированная для Claude. Когда вы подключаете хранилище к сессии, оно монтируется как каталог внутри песочницы сессии. Агент читает и записывает его с помощью тех же файловых инструментов, которые он использует для остальной файловой системы, а заметка с описанием каждой точки монтирования автоматически добавляется в «system prompt» (системную подсказку), сообщая агенту, где искать. Для этих взаимодействий требуется набор инструментов агента; обязательно включите его при создании агента. В самостоятельно размещаемых песочницах этот каталог не является живой точкой монтирования. Вместо этого рабочий процесс окружения SDK загружает каждое подключённое хранилище в вашу песочницу до запуска инструментов агента и поддерживает эту копию синхронизированной с хранилищем.

Каждая запись памяти («memory») в хранилище адресуется по пути и может быть прочитана и отредактирована напрямую через API или Claude Console, что позволяет выполнять настройку, импорт и экспорт.

Каждое изменение записи памяти создаёт неизменяемую версию памяти («memory version»), предоставляя вам журнал аудита и возможность восстановления на определённый момент времени для всего, что записывает агент.

Создание хранилища памяти

Задайте хранилищу name и description. Описание передаётся агенту и сообщает ему, что содержит хранилище.

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

id хранилища памяти (memstore_...) — это то, что вы передаёте при подключении хранилища к сессии.

Наполнение содержимым (необязательно)

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

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null

Подключение хранилища памяти к сессии

Хранилища памяти подключаются в массиве resources[] сессии при создании сессии. В отличие от файловых ресурсов, хранилища памяти можно подключать только в момент создания сессии; добавление или удаление хранилища из работающей сессии не поддерживается. Вы подключаете хранилища памяти одинаковым образом для сессий в облачных и самостоятельно размещаемых окружениях; самостоятельно размещаемые окружения принимают только ресурсы memory_store.

При необходимости включите instructions, чтобы предоставить специфичные для сессии указания о том, как агент должен использовать это хранилище. Они показываются агенту вместе с name и description хранилища и ограничены 4 096 символами.

Вы также можете настроить access. По умолчанию используется read_write (явно показано в следующем примере), но также поддерживается read_only.

ant beta:sessions create <<YAML
agent: $agent_id
environment_id: $environment_id
resources:
  - type: memory_store
    memory_store_id: $store_id
    access: read_write
    instructions: User preferences and project context. Check before starting any task.
YAML

На одну сессию поддерживается максимум 8 хранилищ памяти. Подключайте несколько хранилищ, когда разные части памяти имеют разных владельцев или разные правила доступа. Типичные причины:

• Общие справочные материалы: одно хранилище только для чтения, подключённое ко многим сессиям (стандарты, соглашения, знания предметной области), отделённое от собственного хранилища каждой сессии с доступом на чтение и запись.
• Соответствие структуре вашего продукта: одно хранилище на конечного пользователя, на команду или на проект при использовании единой конфигурации агента.
• Разные жизненные циклы: хранилище, которое живёт дольше любой отдельной сессии, или хранилище, которое вы хотите архивировать по собственному расписанию.

Как агент получает доступ к памяти

Каждое подключённое хранилище монтируется внутри песочницы сессии как каталог в /mnt/memory/. Имя каталога — это отображаемое имя хранилища, преобразованное в безопасный для файловой системы слаг (в нижнем регистре; последовательности не буквенно-цифровых символов заменяются одним дефисом), поэтому хранилище с именем «Demo Memory» монтируется в /mnt/memory/demo-memory/. Точный путь возвращается в поле mount_path ресурса хранилища памяти сессии; читайте его оттуда, а не конструируйте самостоятельно. Агент читает и записывает хранилище с помощью стандартного набора инструментов агента. Записи по пути монтирования сохраняются обратно в хранилище и остаются синхронизированными между сессиями, которые его совместно используют; записи по любому другому пути в /mnt/memory/ завершаются ошибкой, поскольку песочница монтирует этот родительский каталог только для чтения. Краткое описание каждой точки монтирования (отображаемое имя, путь монтирования, режим доступа, description хранилища и любые instructions) автоматически добавляется в системную подсказку.

access применяется на уровне файловой системы: точка монтирования read_only отклоняет записи, тогда как записи в точку монтирования read_write создают версии памяти, приписываемые сессии.

Операции чтения и записи агента отображаются в потоке событий как обычные события agent.tool_use и agent.tool_result для того инструмента, который обращался к точке монтирования.

Просмотр и редактирование записей памяти

Хранилищами памяти можно управлять напрямую через API. Используйте это для построения процессов проверки, исправления некорректных записей памяти или наполнения хранилищ до запуска любой сессии.

Список записей памяти

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

• path_prefix ограничивает список одним каталогом. Он должен заканчиваться на / и сопоставляется с целыми сегментами пути, поэтому path_prefix=/notes/ возвращает /notes/todo.md, но не /notes-archive/todo.md.
• depth управляет глубиной списка ниже path_prefix: опустите его (или передайте 0), чтобы получить всё поддерево, или передайте 1, чтобы получить только непосредственных потомков. Другие значения возвращают ошибку 400.

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/"

Полные параметры и схему ответа см. в справочнике по получению списка записей памяти.

Чтение записи памяти

Получение отдельной записи памяти возвращает полное содержимое.

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

Полные параметры и схему ответа см. в справочнике по получению записи памяти.

Создание записи памяти

memories.create создаёт запись памяти по заданному path. Создание не перезаписывает; чтобы изменить существующую запись памяти, используйте memories.update.

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

Полные параметры и схему ответа см. в справочнике по созданию записи памяти.

Обновление записи памяти

memories.update изменяет существующую запись памяти по ID. Вы можете изменить content, path (переименование) или и то, и другое. В примере запись памяти переименовывается в архивный путь:

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

Полные параметры и схему ответа см. в справочнике по обновлению записи памяти.

Безопасное редактирование содержимого (оптимистичный контроль параллелизма)

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

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null

Удаление записи памяти

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

Полные параметры и схему ответа см. в справочнике по удалению записи памяти.

Аудит изменений памяти

Каждое изменение записи памяти создаёт неизменяемую версию памяти (memver_...). Используйте конечные точки версий, чтобы проверять, кто что изменил и когда, просматривать или восстанавливать предыдущий снимок, а также вычищать конфиденциальное содержимое из истории с помощью редактирования (redact).

Версии принадлежат хранилищу (а не отдельной записи памяти) и не удаляются при удалении самой записи памяти, поэтому журнал аудита также охватывает удалённые записи памяти с учётом срока хранения, описанного ниже. Версии хранятся в течение 30 дней после записи; однако последние версии существующей записи памяти всегда сохраняются независимо от возраста, поэтому записи памяти, которые изменяются редко, могут сохранять историю дольше 30 дней. Вызов memories.retrieve для существующей записи всегда возвращает последнюю версию; конечные точки версий предоставляют вам сохранённую историю.

Отдельной конечной точки восстановления нет; чтобы выполнить откат, получите нужную версию и запишите её content обратно с помощью memories.update (или memories.create, если родительская запись памяти была удалена, при условии, что нужная версия всё ещё сохранена).

Прошлые версии памяти могут быть удалены через 30 дней. Чтобы сохранить историю памяти на более длительный срок, экспортируйте версии через API.

Список версий

Получите историю версий хранилища, начиная с самых новых. В примере выполняется фильтрация по истории одной записи памяти:

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
# `list --format json` выводит один JSON-объект на элемент.
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

Полные параметры и схему ответа см. в справочнике по получению списка версий памяти.

Получение версии

Получение отдельной версии возвращает те же поля, что и ответ со списком, плюс полное тело content.

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Полные параметры и схему ответа см. в справочнике по получению версии памяти.

Редактирование (redact) версии

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

Версию, которая является текущей головной версией существующей записи памяти, отредактировать нельзя. Сначала запишите новую версию (или удалите запись памяти), а затем отредактируйте старую.

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

Полные параметры и схему ответа см. в справочнике по редактированию версии памяти.

Управление хранилищами памяти

Помимо create, хранилища памяти поддерживают retrieve, update, list, archive и delete.

Список хранилищ

Получите список хранилищ в рабочем пространстве. Архивированные хранилища по умолчанию исключаются; передайте include_archived: true, чтобы включить их.

ant beta:memory-stores list --include-archived

Полные параметры и схему ответа см. в справочнике по получению списка хранилищ памяти.

Архивирование хранилища

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

ant beta:memory-stores archive --memory-store-id "$store_id"

Полные параметры и схему ответа см. в справочнике по архивированию хранилища памяти.

Чтобы безвозвратно удалить хранилище вместе со всеми его записями памяти и версиями, используйте memory_stores.delete.

Лучшие практики управления памятью

Когда хранилище достигает лимита в 10 000 записей памяти, запись новых записей памяти завершается ошибкой: как прямые вызовы memories.create, так и файловые записи агента по несопоставленным путям. Существующие записи памяти остаются доступными для чтения и редактирования. Следующие практики помогут вам оставаться значительно ниже лимита и корректно восстановиться, если вы его достигнете.

• Используйте сфокусированные хранилища. Вместо одного большого хранилища общего назначения используйте меньшие специализированные хранилища: одно на пользователя, одно для общих знаний предметной области и одно для контекста конкретного проекта. У каждого хранилища свой лимит в 10 000 записей памяти, поэтому ограничение области хранилищ снижает вероятность того, что какое-либо одно из них заполнится.

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

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

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