Правила для агентов

Память полезна настолько, насколько аккуратно в неё пишут. К концу этой страницы у вас будет:

список того, что агенту стоит сохранять, и того, что не стоит;
правила именования fact_key, работы с источниками и сводками;
готовая инструкция, которую можно вставить в CLAUDE.md или AGENTS.md.

Что запоминать

Сохранять	Пример
Решения и их причины	«Сессии храним в Redis, а не в PostgreSQL: нужен TTL и быстрые чтения»
Договорённости команды	«Ревью обязательно для любых изменений в миграциях»
Как что-то сделать в этом проекте	«staging выкатывается через systemd-юнит app-staging»
Причины найденных ошибок	«Падение импорта было из-за часового пояса в cron; исправлено заданием TZ=UTC»
Предпочтения пользователя	«Пользователь просит отвечать по-русски и без эмодзи»
Факты из документов — с источником	«API v2 отдаёт даты в ISO 8601» + `source_id: docs/api.md`

Что не запоминать

Секреты. Ключи, токены, пароли, строки подключения. Memory Guard заменит их заглушками, но рассчитывать на это как на основную защиту не стоит: секрету не место в памяти даже в виде заглушки.
Сырые выгрузки разговоров и логов. Длинный кусок переписки — это шум, по которому трудно искать и который нельзя проверить. Для архива сессий есть история сессий; в память кладите выводы.
То, что легко прочитать из кода. Сигнатуры функций и структура каталогов устаревают при первом рефакторинге.
Временное состояние. «Сейчас запущен тест», «ветка feature-x не смержена» — через час это неправда.
Чужие персональные данные без необходимости и согласия.

Как формулировать запись

Один факт — одна запись. Так её можно обновить, удалить или пометить отдельно.
Запись понятна без контекста. Не «как мы договорились, делаем так», а «staging выкатывается через systemd-юнит app-staging».
Слова, по которым будут искать. Поиск опирается на слова из текста записи, поэтому пишите их явно: «выкатка», «staging», «деплой», а не «это».
С причиной. «Используем X, потому что Y» полезнее, чем «используем X»: через полгода агент поймёт, когда правило можно менять.

Именование fact_key

fact_key — это вопрос, на который отвечает запись. Все записи, отвечающие на один вопрос, должны иметь один ключ: тогда расхождения станут видны как conflict.

Хорошо	Плохо	Почему
`deploy.staging.method`	`deploy`	Слишком широкий ключ: разные факты про деплой начнут «конфликтовать».
`backend.sessions.storage`	`решение-про-redis-2026-10-05`	Дата и ответ в ключе: следующая версия получит другой ключ, и конфликт не будет замечен.
`team.review.migrations`	`Review Rule`	Регистр и пробелы: легко записать по-разному.

Правила: строчные латинские буквы, точки между уровнями «область.предмет.свойство», без дат и без самого ответа. Исключение — сводки за период: deploy.weekly-summary.2026-w41.

Источники

Если факт взят из документа, указывайте:

source_id — путь от корня репозитория или URL (docs/deploy.md);
source_hash — хеш содержимого (sha256sum), всегда вместе с source_id;
source_revision — коммит или номер версии.

Так позже можно проверить свежесть через validate_memory и удалить все факты устаревшего документа одним forget по source_id. Подробно — Источник и свежесть.

Сводки

Когда записей по теме много, агент может сделать сводку. Передавайте в derived_from ID записей, из которых она собрана (до 50). Тогда сводка унаследует conflict и stale исходных записей и не спрячет нерешённое. Подробно — Конфликты и сводки.

Когда удалять (forget)

Человек подтвердил, что факт неверен.
Разрешён конфликт: неверная версия удаляется по memory_id.
Документ переписан: старые факты удаляются по source_id перед сохранением новых.
Человек попросил забыть.

Не удаляйте записи только потому, что они старые: возраст — не ошибка. Удаление мягкое и затрагивает только записи, которые видит вызывающий.

Уверенность

0,9–1,0 — прочитано в документе или подтверждено человеком;
0,5 (по умолчанию) — вывод агента из работы;
ниже 0,5 — гипотеза, которую стоит проверить.

Повторы без дублей: X-Idempotency-Key

Если вы пишете в MMW своим скриптом или интеграцией по HTTP, добавляйте заголовок X-Idempotency-Key (1–256 печатных ASCII-символов без пробелов) к вызову remember. Повтор с тем же ключом и тем же содержимым вернёт ту же запись, а не создаст вторую. Тот же ключ с другим содержимым — ошибка 409 Conflict: idempotency key was used with different input. Ключ действует в пределах API-ключа, проекта и рабочей области.

Инструкция для вашего агента

Вставьте этот блок в CLAUDE.md, AGENTS.md или правила Cursor и поправьте имена рабочих областей под себя.

## Память MMW

У тебя есть долговременная память MMW (инструменты search, remember, forget, validate_memory).

Когда искать (search):
- в начале задачи — по теме задачи, чтобы узнать прошлые решения и договорённости;
- перед тем как предложить архитектурное решение или способ деплоя;
- когда пользователь спрашивает «как у нас…», «что мы решили…», «почему…».
Рабочие области: default — факты проекта, decisions — решения, docs — факты из документов.

Как читать результаты:
- status=conflict — в памяти противоречие; не выбирай сам, покажи обе версии пользователю;
- status=stale — источник изменился; перечитай его, прежде чем действовать;
- status=unverified — обычная запись; учитывай source_id и confidence.

Когда сохранять (remember):
- принято решение — с причиной (workspace=decisions);
- найдена и исправлена причина ошибки;
- пользователь сообщил правило, договорённость или предпочтение;
- прочитан документ, и из него следует важный факт — с source_id, source_hash, source_revision.

Как сохранять:
- один факт на запись, понятный без контекста, со словами, по которым его будут искать;
- fact_key вида область.предмет.свойство (deploy.staging.method), без дат и без ответа в ключе;
- перед сохранением поищи: если факт уже есть и не изменился — не дублируй;
- сводки — с derived_from = ID исходных записей.

Никогда не сохраняй: ключи, токены, пароли, строки подключения; сырые выгрузки переписки и логов;
временное состояние («сейчас идёт тест»).

forget — только когда пользователь подтвердил, что факт неверен, при разрешении конфликта
или когда документ-источник переписан (forget по source_id перед новыми remember).

Что дальше

Основные понятия Поля записи и статусы, на которые ссылается инструкция.

Memory Guard Что сервер вычищает и отклоняет.

Справочник remember Все параметры и ошибки.