103 lines
5.4 KiB
Markdown
103 lines
5.4 KiB
Markdown
---
|
||
name: "Adr 0003 Compression Strategy"
|
||
description: "Rule‑based compression, no summariser model for v1"
|
||
depth: 2
|
||
links: ["../index.md", "../architecture/context-layers.md"]
|
||
---
|
||
|
||
# ADR 0003: adopt rule‑based compression with structured decision points; defer model‑based summarisation
|
||
|
||
**status:** accepted
|
||
**date:** 07.05.2026 (May)
|
||
**deciders:** Kami
|
||
|
||
---
|
||
|
||
## context
|
||
|
||
Correx must feed large volumes of tool output, conversation history, artifacts, and event streams into limited local model context windows. Raw accumulation destroys performance, especially for smaller models. We need a compression strategy that:
|
||
|
||
* is deterministic and replay‑safe
|
||
* does not itself require a large or separate model (for v1)
|
||
* preserves decision‑critical context, not just surface summaries
|
||
* works across multiple data sources (tools, chat, artifacts, events)
|
||
|
||
## decision
|
||
|
||
We adopt a **100% rule‑based compression system** for v1. No summariser model will be used for compression, even as an option.
|
||
|
||
The four data sources will be handled as follows:
|
||
|
||
### 1. tool output – RTK‑style pipeline
|
||
|
||
All shell and tool command output is compressed using a configurable pipeline:
|
||
|
||
1. **smart filter** – strip comments, whitespace, and known boilerplate
|
||
2. **group** – aggregate similar items (e.g., files by directory, errors by type)
|
||
3. **deduplicate** – collapse repeated identical lines with occurrence counts (`Error: timeout (×14)`)
|
||
4. **truncate** – keep first N and last M lines; discard middle unless marked critical
|
||
|
||
On command failure, the full unfiltered output is saved to disk and only a pointer path is included in the compressed receipt. The model may request the raw log if needed.
|
||
|
||
User‑defined tools can declare their own compression patterns (regex + fallback) directly in the tool definition, not in a global config. This ties compression ownership to the tool.
|
||
|
||
### 2. conversation history – manual compaction with micro‑compaction
|
||
|
||
For Router ↔ User conversations:
|
||
|
||
* the last N messages are kept verbatim (configurable; default N = 6)
|
||
* **micro‑compaction** at ~60‑70% context pressure silently clears old tool outputs, keeping conversation intact
|
||
* **manual compaction** (like `/compact`) at logical breakpoints summarises older conversation into a brief paragraph, preserving action items and user intent
|
||
* users may **pin individual messages** to prevent their removal during compaction
|
||
|
||
No automatic summarisation of conversation will occur; compaction is only triggered explicitly or when token pressure requires micro‑compaction.
|
||
|
||
### 3. artifacts – chunking + summary field
|
||
|
||
Large artifacts (e.g., plans) are broken into chunks; only the current step ± 1 neighbor is kept in context. Remaining chunks are stored on disk with a file pointer left in the artifact.
|
||
|
||
All artifacts must include a `summary` field as part of their canonical schema. Non‑chunkable artifacts use this summary directly in context packs.
|
||
|
||
### 4. event history → L2 – structured decision points
|
||
|
||
L2 (compressed session memory) is built not by summarising events but by harvesting structured fields from existing validated artifacts and approval events:
|
||
|
||
* `summary` from the artifact → what was done
|
||
* `rationale` from the artifact (optional) → why it was done
|
||
* user steering text from approval events → human guidance
|
||
* stage outcome (success/failure/retry) → final status
|
||
|
||
These are assembled into a lightweight `DecisionPoint` record per completed stage. No model‑based summarisation is performed; the process is purely rule‑based and deterministic.
|
||
|
||
Older decision points eventually graduate to L3 project memory when the L2 token cap is exceeded.
|
||
|
||
### 5. no tiny summariser model
|
||
|
||
We explicitly postpone any model‑based compression beyond v1. Even v2 will re‑evaluate only if rule‑based compression proves insufficient, and then only for specific narrow tasks.
|
||
|
||
## consequences
|
||
|
||
**positive:**
|
||
|
||
* full determinism and replayability for all compression steps
|
||
* zero additional inference cost for compression
|
||
* tool output compressed dramatically (≥90% reduction on typical dev commands)
|
||
* conversation compaction is user‑controlled, preventing silent loss of important instructions
|
||
* decision points capture the *why*, not just the *what*, allowing later stages to reason about past choices
|
||
* architecture scales with more sophisticated compression later without changing contracts
|
||
|
||
**negative:**
|
||
|
||
* rule‑based extraction may miss decision nuances when models omit the `rationale` field (mitigated by prompt design and user steering)
|
||
* manual compaction requires user awareness; if never used, conversation history may still grow until micro‑compaction kicks in
|
||
* per‑tool regex patterns require tool authors to think about summarisation, adding a small authoring burden (mitigated by sensible defaults and fallback truncation)
|
||
|
||
## alternatives considered
|
||
|
||
* **dedicated tiny summariser model** – would improve compression quality but introduces nondeterminism, increased system complexity, and higher resource usage. Rejected for v1.
|
||
* **only truncation** – simplest but loses too much critical information. Rejected.
|
||
* **full context window without compression** – impossible for local models with limited context (≤32k tokens) and long‑running sessions. Rejected.
|
||
|
||
## status
|
||
|
||
This decision defines the v1 compression architecture. It may be revisited in a future ADR if empirical data shows rule‑based compression is insufficient for critical decision‑making. |