OmniRoute Compression Engine Stages: RTK, Caveman, CCR, and Headroom Explained

OmniRoute’s prompt-compression pipeline processes LLM messages through four specialized stages—RTK (Rule-aware Tool-output Kernels), Caveman (semantic shrinker), Headroom (statistical sampler), and CCR (Content-Compression-Retrieve)—that execute in a configurable order to reduce token count while preserving critical context.

The diegosouzapw/OmniRoute repository implements a modular compression architecture that chains independent engines to minimize prompt size without losing information essential for LLM reasoning. Each stage applies distinct transformations to message payloads, with the default execution order running RTK → Caveman → Headroom → CCR as determined by the strategySelector.ts logic.

RTK (Rule-aware Tool-output Kernels): Intelligent Tool Output Filtering

The RTK engine, implemented in open-sse/services/compression/engines/rtk/index.ts, serves as the first line of defense against verbose shell-tool results. It detects blocks containing output from commands like bash, git, or docker and applies declarative filters stored under the rtk/filters catalog.

Key capabilities include:

• Pattern matching against command-specific output formats
• Smart truncation via rtk/smartTruncate.ts to retain only relevant log sections
• Line deduplication handled by rtk/lineFilter.ts and rtk/deduplicator.ts
• Raw-output retention for blocks that require exact preservation
• Analytics generation that produces a list of applied techniques for the engineBreakdown

When RTK disables a block (for example, due to an unrecognized command), downstream stages receive the original text unchanged, ensuring safety.

Caveman: The Semantic Shrinker

Located in open-sse/services/compression/caveman.ts, the Caveman engine functions as a fast, rule-based "semantic shrinker" that strips superficial noise without affecting LLM reasoning. It operates on both plain-text messages and code blocks when enabled.

The engine applies rules defined in cavemanRules.ts to:

• Remove or shorten identifiers and variable names
• Strip version strings (e.g., converting v2.3.1-abc123 to shorter representations)
• Eliminate hash-like fragments and other non-semantic tokens

Because Caveman is computationally cheap, it runs after RTK in the default pipeline. This ordering ensures RTK has already removed large log clutter, making Caveman’s work lighter and more efficient.

Headroom: Statistical Sampling for Large Arrays

The Headroom engine, found in open-sse/services/compression/engines/headroom/index.ts, targets very large homogeneous JSON arrays—such as tool-result tables or log dumps—that would otherwise consume excessive tokens.

Headroom implements head-plus-tail sampling via headroom/sample.ts:

• Keeps a configurable number of rows from the start and end of arrays (default 100 rows each)
• Replaces the original array with a compact marker containing metadata

The marker format follows this pattern:

[ionizer: kept <kept>/<total> rows; full → CCR retrieve hash=<24-hex> chars=<N>]

The full original array is stored in the CCR store for later retrieval, making Headroom safe for lossy compression of massive datasets.

CCR (Content-Compression-Retrieve): Lossless Recovery Store

The final stage, CCR, lives in open-sse/services/compression/engines/ccr/index.ts and guarantees lossless recoverability for any data aggressively reduced by previous engines. When a block is replaced by a short marker, the original text is stored in a bounded in-memory CCR store.

Implementation details:

• Keys are generated using SHA-256 hashes of the block content combined with the request’s principal (API-key ID)
• The store caps at MAX_CCR_ENTRIES = 5,000 and evicts entries FIFO to prevent unbounded memory growth
• Retrieval is available via the MCP "compression-ccr" tools at /api/mcp/.../ccrRetrieve or through the ccr/ccrQuery.ts helpers

This ensures that even after extreme compression, the full original context remains accessible via cheap hash lookups.

Pipeline Execution and Strategy Selection

The open-sse/services/compression/strategySelector.ts file orchestrates which engines run and in what sequence. Each engine advertises a stackPriority value, and the selector sorts them accordingly:

• RTK: priority 10
• Caveman: priority 20
• Headroom: priority 15
• CCR: priority 4

Because each engine implements the stackable: true interface in engineCatalog.ts, the pipeline can be extended with future engines without breaking existing behavior. Users can override the default order via the pipeline field in compression requests or through combo-override settings.

Code Examples: Working with the Compression Pipeline

The following TypeScript snippets demonstrate how to invoke the compression pipeline directly using the same code path as the API:

import { applyCompression } from "@omniroute/open-sse/services/compression";
import { compressionEngineRegistry } from "@omniroute/open-sse/services/compression/engineCatalog";

// Build a request body matching the /chat endpoint format
const body = {
  messages: [
    { role: "assistant", content: "`git diff` output…" },
    { role: "tool", content: "very‑long‑log‑output…" },
  ],
};

// Define pipeline order (optional - otherwise derived from combo config)
const pipeline = ["rtk", "caveman", "headroom", "ccr"];

// Execute compression with per-engine configuration
const result = applyCompression(body, {
  pipeline,
  config: {
    rtk: { enabled: true, intensity: "aggressive" },
    caveman: { enabled: true, level: "full" },
    headroom: { enabled: true, sampleRows: 100 },
    ccr: { enabled: true }
  }
});

// Inspect results
console.log("Compressed?", result.compressed);
console.log("Techniques used:", result.stats?.techniquesUsed);
console.log("Engine breakdown:", result.stats?.engineBreakdown);

Retrieving stored CCR blocks:

import { getCcrBlock } from "@omniroute/open-sse/mcp-server/tools/compressionTools";

const marker = "[ionizer: kept 200/10000 rows; full → CCR retrieve hash=1a2b3c4d5e6f7g8h9i0j1k2l chars=120]";
const hash = marker.match(/hash=([0-9a-f]{24})/)[1];

// Retrieve via MCP tool or REST endpoint:
// GET /api/mcp/compression/ccr/retrieve?hash=<hash>
const fullBlock = await getCcrBlock({ hash });   // Returns original CSV text

Summary

• RTK handles tool-specific output filtering and truncation at the entry point, implemented in rtk/index.ts with helpers like smartTruncate.ts and deduplicator.ts
• Caveman performs fast semantic shrinking of identifiers and version strings via caveman.ts and cavemanRules.ts
• Headroom samples large homogeneous arrays (default 100 head/tail rows) and offloads full data to CCR, controlled by headroom/index.ts
• CCR provides lossless storage with a 5,000-entry FIFO cache and SHA-256 keyed retrieval, implemented in ccr/index.ts
• The strategy selector in strategySelector.ts orders execution by stackPriority (RTK 10 → Caveman 20 → Headroom 15 → CCR 4) but supports custom pipeline configurations

Frequently Asked Questions

What determines the execution order of RTK, Caveman, CCR, and Headroom?

The execution order is determined by the stackPriority values defined in each engine’s descriptor and processed by strategySelector.ts. The default priorities are RTK (10), Caveman (20), Headroom (15), and CCR (4), resulting in the sequence RTK → Caveman → Headroom → CCR. You can override this by specifying a custom pipeline array in the compression request configuration.

How does CCR ensure I don't lose data after aggressive compression?

CCR (Content-Compression-Retrieve) stores the original text of any block replaced by a marker in a bounded in-memory store keyed by SHA-256 hash. With a capacity of MAX_CCR_ENTRIES = 5,000 and FIFO eviction, it guarantees that recently compressed content remains retrievable via the MCP ccrRetrieve tool or the /api/mcp/compression/ccr/retrieve endpoint.

Can I configure the number of rows Headroom keeps when sampling arrays?

Yes. Headroom accepts a sampleRows parameter in the engine configuration (default 100). This determines how many rows are kept from both the head and tail of large homogeneous arrays. The total retained rows will be twice this value (head + tail) unless the array is smaller than the combined sample size.

Why does Caveman run after RTK in the default pipeline?

Caveman runs after RTK because RTK first removes large-scale tool-output clutter (logs, diffs) that would otherwise complicate Caveman’s semantic analysis. By placing the computationally expensive pattern matching of RTK first, Caveman can operate more efficiently on the already-truncated content, reducing the volume of text that needs identifier and version-string processing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}