diff --git a/README.md b/README.md
index 02f5eb6af..243e5be68 100644
--- a/README.md
+++ b/README.md
@@ -1,547 +1,246 @@
-
-
Headroom
-
- Compress everything your AI agent reads. Same answers, fraction of the tokens.
-
-
- Every tool call, DB query, file read, and RAG retrieval your agent makes is 70-95% boilerplate.
- Headroom compresses it away before it hits the model.
- Works with any agent — coding agents (Claude Code, Codex, Cursor, Aider), custom agents
- (LangChain, LangGraph, Agno, Strands, OpenClaw), or your own Python and TypeScript code.
-
-
+
---
-## Where Headroom Fits
+Every tool call, log line, DB read, RAG chunk, and file your agent injects into a prompt is mostly boilerplate. Headroom strips the noise and keeps the signal — **losslessly, locally, and without touching accuracy.**
-```
-Your Agent / App
- (coding agents, customer support bots, RAG pipelines,
- data analysis agents, research agents, any LLM app)
- │
- │ tool calls, logs, DB reads, RAG results, file reads, API responses
- ▼
- Headroom ← proxy, Python/TypeScript SDK, or framework integration
- │
- ▼
- LLM Provider (OpenAI, Anthropic, Google, Bedrock, 100+ via LiteLLM)
-```
-
-Headroom sits between your application and the LLM provider. It intercepts requests, compresses the context, and forwards an optimized prompt. Use it as a transparent proxy (zero code changes), a Python function (`compress()`), or a framework integration (LangChain, LiteLLM, Agno).
-
-### What gets compressed
-
-Headroom optimizes any data your agent injects into a prompt:
-
-- **Tool outputs** — shell commands, API calls, search results
-- **Database queries** — SQL results, key-value lookups
-- **RAG retrievals** — document chunks, embeddings results
-- **File reads** — code, logs, configs, CSVs
-- **API responses** — JSON, XML, HTML
-- **Conversation history** — long agent sessions with repetitive context
+> **100 logs. One FATAL error buried at position 67. Both runs found it.**
+> Baseline **10,144 tokens** → Headroom **1,260 tokens** — **87% fewer, identical answer.**
+> `python examples/needle_in_haystack_test.py`
---
-## Quick Start
+## Quick start
+
+Works with Anthropic, OpenAI, Google, Bedrock, Vertex, Azure, OpenRouter, and 100+ models via LiteLLM.
+
+**Wrap your coding agent — one command:**
-**Python:**
```bash
pip install "headroom-ai[all]"
+
+headroom wrap claude # Claude Code
+headroom wrap codex # Codex
+headroom wrap cursor # Cursor
+headroom wrap aider # Aider
+headroom wrap copilot # GitHub Copilot CLI
```
-**TypeScript / Node.js:**
-```bash
-npm install headroom-ai
-```
+**Drop it into your own code — Python or TypeScript:**
-**Docker-native (no Python or Node on host):**
-```bash
-curl -fsSL https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.sh | bash
-```
-
-macOS uses Bash 4.3+, so run the installer with a newer Bash such as Homebrew's `bash`.
-
-PowerShell:
-```powershell
-irm https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.ps1 | iex
-```
-
-**Persistent local runtime (Python-native service/task flow):**
-```bash
-headroom install apply --preset persistent-service --providers auto
-```
-
-**Persistent local runtime (Docker-native wrapper / compose flow):**
-```bash
-headroom install apply --preset persistent-docker
-```
-
-### Any agent — one function
-
-**Python:**
```python
from headroom import compress
-# Default (coding agents — protects user messages, compresses tool outputs)
-result = compress(messages, model="claude-sonnet-4-5-20250929")
-response = client.messages.create(model="claude-sonnet-4-5-20250929", messages=result.messages)
+result = compress(messages, model="claude-sonnet-4-5")
+response = client.messages.create(model="claude-sonnet-4-5", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
-
-# Document compression (financial, legal, clinical — compress everything, keep 50%)
-result = compress(messages, model="claude-opus-4-20250514",
- compress_user_messages=True, # Compress user messages too
- target_ratio=0.5, # Keep 50% (preserves numbers/entities)
- protect_recent=0, # Don't protect recent messages
-)
```
-**TypeScript:**
```typescript
import { compress } from 'headroom-ai';
-
const result = await compress(messages, { model: 'gpt-4o' });
-const response = await openai.chat.completions.create({ model: 'gpt-4o', messages: result.messages });
-console.log(`Saved ${result.tokensSaved} tokens`);
```
-Works with any LLM client — Anthropic, OpenAI, LiteLLM, Bedrock, Vercel AI SDK, or your own code. Full options via `CompressConfig`: `compress_user_messages`, `target_ratio`, `protect_recent`, `protect_analysis_context`.
-
-### Any agent — proxy (zero code changes)
+**Or run it as a proxy — zero code changes, any language:**
```bash
headroom proxy --port 8787
-```
-
-```bash
-# Run mode (default: token)
-headroom proxy --mode token # maximize compression
-headroom proxy --mode cache # preserve Anthropic/OpenAI prefix cache stability
-```
-
-```bash
-# Point any LLM client at the proxy
ANTHROPIC_BASE_URL=http://localhost:8787 your-app
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
```
-Use `token` mode for short/medium sessions where raw compression savings matter most.
-Use `cache` mode for long-running chats where preserving prior-turn bytes improves provider cache reuse.
+---
-Works with any language, any tool, any framework. **[Proxy docs](docs/content/docs/proxy.mdx)**
+## Why Headroom
-Prefer Docker as the runtime provider? See **[Installation — Docker](docs/content/docs/installation.mdx)**.
+- **Accuracy-preserving.** GSM8K **0.870 → 0.870** (±0.000). TruthfulQA **+0.030**. SQuAD v2 and BFCL both **97%** accuracy after compression. Validated on public OSS benchmarks you can rerun yourself.
+- **Runs on your machine.** No cloud API, no data egress. Compression latency is milliseconds — faster end-to-end for Sonnet / Opus / GPT-4 class models than a hosted service round-trip.
+- **[Kompress-base](https://huggingface.co/headroom-ai/Kompress-base) on HuggingFace.** Our open-source text compressor, fine-tuned on real agentic traces — tool outputs, logs, RAG chunks, code. Install with `pip install "headroom-ai[ml]"`.
+- **Cross-agent memory and learning.** Claude Code saves a fact, Codex reads it back. `headroom learn` mines failed sessions and writes corrections straight to `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` — reliability compounds over time.
+- **Reversible (CCR).** Compression is not deletion. The model can always call `headroom_retrieve` to pull the original bytes. Nothing is thrown away.
-### Coding agents — one command
-
-```bash
-headroom wrap claude # Starts proxy + launches Claude Code
-headroom wrap copilot -- --model claude-sonnet-4-20250514
- # Starts proxy + launches GitHub Copilot CLI
-headroom wrap codex # Starts proxy + launches OpenAI Codex CLI
-headroom wrap aider # Starts proxy + launches Aider
-headroom wrap cursor # Starts proxy + prints Cursor config
-headroom wrap openclaw # Installs + configures OpenClaw plugin
-headroom wrap claude --memory # With persistent cross-agent memory
-headroom wrap codex --memory # Shares the same memory store
-headroom wrap claude --code-graph # With code graph intelligence (codebase-memory-mcp)
-```
-
-Headroom starts a proxy, points your tool at it, and compresses everything automatically. Add `--memory` for persistent memory that's shared across agents. Add `--code-graph` for code intelligence via [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) — indexes your codebase into a knowledge graph for call-chain traversal, impact analysis, and architectural queries. `wrap copilot` is part of the Python-native CLI; the Docker-native wrapper currently supports `claude`, `codex`, `aider`, `cursor`, and `openclaw`.
-
-In Docker-native mode, Headroom still runs in Docker while wrapped tools run on the host. `wrap claude`, `wrap codex`, `wrap aider`, `wrap cursor`, and OpenClaw plugin setup (`wrap openclaw` / `unwrap openclaw`) are host-managed through the installed wrapper.
-
-### Multi-agent — SharedContext
-
-```python
-from headroom import SharedContext
-
-ctx = SharedContext()
-ctx.put("research", big_agent_output) # Agent A stores (compressed)
-summary = ctx.get("research") # Agent B reads (~80% smaller)
-full = ctx.get("research", full=True) # Agent B gets original if needed
-```
-
-Compress what moves between agents — any framework. **[SharedContext Guide](docs/content/docs/shared-context.mdx)**
-
-### MCP Tools (Claude Code, Cursor)
-
-```bash
-headroom mcp install && claude
-```
-
-Gives your AI tool three MCP tools: `headroom_compress`, `headroom_retrieve`, `headroom_stats`. **[MCP Guide](docs/content/docs/mcp.mdx)**
-
-### Drop into your existing stack
-
-| Your setup | Add Headroom | One-liner |
-|------------|-------------|-----------|
-| **Any Python app** | `compress()` | `result = compress(messages, model="gpt-4o")` |
-| **Any TypeScript app** | `compress()` | `const result = await compress(messages, { model: 'gpt-4o' })` |
-| **Vercel AI SDK** | Middleware | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
-| **OpenAI Node SDK** | Wrap client | `const client = withHeadroom(new OpenAI())` |
-| **Anthropic TS SDK** | Wrap client | `const client = withHeadroom(new Anthropic())` |
-| **Multi-agent** | SharedContext | `ctx = SharedContext(); ctx.put("key", data)` |
-| **LiteLLM** | Callback | `litellm.callbacks = [HeadroomCallback()]` |
-| **Any Python proxy** | ASGI Middleware | `app.add_middleware(CompressionMiddleware)` |
-| **Agno agents** | Wrap model | `HeadroomAgnoModel(your_model)` |
-| **LangChain** | Wrap model | `HeadroomChatModel(your_llm)` |
-| **OpenClaw** | One-command wrap/unwrap | `headroom wrap openclaw` / `headroom unwrap openclaw` |
-| **Claude Code** | Wrap | `headroom wrap claude` |
-| **GitHub Copilot CLI** | Wrap | `headroom wrap copilot -- --model claude-sonnet-4-20250514` |
-| **Codex / Aider** | Wrap | `headroom wrap codex` or `headroom wrap aider` |
-| **Always-on local proxy** | Persistent install | `headroom install apply --preset persistent-service --providers auto` |
-
-**[Full Integration Guide](docs/content/docs/index.mdx)**
+Bundles the [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — full [attribution below](#compared-to).
---
-## Demo
+## How it fits
-
- 
-
+```
+ Your agent / app
+ (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
+ │ prompts · tool outputs · logs · RAG results · files
+ ▼
+ ┌────────────────────────────────────────────────────┐
+ │ Headroom (runs locally — your data stays here) │
+ │ ─────────────────────────────────────────────── │
+ │ CacheAligner → ContentRouter → CCR │
+ │ ├─ SmartCrusher (JSON) │
+ │ ├─ CodeCompressor (AST) │
+ │ └─ Kompress-base (text, HF) │
+ │ │
+ │ Cross-agent memory · headroom learn · MCP │
+ └────────────────────────────────────────────────────┘
+ │ compressed prompt + retrieval tool
+ ▼
+ LLM provider (Anthropic · OpenAI · Bedrock · …)
+```
+
+→ [Architecture](https://chopratejas.github.io/headroom/docs/architecture) · [CCR reversible compression](https://chopratejas.github.io/headroom/docs/ccr) · [Kompress-base model card](https://huggingface.co/headroom-ai/Kompress-base)
---
-## Does It Actually Work?
+## Proof
-**100 production log entries. One critical error buried at position 67.**
+**Savings on real agent workloads:**
-| | Baseline | Headroom |
-|--|----------|----------|
-| Input tokens | 10,144 | 1,260 |
-| Correct answers | **4/4** | **4/4** |
+| Workload | Before | After | Savings |
+|-------------------------------|-------:|-------:|--------:|
+| Code search (100 results) | 17,765 | 1,408 | **92%** |
+| SRE incident debugging | 65,694 | 5,118 | **92%** |
+| GitHub issue triage | 54,174 | 14,761 | **73%** |
+| Codebase exploration | 78,502 | 41,254 | **47%** |
-Both responses: *"payment-gateway, error PG-5523, fix: Increase max_connections to 500, 1,847 transactions affected."*
+**Accuracy preserved on standard benchmarks:**
-**87.6% fewer tokens. Same answer.** Run it: `python examples/needle_in_haystack_test.py`
+| Benchmark | Category | N | Baseline | Headroom | Delta |
+|------------|----------|----:|---------:|---------:|----------:|
+| GSM8K | Math | 100 | 0.870 | 0.870 | **±0.000**|
+| TruthfulQA | Factual | 100 | 0.530 | 0.560 | **+0.030**|
+| SQuAD v2 | QA | 100 | — | **97%** | 19% compression |
+| BFCL | Tools | 100 | — | **97%** | 32% compression |
-
-What Headroom kept
-
-From 100 log entries, SmartCrusher kept 6: first 3 (boundary), the FATAL error at position 67 (anomaly detection), and last 2 (recency). The error was automatically preserved — not by keyword matching, but by statistical analysis of field variance.
-
-
-### Real Workloads
-
-| Scenario | Before | After | Savings |
-|----------|--------|-------|---------|
-| Code search (100 results) | 17,765 | 1,408 | **92%** |
-| SRE incident debugging | 65,694 | 5,118 | **92%** |
-| Codebase exploration | 78,502 | 41,254 | **47%** |
-| GitHub issue triage | 54,174 | 14,761 | **73%** |
-
-### Accuracy Benchmarks
-
-Compression preserves accuracy — tested on real OSS benchmarks.
-
-**Standard Benchmarks** — Baseline (direct to API) vs Headroom (through proxy):
-
-| Benchmark | Category | N | Baseline | Headroom | Delta |
-|-----------|----------|---|----------|----------|-------|
-| [GSM8K](https://huggingface.co/datasets/openai/gsm8k) | Math | 100 | 0.870 | 0.870 | **0.000** |
-| [TruthfulQA](https://huggingface.co/datasets/truthfulqa/truthful_qa) | Factual | 100 | 0.530 | 0.560 | **+0.030** |
-
-**Compression Benchmarks** — Accuracy after full compression stack:
-
-| Benchmark | Category | N | Accuracy | Compression | Method |
-|-----------|----------|---|----------|-------------|--------|
-| [SQuAD v2](https://huggingface.co/datasets/rajpurkar/squad_v2) | QA | 100 | **97%** | 19% | Before/After |
-| [BFCL](https://huggingface.co/datasets/gorilla-llm/Berkeley-Function-Calling-Leaderboard) | Tool/Function | 100 | **97%** | 32% | LLM-as-Judge |
-| Tool Outputs (built-in) | Agent | 8 | **100%** | 20% | Before/After |
-| CCR Needle Retention | Lossless | 50 | **100%** | 77% | Exact Match |
-
-Run it yourself:
+Reproduce:
```bash
-# Quick smoke test (8 cases, ~10s)
-python -m headroom.evals quick -n 8 --provider openai --model gpt-4o-mini
-
-# Full Tier 1 suite (~$3, ~15 min)
-python -m headroom.evals suite --tier 1 -o eval_results/
-
-# CI mode (exit 1 on regression)
-python -m headroom.evals suite --tier 1 --ci
+python -m headroom.evals suite --tier 1
```
-Full methodology: [Benchmarks](docs/content/docs/benchmarks.mdx) | [Evals Framework](headroom/evals/README.md)
+**Community, live:**
+
+
+
+→ [Full benchmarks & methodology](https://chopratejas.github.io/headroom/docs/benchmarks)
---
-## Key Capabilities
+## Built for coding agents
-### Lossless Compression
+| Agent | One-command wrap | Notes |
+|--------------------|------------------------------------|------------------------------------------------------------------|
+| **Claude Code** | `headroom wrap claude` | `--memory` for cross-agent memory, `--code-graph` for codebase intel |
+| **Codex** | `headroom wrap codex --memory` | Shares the same memory store as Claude |
+| **Cursor** | `headroom wrap cursor` | Prints Cursor config — paste once, done |
+| **Aider** | `headroom wrap aider` | Starts proxy, launches Aider |
+| **Copilot CLI** | `headroom wrap copilot` | Starts proxy, launches Copilot |
+| **OpenClaw** | `headroom wrap openclaw` | Installs Headroom as ContextEngine plugin |
-Headroom never throws data away. It compresses aggressively, stores the originals, and gives the LLM a tool to retrieve full details when needed. When it compresses 500 items to 20, it tells the model *what was omitted* ("87 passed, 2 failed, 1 error") so the model knows when to ask for more.
+MCP-native too — `headroom mcp install` exposes `headroom_compress`, `headroom_retrieve`, and `headroom_stats` to any MCP client.
-### Smart Content Detection
-
-Auto-detects what's in your context — JSON arrays, code, logs, plain text — and routes each to the best compressor. JSON goes to SmartCrusher, code goes through AST-aware compression (Python, JS, Go, Rust, Java, C++), text goes to Kompress (ModernBERT-based, with `[ml]` extra).
-
-### Cache Optimization
-
-Stabilizes message prefixes so your provider's KV cache actually works. Claude offers a 90% read discount on cached prefixes — but almost no framework takes advantage of it. Headroom does.
-
-### Cross-Agent Memory
-
-```bash
-headroom wrap claude --memory # Claude with persistent memory
-headroom wrap codex --memory # Codex shares the SAME memory store
-```
-
-Claude saves a fact, Codex reads it back. All agents sharing one proxy share one memory — project-scoped, user-isolated, with agent provenance tracking and automatic deduplication. No SDK changes needed. **[Memory docs](docs/content/docs/memory.mdx)**
-
-### Failure Learning
-
-```bash
-headroom learn # Auto-detect agent (Claude, Codex, Gemini)
-headroom learn --apply # Write learnings to agent-native files
-headroom learn --agent codex --all # Analyze all Codex sessions
-```
-
-Plugin-based: reads conversation history from Claude Code, Codex, or Gemini CLI. Finds failure patterns, correlates with successes, writes corrections to CLAUDE.md / AGENTS.md / GEMINI.md. External plugins via entry points. **[Learn docs](docs/content/docs/failure-learning.mdx)**
-
-
- 
-
-
-### Image Compression
-
-40-90% token reduction via trained ML router. Automatically selects the right resize/quality tradeoff per image.
-
-
-All features
-
-| Feature | What it does |
-|---------|-------------|
-| **Content Router** | Auto-detects content type, routes to optimal compressor |
-| **SmartCrusher** | Universal JSON compression — arrays of dicts, strings, numbers, mixed types, nested objects |
-| **CodeCompressor** | AST-aware compression for Python, JS, Go, Rust, Java, C++ |
-| **Kompress** | ModernBERT token compression (replaces LLMLingua-2) |
-| **CCR** | Reversible compression — LLM retrieves originals when needed |
-| **Compression Summaries** | Tells the LLM what was omitted ("3 errors, 12 failures") |
-| **CacheAligner** | Stabilizes prefixes for provider KV cache hits |
-| **IntelligentContext** | Score-based context management with learned importance |
-| **Image Compression** | 40-90% token reduction via trained ML router |
-| **Memory** | Cross-agent persistent memory — Claude saves, Codex reads it back. Agent provenance + auto-dedup |
-| **Compression Hooks** | Customize compression with pre/post hooks |
-| **Read Lifecycle** | Detects stale/superseded Read outputs, replaces with CCR markers |
-| **`headroom learn`** | Plugin-based failure learning for Claude Code, Codex, Gemini CLI (extensible via entry points) |
-| **`headroom wrap`** | One-command setup for Claude Code, GitHub Copilot CLI, Codex, Aider, Cursor |
-| **SharedContext** | Compressed inter-agent context sharing for multi-agent workflows |
-| **MCP Tools** | headroom_compress, headroom_retrieve, headroom_stats for Claude Code/Cursor |
-
-
-
----
-
-## Headroom vs Alternatives
-
-Context compression is a new space. Here's how the approaches differ:
-
-| | Approach | Scope | Deploy as | Framework integrations | Data stays local? | Reversible |
-|---|---|---|---|---|---|---|
-| **Headroom** | Multi-algorithm compression | All context (tool outputs, DB reads, RAG, files, logs, history) | Proxy, Python library, ASGI middleware, or callback | LangChain, LangGraph, Agno, Strands, LiteLLM, MCP | Yes (OSS) | Yes (CCR) |
-| **[RTK](https://github.com/rtk-ai/rtk)** | CLI command rewriter | Shell command outputs | CLI wrapper | None | Yes (OSS) | No |
-| **[Compresr](https://compresr.ai)** | Cloud compression API | Text sent to their API | API call | None | No | No |
-| **[Token Company](https://thetokencompany.ai)** | Cloud compression API | Text sent to their API | API call | None | No | No |
-
-**Use it however you want.** Headroom works as a standalone proxy (`headroom proxy`), a one-function Python library (`compress()`), ASGI middleware, or a LiteLLM callback. Already using LiteLLM, LangChain, or Agno? Drop Headroom in without replacing anything.
-
-**Headroom + RTK work well together.** RTK rewrites CLI commands (`git show` → `git show --short`), Headroom compresses everything else (JSON arrays, code, logs, RAG results, conversation history). Use both.
-
-**Headroom vs cloud APIs.** Compresr and Token Company are hosted services — you send your context to their servers, they compress and return it. Headroom runs locally. Your data never leaves your machine. You also get lossless compression (CCR): the LLM can retrieve the full original when it needs more detail.
-
----
-
-## How It Works Inside
-
-```
- Your prompt
- │
- ▼
- 1. CacheAligner Stabilize prefix for KV cache
- │
- ▼
- 2. ContentRouter Route each content type:
- │ → SmartCrusher (JSON)
- │ → CodeCompressor (code)
- │ → Kompress (text, with [ml])
- ▼
- 3. IntelligentContext Score-based token fitting
- │
- ▼
- LLM Provider
-
- Needs full details? LLM calls headroom_retrieve.
- Originals are in the Compressed Store — nothing is thrown away.
-```
-
-**Overhead**: 15-200ms compression latency (net positive for Sonnet/Opus). Full data: [Benchmarks](docs/content/docs/benchmarks.mdx)
+
+
+
+Drop Headroom into any stack
+
+| Your setup | Hook in with |
+|-------------------------|------------------------------------------------------------------|
+| Any Python app | `compress(messages, model=…)` |
+| Any TypeScript app | `await compress(messages, { model })` |
+| Anthropic / OpenAI SDK | `withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())` |
+| Vercel AI SDK | `wrapLanguageModel({ model, middleware: headroomMiddleware() })` |
+| LiteLLM | `litellm.callbacks = [HeadroomCallback()]` |
+| LangChain | `HeadroomChatModel(your_llm)` |
+| Agno | `HeadroomAgnoModel(your_model)` |
+| Strands | [Strands guide](https://chopratejas.github.io/headroom/docs/strands) |
+| ASGI apps | `app.add_middleware(CompressionMiddleware)` |
+| Multi-agent | `SharedContext().put / .get` |
+| MCP clients | `headroom mcp install` |
+
+
+
+
+What's inside
+
+- **SmartCrusher** — universal JSON: arrays of dicts, nested objects, mixed types.
+- **CodeCompressor** — AST-aware for Python, JS, Go, Rust, Java, C++.
+- **Kompress-base** — our HuggingFace model, trained on agentic traces.
+- **Image compression** — 40–90% reduction via trained ML router.
+- **CacheAligner** — stabilizes prefixes so Anthropic/OpenAI KV caches actually hit.
+- **IntelligentContext** — score-based context fitting with learned importance.
+- **CCR** — reversible compression; LLM retrieves originals on demand.
+- **Cross-agent memory** — shared store, agent provenance, auto-dedup.
+- **SharedContext** — compressed context passing across multi-agent workflows.
+- **`headroom learn`** — plugin-based failure mining for Claude, Codex, Gemini.
+
+
---
-## OpenClaw Plugin
-
-The [`@headroom-ai/openclaw`](plugins/openclaw) plugin integrates Headroom as a ContextEngine for [OpenClaw](https://github.com/openclaw/openclaw). It compresses tool outputs, code, logs, and structured data inline — 70-90% token savings with zero LLM calls. The plugin can connect to a local or remote Headroom proxy and will auto-start one locally if needed.
-
-### Install
+## Install
```bash
-pip install "headroom-ai[proxy]"
-openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw
+pip install "headroom-ai[all]" # Python, everything
+npm install headroom-ai # TypeScript / Node
+docker pull ghcr.io/chopratejas/headroom:latest
```
-> **Why `--dangerously-force-unsafe-install`?** The plugin auto-starts `headroom proxy` as a subprocess when no running proxy is detected. OpenClaw blocks process-launching plugins by default, so this flag is required to permit that behavior.
+Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-base), `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.
-Once installed, assign Headroom as the context engine in your OpenClaw config:
-
-```json
-{
- "plugins": {
- "entries": { "headroom": { "enabled": true } },
- "slots": { "contextEngine": "headroom" }
- }
-}
-```
-
-The plugin auto-detects and auto-starts the proxy — no manual proxy management needed. See the [plugin README](plugins/openclaw/README.md) for full configuration options, local development setup, and launcher details.
-
----
-
-## Cloud Providers
-
-```bash
-headroom proxy --backend bedrock --region us-east-1 # AWS Bedrock
-headroom proxy --backend vertex_ai --region us-central1 # Google Vertex
-headroom proxy --backend azure # Azure OpenAI
-headroom proxy --backend openrouter # OpenRouter (400+ models)
-```
-
----
-
-## Installation
-
-```bash
-pip install headroom-ai # Core library
-pip install "headroom-ai[all]" # Everything including evals (recommended)
-pip install "headroom-ai[proxy]" # Proxy server + MCP tools
-pip install "headroom-ai[mcp]" # MCP tools only (no proxy)
-pip install "headroom-ai[ml]" # ML compression (Kompress, requires torch)
-pip install "headroom-ai[agno]" # Agno integration
-pip install "headroom-ai[langchain]" # LangChain (experimental)
-pip install "headroom-ai[evals]" # Evaluation framework only
-```
-
-### Container images (GHCR tags)
-
-- supported platforms: `linux/amd64`, `linux/arm64`
-- tags `:code` - image with Code-Aware Compression (AST-based) i.e. `pip install "headroom-ai[proxy,code]"`
-- tags `:slim` - image with distorless base
-
-| Tag | | Extras | Docker Bake target |
-|---------------------|------------------------------------------------------|--------------|-----------------------------|
-| `` | ```ghcr.io/chopratejas/headroom:``` | `proxy` | `runtime` |
-| `latest` | ```ghcr.io/chopratejas/headroom:latest``` | `proxy` | `runtime` |
-| `nonroot` | ```ghcr.io/chopratejas/headroom:nonroot``` | `proxy` | `runtime-nonroot` |
-| `code` | ```ghcr.io/chopratejas/headroom:code``` | `proxy,code` | `runtime-code` |
-| `code-nonroot` | ```ghcr.io/chopratejas/headroom:code-nonroot``` | `proxy,code` | `runtime-code-nonroot` |
-| `slim` | ```ghcr.io/chopratejas/headroom:slim``` | `proxy` | `runtime-slim` |
-| `slim-nonroot` | ```ghcr.io/chopratejas/headroom:slim-nonroot``` | `proxy` | `runtime-slim-nonroot` |
-| `code-slim` | ```ghcr.io/chopratejas/headroom:code-slim``` | `proxy,code` | `runtime-code-slim` |
-| `code-slim-nonroot` | ```ghcr.io/chopratejas/headroom:code-slim-nonroot``` | `proxy,code` | `runtime-code-slim-nonroot` |
-
-### Docker Bake
-
-```bash
-# List all available build targets
-docker buildx bake --list targets
-
-# Build default image locally (proxy + nonroot)
-docker buildx bake runtime-default
-
-# Build one variant and load to local Docker image store
-docker buildx bake runtime-code-slim-nonroot \
- --set runtime-code-slim-nonroot.platform=linux/amd64 \
- --set runtime-code-slim-nonroot.tags=headroom:local \
- --load
-```
-
-Python 3.10+
+→ [Installation guide](https://chopratejas.github.io/headroom/docs/installation) — Docker tags, persistent service, PowerShell, devcontainers.
---
## Documentation
-| | |
-|---|---|
-| [Integration Guide](docs/content/docs/index.mdx) | LiteLLM, ASGI, compress(), proxy |
-| [Proxy Docs](docs/content/docs/proxy.mdx) | Proxy server configuration |
-| [Architecture](docs/content/docs/architecture.mdx) | How the pipeline works |
-| [CCR Guide](docs/content/docs/ccr.mdx) | Reversible compression |
-| [Benchmarks](docs/content/docs/benchmarks.mdx) | Accuracy validation |
-| [Limitations](docs/content/docs/limitations.mdx) | When compression helps, when it doesn't |
-| [Evals Framework](headroom/evals/README.md) | Prove compression preserves accuracy |
-| [Memory](docs/content/docs/memory.mdx) | Cross-agent persistent memory with provenance + dedup |
-| [Agno](docs/content/docs/agno.mdx) | Agno agent framework |
-| [MCP](docs/content/docs/mcp.mdx) | Context engineering toolkit (compress, retrieve, stats) |
-| [SharedContext](docs/content/docs/shared-context.mdx) | Compressed inter-agent context sharing |
-| [Learn](docs/content/docs/failure-learning.mdx) | Plugin-based failure learning (Claude, Codex, Gemini, extensible) |
-| [Installation](docs/content/docs/installation.mdx) | pip, npm, Docker install methods |
-| [Configuration](docs/content/docs/configuration.mdx) | All options |
-| [Filesystem Contract](wiki/filesystem-contract.md) | `HEADROOM_CONFIG_DIR` / `HEADROOM_WORKSPACE_DIR` and per-resource path overrides |
+| Start here | Go deeper |
+|-------------------------------------------------------------------------|------------------------------------------------------------------------|
+| [Quickstart](https://chopratejas.github.io/headroom/docs/quickstart) | [Architecture](https://chopratejas.github.io/headroom/docs/architecture) |
+| [Proxy](https://chopratejas.github.io/headroom/docs/proxy) | [How compression works](https://chopratejas.github.io/headroom/docs/how-compression-works) |
+| [MCP tools](https://chopratejas.github.io/headroom/docs/mcp) | [CCR — reversible compression](https://chopratejas.github.io/headroom/docs/ccr) |
+| [Memory](https://chopratejas.github.io/headroom/docs/memory) | [Cache optimization](https://chopratejas.github.io/headroom/docs/cache-optimization) |
+| [Failure learning](https://chopratejas.github.io/headroom/docs/failure-learning) | [Benchmarks](https://chopratejas.github.io/headroom/docs/benchmarks) |
+| [Configuration](https://chopratejas.github.io/headroom/docs/configuration) | [Limitations](https://chopratejas.github.io/headroom/docs/limitations) |
---
-## Community
+## Compared to
-Questions, feedback, or just want to follow along? **[Join us on Discord](https://discord.gg/yRmaUNpsPJ)**
+Headroom runs **locally**, covers **every** content type (not just CLI or text), works with every major framework, and is **reversible**.
+
+| | Scope | Deploy | Local | Reversible |
+|----------------------------------|-------------------------------------------------|-------------------------------------|:-----:|:----------:|
+| **Headroom** | All context — tools, RAG, logs, files, history | Proxy · library · middleware · MCP | Yes | Yes |
+| [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs | CLI wrapper | Yes | No |
+| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | No | No |
+| OpenAI Compaction | Conversation history | Provider-native | No | No |
+
+> **Attribution.** Headroom ships with the excellent [RTK](https://github.com/rtk-ai/rtk) binary for shell-output rewriting — `git show` → `git show --short`, noisy `ls` → scoped, chatty installers → summarized. Huge thanks to the RTK team; their tool is a first-class part of our stack, and Headroom compresses everything downstream of it.
---
@@ -552,10 +251,16 @@ git clone https://github.com/chopratejas/headroom.git && cd headroom
pip install -e ".[dev]" && pytest
```
-Prefer a containerized setup? Open the repo in **`.devcontainer/devcontainer.json`** for the default Python/uv workflow, or **`.devcontainer/memory-stack/devcontainer.json`** when you need local Qdrant + Neo4j services and the locked `memory-stack` extra for the `qdrant-neo4j` memory backend. Inside that container, use `qdrant:6333` and `neo4j://neo4j:7687` instead of `localhost`.
+Devcontainers in `.devcontainer/` (default + `memory-stack` with Qdrant & Neo4j). See [CONTRIBUTING.md](CONTRIBUTING.md).
---
+## Community
+
+- **[Live leaderboard](https://headroomlabs.ai/dashboard)** — 60B+ tokens saved and counting.
+- **[Discord](https://discord.gg/yRmaUNpsPJ)** — questions, feedback, war stories.
+- **[Kompress-base on HuggingFace](https://huggingface.co/headroom-ai/Kompress-base)** — the model behind our text compression.
+
## License
-Apache License 2.0 — see [LICENSE](LICENSE).
+Apache 2.0 — see [LICENSE](LICENSE).
diff --git a/headroom-savings.png b/headroom-savings.png
new file mode 100644
index 000000000..1adbbf23e
Binary files /dev/null and b/headroom-savings.png differ
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
-
-
- 
+