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

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



Обзор

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

Каждая память (memory) в хранилище адресуется по пути и может быть прочитана и отредактирована напрямую через API или 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[] сессии при её создании. В отличие от файловых ресурсов и ресурсов репозиториев, хранилища памяти можно подключать только в момент создания сессии; добавление или удаление хранилища из работающей сессии не поддерживается.

При необходимости включите 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 для просмотра пути как каталога:

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

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



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

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

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 изменяет существующую запись памяти по идентификатору. Вы можете изменить 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)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

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



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

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

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

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



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

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

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

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.



Рекомендации по управлению памятью

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

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

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

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

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