---
name: "Context Layers"
description: "Context hierarchy, compression, and token budgeting"
depth: 2
links:
   - "../index.md"
   - "./overview.md" 
   - "./replay-model.md"
---

# context layers

**version:** 0.1-draft  
**status:** architectural reference

---

## 1. motivation

Raw conversation accumulation destroys performance in local models. Correx forces all context to be synthesized, filtered, and layer‑separated before it reaches a model.

---

## 2. layer model

```
L0  live execution      [active request, current tool output, pending approval text]
L1  stage‑local context [artifacts and receipts from the current stage]
L2  compressed session  [summaries of completed stages; kept under a token cap]
L3  project memory      [persistent facts, architecture decisions, key outputs]
L4  archival history    [full event log; not used for inference]
```

Models receive a ContextPack built from L0–L2, with L3 optionally injected if relevant.

---

## 3. context pack building pipeline

1. **Retrieve** – pull relevant events from projections using the current session cursor.
2. **Deduplicate** – remove duplicate artifact versions, identical tool receipts, and stale retries. (Tool output deduplication happens later, within the tool‑specific compressor.)
3. **Rank** – order entries by recency and relevance to the current stage’s declared goal (simple heuristic, no model required).
4. **Compress (layer‑specific, deterministic):**
   * **Tool logs** → RTK‑style pipeline: filter noise → group similar items → deduplicate repeated lines → truncate to token budget; **full output always saved on failure** and replaced with a file pointer. Per‑tool regex patterns from the tool definition control what’s extracted.
   * **Conversation** → keep last N messages verbatim; **manually triggered compaction** (`/compact`) summarizes older turns; **micro‑compaction** silently clears old tool outputs when token pressure rises; pinned messages survive compaction. No automatic summarization.
   * **Artifacts** → chunkable artifacts (e.g., plans) split into steps; only current step ±1 remains in context, rest stored on disk. Non‑chunkable artifacts use their mandatory `summary` field directly.
   * **Steering notes** → kept verbatim.
   * **Event history → L2** → **harvest structured DecisionPoints** from completed stages: artifact `summary` + `rationale` + approval steering + stage outcome. No summarization model; pure field extraction.
5. **Inject policies** – attach active permissions, allowed tools, and stage‑specific rules.
6. **Tokenize & trim** – enforce hard token budget; if exceeded, oldest L2 DecisionPoints are dropped first (they graduate to L3 project memory).
7. **Assemble** – produce the final, deterministic **ContextPack**.

This pipeline is entirely rule‑based, replay‑safe, and uses zero model calls for compression.

---

## 4. context pack structure

```kotlin
data class ContextPack(
    val layers: Map<ContextLayer, List<ContextEntry>>,
    val budgetUsed: Int,
    val budgetLimit: Int
)
```

Each entry is a typed reference to an event, artifact excerpt, summary, or policy snippet.

---

## 5. router context isolation

The Router maintains its own separate L2 memory, rebuilt from stage summaries. During active execution, the Router’s context is unloaded from the execution model’s context window. When the user interrupts, the Router rebuilds its view from the latest L2 snapshot, interprets steering, and injects it without polluting the execution model.

---

## 6. token budgeting

* Each model and stage can define a max token limit.
* System prompts and policies reserve a portion.
* If the compressed context still exceeds the budget, older L2 entries are merged into L3 and dropped from L2.
* A session‑level cap on L2 memory exists to prevent gradual bloat in long‑running sessions.

---

## 7. observability

The context processor emits events (`ContextPackBuilt`, `LayerTruncated`) with metrics on compression ratios, token usage, and deduplication hits. This data is invaluable for tuning compression strategies.