[Feature]: Continuous Context GC — Virtual Memory for Conversations

Problem

Long-running sessions hit context window limits. Once that happens, the session either errors out or gets compacted — losing granular context. There's no middle ground between "full context" and "summarized everything."

Proposed Solution: Tiered Context Garbage Collection

We've been working on a continuous context GC hook that treats the conversation like virtual memory. Messages age through tiers with progressive compression:

HOT (recent) → WARM (compressed) → COLD (heavily compressed) → GONE (removed)

How it works:

• Dual watermark gating — GC triggers at a configurable high watermark (e.g. 60% of context) and targets a low watermark (e.g. 40%)
• Tier classification — messages classified by turn age (recency from the current turn)
• Progressive compression — each tier applies increasingly aggressive compression:
  • Warm: tool outputs trimmed to key lines, thinking blocks removed
  • Cold: tool outputs reduced to one-line summaries, assistant responses truncated
  • Gone: messages removed entirely (with pair validation to maintain tool_use/tool_result atomicity)
• Relevance scoring — messages referenced by recent (hot) messages get promoted back to warm, preventing premature removal of still-relevant context
• Dynamic budget — 5-zone pressure system adjusts tier boundaries based on real-time context usage
• Cooldown — configurable cooldown between GC cycles to prevent thrashing

Config:

{
  "experimental": {
    "context_gc": true,
    "context_gc_config": {
      "gc_trigger_pct": 60,
      "gc_target_pct": 40,
      "gc_cooldown_ms": 30000,
      "max_gone_per_cycle": 20
    }
  }
}

How It Complements Preemptive Compaction

GC and preemptive compaction work together as two lines of defense:

1. Context GC (first line) — continuously reclaims space by compressing/removing old messages. Keeps the session alive and productive without any disruption.
2. Preemptive compaction (last resort) — if GC can't keep up (all remaining context is recent and needed), compaction fires as the final safety net.

In practice, GC handles most context pressure on its own. Compaction becomes a rare fallback rather than a regular occurrence.

Optional Enhancement: Memory Write-Through

Our implementation optionally integrates with a persistent memory backend. When large tool outputs are compressed, the full content is captured to storage and replaced with a marker (e.g. [memory#42: grep results]). The agent can recall the full content later if needed.

This is entirely optional — without a memory backend, GC still works fine. Compressed content is simply discarded. But with a memory backend, nothing is truly gone — just moved from expensive context tokens to cheap persistent storage.

What We Have

Working implementation: ~2000 LOC, 33 files, 143 tests. Key components:

• Hook factory (messages.transform + event handlers)
• Tier classifier with dynamic boundaries
• Message compressor with per-tier strategies (tool output, assistant response, system message)
• Tool_use/tool_result pair validator for safe removal
• Compression cache for idempotency
• Relevance scorer (prevents removing still-referenced context)
• Token budget estimator
• Full test suite

Happy to contribute as a PR if there's interest.