CCR Reversible Compression Architecture
Learning Headroom
From Squeezing Data to Never Losing It
**Recap — the pipeline so far**
- 3.3 Live-Zone-Only Compression: only the volatile part of the prompt gets touched
- 5.1 Specialized Compressors: some tools have dedicated compressors + preservation rules that protect fields the model still needs
**The tradeoff those tools face**
- Compress aggressively -> risk deleting data the model actually needs later
- Compress conservatively -> waste tokens keeping stuff "just in case"
**CCR's answer: don't choose. Compress hard, keep the original anyway.**
Builds on ← 3.3 (only live-zone content is touched) and 5.1 (specialized compressors decide *what* to shrink)
Where this leads → 5.4 (what happens when a retrieval hash goes stale) and 5.5 (how routing decides *which* compressor + CCR combo to use)
The Four-Phase CCR Flow
**CCR = Compress, Cache, Retrieve**
```mermaid
flowchart TD
A["Tool output: 1000 items"] --> B["SmartCrusher compresses to 20 items"]
B --> C["Original 1000 items stored in CCR cache under hash"]
C --> D["Marker + retrieval tool placed in context"]
D --> E{"Model needs full data?"}
E -- No, 20 items enough --> F["Task solved, about 90 percent tokens saved"]
E -- Yes --> G["Model calls headroom_retrieve with hash"]
G --> H["Handler returns original 1000 items"]
```
**Four phases, four KCs:**
1. Compress — SmartCrusher shrinks the output
2. Store — original cached, hash generated
3. Represent — marker + retrieval tool shown to model
4. Retrieve — model recovers the original on demand
Phase 1 & 2 — Compress and Store
**Phase 1: Compress**
- Input: raw tool output (e.g. 1000 search results)
- SmartCrusher (4.1–4.5) applies retention scoring, produces a smaller output
**Phase 2: Store**
- The *original*, uncompressed content is written into a local LRU cache (SQLite-backed)
- A **retrieval hash** is generated: a short unique key, e.g. `abc123`
- The hash maps: `abc123 -> [original 1000 items]`
**Worked example**
```
Input: 1000 GitHub issue objects (raw JSON)
Step 1: SmartCrusher scores each issue by retention value
Step 2: Keeps top-scoring fields only -> title + status per issue
Output: 20 issue summaries (title + status only)
Step 3: Full 1000 objects written to cache, key "abc123" generated
Store: CCR["abc123"] = <all 1000 full issue objects>
```
**Why a hash (not the full content) travels forward:** the *pointer* is cheap in tokens — a 6-character key costs roughly 2-3 tokens — while re-sending 1000 full JSON objects could cost tens of thousands of tokens. Passing the pointer instead of the payload is what makes the savings real.
Phase 3 — What the Model Actually Sees
**The compression marker** (appended to the compressed output):
```
[1000 items compressed to 20. Retrieve more: hash=abc123]
```
- Tells the model: data was reduced, here's the receipt
- The `hash=abc123` is the retrieval key from Phase 2
**The injected `headroom_retrieve` tool:**
```json
{
"name": "headroom_retrieve",
"description": "Retrieve original uncompressed data from Headroom cache",
"parameters": { "hash": "The hash key from the compression marker" }
}
```
- Appears in the model's tool list *alongside* your app's normal tools
- Only usable if the model actually saw a marker with a matching hash
**Why both exist:** the marker is the *signal* ("more exists"), the tool is the *mechanism* ("here's how to get it")
Phase 4 — Retrieval and Recovery, Worked End-to-End
**Scenario:** Model is asked "Which issue has the most comments?" — comment counts weren't kept in the 20-item summary.
```mermaid
sequenceDiagram
participant M as Model
participant C as Compressed context
participant H as headroom_retrieve tool
participant Cache as CCR store
M->>C: reads 20 summaries, no comment counts
M->>H: headroom_retrieve(hash="abc123")
H->>Cache: lookup key abc123
Cache-->>H: original 1000 full issue objects
H-->>M: full data returned into context
M->>M: scans comment counts, finds max
```
**Result:** model answers correctly using recovered originals — no data was ever permanently lost, only *deferred*.
**headroom_retrieve usage = spending headroom on demand:** each retrieval re-adds tokens to the context, trading saved headroom for completeness only when actually needed.
Where CCR Fits — and What It Doesn't Guarantee Forever
**CCR vs. the alternatives**
| Mode | Behavior |
|---|---|
| Default (CCR on) | Compress aggressively, marker + retrieve tool injected, original recoverable |
| `--no-ccr` | Markers and retrieval tool disabled — compression becomes one-way |
| `--lossless` | Format-native lossless mode, no markers needed — nothing was ever thrown away |
**Key nuance:** CCR guarantees the original is *recoverable while cached* — not *forever*. The cache is LRU: old entries can be evicted.
Where this leads → 5.4 covers what happens when the model calls `headroom_retrieve` on a hash that's already been evicted (retrieval failure handling), and 5.5 covers how routing metadata decides *when* CCR vs. a specialized compressor applies.
**One line to remember:** compression stops being risky the moment recovery becomes a tool call away.
بازگشت به دوره