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

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

Память поддерживает извлечение контекста по требованию. Вместо того чтобы загружать всю релевантную информацию заранее, агент записывает то, что узнаёт, в файлы памяти и считывает их по мере необходимости. Это позволяет активному контексту оставаться сосредоточенным на текущей задаче, что важно для длительных сессий, которые иначе переполнили бы контекстное окно. Более широкое описание этого паттерна см. в статье Effective context engineering.

Инструмент памяти работает на стороне клиента: Claude запрашивает файловые операции, а ваше приложение их выполняет. Вы контролируете, где и как хранятся данные, через собственную инфраструктуру.



Сценарии использования

• Сохранение контекста проекта между несколькими сессиями агента
• Применение уроков из прошлых взаимодействий, решений и обратной связи к новым задачам
• Накопление базы знаний со временем



Как это работает

Когда инструмент памяти включён, Claude автоматически проверяет свой каталог памяти перед началом задачи. В процессе работы Claude сохраняет то, что узнаёт, в файлах внутри /memories и считывает их в последующих разговорах, чтобы продолжить ранее начатую работу.

Поскольку инструмент памяти работает на стороне клиента, Claude только запрашивает операции с памятью. Ваше приложение выполняет каждый запрос к хранилищу, которое вы контролируете, и возвращает результат в блоке tool_result (см. Обработка вызовов инструментов). Путь /memories — это префикс, который ваш обработчик сопоставляет с реальным хранилищем, например с каталогом для конкретного пользователя или ключами в базе данных. Память полностью находится в вашем приложении. Последующий разговор продолжается с той же памятью, если он отправляет ту же запись в tools, а ваш обработчик обслуживает то же хранилище. В целях безопасности ограничьте все операции с памятью каталогом /memories (см. Защита от обхода пути).



Пример: как работают вызовы инструмента памяти

Типичное взаимодействие выглядит так:

1. Запрос пользователя:

"Help me respond to this customer service ticket."

2. Claude проверяет каталог памяти:

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Claude вызывает инструмент памяти:

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. Ваше приложение возвращает содержимое каталога:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}

4. Claude читает релевантные файлы:

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. Ваше приложение возвращает содержимое файла:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude использует память, чтобы помочь:

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

Инструмент памяти доступен во всех моделях Claude 4 и более поздних. Полный список инструментов, предоставляемых Anthropic, см. в Справочнике по инструментам.



Начало работы

Инструмент памяти общедоступен в Messages API: бета-заголовок не требуется. Для его использования нужно выполнить два шага:

1. Добавьте инструмент памяти в ваш запрос. Запись в tools вида {"type": "memory_20250818", "name": "memory"} — это вся конфигурация: значение name должно быть memory, и вам не нужно определять схему входных данных для инструмента, предоставляемого Anthropic.
2. Реализуйте обработчик на стороне клиента для каждой команды памяти. Ваш обработчик должен отклонять пути за пределами /memories, поэтому прочитайте раздел Защита от обхода пути, прежде чем писать его.



Базовое использование

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Help me respond to this customer service ticket.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)



Реализация обработчика памяти

Ответ Claude на запрос, подобный предыдущему, заканчивается блоком tool_use, который запрашивает операцию с памятью, например view /memories. Ваше приложение выполняет операцию и возвращает результат в блоке tool_result, а затем отправляет разговор обратно, чтобы Claude мог продолжить: это стандартный цикл использования инструментов.

Четыре SDK предоставляют вспомогательные классы для инструмента памяти, которые обрабатывают интерфейс инструмента и цикл. Создайте подкласс BetaAbstractMemoryTool (Python и C#), используйте betaMemoryTool (TypeScript) или реализуйте BetaMemoryToolHandler (Java), чтобы подключить память к собственному хранилищу, например к файлам на диске, базе данных, облачному хранилищу или зашифрованным файлам. Python и TypeScript также поставляются с готовой реализацией для локальной файловой системы — BetaLocalFilesystemMemoryTool. Вспомогательные классы и средства запуска инструментов находятся в бета-пространстве имён каждого SDK, хотя сам инструмент памяти общедоступен. В SDK для Go и Ruby нет вспомогательного класса для памяти, поэтому эти примеры сами выполняют цикл использования инструментов, а PHP оборачивает ваше замыкание-обработчик в универсальный BetaRunnableTool. Все три используют хранилище в оперативной памяти, которое вы заменяете собственным.

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Хранилища в оперативной памяти в примерах для Go, PHP и Ruby делают их самодостаточными: каждое из них выполняет диспетчеризацию по полю command во входных данных input блока tool_use и возвращает строки, описанные в разделе Команды инструмента. Производственному обработчику также нужна проверка путей, которую эти демонстрационные хранилища пропускают. Полные примеры из самих SDK см. здесь:

• Python: examples/memory/basic.py
• TypeScript: examples/tools-helpers-memory.ts
• C#: MemoryToolExample
• Java: BetaMemoryToolExample.java



Команды инструмента

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



view

Показывает содержимое каталога или содержимое файла с необязательным диапазоном строк:

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

Параметр view_range необязателен и применяется к просмотру текстовых файлов: [start_line, end_line] возвращает указанные строки, а [start_line, -1] возвращает всё от start_line до конца файла.



Возвращаемые значения

Для каталогов: верните листинг, показывающий файлы и каталоги с их размерами:

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}

• Перечисляет файлы на глубину до 2 уровней
• Показывает размеры в удобочитаемом виде (например, 5.5K, 1.2M)
• Исключает скрытые элементы (файлы, начинающиеся с .) и node_modules
• Использует символ табуляции между размером и путём

Первый вызов view для /memories на пустом хранилище не является ошибкой. Инструменты памяти для локальной файловой системы из SDK (BetaLocalFilesystemMemoryTool) создают корневой каталог памяти перед первым вызовом Claude и возвращают заголовок листинга, за которым следует одна строка с размером и путём для самого пустого каталога.

Для файлов: верните содержимое файла с заголовком и номерами строк:

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

Форматирование номеров строк:

• Ширина: 6 символов, выравнивание по правому краю с заполнением пробелами
• Разделитель: символ табуляции между номером строки и содержимым
• Индексация: с 1 (первая строка — строка 1)
• Лимит строк: для файлов с более чем 999 999 строк следует возвращать ошибку: "File {path} exceeds maximum line limit of 999,999 lines."

Пример вывода:

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

В описании инструмента Claude также сказано, что view отображает файлы изображений (.jpg, .jpeg и .png) и усекает текстовое представление файлов длиннее 16 000 символов. Ожидайте вызовов view для путей к изображениям и последующих просмотров длинных файлов с указанием диапазона.



Обработка ошибок

• Файл или каталог не существует: "The path {path} does not exist. Please provide a valid path."



create

Создаёт новый файл:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}



Возвращаемые значения

• Успех: "File created successfully at: {path}"



Обработка ошибок

• Файл уже существует: "Error: File {path} already exists"

В описании инструмента Claude сказано, что create «создаёт или перезаписывает» файл, поэтому ожидайте вызовов create для путей, которые уже существуют. Возврат ошибки — это эталонное поведение, а перезапись вместо этого — допустимый вариант реализации.



str_replace

Заменяет текст в файле:

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

Параметр new_str необязателен для str_replace: если он опущен, old_str удаляется без замены.



Возвращаемые значения

• Успех: "The memory file has been edited.", за которым следует фрагмент отредактированного файла с номерами строк



Обработка ошибок

• Файл не существует: "Error: The path {path} does not exist. Please provide a valid path."
• Текст не найден: "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
• Дублирующийся текст: если old_str встречается несколько раз, верните: "No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"



Обработка каталогов

Если путь указывает на каталог, верните ошибку «файл не существует».



insert

Вставляет текст в указанную строку:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

insert_text вставляется после строки insert_line, а 0 вставляет в начало файла.



Возвращаемые значения

• Успех: "The file {path} has been edited."



Обработка ошибок

• Файл не существует: "Error: The path {path} does not exist"
• Недопустимый номер строки: "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"



Обработка каталогов

Если путь указывает на каталог, верните ошибку «файл не существует».



delete

Удаляет файл или каталог:

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}



Возвращаемые значения

• Успех: "Successfully deleted {path}"



Обработка ошибок

• Файл или каталог не существует: "Error: The path {path} does not exist"



Обработка каталогов

Удаляет каталог и всё его содержимое рекурсивно. В описании инструмента Claude сказано, что он не может удалить сам каталог /memories, поэтому отклоняйте команду delete, путь которой указывает на корень памяти.



rename

Переименовывает или перемещает файл или каталог:

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}



Возвращаемые значения

• Успех: "Successfully renamed {old_path} to {new_path}"



Обработка ошибок

• Источник не существует: "Error: The path {old_path} does not exist"
• Назначение уже существует: верните ошибку (не перезаписывайте): "Error: The destination {new_path} already exists"



Обработка каталогов

Переименовывает каталог. В описании инструмента Claude сказано, что он не может переименовать сам каталог /memories, поэтому отклоняйте команду rename, у которой old_path указывает на корень памяти.



Рекомендации по подсказкам

Когда инструмент памяти присутствует в tools вашего запроса, API автоматически добавляет эту инструкцию в системную подсказку. Вам не нужно отправлять её самостоятельно:

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

В описании инструмента Claude уже сказано поддерживать порядок в каталоге памяти, поэтому вам не нужно повторять эту инструкцию. Если Claude всё же создаёт захламлённые файлы памяти, вы можете усилить это в своей подсказке:

Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.

Вы также можете направлять то, что Claude записывает в память. Например: «Записывай в свою систему памяти только информацию, относящуюся к <topic>».



Соображения безопасности

Ваше приложение выполняет каждую файловую операцию, которую запрашивает Claude, поэтому следующие меры защиты — ваша ответственность:



Конфиденциальная информация

Claude обычно отказывается записывать конфиденциальную информацию в файлы памяти. Для более надёжных гарантий добавьте проверку, которая удаляет конфиденциальные данные до того, как ваш обработчик запишет файл.



Размер файлового хранилища

Отслеживайте размеры файлов памяти и ограничивайте максимальный размер файла. Рассмотрите возможность ограничить количество символов, возвращаемых командой view, и позвольте Claude постранично просматривать остальное с помощью view_range.



Истечение срока хранения памяти

Периодически удаляйте файлы памяти, к которым давно не было обращений.



Защита от обхода пути

Рассмотрите следующие меры защиты:

• Проверяйте, что все пути начинаются с /memories
• Приводите пути к их канонической форме и проверяйте, что они остаются внутри каталога памяти
• Отклоняйте пути, содержащие последовательности вроде ../, ..\\ или другие паттерны обхода
• Следите за URL-кодированными последовательностями обхода (%2e%2e%2f)
• Используйте встроенные утилиты безопасности путей вашего языка (например, pathlib.Path.resolve() и relative_to() в Python)



Обработка ошибок

Инструмент памяти использует паттерны обработки ошибок, аналогичные инструменту текстового редактора. Сообщения об ошибках для каждой команды перечислены в разделе Команды инструмента. Чтобы вернуть ошибку Claude, установите is_error в true в результате инструмента и поместите сообщение в content:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}



Интеграция с редактированием контекста

Инструмент памяти хорошо сочетается с редактированием контекста для управления длительными разговорами. Подробнее см. Редактирование контекста.



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

Инструмент памяти также можно сочетать с уплотнением, которое суммирует более старый контекст разговора на стороне сервера. Редактирование контекста очищает конкретные результаты инструментов на клиенте. Уплотнение автоматически суммирует весь разговор на сервере, когда разговор приближается к лимиту контекстного окна.

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



Паттерн многосессионной разработки программного обеспечения

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



Как работает паттерн

1. Инициализирующая сессия: первая сессия настраивает файлы памяти до начала какой-либо содержательной работы. Сюда входят журнал прогресса (отслеживающий, что было сделано и что предстоит), чек-лист функций (определяющий объём работы) и ссылка на любой скрипт запуска или инициализации, который нужен проекту.

2. Последующие сессии: каждая новая сессия начинается с чтения этих файлов памяти. Это восстанавливает состояние проекта без повторного изучения кодовой базы или повторного прохождения ранее принятых решений.

3. Обновление в конце сессии: перед завершением сессия обновляет журнал прогресса, указывая, что было выполнено и что осталось. Это гарантирует, что следующая сессия будет иметь точную отправную точку.



Ключевой принцип

Работайте над одной функцией за раз. Отмечайте функцию как завершённую только после того, как сквозная проверка подтвердит, что она работает, а не когда код написан. Это поддерживает точность журнала прогресса от сессии к сессии.



Дальнейшие шаги