ACE - Compressor

Compress Markdown and text into ContextPack/3 artifacts for efficient LLM context loading. ACE Logo

Gem Version Ruby License: MIT

Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.

Getting Started | Usage Guide

ace-compressor demo

ace-compressor provides deterministic context compression for one or more sources, with exact extraction, policy-driven compact output, and agent-assisted payload rewriting while preserving record structure. It integrates with ace-bundle for input resolution and ace-llm for agent-mode rewriting. Compression returns are moderate — expect ~10% byte reduction in exact mode and ~25% in agent mode — with the main wins coming from line count reduction and structured record normalization.

How It Works

  1. Feed one or more Markdown or text sources into a compression mode.
  2. The compressor extracts structured records, applies mode-specific reduction policies, and produces a stable ContextPack/3 artifact — a pipe-delimited record format preserving document structure in minimal tokens.
  3. Output goes to a cache-backed path for reuse or inline to stdio, with optional stats summaries and benchmark comparisons.
Mode What it does Tradeoff
exact Canonical semantic extraction — headings, prose, lists, and code become compact typed records. Fully deterministic, no LLM involved. ~10% byte reduction; preserves all content
compact Policy-driven narrative compaction that classifies sections and applies aggressive reduction rules. Emits explicit `LOSS ` markers for anything dropped.
agent Runs exact extraction first, then uses an LLM to rewrite selected payloads (`SUMMARY ,FACT

Use Cases

Prepare large docs for agent workflows - run ace-compressor docs/vision.md --mode exact to reduce source size while keeping provenance and section structure intact for ace-bundle payloads.

Compare compression strategies on real files - run benchmark mode across exact, compact, and agent to inspect retention and size tradeoffs before committing to a compression approach.

Build repeatable context artifacts - generate stable output paths and reuse cache-backed pack artifacts across runs in CI pipelines and multi-agent loops.

Rewrite payloads with LLM assistance - use agent mode with ace-llm to rewrite payload text while keeping the deterministic ContextPack/3 structure, producing more concise context for downstream consumers.

Getting Started | Usage Guide | Part of ACE