Context-window packing
contextwindow.Pack() chooses which context fragments earn a place in a bounded model window. It scores them with deterministic BM25 plus small recency, error, priority, and pinned signals, fits the winners into a token budget, and returns them in their original chronological order.
Compression makes individual fragments smaller. Packing decides which fragments to send at all. When candidate context exceeds the window, Pack selects the best set under budget. It is deterministic and local-only: Okapi BM25 for relevance, no embeddings, no network.
How scoring works
Each candidate Item gets a score built from five signals:
- BM25 relevance against the query (the standard Okapi formula,
k1=1.5,b=0.75). - Recency — a small exponential decay so newer fragments edge out older ones.
- Error signal — a boost for fragments containing tokens like
ERROR,PANIC,TRACEBACK,FAIL,SECURITY, orREGRESSION. The thing that broke is usually what you need to see. - Explicit priority — a caller-supplied
Priorityadded directly to the score. - Pinned items —
Pin: trueforces an item in, ahead of everything scored.
The packer sorts by score, then greedily takes items until the token budget runs out. Items it can't fit are counted as deferred, not discarded.
Original order is preserved
Pack scores in relevance order but returns the selected items in their original order, so message chronology stays intact. A model reads them in the sequence they happened, not the sequence they ranked.
The call shape
Pack takes the query, the candidate items, and options for the budget and signal weights. Items can carry a pre-counted Tokens value; when it's zero, Pack counts the text with the engine's offline counter.
items := []contextwindow.Item{
{ID: "sys", Text: systemPrompt, Pin: true}, // always included
{ID: "err", Text: stackTrace, Timestamp: now}, // error signal boosts it
{ID: "doc", Text: oldNote, Timestamp: yesterday},
}
res := contextwindow.Pack("why did the deploy fail", items, contextwindow.Options{
MaxTokens: 8000, // total window budget
ReserveTokens: 1000, // left free for the model's response / tool call
})
// res.Items are in original order; the rest is honest accounting.
for _, it := range res.Items {
use(it.Text)
}
_ = res.TokensUsed // tokens the packed context occupies
_ = res.TokensBefore // tokens if everything had been sent
_ = res.DeferredCount // items that didn't fit the budgetMaxTokens is the whole window; ReserveTokens is carved out and left unused for the next model response or tool call. The budget the packer fills is MaxTokens − ReserveTokens.
Why deterministic
The same query, items, and options always produce the same selection. There is no embedding model and no network call in the path, so packing behaves identically offline and in CI, and a selection is reproducible. TokensBefore and TokensUsed are counted with the engine's inferred counter — the same counter behind every other ratio in the engine.
Honesty rule
The packer's token figures are inferred, per-run estimates from the offline counter, never verified and never re-projected. It selects and accounts for context; it doesn't claim a saving.