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

Каждая сессия 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 ограничивает список одним каталогом. Он должен заканчиваться на / и сопоставляется с целыми сегментами пути, поэтому 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

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



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

Каждая мутация записи памяти создаёт неизменяемую «memory version» (версию памяти) (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) вычищает содержимое из исторической версии, сохраняя при этом журнал аудита (кто, что и когда сделал). Используйте его для рабочих процессов соответствия требованиям, таких как удаление утёкших секретов, персональных данных (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. Вы также можете запустить сессию сновидений, которая консолидирует фрагментированное содержимое в отдельное новое выходное хранилище, а не изменяет исходное. Переключите ваши сессии на это выходное хранилище, затем архивируйте или удалите исходное.

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

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