# compact-memory

Audit a zhuštění `memory/MEMORY.md` — zahazuje záznamy, které už neplatí, opakují se, jsou příliš
detailní nebo jednorázové, a slučuje související odrážky. Mění **jen** `memory/MEMORY.md`;
`USER.md`, `SOUL.md` a `keep.md` čte pouze pro detekci duplicit.

## Dva režimy

| | Interaktivní | Noční |
|---|---|---|
| Spouštěč | uživatel v chatu („compact memory") | crontab `0 2 * * *` → `scripts/compact_memory_auto.py` |
| Kdo aplikuje změnu | agent svými file tooly | skript (agent nesmí nic zapsat) |
| Výstup | číslovaný návrh v chatu, čeká na `apply` \| `keep <čísla>` \| `delete <čísla>` \| `cancel` | Telegram zpráva složená skriptem |
| Backup | ne (dohledatelnost přes `log/memory-clean.log`) | `backup/<YYYY-MM-DD_HHMM>_memory.backup.md` |

## Co se maže a slučuje

| Kategorie | Co znamená |
|---|---|
| `superseded` | překonáno novějším faktem, práce dokončená, už neplatí |
| `detail` | konkrétní příkazy, cesty, čísla, odkazy do kódu — patří do skillu nebo kódu, ne do paměti |
| `duplicate` | stejný fakt už je v `USER.md`, `SOUL.md` nebo `keep.md` |
| `ephemeral` | jednorázový debug, dočasný stav, vyřešený incident, průběh běhu |
| `stale-section` | celá `##`/`###` sekce, jejíž obsah je celý překonaný nebo jednorázový |
| `merge` | sloučení souvisejících odrážek do jedné — jen v rámci téže `###` podsekce |

## Noční běh krok za krokem

1. Skript spustí agenta přes `Nanobot.from_config(model_preset="kimi")` s vždy novým
   `session_key` (`compact-memory-auto:<timestamp>`), aby noční běhy nekontaminovaly živý chat
   ani sebe navzájem. Celý běh má timeout 10 min.
2. Agent provede audit a odpoví **jedním JSON blokem** se seznamem `changes`
   (prázdný seznam = není co měnit). Prózu agenta nikdo nečte.
3. Skript change-set zvaliduje proti aktuálnímu obsahu `MEMORY.md` a ověří sha256, že agent
   soubor sám nezměnil.
4. Odmítnutý change-set → retry ve stejné session s výpisem chyb validátoru, celkem max 3 pokusy.
5. Platný change-set → backup, přepis `MEMORY.md`, append do `log/memory-clean.log`, Telegram report
   (počty + jeden řádek na změnu s důvodem).

Proč takhle: model rozhoduje *co* se má smazat, skript řeší *jak* — doručená zpráva tak nezávisí
na tom, jestli model dodržel formát výstupu.

## Validace

Skript change-set přijme jen když přesně sedí na aktuální soubor: každý blok v `original` musí být
zkopírovaný znak po znaku a v souboru se smí vyskytovat jen jednou, bloky se nesmí překrývat
a sloučený text musí být kratší než původní. Navíc platí limity na délku (`reason` je krátká česká
věta) a change-set nesmí smazat víc než polovinu souboru. Přesná čísla jsou v `SKILL.md`
a v konstantách skriptu.

## Cesty (relativně k workspace)

| Cesta | Role |
|---|---|
| `memory/MEMORY.md` | jediný soubor, který se mění |
| `backup/` | snapshot před nočním přepisem |
| `log/memory-clean.log` | append-only audit smazaných/sloučených položek |
| `log/compact_memory_auto_cron.log` | stdout/stderr cronu — odpověď modelu a důvod odmítnutí per pokus |
| `skills/compact-memory/scripts/compact_memory_auto.py` | noční runner |

## Když noční běh spadne

- Zpráva začínající `Memory compact: CHYBA —` znamená, že se **nic neaplikovalo**.
- Detail (odpovědi modelu, chyby validátoru) je v `log/compact_memory_auto_cron.log`.
- Ruční spuštění: `uv run skills/compact-memory/scripts/compact_memory_auto.py` — pozor, reálně
  mění paměť a pošle Telegram zprávu.