actx compact

actx compact

Run the CTX-ACCE (Agent Context Compaction Engine) to compress, deduplicate, and optimize context entries. Uses the Rust N-API sidecar bridge for native-speed compaction with zone-based pressure strategies.

Usage

actx compact --input <path> [options]

Options

Option	Default	Description
--input <path>	—	(Required) JSON file containing context entries
--output <path>	stdout	Output path for the compacted result
--model <string>	auto	Model identifier for pressure calculation (e.g., gpt-4, claude-3)
--level <level>	auto	Compaction level: none, conservative, moderate, aggressive, emergency, auto
--stats	—	Show before/after token statistics instead of raw entries
--dry-run	—	Calculate pressure and strategies without actually compacting

Compaction Levels

Level	Behavior
none	No compaction applied
conservative	Dedup and prune only
moderate	Dedup, prune, delta compression
aggressive	All strategies including schema collapse and summarization
emergency	Maximum compression — summarize, reorder, and evict aggressively
auto	Determine level automatically based on context pressure zone

Pressure Zones

The compactor evaluates your context against the model’s effective ceiling (context window × headroom factor):

Zone	Strategies Applied
Green	None — context fits comfortably
Yellow	Dedup, prune
Orange	Dedup, prune, delta, collapse, schema
Red / Critical	All strategies including summarize and reorder

Examples

# Dry run — see what would happen
$ actx compact --input context.json --dry-run
{
  "ok": true,
  "pressure": 0.72,
  "zone": "Yellow",
  "strategies_would_apply": ["dedup", "prune"],
  "model": "gpt-4",
  "effective_ceiling": 57344
}

# Full compaction with stats
$ actx compact --input context.json --stats
{
  "ok": true,
  "zone": "Yellow",
  "tokens_before": 24000,
  "tokens_after": 18200,
  "savings_pct": 24,
  "strategies_applied": ["dedup", "prune"],
  "pressure_before": 0.72,
  "pressure_after": 0.55
}

Error Codes

Code	Meaning
NAPI_UNAVAILABLE	Rust compactor native addon not compiled
INPUT_NOT_FOUND	Input file does not exist or cannot be read
PRESSURE_FAILED	Pressure calculation failed
COMPACT_FAILED	Compaction engine encountered an error

See Also

• actx start —compact — automatic per-turn compaction
• actx top — monitor real-time context pressure