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

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

Память поддерживает извлечение контекста «точно в срок» (just-in-time). Вместо того чтобы загружать всю релевантную информацию заранее, агент записывает то, что узнаёт, в файлы памяти и читает их по мере необходимости. Это позволяет держать активный контекст сфокусированным на текущей задаче, что важно для длительных сессий, которые иначе переполнили бы контекстное окно. См. Эффективная инженерия контекста для более широкого описания этого паттерна.

Инструмент памяти работает на стороне клиента: 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-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. Вспомогательные средства и интерфейсы запуска инструментов находятся в бета-пространстве имён каждого 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",
    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. Обновление в конце сессии: Перед завершением сессии она обновляет журнал прогресса с информацией о том, что было завершено и что осталось. Это гарантирует, что следующая сессия будет иметь точную отправную точку.



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

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



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