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

> Что агенту стоит запоминать, а что нет, как называть fact_key, работать с источниками и сводками — и готовая инструкция для CLAUDE.md или AGENTS.md.

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

1. список того, что агенту стоит сохранять, и того, что не стоит;
2. правила именования `fact_key`, работы с источниками и сводками;
3. готовая инструкция, которую можно вставить в `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](/memory/memory-guard/) заменит их заглушками, но рассчитывать на это как на основную защиту не стоит: секрету не место в памяти даже в виде заглушки.
- **Сырые выгрузки разговоров и логов.** Длинный кусок переписки — это шум, по которому трудно искать и который нельзя проверить. Для архива сессий есть [история сессий](/agent/session-history/); в память кладите выводы.
- **То, что легко прочитать из кода.** Сигнатуры функций и структура каталогов устаревают при первом рефакторинге.
- **Временное состояние.** «Сейчас запущен тест», «ветка 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`. Подробно — [Источник и свежесть](/memory/source-and-freshness/).

## Сводки

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

## Когда удалять (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-ключа, проекта и рабочей области.

Как правило, MCP-клиенты (Claude, Cursor, Codex) не дают модели задавать HTTP-заголовки, поэтому для обычной работы агента этот механизм не нужен. Он для ваших собственных интеграций и скриптов, которые повторяют запросы при сбоях сети.

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

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

```markdown title="CLAUDE.md / AGENTS.md"
## Память 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).
```

## Что дальше