headroom-context-optimizer
Optimize LLM context budgets, compress tool observations, deduplicate multi-turn transcripts, and detect prompt cache drift. Do not use for raw model prompt drafting or simple file truncation.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- headroom-context-optimizer
- description
- Optimize LLM context budgets, compress tool observations, deduplicate multi-turn transcripts, and detect prompt cache drift. Do not use for raw model prompt drafting or simple file truncation.
02 资源文件 3
- 参考文档CARD.md2.1 KB
- 参考文档config.default.yaml521 B
- 脚本scripts/headroom_runner.py3.6 KB
03 SKILL.md 正文
Headroom Context Optimizer: Production Context Engineering
headroom-context-optimizer provides automated, structure-aware context optimization, Cross-Context Retrieval (CCR) deduplication, prompt cache drift detection, and prior-turn extended thinking compaction. It is modeled after the industrial patterns in Headroom v0.41.0 to slash token consumption by 50% to 90% without losing reasoning fidelity.
See CARD.md for the companion summary card, 5-stage progression matrix, and invariants checklist.
The 5-Stage Context Optimization Pipeline
[1. Trigger & Type Detection] ──► [2. ContentRouter & SmartCrush] ──► [3. CCR Cross-Turn Dedup]
│
▼
[5. Savings Ledger & Attribution] ◄── [4. Cache Alignment Check] ◄──────────────┘
1. Trigger & Type Detection
Evaluate candidate content or conversation transcripts against optimization thresholds:
- Detect Structure:
- Inspect payloads to identify format:
json(arrays/objects),code(Python, JS, TS, Rust),diff(git patches),log(build/test traces),search(grep/ripgrep matches), ortext.
- Inspect payloads to identify format:
- Apply Activation Gates:
- Only compress content exceeding 100 characters or 25 tokens.
- For multi-turn transcripts, gate deduplication on messages exceeding 3 lines and 40 characters.
Completion criterion: Content format classified and activation threshold verified.
2. ContentRouter & SmartCrush
Route content to specialized compressors rather than uniform blind summarization:
- JSON Array Compaction (SmartCrusher):
- For lists with >5 dict elements, extract unified schema keys, retain a 3-row head sample and 2-row tail sample, and emit a compact summary structure.
- Code AST-Aware Compression:
- Strip redundant whitespace and consecutive blank lines while preserving AST boundaries.
- Log & Search Reduction:
- Truncate repetitive log entries, keeping the initial 10 lines, omitted count sentinel, and trailing 10 lines.
Completion criterion: Structure-aware compression applied; savings ratio $\ge 0.20$ on redundant data.
3. CCR Cross-Turn Deduplication
Reclaim context from repetitive multi-turn tool observations:
- Compute SHA-256 Block Digest:
- Calculate short 12-character cryptographic digests for multi-line assistant and tool returns.
- Emit CCR Retrieval Marker:
- Replace repeating observation blocks with
[CCR tool digest: <hash> | original length: <N> chars | matching turn <origin>].
- Replace repeating observation blocks with
- Preserve Recent Turns:
- Keep the most recent 2 to 4 turns completely verbatim for immediate reasoning coherence.
Completion criterion: Duplicate tool returns folded into deterministic retrieval markers.
4. Cache Alignment Check
Inspect system prompts to guarantee stable prefix prompt caching:
- Scan for Volatile Elements:
- Check system prompt for UUIDs, ISO-8601 timestamps, JWT tokens, and hex hashes.
- Enforce Prompt Immutability (Detector-Only):
- Never mutate system prompts in place (which destroys cache prefixes).
- Flag detected volatile elements to the developer so dynamic context can be relocated into user turns.
Completion criterion: System prompt confirmed 100% byte-stable or volatile elements flagged.
5. Savings Ledger & Attribution
Record cumulative context savings:
- Calculate Metrics:
- Track
total_in_tokens,total_out_tokens,net_tokens_saved, and estimated dollar savings ($3.00/MTok blend).
- Track
- Emit Observability Event:
- Log savings metrics into the session transcript or Prometheus
/metrics.
- Log savings metrics into the session transcript or Prometheus
Completion criterion: Savings ledger updated and compression statistics surfaced.
Anti-Patterns
- Uniform Blind Truncation — Chopping raw characters off the end of a payload without recognizing JSON, code, or log structures.
- System Prompt Cache Busting — Dynamically inserting timestamps or run IDs into the system prompt, invalidating Anthropic/OpenAI prompt cache prefixes.
- Excessive Dedup Fragmentation — Folding small single-line strings into digest markers where the marker itself costs more tokens than the original text.
- LLM Parse Failure Reprompts — Paying full LLM API roundtrips for malformed JSON before executing fast local string salvage.
- Unverified In-Process Sandboxing — Running untrusted external scripts in-process without sandboxed execution boundaries.
04 同仓库更多 Skills
ui-behavior-primitive-architect
Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA/SSR/RTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.
trustgraph-ontology-governor
Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.
shim-harness-governor
Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.
graphiti-zep-memory-governor
Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash/LSH entity dedup, RRF/MMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.
agora-mcp-workbench-architect
Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway/dispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.
skill-eval-assurance-runner
Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.