The context engine

One of KHAELOR's most important components: it decides what the model actually receives — and never simply appends everything forever.

What the model sees#

Context pressure, three stages#

1. Prune (cheap, deterministic, no LLM): old tool results are blanked with an explicit placeholder — recorded as a durable context.pruned event, so the rebuild is byte-exact.
2. Compact: when nothing prunable remains, the aux model writes a structured checkpoint and a pairing-safe cut of history is replaced by it — durable context.compacted.
3. Reactive: a context-overflow error from the API routes straight to compaction and the call retries.

objective: fix the renderer memory leak
completed: [ring buffer in render.ts, tests updated]
current_state: all checks green, awaiting user review
important_files:
  - path: src/tui/render.ts
    reason: the ring buffer implementation
failed_attempts: [capping the array in place — broke scrollback]
decisions: [keep the 16ms tick contract untouched]
running_processes: []
next_steps: [consider the same fix for the composer history]

The checkpoint is YAML with fixed sections — objective, completed, state, files with reasons, failed attempts, decisions, processes, next steps — so nothing load-bearing dissolves into prose.

 context · section estimates (~4 chars/token)
 system:identity                 ~1,240 tokens
 system:tools                    ~2,610 tokens
 system:project-instructions     ~3,905 tokens
 tools                           ~1,878 tokens
 history                        ~38,412 tokens
 total (estimated)              ~48,045 tokens
 window 200,000 · usable 168,000 (output + compaction reserve held back)
 last real total 45,208 tokens · pressure 27%

Prompt caching#

System tiers are frozen at assembly and never re-rendered; switching models starts a fresh cache lineage on purpose. The status-bar gauge shows real pressure (last real token total vs the usable window) — estimates are always labeled as estimates.

Commands#