From 83059a0fcbc27a75fdb1f95908d12a5e4e19d580 Mon Sep 17 00:00:00 2001 From: iris Date: Fri, 5 Jun 2026 18:26:40 +0200 Subject: [PATCH] docs(turn-loop): document hyperhive.autoCompact nix option The compaction section already documented HIVE_COMPACT_WATERMARK_TOKENS but didn't mention the per-agent nix option (hyperhive.autoCompact, default true) that maps to it. Add a short note after the watermark paragraph explaining that operators can set autoCompact = false in agent.nix to disable proactive compaction, and note the reactive path still applies. Useful for sonnet/opus agents where the 75% heuristic fires before the session is actually full. --- docs/turn-loop.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/turn-loop.md b/docs/turn-loop.md index f6644d14..01fb7232 100644 --- a/docs/turn-loop.md +++ b/docs/turn-loop.md @@ -199,6 +199,17 @@ or `/compact` is surfaced as a `Note` but never fails the turn that already succeeded. The operator can also force a compaction any time via `/api/compact`. +To disable proactive compaction for a specific agent, use the nix option: + +```nix +hyperhive.autoCompact = false; # default true +``` + +Setting `autoCompact = false` is equivalent to `HIVE_COMPACT_WATERMARK_TOKENS=0`. +Useful for agents running large-context models (sonnet/opus) where the 75% +heuristic fires before the session is actually full — the reactive path +(compact-on-overflow when the session hits the hard limit) still applies. + - **Auto session-reset** — a third path that fires when both conditions hold: context is ≥ a watermark (`HIVE_AUTO_RESET_WATERMARK_TOKENS`, default **50% of `context_window_tokens(model)`**) AND the time since