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

Инструмент памяти позволяет 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": "Directory: /memories\n- customer_service_guidelines.xml\n- 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": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- Use empathetic language\n..."
}

6. Claude использует память для помощи:

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

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

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

• 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)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

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

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

1. Включите бета-заголовок context-management-2025-06-27 в ваши API-запросы
2. Добавьте инструмент памяти в ваш запрос
3. Реализуйте обработчики на стороне клиента для операций с памятью

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

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" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "Я работаю над веб-скрапером на Python, который постоянно падает с ошибкой таймаута. Вот проблемная функция:\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\nПожалуйста, помогите мне отладить это."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

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

Ваша реализация на стороне клиента должна обрабатывать эти команды инструмента памяти:

view

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

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // Опционально: просмотр конкретных строк
}

create

Создать или перезаписать файл:

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Заметки встречи:\n- Обсудили временные рамки проекта\n- Определили следующие шаги\n"
}

str_replace

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

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Любимый цвет: синий",
  "new_str": "Любимый цвет: зелёный"
}

insert

Вставить текст на конкретной строке:

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Просмотреть документацию инструмента памяти\n"
}

delete

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

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

rename

Переименовать или переместить файл/каталог:

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

Руководство по промптингу

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

ВАЖНО: ВСЕГДА ПРОСМАТРИВАЙТЕ ВАШ КАТАЛОГ ПАМЯТИ ПЕРЕД ТЕМ, КАК ДЕЛАТЬ ЧТО-ЛИБО ЕЩЁ.
ПРОТОКОЛ ПАМЯТИ:
1. Используйте команду `view` вашего инструмента `memory` для проверки предыдущего прогресса.
2. ... (работайте над задачей) ...
     - По мере продвижения записывайте статус / прогресс / мысли и т.д. в вашу память.
ПРЕДПОЛАГАЙТЕ ПРЕРЫВАНИЕ: Ваше окно контекста может быть сброшено в любой момент, поэтому вы рискуете потерять любой прогресс, который не записан в вашем каталоге памяти.

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

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

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

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

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

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

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.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # Ваши другие инструменты
    ],
    betas=["context-management-2025-06-27"],
    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"]
        }
    ]
}