spb/khaelor Public
KHAELOR — a terminal-native autonomous engineering agent powered by Anthropic.
TypeScript 82.9%
HTML 14.9%
CSS 1.1%
JavaScript 0.7%
1<!doctype html>2<!--3KHAELOR4File: website/public/docs/context.html5Description: Docs — How KHAELOR decides what the model sees: tiers, byte-stable history, pruning, structured compaction checkpoints, /context and /cost.6Author: Simon-Pierre Boucher7Contact: contact@spboucher.ai8-->9<html lang="en">10<head>11<meta charset="utf-8">12<meta name="viewport" content="width=device-width, initial-scale=1">13<title>Context engine — KHAELOR docs</title>14<meta name="description" content="How KHAELOR decides what the model sees: tiers, byte-stable history, pruning, structured compaction checkpoints, /context and /cost.">15<link rel="stylesheet" href="/styles.css">16<script>17(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})();18</script>19<script defer src="/site.js"></script>20</head>21<body>2223<header class="site-header"><div class="inner">24 <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a>25 <nav>26 <a href="/docs/getting-started.html">Docs</a>27 <a href="/#install">Install</a>28 <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button>29 </nav>30</div></header>3132<main class="page"><div class="docs-layout">3334<aside class="sidebar">35 <div class="group"><div class="group-title">Start</div>36 <a href="/docs/getting-started.html">Getting started</a>37 <a href="/docs/cookbook.html">Cookbook</a>38 </div>39 <div class="group"><div class="group-title">Using KHAELOR</div>40 <a href="/docs/usage.html">The TUI</a>41 <a href="/docs/commands.html">Commands & keyboard</a>42 <a href="/docs/tools.html">Tools</a>43 <a href="/docs/sessions.html">Sessions</a>44 </div>45 <div class="group"><div class="group-title">Autonomy</div>46 <a href="/docs/phases.html">Phase gates</a>47 <a href="/docs/verification.html">Verification</a>48 <a href="/docs/worktrees.html">Parallel worktrees</a>49 <a href="/docs/daemon.html">The daemon</a>50 </div>51 <div class="group"><div class="group-title">Intelligence</div>52 <a href="/docs/repograph.html">Semantic index</a>53 <a href="/docs/memory.html">Project memory</a>54 <a href="/docs/context.html">Context engine</a>55 <a href="/docs/fork-replay.html">Fork · replay · sdiff</a>56 </div>57 <div class="group"><div class="group-title">Control</div>58 <a href="/docs/permissions.html">Permissions</a>59 <a href="/docs/configuration.html">Configuration</a>60 <a href="/docs/cli.html">CLI reference</a>61 </div>62 <div class="group"><div class="group-title">Internals</div>63 <a href="/docs/architecture.html">Architecture</a>64 <a href="/docs/events.html">The event model</a>65 <a href="/docs/theming.html">Theming & terminal</a>66 </div>67 <div class="group"><div class="group-title">Help</div>68 <a href="/docs/faq.html">FAQ & troubleshooting</a>69 </div>70</aside>7172<article class="content">7374<h1>The context engine</h1>75<p class="lead">One of KHAELOR's most important components: it decides what the model actually76receives — and never simply appends everything forever.</p>7778<h2 id="layout">What the model sees<a class="anchor" href="#layout">#</a></h2>79<table>80 <tr><th>Tier</th><th>Content</th><th>Stability</th></tr>81 <tr><td>SYSTEM</td><td class="wrap">Identity & behavior (the three phases live here), tool guidance, project instructions (<code>KHAELOR.md</code> / <code>CLAUDE.md</code> / <code>AGENTS.md</code> + project memory).</td><td class="wrap">Byte-stable per session — prompt-cache breakpoints land at tier ends.</td></tr>82 <tr><td>HISTORY</td><td class="wrap">A deterministic projection of the durable event log into Anthropic messages — same events, same bytes, every time.</td><td class="wrap">Append-only between compactions.</td></tr>83 <tr><td>VOLATILE</td><td class="wrap">Current-turn context (git status, mention contents, verification nudges) — injected into the API copy of the current message only, never recorded.</td><td class="wrap">Per call.</td></tr>84</table>8586<h2 id="pressure">Context pressure, three stages<a class="anchor" href="#pressure">#</a></h2>87<ol>88 <li><strong>Prune</strong> (cheap, deterministic, no LLM): old tool results are blanked with an89 explicit placeholder — recorded as a durable <code>context.pruned</code> event, so the rebuild is90 byte-exact.</li>91 <li><strong>Compact</strong>: when nothing prunable remains, the aux model writes a structured92 checkpoint and a pairing-safe cut of history is replaced by it — durable93 <code>context.compacted</code>.</li>94 <li><strong>Reactive</strong>: a context-overflow error from the API routes straight to95 compaction and the call retries.</li>96</ol>97<pre><code>objective: fix the renderer memory leak98completed: [ring buffer in render.ts, tests updated]99current_state: all checks green, awaiting user review100important_files:101 - path: src/tui/render.ts102 reason: the ring buffer implementation103failed_attempts: [capping the array in place — broke scrollback]104decisions: [keep the 16ms tick contract untouched]105running_processes: []106next_steps: [consider the same fix for the composer history]</code></pre>107<p>The checkpoint is YAML with fixed sections — objective, completed, state, files with reasons,108failed attempts, decisions, processes, next steps — so nothing load-bearing dissolves into prose.</p>109<div class="termwrap"><div class="termbar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="title">/context</span></div>110<pre class="term" data-no-copy><code> <span class="t-b">context · section estimates</span> <span class="t-dim">(~4 chars/token)</span>111 system:identity ~1,240 tokens112 system:tools ~2,610 tokens113 system:project-instructions ~3,905 tokens114 tools ~1,878 tokens115 history ~38,412 tokens116 <span class="t-b">total (estimated) ~48,045 tokens</span>117 window 200,000 · usable 168,000 <span class="t-dim">(output + compaction reserve held back)</span>118 last real total 45,208 tokens · pressure <span class="gauge">27%</span></code></pre></div>119<h2 id="cache">Prompt caching<a class="anchor" href="#cache">#</a></h2>120<p>System tiers are frozen at assembly and never re-rendered; switching models starts a fresh cache121lineage on purpose. The status-bar gauge shows <em>real</em> pressure (last real token total vs the122usable window) — estimates are always labeled as estimates.</p>123124<h2 id="commands">Commands<a class="anchor" href="#commands">#</a></h2>125<table>126 <tr><td><code>/context</code></td><td class="wrap">The budget breakdown above.</td></tr>127 <tr><td><code>/compact</code></td><td class="wrap">Manual compaction: prune first, summarize-compact only if nothing prunable remains.</td></tr>128 <tr><td><code>/cost</code></td><td class="wrap">Real usage per model — requests, input/output, cache read/write. Dollar figures only with configured pricing.</td></tr>129</table>130131<div class="pager">132 <div><span class="label">Previous</span><a href="/docs/memory.html">← Project memory</a></div>133 <div class="next"><span class="label">Next</span><a href="/docs/fork-replay.html">Fork · replay · sdiff →</a></div>134</div>135136</article>137</div></main>138139<footer class="site-footer"><div class="inner">140 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>141 <span>Anthropic-powered · terminal-native by design</span>142</div></footer>143144</body>145</html>146