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

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

Обзор

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

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

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

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

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

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

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

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

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

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

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

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

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

Вы также можете настроить 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",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

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

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

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

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

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

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

Список воспоминаний

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

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

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

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

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

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

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

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

Безопасные записи (оптимистичная параллелизм)

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

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

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

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

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

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

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

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

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

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

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,
)

Опционально передайте 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, когда вам нужно полное содержимое.

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

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

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

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

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

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

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