> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supercompress.vercel.app/llms.txt
> Use this file to discover all available pages before exploring further.
# SuperCompress: Learned Context Compression for LLMs
> SuperCompress trims long LLM context with a learned eviction policy — 100% oracle recall at 35% token budget, sub-millisecond CPU overhead, documented environmental impact.
SuperCompress is a Python library that compresses long agent context before every LLM call. Instead of blindly truncating from the head or tail, SuperCompress uses a lightweight \~5K-parameter eviction policy to retain the tokens most relevant to your current query — including answer-bearing lines in the middle of long documents that naive truncation drops entirely.
Get from install to your first compressed context in under five minutes.
Understand the learned eviction pipeline and why it beats truncation.
Full signatures for `compress_context`, `compress_for_turn`, and every public export.
Wire SuperCompress into OpenAI messages, LangChain agents, or any HTTP client.
## Why SuperCompress?
Long agent context is expensive. Every token in the KV cache costs GPU prefill time. Truncation keeps the head and tail but silently drops answers buried in the middle. SuperCompress learns **which lines to keep** for the current question — under a fixed token budget.
| Metric | SuperCompress | Truncation / FIFO |
| ----------------------- | ----------------------- | ----------------- |
| KV savings @ 35% budget | \~65% | \~65% |
| Oracle recall | **100%** | \~25% |
| Policy size | \~5K params | rule-based |
| Runs on | **CPU** (pre-inference) | CPU |
```bash theme={null}
pip install git+https://github.com/arjunkshah/supercompress.git
```
```python theme={null}
from supercompress import compress_context
result = compress_context(
"long context text…",
"What does fetch return when the row is missing?",
budget_ratio=0.35,
)
print(result.compressed_text)
print(f"{result.kv_savings_pct:.1f}% KV saved · {result.kept_tokens}/{result.original_tokens} tokens")
```
Use `result.compressed_text` wherever you'd pass your original context — it's a plain string.
## Explore the docs
FIFO, Truncation, H2O, Summarization, and the learned SuperCompress policy explained.
Reproducible benchmark results across 8 seeds — oracle recall, entity recall, latency.
How tokens saved translates to GPU-seconds, Wh, and CO₂ with documented assumptions.
Firebase auth, API key management, and per-key usage tracking for the hosted API.
Run the FastAPI server locally for development and integration testing.
REST endpoints for the hosted compress service with API key authentication.