docs: add proactive context usage and compaction guidance

2026-02-16 15:44:13 -08:00
parent fee8be1de0
commit 9c8da41610
5 changed files with 187 additions and 1 deletions
@@ -961,6 +961,30 @@ When the selected backend is unavailable (for example embedding provider errors)

 `memory.auto_extract` controls whether compaction appends extracted durable facts to `global` memory.

+### Proactive Context Management
+
+Flynn can proactively signal context pressure, checkpoint conversation state to memory, and auto-compact before hard context overflows.
+
+```yaml
+compaction:
+  enabled: true
+  threshold_pct: 80
+  keep_turns: 4
+  summary_max_tokens: 1024
+  importance_threshold: 1
+  proactive:
+    enabled: true
+    warn_pct: 75
+    checkpoint_pct: 85
+    auto_compact_pct: 95
+    checkpoint_cooldown_ms: 300000
+    memory_namespace: session/checkpoints
+```
+
+Gateway surfaces this via:
+- `context_warning` streamed event during `agent.send` (before `done`)
+- `system.contextUsage` RPC for per-session context budget snapshots
+
 ### Embedding Config Fields

 | Field | Required | Description |