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

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

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

Варианты использования

• Сохранение контекста проекта между несколькими выполнениями агента
• Обучение на основе прошлых взаимодействий, решений и обратной связи
• Построение баз знаний с течением времени
• Включение кросс-разговорного обучения, где Claude улучшается в повторяющихся рабочих процессах

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

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

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

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

Когда вы просите Claude помочь с задачей, Claude автоматически сначала проверяет директорию памяти. Вот как выглядит типичное взаимодействие:

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

"Помогите мне ответить на этот билет службы поддержки."

2. Claude проверяет директорию памяти:

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

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 использует память для помощи:

"На основе ваших рекомендаций по обслуживанию клиентов я могу помочь вам составить ответ. Пожалуйста, поделитесь деталями билета..."

Поддерживаемые модели

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

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

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

Для использования инструмента памяти:

1. Добавьте инструмент памяти в ваш запрос
2. Реализуйте обработчики на стороне клиента для операций с памятью

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "I'\''m working on a Python web scraper that keeps crashing with a timeout error. Here'\''s the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPlease help me debug this."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

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

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

view

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

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Optional: view specific lines
}

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

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

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

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

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

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

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

• Файл/директория не существует: "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"

str_replace

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

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

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

• Успех: "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"
}

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

• Успех: "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"

Обработка директорий

Удаляет директорию и всё её содержимое рекурсивно.

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"

Обработка директорий

Переименовывает директорию.

Руководство по подсказкам

Мы автоматически включаем эту инструкцию в системный запрос, когда включен инструмент памяти:

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 записывает в память. Например: "Записывайте в вашу систему памяти только информацию, релевантную <topic>."

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

Вот важные проблемы безопасности при реализации вашего хранилища памяти:

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

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

Размер хранилища файлов памяти

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

Истечение памяти

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

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

Рассмотрите эти меры защиты:

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

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

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

Использование с редактированием контекста

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

Как они работают вместе

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

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

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

Пример рабочего процесса

Рассмотрим проект рефакторинга кода с множеством операций с файлами:

1. Claude делает многочисленные правки в файлы, генерируя много результатов инструментов
2. По мере роста контекста и приближения к вашему порогу, Claude получает предупреждение
3. Claude суммирует сделанные до сих пор изменения в файл памяти (например, /memories/refactoring_progress.xml)
4. Редактирование контекста автоматически очищает старые результаты инструментов
5. Claude продолжает работу, ссылаясь на файл памяти, когда ему нужно вспомнить, какие изменения уже были завершены
6. Рабочий процесс может продолжаться бесконечно, с Claude управляющим как активным контекстом, так и постоянной памятью

Конфигурация

Для использования обеих функций вместе:

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # Your other tools
    ],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 100000},
                "keep": {"type": "tool_uses", "value": 3},
            }
        ]
    },
)

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

context_management = {
    "edits": [{"type": "clear_tool_uses_20250919", "exclude_tools": ["memory"]}]
}

Использование с компактификацией

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

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