Claude Platform Docs
Управляемые агентыСоздание постоянной памяти

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

Предоставьте вашим агентам постоянную память, которая сохраняется между сессиями, с помощью хранилищ памяти.

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

Обзор

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

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

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

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

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

ant apply memory_store.yaml
memory_store.yaml
# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.

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

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

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

client.beta.memory_stores.memories.create(
    store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

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

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

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

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

session = client.beta.sessions.create(
    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.",
        }
    ],
)

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

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

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

Каждое подключённое хранилище монтируется внутри песочницы сессии как каталог в /mnt/memory/. Имя каталога — это отображаемое имя хранилища, преобразованное в безопасный для файловой системы slug (в нижнем регистре, каждая последовательность небуквенно-цифровых символов заменена одним дефисом), поэтому хранилище с именем “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.
page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for item in page.data:
    print(item.type, item.path)

Полное описание параметров и схемы ответа см. в справочнике Список записей памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

retrieved = client.beta.memory_stores.memories.retrieve(
    mem.id,
    memory_store_id=store.id,
)
print(retrieved.content)

Полное описание параметров и схемы ответа см. в справочнике Получить запись памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

mem = client.beta.memory_stores.memories.create(
    store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

Полное описание параметров и схемы ответа см. в справочнике Создать запись памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

Полное описание параметров и схемы ответа см. в справочнике Обновить запись памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

client.beta.memory_stores.memories.update(
    memory_id=mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)

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

client.beta.memory_stores.memories.delete(
    mem.id,
    memory_store_id=store.id,
)

Полное описание параметров и схемы ответа см. в справочнике Удалить запись памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

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

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

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

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

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

versions = client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
)
for version in versions:
    print(f"{version.id}: {version.operation}")

version_id = versions.data[1].id

Полное описание параметров и схемы ответа см. в справочнике Список версий записи памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

Полное описание параметров и схемы ответа см. в справочнике Получить версию записи памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

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

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)

Полное описание параметров и схемы ответа см. в справочнике Скрыть содержимое версии записи памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

Помимо createДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., хранилища памяти поддерживают retrieveДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., updateДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., listДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape., archiveДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. и deleteДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

for memory_store in client.beta.memory_stores.list(include_archived=True):
    print(memory_store.id, memory_store.name, memory_store.archived_at)

Полное описание параметров и схемы ответа см. в справочнике Список хранилищ памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

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

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

client.beta.memory_stores.archive(store.id)

Полное описание параметров и схемы ответа см. в справочнике Архивировать хранилище памятиДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape..

Чтобы навсегда удалить хранилищеДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape. вместе со всеми его записями памяти и версиями, вызовите client.beta.memory_stores.delete().

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

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

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

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

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

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

Доступность

Хранилища памяти
Статус
Бета
API
  • Managed Agents
Бета-заголовок
Требуется
Модели
  • Все модели
Примечание

Отправка managed-agents-2026-04-01 вместе с agent-memory-2026-07-22 в вызове хранилища памяти возвращает ошибку 400.

Обработка данных

Обзор обработки данных

Применимые конечные точки

  • /v1/agents
  • /v1/sessions
  • /v1/environments
Нулевое хранение данныхНе допускается

Не подпадает под ZDR, за исключением самостоятельно размещаемых Managed Agents. Сессии — это ресурсы с состоянием; их расшифровки хранятся, пока вы их не удалите. Подробнее

HIPAAНе допускается

Не подпадает под HIPAA. Относится ко всем подфункциям Managed Agents.

Эта страница была полезной?