Claude Platform Docs
СообщенияИнструменты

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

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

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

Память поддерживает извлечение контекста «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, см. в Справочнике по инструментам.

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

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

  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. Вспомогательные средства и средства запуска инструментов находятся в бета-пространстве имён вашего 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 см. здесь:

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

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

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

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

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

Выполняйте команды оболочки в постоянном сеансе bash.

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

Сжатие контекста на стороне сервера для управления длинными разговорами, приближающимися к пределам контекстного окна.

Каталог инструментов, предоставляемых Anthropic, и справочник по необязательным свойствам определения инструментов.

Доступность

Инструмент памяти
Требования к доступности Инструмент памяти одинаковы на всех поддерживаемых платформах.
API
  • Messages API
Модели
  • Все модели

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

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

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

  • /v1/messages с инструментом memory
Нулевое хранение данныхДопускается

Кроме Охватываемые модели

Клиентское хранилище памяти, хранение данных в котором контролируете вы.

HIPAAДопускается

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