Compact First, Recall When Needed

RTK's recovery system answers the hardest question created by a compact result: what happens when the agent needs evidence that the first view omitted? This chapter follows raw output through failure recovery, successful truncation, local storage, and analytics. It also shows how gain, discover, and recall-efficiency data qualify the headline reduction, so readers can operate RTK as a reversible context boundary rather than a one-way deletion filter.

Recovery begins when information is lost

A filter can be useful precisely because it does not show everything immediately. A test run may need only failures and a summary. A long search or inventory may need an initial set of results rather than every matching line. But the omitted content remains part of the command's evidence. If the agent has no way to obtain it, a compact result can turn an ordinary absence of detail into a dead end.

RTK addresses that problem with a recovery hint. When a command fails and its output is substantial enough to matter, the raw payload can be stored and the compact result can include a command such as rtk recall <hash>. When a successful filter truncates a long list, RTK can store the hidden portion and emit a hint that identifies how many items were omitted. The agent can run the hint to retrieve the missing evidence instead of executing the original development command again.

sequenceDiagram participant T as Underlying tool participant F as RTK filter participant S as Recovery store participant A as AI agent participant D as Local analytics T->>F: Raw output and exit status F-->>A: Compact result alt Failure or successful truncation F->>S: Store recoverable raw payload S-->>F: Recall hash F-->>A: Compact result plus recall hint A->>S: Run rtk recall hash S-->>A: Hidden or full output S->>D: Record recall else No omitted evidence F->>D: Record result without recall entry end F->>D: Record savings and execution time

The storage and the displayed result have to agree. For a flat list, the stored representation can be organized so the default recall begins at the first hidden line. For multi-line failure blocks, the agent may need the full stored payload or a selected range rather than a simple line offset. This is why recovery is part of filter design: the code must know what was shown, what was hidden, and which slice the hint promises to return.

The default recovery mode uses an embedded SQLite store. Each entry is addressed by a short hash derived from the command and its content, so a hint can refer to a particular captured result without exposing a long path or requiring the agent to remember a filename. The payload can be gzip-compressed, but decompression is lossless. The store retains metadata such as the command, working directory, exit code, line information, original byte size, and whether the entry was truncated. A recall operation can return the full payload, start from a line, take a number of lines, or filter the selected bytes by a pattern.