Persistent memory в агентах

Почему это важно именно вам

Вы провели совещание с подрядчиком и попросили агента-ревьюера проверить протокол. В конце вы поправили его: «Протоколы у нас пишутся с решениями в первом абзаце, ответственными в конце, без отдельного раздела "общие вопросы"». Агент принял правку, выдал хороший результат. На следующей неделе вы снова открываете Claude Code — и снова объясняете те же три правила. Агент их не помнит. Он каждый раз начинает с нуля.

Для директора, у которого сложились устойчивые стандарты работы с документами, это ощутимые потери. У вас есть правила оформления коммерческих предложений, выработанные за три года. Есть список «красных флагов» в договорах, который вы собирали на собственных ошибках. Есть предпочтения по структуре аналитических отчётов — которые вы разъясняли разным людям, включая Claude, уже раз двадцать. Всё это знание существует только у вас в голове и воссоздаётся с нуля при каждом сеансе.

Persistent memory в агентах — это механизм, который позволяет агенту сохранять что-то между запусками. Не пересказ чатов, не полный контекст — конкретные структурированные заметки: стандарты, предпочтения, уточнения, накопленный опыт взаимодействия с вами. После настройки агент-ревьюер будет помнить про «решения в первом абзаце» без напоминания. Это не маленькое удобство — это разница между инструментом, который работает, и инструментом, которому каждый раз нужно представляться заново.

Что это такое

Поле memory во frontmatter агента указывает, как агент работает с долговременными заметками. Важно: память субагента — часть общей авто-памяти. Если вы её выключили (autoMemoryEnabled: false), поле молча перестаёт работать. Есть три варианта: user, project и local. Каждый определяет, где хранятся заметки агента и в каком объёме они доступны.

Аналогия из офисной жизни помогает разобраться. Представьте трёх сотрудников. Первый — фрилансер, которого вы нанимаете для разных клиентов. Он ведёт личный блокнот с общими наблюдениями про вас как заказчика — эти заметки он берёт с собой на любой проект. Второй — штатный сотрудник, прикреплённый к конкретному проекту. Его рабочая тетрадь лежит в папке проекта и специально задумана как общая: её кладут в репозиторий, чтобы знание копилось у всей команды. Третий — временный контрактор, работающий в этом проекте локально: его черновики тоже привязаны к проекту, но в общий репозиторий не попадают. Это область local. Его черновики хранятся на рабочем столе, в общий репозиторий не попадают, другие не видят.

memory: user — заметки агента доступны во всех проектах. Если вы работаете с несколькими рабочими папками, агент с user-памятью принесёт накопленный контекст в каждую из них. Это подходит для агентов с личными предпочтениями — например, если вы хотите, чтобы агент-редактор знал ваш стиль везде, не только в одном проекте.

memory: project — заметки живут в текущем проекте, в файле .claude/agent-memory/<имя-агента>/ (внутри — файл-индекс MEMORY.md). Это самый частый вариант для рабочих агентов. Стандарты качества документов компании, история уточнений по конкретному проекту, накопленные паттерны — всё это привязано к контексту проекта. Если проект в Git, файл памяти тоже можно включить в репозиторий — или не включать, если там личные заметки.

memory: local — заметки хранятся локально, в Git не попадают никогда. Полезно, если агент работает с чувствительными данными или вы не хотите, чтобы память агента синхронизировалась между машинами.

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

Разберём на конкретном примере. Вы хотите агента-ревьюера документов, который со временем накапливает стандарты вашей компании — и не требует их повторного объяснения.

Шаг 1. Создайте файл агента

Создайте файл .claude/agents/doc-reviewer.md:

---
name: doc-reviewer
description: Проверяет деловые документы на соответствие стандартам компании. Запоминает и применяет уточнения по стилю. Вызывай для проверки договоров, протоколов, коммерческих предложений.
tools:
  - Read
  - Write
memory: project
---

Ты ревьюер деловых документов. Проверяешь тексты на соответствие стандартам компании.

При проверке документа:
1. Прочитай файл памяти (если существует) — там стандарты, накопленные из прошлых сессий
2. Проверь документ по этим стандартам
3. Если в ходе работы получил новые уточнения от пользователя — добавь их в память

Что записывать в память:
- Стандарты оформления (структура, обязательные разделы, порядок элементов)
- Предпочтения по стилю и тону
- Типичные ошибки, которые нужно проверять
- Правила, специфичные для отдельных типов документов (договоры, протоколы, КП)

Чего не записывать:
- Содержание конкретных документов
- Имена людей и организации
- Цифры и коммерческие данные

При получении задачи: сначала скажи какие стандарты из памяти применяешь, потом дай результат.

Поле memory: project говорит агенту: храни заметки в рамках этого проекта. Claude Code создаст файл .claude/agent-memory/doc-reviewer/MEMORY.md при первой записи.

Шаг 2. Запустите агента и посмотрите что происходит

Вызовите агента:

@agent-doc-reviewer проверь протокол совещания

При первом запуске файл памяти пустой. Агент проверит документ на основе своего системного промта — базовых правил. После проверки вы можете уточнить:

Хорошо. Добавь к своим стандартам: протоколы у нас всегда начинаются
с раздела "Решения", потом "Ход обсуждения". Ответственные указываются
с дедлайном в формате "Иванов — к 15 июня".

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

Шаг 3. Посмотрите, что сохранилось

Файл памяти — это обычный текстовый файл, вы можете открыть его и прочитать:

.claude/agent-memory/doc-reviewer/MEMORY.md

Содержимое будет примерно таким:

# Стандарты ревью документов

## Протоколы совещаний
- Структура: "Решения" → "Ход обсуждения"
- Ответственные: формат "Фамилия — к ДД Месяц"
- Раздел "Общие вопросы" не используется

## Коммерческие предложения
(пока пусто — добавится после первой работы с КП)

## Договоры
(пока пусто)

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

Шаг 4. Постепенное обучение — как это выглядит в реальности

На практике агент накапливает стандарты итеративно. Вы дали задачу — он выполнил — вы уточнили что-то — он записал. Через несколько сессий файл памяти будет отражать реальные рабочие стандарты вашей компании, которые сложились из ваших конкретных уточнений, а не из общих рекомендаций из интернета.

Хорошая практика — периодически открывать файл памяти и проверять, что там накопилось. Если агент записал что-то неточно или устаревшее — отредактируйте файл напрямую. Это быстрее, чем объяснять агенту «забудь то, что ты знал».

Шаг 5. Агент с памятью типа user

Если хотите, чтобы агент помнил ваши личные предпочтения во всех проектах, используйте memory: user:

---
name: style-editor
description: Редактирует тексты под личный стиль пользователя. Запоминает стилевые предпочтения и применяет их везде.
tools:
  - Read
  - Edit
memory: user
---

Ты персональный редактор. Знаешь стилевые предпочтения пользователя
и применяешь их к любому тексту.

Читай файл памяти при каждом запуске. Когда получаешь новые предпочтения —
дополняй память. Никогда не предлагай стиль, который пользователь
отклонял раньше.

Заметки такого агента хранятся в ~/.claude/agent-memory/<имя-агента>/ и доступны при работе в любой папке.

Частые ошибки

Ошибка 1: Не читать файл памяти в системном промте

Создали агента с memory: project, но не написали в системном промте инструкции читать и дополнять файл памяти. Агент будет создавать файл, но использовать его некорректно — не читать при запуске, не добавлять уточнения, или добавлять всё подряд без разбора.

Как исправить: явно напишите в системном промте: «При запуске читай файл памяти. Добавляй туда только [конкретный тип информации]. Не записывай [что не нужно].» Чем точнее инструкция про работу с памятью — тем предсказуемее поведение.

Ошибка 2: Агент записывает содержание документов, а не стандарты

Попросили проверить договор с конкретными суммами. Агент честно записал в память «Договор с ООО Ромашка на 2,3 млн рублей, срок до декабря». Это не стандарт — это содержание конкретного документа. При следующем запуске эта информация бесполезна и загрязняет файл памяти.

Как исправить: в системном промте явно опишите, что записывать (правила, паттерны, стандарты), а что нет (конкретные данные из документов — суммы, имена, даты конкретных событий). Хорошее правило: в память попадает только то, что применимо к следующему документу.

Ошибка 3: Забыть, что файл памяти можно редактировать напрямую

Пытаетесь «перетренировать» агента через диалог: «Забудь про старое правило, теперь будет по-другому». Это неэффективно — агент может записать оба правила и запутаться при следующем запуске.

Как исправить: откройте .claude/agent-memory/<имя-агента>/MEMORY.md как обычный файл и отредактируйте напрямую. Удалите устаревшее правило, добавьте новое. Это занимает 30 секунд и даёт предсказуемый результат. Думайте о файле памяти как о документе, который вы совместно ведёте с агентом — а не как о магическом хранилище, доступном только через диалог.

Ошибка 4: Использовать memory: user для рабочих стандартов

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

Как исправить: memory: user для личного стиля (тон, предпочтения по структуре, то что «про вас как автора»). memory: project для стандартов, связанных с конкретной рабочей зоной, проектом, компанией. Разделение чёткое: личное vs корпоративное.

Когда нужно / когда нет

Persistent memory нужна агенту, если:

• Задача повторяется регулярно с одними и теми же стандартами. Агент-ревьюер протоколов, который проверяет 3-4 протокола в месяц — идеальный кандидат.
• У вас есть накопленный набор правил и предпочтений, который вы устали объяснять каждый раз.
• Агент работает в долгом проекте, где стандарты уточняются итеративно. Лучше, чтобы уточнения накапливались сами, а не требовали ручной правки CLAUDE.md.
• Вы хотите, чтобы несколько людей в команде пользовались одним агентом с общими стандартами — файл памяти в Git будет общим.

Persistent memory не нужна, если:

• Агент используется для разовых задач без повторений. Память ему просто негде накапливаться — смысл в ней появляется только при регулярном использовании.
• Стандарты уже полностью описаны в системном промте и не меняются. Если вы один раз написали исчерпывающие правила — память только добавляет сложности без ценности.
• Агент работает с данными, которые не должны нигде сохраняться. В этом случае используйте memory: local, но с осторожностью к тому, что реально записывается.
• Задача одноразовая — например, анализ конкретного пакета документов для завершённого проекта. После закрытия проекта память агента потеряет актуальность.

Практический тест: нужна ли память этому агенту?

Задайте себе два вопроса. Первый: «Я уже объяснял это агенту раньше?» Если да — память нужна. Второй: «Если я удалю всю историю разговоров, агент сможет работать так же хорошо?» Если нет — у него что-то есть в контексте, что нужно перенести в структурированную память.

Связь с другими уроками

День 22: .claude/agents/ — создаём первого агента — там разобрана базовая структура файла агента: frontmatter, поля name, description, tools, системный промт. Поле memory добавляется туда же, в frontmatter. Если не проходили день 22 или не создавали агента — вернитесь: persistent memory бессмысленна без понимания, как вообще устроен агент.

День 23: Frontmatter субагентов — там полный разбор всех полей frontmatter, включая model, tools, disallowedTools. Поле memory — логичное продолжение этого набора. После сегодняшнего урока у вас будут заполнены все ключевые поля и понятен смысл каждого.

День 28: Агент-оркестратор — оркестратор управляет несколькими специализированными агентами. Если каждый субагент ведёт собственную память, оркестратор получает команду, которая учится со временем: не только инструкции в промте, но и накопленный опыт каждого специалиста. Persistent memory и оркестрация хорошо работают вместе именно в этой комбинации.

Задание на сегодня

Откройте любого существующего агента в .claude/agents/ (или создайте нового, если агентов ещё нет). Добавьте в frontmatter поле memory: project. Добавьте в системный промт три строки: что читать при запуске, что записывать, что не записывать.

Запустите агента, дайте ему реальную задачу, потом передайте одно уточнение по стандарту (любое, которое реально актуально для вашей работы). Проверьте, что уточнение попало в файл .claude/agent-memory/<имя-агента>/ (внутри — файл-индекс MEMORY.md).

Критерий «выполнено»: файл памяти существует, содержит ваше уточнение в структурированном виде, и при следующем запуске агент применяет его без повторного объяснения.

Резюме

• Поле memory во frontmatter агента задаёт тип хранения заметок: user (все проекты), project (текущий проект), local (локально, без Git).
• Файл памяти агента — обычный текстовый файл, который можно читать и редактировать напрямую. Это не магия, а рабочий документ.
• Системный промт должен явно описывать: что читать при запуске, что записывать, что не записывать. Без этих инструкций поведение агента непредсказуемо.
• Держите файл памяти компактным — только правила и стандарты, применимые к следующей задаче. Конкретные данные из документов (суммы, имена, даты) в память не идут.
• Persistent memory имеет смысл для повторяющихся задач. Для разовых — не нужна.