correx/docs/decisions/adr-0003-compression-strategy.md

name, description, depth, links

name	description	depth	links
Adr 0003 Compression Strategy	Rule‑based compression, no summariser model for v1	2	../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.