agentops-compress — Сжатие memory-файлов

Memory-файлы отличаются от остальных текстов одним: их читают в начале каждой сессии. Лишний абзац в статье стоит токенов один раз. Лишний абзац в CLAUDE.md стоит токенов столько раз, сколько у тебя было сессий за месяц.

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

Границы применимости

Работает с: CLAUDE.md, AGENTS.md, GEMINI.md, файлами в rules/, списками предпочтений, накопившимися TODO, длинными SKILL.md.

Не работает с: кодом, статьями, постами, документацией для людей. Там другая цель — там текст читает человек, и ритм важнее плотности. Для текстов есть content-humanizer.

Шаг 1. Померь до

python3 scripts/memtool.py detect <файл>

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

Если оценка меньше ~400 токенов, скажи об этом и остановись. Сжимать короткий файл — переставлять слова ради процентов, риск выше выигрыша.

Шаг 2. Сними бэкап

python3 scripts/memtool.py backup <файл>

Копия уезжает в $XDG_DATA_HOME/bear-skills/compress-backups/, а не в соседний каталог. Это принципиально: бэкап рядом с оригиналом подхватит автозагрузчик правил, и «сжатый» файл будет стоить вдвое дороже исходного.

Шаг 3. Сожми

Что убирать, по убыванию отдачи:

Преамбулы и мета-текст. «В этом документе описаны правила работы с…» — агент уже читает документ, ему не нужно сообщать, что это документ.

Дубли между разделами. В разросшихся memory-файлах одно и то же правило часто записано трижды в разных формулировках. Оставь одну, самую конкретную.

Обоснования очевидного. «Не коммить секреты, потому что они попадут в историю и их увидят все, у кого есть доступ к репозиторию» → «Не коммить секреты». Причина нужна там, где без неё правило выглядит произвольным, и не нужна там, где оно самоочевидно.

Примеры сверх необходимого. Три примера на правило оставляют один — самый неочевидный. Примеры на правила без исключений убираются целиком.

Проза, которая была списком. Перечисление через запятую на пять строк — это таблица или список на пять коротких.

Вежливость и хеджирование. «Желательно по возможности стараться» → «делай» или «не делай». Memory-файл — это инструкция, а не просьба.

Что не трогать — см. ../../rules/agentops-auto-clarity.md. Кратко: правила о безопасности и необратимых действиях остаются развёрнутыми, любой код, путь, флаг и имя переменной — байт-в-байт.

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

Шаг 4. Проверь

python3 scripts/memtool.py validate <оригинал> <сжатый>

Код возврата 0 — якоря на месте. Код 2 — что-то потерялось, в lost перечислено что именно.

При потерях делай точечный фикс, а не переписывание заново. Верни потерянные якоря в сжатый текст и прогони валидацию снова. Так до двух раз. Если после двух попыток якоря продолжают теряться — значит, файл сопротивляется сжатию: отдай пользователю то, что получилось, и честно скажи, что дальше резать нечего.

Шаг 5. Покажи результат

Отчёт содержит:

• оценку токенов до и после, с явным словом «оценка» — это приближение по длине, а не замер токенайзером
• что убрано, по категориям: столько-то дублей, столько-то преамбул
• путь к бэкапу
• всё, где ты сомневался, резать или нет

Дальше спроси, применять ли. Не перезаписывай memory-файл без явного подтверждения: это файл, который управляет поведением агента во всех будущих сессиях.

Чего не делать

• Не изобретай сокращения (cfg, impl, req). Токенайзер не считает их дешевле, а читаемость падает.
• Не сжимай примеры команд до «и т.д.» — команда без окончания не выполнится.
• Не объединяй правила, которые кажутся похожими, но описывают разные ситуации. Два правила про force-push — в свою ветку и в main — выглядят дублем и им не являются.
• Не называй оценку токенов замером и не обещай процент экономии, которого не показала валидация.
• Не трогай файл без бэкапа, даже если правка выглядит безобидной.