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

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

Память поддерживает извлечение контекста по требованию (just-in-time). Вместо того чтобы загружать всю релевантную информацию заранее, агент записывает то, что узнаёт, в файлы памяти и считывает их обратно по мере необходимости. Это позволяет сосредоточить активный контекст на текущей задаче, что важно для длительных сессий, которые в противном случае переполнили бы контекстное окно. Более общий паттерн описан в статье 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, см. в Справочнике по инструментам.

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

Использование инструмента памяти состоит из двух шагов:

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

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

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    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. Вспомогательные средства и средства запуска инструментов (tool runner) находятся в бета-пространстве имён каждого 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-5-5",
    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)
• Лимит строк: Для файлов с более чем 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 автоматически добавляет эту инструкцию в «system prompt» (системную подсказку). Вам не нужно отправлять её самостоятельно:

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 записывает в память. Например: «Only write down information relevant to <topic> in your memory system.»

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

Ваше приложение выполняет каждую файловую операцию, которую запрашивает 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
}

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

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

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

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

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

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

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

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

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

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

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

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

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

Следующие шаги