kompact — glossary

Glossary

What the words mean.

The fourteen terms this page uses for its own machinery

AUC: How often the scorer ranks a call that turned out to be needed above one that did not, over every possible pair. 0.5 is a coin flip; 1.0 never gets a pair the wrong way round.
Calibration error: The average gap between a score and what actually happens at it. At 0.035, calls scored near 0.30 are genuinely needed about 30% of the time — which is what makes a threshold mean something rather than just order things.
keep‑result, keep‑call: The two probabilities scored for every call: whether its output is still needed word for word, and whether the call itself should stay. They differ often, which is why both exist.
Function hooks: The Claude Code extension point this plugin runs on: a module that the engine calls at named moments, rather than a shell command it spawns. Early access, which is why CLAUDE_CODE_ENABLE_FUNCTION_HOOKS exists.
Sidecar: The local neural‑model process this plugin was first built to score against, over HTTP. It lost to the built-in model on 10 of 10 paired splits and has been removed; eval/ still measures it. It is the only thing here that ever wanted a GPU, and nothing here wants one now.
Leave-one-session-out: Fit on every session but one, test on the one held out, repeat for each. It is the honest number when sessions differ from each other more than calls within a session do, and it is lower than the grouped-split figure for exactly that reason.
minYieldChars: The smallest result worth dropping. Below it, dropping frees less than it risks, so the call is refused outright — the too small outcome in section 02, Watch it decide.
The floor: keepThreshold, 0.2 by default. At or above it nothing is dropped, whatever the budget still wants. It is the guard the budget cannot argue with.
Points of the context window: The unit a compaction pass is judged in. One point is one per cent of the whole window, so a pass that reclaims nine of them buys back nine per cent of everything the model reads — comparable between a long session and a short one in a way that “a quarter of the transcript” is not, and the same unit as the 60% at which the engine asks. minFreedPercent is a floor in these, and because the two share a unit, a pass that clears it leaves the session below the trigger by construction.
The cap: maxKeptChars, 24,000 by default; 0 turns it off. The floor and the budget decide which results to drop. The cap decides how much of the ones they keep is worth carrying, which is a different question: half of all tool output lives in about 3% of calls. Measured, reuse falls evenly through an output rather than at its head, so this is close to sampling it — 24,000 is the largest setting that frees more while leaving the worst session exactly where it was.
The budget: targetReduction, 0.5 by default. The fraction of droppable characters to free. Calls are dropped lowest-score-first until it is met, and then dropping stops — so a session with little to gain loses little.
Head only: The call survives and its result is cut to its first 300 characters. Enough to see what it was and to run it again.
Pinned: Inside the six newest messages, which are never touched. A pinned call is not scored for dropping at all, so its 1.000 is a statement about the rule, not about the call.
Dry run: npm run dry-run: scores the transcripts already on your machine and prints what one compaction would free and how many passes the loop would take on each of them. It writes nothing, installs nothing, and needs no plugin.

Configuration

Every setting, and its default.

The whole of userConfig in the plugin manifest. Each value is a default in src/compact.ts; leave them and the shipped numbers apply.

kompact configuration options and defaults
Option	Default	Meaning
`keepThreshold`	0.2	a floor: at or above this a result is never dropped
`targetReduction`	0.5	fraction of droppable tool output a pass tries to free
`preserveRecentMessages`	6	newest messages pinned; the first is always kept
`compactAtPercent`	62	context percentage that triggers compaction, under Claude Code’s own 70% so kompact answers first
`minFreedPercent`	5	a pass is taken only if it reclaims this many points of the window; below it the built-in summary runs
`maxPasses`	6	compactions kompact answers on one transcript before handing over regardless
`truncateHeadChars`	300	head kept of a dropped result
`minYieldChars`	200	fewest characters a drop must free to be worth making
`maxKeptChars`	24000	longest a kept result may be; 0 disables the cap
`recordSignals`	false	opt in to recording repeated command shapes for npm run propose