# Compaction Compaction changes the conversation projected into a model request. The durable transcript remains the source for text history, but tool-output image payloads can be elided. The strategy interface and request preparation live in [`compaction.gleam`](../src/albedo/harness/compaction.gleam). The [context inspector](context.md) reports the prepared request and its compaction observation. ## Request preparation A `Strategy` supplies `project` and `compact`. Projection reads saved strategy state without writing it or calling a model. [`prepare`](../src/albedo/harness/compaction.gleam) projects the history, applies notes layers, and compacts when the strategy says the projection is due or the request forces compaction. It compacts at most once per request, then projects again. Errors propagate to the caller. [`triggered`](../src/albedo/harness/compaction.gleam) triggers a forced compaction regardless of capacity. Otherwise it compares the request's size with a percentage of known capacity. Without capacity it does not trigger automatically. Every strategy sizes through `Context.sizing` (`compaction.Sizing`); none turns lengths into tokens itself. A request's size is the provider's count when its route has a count endpoint (`Upstream.count`), else the reported input and output of the request it continues plus an estimate of what came after, else an estimate of the whole request. [The loop](../src/albedo/harness/loop.gleam) keeps how many inputs the measured request carried and their input chain, and a request continues it only while it starts with the same inputs. Rows are priced from the reported usage of the calls that wrote and first sent them (`requests.row_costs`), else estimated. [`size`](../src/albedo/harness/size.gleam) is the one module that estimates: a crude length measure times a correction each response teaches for its route and model, priced high until a route has reported three times and held within one to four times the crude measure. Each observation's `size` says how much of it was counted, reported or estimated, with the correction the estimate used (see [the context inspector](context.md)). Each strategy's observation names where it compacts as `trigger_tokens`, in the same measure as the observation size's `tokens`. For `rolling`, `snapcompact` and `coding-lcm` it is their share of the window rounded up to a whole token, the boundary [`triggered`](../src/albedo/harness/compaction.gleam) compares against; for `persistent-agent` it is `foldTokens`, or 85% of a smaller window. The full and summary context views both carry it, and it is null until a request has been observed. The context meter draws compaction at that point and counts the tokens left until it, and draws neither when the strategy reports none. Clients must not derive the point from the window themselves. `persistent-agent` and `coding-lcm` size their tails, chunk checks, pressure relief and merge guards the same way. `persistent-agent` starts a fold only on the trusted part of a request's size: what providers measured, and estimates once their correction has settled from reported usage. A request sized only by a provisional estimate, such as the first after an upgrade, never folds, and its observation says so. A request that still overflows comes back as a `ContextTooLong` refusal, and [`loop`](../src/albedo/harness/loop.gleam) forces one compaction and resends it. ## Strategies The `/compact` command can retain the active strategy or switch to `snapcompact`, `rolling`, `coding-lcm`, or `persistent-agent`. The command describes an idle session and preserves the transcript. See [`commands/extension.gleam`](../src/albedo/harness/extensions/commands/extension.gleam). [`snapcompact`](../src/albedo/harness/extensions/snapcompact/extension.gleam) can represent earlier conversation as rendered frames or serialized text, with a verbatim tail. Its memory extension exposes `transcript.grep` and `transcript.read` to retrieve transcript rows. Its defaults are an 80% trigger, 10% tail, and 20% archive budget. When `maxFrames` is unset, the frame budget depends on capacity and the provider's declared image limits, with an upper bound of 80 frames. Each provider's `ImageLimits` carries a `VisionProfile` (geometry family, whether images ride inline, and a frame cap for a provider that states no image count); snapcompact reads only that, never a provider or model name. Settings validation requires `0 < tailPercent < triggerPercent < 100` and `0 < archivePercent < 100`. Snapcompact's Gleam extension owns archive normalization and pagination. It expands tabs to four spaces and folds adjacent CR/LF runs into full-block cells. Escape removal consumes whole Unicode scalars; malformed legacy bytes become replacement characters. The scanner retains limited CSI and OSC handling, including OSC termination by ESC followed by any character, rather than acting as a terminal emulator. Frames count scalars, including combining marks and joiners, independently. Nonpositive advance, width, or row count, or a frame with no cells, returns no pages. `render_frames` writes every missing chunk to one scratch directory and renders them in one [`sdk/renderer`](../src/albedo/harness/sdk/renderer.gleam) run. Input names sort in chunk order. `sdk/renderer` finds the binary, sets the 30-second timeout and runs it through [`albedo_ports`](../packages/albedo_ports/src/albedo_ports.gleam). The other strategies have their own state and configuration in [`rolling`](../src/albedo/harness/extensions/rolling/strategy.gleam), [`coding-lcm`](../src/albedo/harness/extensions/lcm/core.gleam), and [`persistent-agent`](../src/albedo/harness/extensions/persistent_agent/extension.gleam). Their implementation, rather than snapcompact's defaults, determines their behavior. When the model reads no images, snapcompact runs rolling's strategy as its text fallback, and that strategy keeps its summary in rolling's table under rolling's storage handle. See [public features own their tables](extensions.md#public-features-own-their-tables). `coding-lcm` and `persistent-agent` share the LCM summary graph. The [`lcm-memory`](../src/albedo/harness/extensions/lcm/memory.gleam) extension follows forks and rewinds for that graph through a [`FollowPlugin`](plugins.md#daemon-contributions), whichever strategy is active. A fork copies the nodes whose whole source span it keeps. A rewind drops the nodes that reach past the cut, and their complete children become the frontier again. See [`graph.follow`](../src/albedo/harness/extensions/lcm/graph.gleam). The graph's tables belong to `lcm-memory`. `coding-lcm` and `persistent-agent` declare its owner, so the graph's functions run under its storage handle whichever strategy calls them. `persistent-agent` consolidates memories while they take more than `memoryTokens` and stops once they fit it. Six tenths of `memoryTokens` only sizes how much one pass tries to free; consolidation does not chase it. A memory's size is a [`size`](../src/albedo/harness/size.gleam) value: the provider's count of the request with the memories in it, past the request without them, when the route has a count endpoint; else the output tokens, thinking included, that the call named by the memory's `written_by` reported; else the size module's labelled estimate. Whether to consolidate is decided on trusted sizes only: measured ones, and estimates once their correction has settled from reported usage. Memories written before sizes were linked, priced with a provisional correction, never start a consolidation by themselves. A pass sizes the whole frontier, the batches it takes, and once the memories it leaves. [`consolidation.plan`](../src/albedo/harness/extensions/persistent_agent/consolidation.gleam) picks the batches oldest first: four consecutive memories of one level merge into one a level up, and adjacent pairs merge only when no such group is left. It counts each batch as saving half of itself and stops once that covers the excess, so older life grows lossier and the newest memories keep their detail. A compaction makes one pass of merges side by side, at most four, and leaves the rest to the next fold; another pass runs only to fall back to smaller batches after refusals. A memory a merge wrote during this compaction is not merged again, alone or in a batch, until the next compaction, so a memory climbs at most one level per compaction. The trailing level-0 memories, grouped in fours from the oldest of them, end in the newest group of written memories, whole or still forming. A batch touching it is merged only when that group is the whole frontier and the compaction has not merged anything yet, so recent memories stay as the agent wrote them even when that leaves the memories over `memoryTokens` until a later compaction. Each merge prompt asks for a length relative to the memories it joins, never a number: about half as long, or a third when half would pass half the summarizer's output limit. When half would still leave the memories over `memoryTokens`, even counting half of every older memory still free to merge, the pass's merges share by size what `memoryTokens` leaves beside the memories they do not merge, asking for a third or a quarter, never less. It also asks for a cue to each detail it leaves out. The joined memories stay in the graph as the merge's children, so `lcm.grep`, `lcm.describe` and `lcm.expand` still reach them and their rows. The length is prompt guidance; nothing truncates the reply. A merge cut off at its output limit, or one whose size is not a tenth below the memories it replaces, is discarded. The round then falls back from groups of four to pairs, a refused pair ends it, and no fold asks for that batch again for a day. Everything an LCM request shows before its verbatim tail follows from the rows the graph covers. When the tail continues a turn whose user message a fold took, that message stays verbatim before the tail until the next fold, even after a newer message arrives. A new message therefore only appends, so the next request keeps the provider's cache and reuses its reported count. See [`uncovered_of`](../src/albedo/harness/extensions/lcm/core.gleam). ## Summary failures and progress [`reply_text`](../src/albedo/harness/compaction.gleam) rejects an empty summarizer reply and detects replies that stopped before finishing. A long reply cut at its output limit is kept as a `Summary` with `cut_off` set, and its text ends with a closing note for the reader. Code decides on the flag, never on the note. A summary combined from parts is `cut_off` when any part was, even when the reply that combined them finished. `persistent-agent` discards a consolidation merge marked `cut_off`, because the merge lost its end and would replace complete memories. LCM graph nodes and pending memories store the flag in a `cut_off` column, and a forced `persistent-agent` fold re-forms any cut-off leaf from its rows. Nodes written before that column were marked once, when it was added, by whether their text ends with the note. A `Summary` also names the provider request whose reply is its text, in `written_by`: the `provider_requests` row the loop recorded for the call, or the call that joined a summary's parts. Text kept verbatim has none. Graph nodes and pending memories store it in a `written_by` column, so what a memory cost to write is read from that call's reported usage rather than from its text. Nodes written before the column stay unlinked, and nothing guesses a link for them. A transfer shifts the column with the requests it moves. Compaction exposes progress stages and updates through `ProgressUpdate`. Consumers must handle failure as well as progress. A compacted request is a projection, not a replacement for the durable transcript. The [notes layer](../src/albedo/harness/extensions/notes/extension.gleam) can rewrite notes when newly evicted history extends beyond its saved cut. A summarizer failure keeps the previous notes and adds a failure observation. Configuration, storage reads, or saving rewritten notes can still fail preparation after the strategy commits. ## Image retention [`images.elide_evicted`](../src/albedo/daemon/images.gleam) can replace evicted tool-output images with a marker while retaining their text. Unreferenced payloads are then released. User uploads are excluded from that cleanup. The same module implements age-based tool-image expiry. Payload reads and inserts live in [`sdk/images`](../src/albedo/harness/sdk/images.gleam). A transcript row or a saved summary does not guarantee continued access to an image payload. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Context inspector](context.md) - [Extensions](extensions.md) - [Python kernel state](kernel-state.md) - [Plugins](plugins.md)