Context Garbage Collection System
JAATO implements a pluggable context garbage collection system that prevents context window overflow during long-running agentic sessions. Four strategy plugins share a common GCPlugin protocol. The most advanced strategy, gc_budget, uses the InstructionBudget for policy-aware removal across a five-tier priority system and supports continuous collection mode for predictable context trimming.
Four GC Strategies
| Strategy | Approach | Content Discrimination | Best For |
|---|---|---|---|
| gc_truncate | Remove oldest turns entirely | None — all turns equal | Simple sessions, minimal overhead |
| gc_summarize | Compress old turns into summary | None — all turns equal | Long sessions needing context continuity |
| gc_hybrid | Generational: truncate ancient, summarize middle, preserve recent | Age-based tiers | Balanced approach |
| gc_budget | Policy-aware: remove by GC policy tier | Policy-based tiers (5 levels) | Enterprise, long-running agents |
GC Policy Tiers
The InstructionBudget assigns a GCPolicy to every tracked instruction source. These policies determine removal priority during budget-aware garbage collection:
| Policy | Indicator | Removal Behavior | Examples |
|---|---|---|---|
| LOCKED | 🔒 | Never removed | System instructions, user's original request, core tool schemas |
| PRESERVABLE | ◑ | Only under extreme pressure | Clarification Q&A, turn summaries, GC summaries |
| PARTIAL | ◐ | Container with mixed children | CONVERSATION source, PLUGIN source |
| EPHEMERAL | ○ | First candidates for removal | Enrichment data, discoverable tool schemas, verbose output |
Five-Phase Removal (gc_budget)
The gc_budget plugin executes removal in strict priority order, stopping as soon as enough tokens are freed:
- Phase 1a: ENRICHMENT — Bulk clear entire enrichment source (regenerated every turn)
- Phase 1b: EPHEMERAL — Remove other ephemeral entries, oldest first
- Phase 2: PARTIAL turns — Remove old conversation turns, respecting
preserve_recent_turnsand pinned indices - Phase 3: PRESERVABLE — Only if usage exceeds
pressure_percent; never in continuous mode - LOCKED — Never removed under any circumstances
Continuous vs Threshold Mode
| Aspect | Threshold Mode (default) | Continuous Mode |
|---|---|---|
| Trigger | Usage ≥ threshold_percent (80%) | Usage > target_percent (60%) after every turn |
| Enable | pressure_percent > 0 | pressure_percent = 0 or None |
| Collection size | Large, infrequent | Small, every turn |
| PRESERVABLE | Touched under extreme pressure | Never touched |
| Pattern | Sawtooth (80% → 60% → 80%) | Gentle ripple around target |
Session Integration
GC integrates at three points during each turn: a pre-send check before the message is sent, streaming threshold monitoring during token generation, and post-turn collection if the threshold was crossed. After collection, the session synchronizes the InstructionBudget using the GCRemovalItem list returned by the plugin, then emits a budget update event for the UI.
Coherence Preservation
- preserve_recent_turns — Last N turns are never removed (default: 5)
- pinned_turn_indices — Specific turns that are never removed
- LOCKED policy — User's original request and system instructions are never collected
- Summary chain — GC summaries are marked PRESERVABLE and bridge removed history to current context
- Turn boundaries — GC operates on complete turns, never splitting a turn partially