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

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

Обзор

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

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

Каждое изменение памяти создаёт неизменяемую memory_version для поддержки аудита и отката изменений памяти.

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

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

store=$(curl -fsS https://api.anthropic.com/v1/memory_stores \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "name": "User Preferences",
  "description": "Per-user preferences and project context."
}
EOF
)
store_id=$(jq -r '.id' <<< "$store")
echo "$store_id"  # memstore_01Hx...

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

Заполните его содержимым (опционально)

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

Подключение памяти к сеансу

Хранилища памяти подключаются в массиве resources[] сеанса.

Опционально включите prompt, если вы хотите предоставить Claude инструкции, специфичные для сеанса, о том, как использовать это хранилище памяти. Оно предоставляется Claude в дополнение к name и description хранилища памяти и ограничено 4096 символами.

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

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

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

Инструменты памяти

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

Проверка и исправление памяти

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

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

Список не возвращает содержимое памяти, только метаданные объекта. Используйте path_prefix для списков с ограничением по каталогам (включите завершающий слэш: /notes/ совпадает с /notes/a.md, но не с /notes_backup/old.md).

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

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

Запись документа

Используйте memories.write для создания или обновления документа по пути. Если по пути ничего не существует, оно создаётся; если документ уже существует там, его содержимое заменяется. Для изменения существующего документа по mem_... ID (например, для переименования его пути или безопасного применения редактирования содержимого) используйте вместо этого memories.update (см. Update ниже).

Создание только если путь свободен

Передайте precondition={"type": "not_exists"} в memories.write, чтобы сделать это охраной только для создания. Если документ уже существует по пути, запись возвращает 409 memory_precondition_failed вместо замены. Используйте это при заполнении хранилища, когда вы хотите избежать перезаписи существующего содержимого.

Для безопасного редактирования существующего документа (чтение, изменение, запись обратно без перезаписи одновременного изменения) используйте memories.update с предусловием content_sha256 вместо этого. См. Update ниже.

Обновление

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

Переименование на занятый путь возвращает 409 conflict. Вызывающий должен удалить или переименовать блокировщик, или передать precondition={"type": "not_exists"}, чтобы сделать переименование no-op, если что-либо уже существует по целевому пути.

Пример ниже переименовывает документ в архивный путь:

Безопасное редактирование содержимого (оптимистичная конкурентность)

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

Удаление документа

Опционально передайте expected_content_sha256 для условного удаления.

Версии памяти

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

Новая версия записывается при каждом изменении:

• Первый memories.write по пути создаёт версию с operation: "created".
• memories.update, который изменяет content, path или оба, создаёт версию с operation: "modified".
• memories.delete создаёт версию с operation: "deleted".

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

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

Список метаданных версий с разбивкой по страницам для хранилища, от новейших к старейшим. Фильтруйте по memory_id, operation (created, modified или deleted), session_id, api_key_id или диапазону времени created_at_gte/created_at_lte. Ответ списка не включает тело content; получите отдельные версии с помощью retrieve, когда вам нужно полное содержимое.

Получить версию

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

Редактировать версию

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