SuperCompress documentation

Everything you need to reduce LLM token costs with query-aware context compression. Open source (MIT), runs on CPU, a learned query-aware neural policy, no GPU required.

⚡

Quickstart

Install, get a key, compress your first prompt — in under 5 minutes.

📖

API Reference

Python API, HTTP endpoints, response fields, error codes, and client usage.

🔌

Integrations

Wire SuperCompress into OpenAI, LangChain, Express.js, Vercel AI SDK, and more.

🚀

Usage

Call the hosted API or pip install locally — no servers to manage.

🧠

Architecture

How the learned policy works: features, training, inference, and compiler mode.

🌱

Environment & CO₂

Methodology for estimating energy and carbon savings from token reduction.

🤖

Coding Agents

Install the proxy — one command to compress context for Cursor, Windsurf, Claude Code, and more.

What is SuperCompress?

SuperCompress is a query-aware context compiler for LLM inference. It sits between your application and the language model, preprocessing the prompt to remove tokens that aren't relevant to the current user question. This reduces input token counts by ~65% on average, cutting API costs and latency while preserving the evidence the model needs to answer correctly.

Unlike truncation (which blindly drops the tail) or summarization (which rewrites content and risks losing detail), SuperCompress scores every segment of the prompt against the user's actual question and keeps only what matters for that query.

Key facts

Metric	Value
Policy size	~5,200 parameters
Latency	~60ms per compression (CPU)
Token savings (compiler mode)	82.5% avg on bundled presets
Oracle recall	100% — every answer-critical line preserved (fixed-budget suite)
Held-out answers	≥98% gold containment · ≥55% mean cut on real/fresh suites
Model download	None — weights included in pip package
GPU required	No — runs on CPU before inference
License	MIT — free for commercial use

When to use it

SuperCompress is designed for production AI features where context grows over time and token costs scale linearly with usage:

Chatbots & conversational AI — long chat histories where each turn appends to the context window
RAG pipelines — retrieved chunks that overshoot the context budget
AI search — indexing results, snippets, and document extracts sent with every query
Support copilots — customer transcripts, ticket history, knowledge base articles
Agent loops — tool call traces, intermediate outputs, log entries accumulating across turns
Memory systems — compressed episodic context for persistent agent memory

Not sure if it fits? Try the interactive playground — paste your actual context and see the compression results in real time. No signup needed.

How it works (briefly)

In compiler mode (the default), SuperCompress:

Segments the input context into semantic blocks (headings, code blocks, log entries, prose sections)
Scores each block against the user's query using a learned policy
Removes duplicate content, noise, boilerplate, and low-value blocks
Preserves context dependencies (nearby headings, imports, trace context)
Reports tokens saved, important context kept %, and compression risk level

The full pipeline takes ~60ms on a single CPU core — no GPU, no model download, no extra LLM calls.