Content
# Copium
**The context compression layer for LLM applications**
> 65–94% fewer tokens. Zero quality loss. Drop-in proxy for Claude, GPT, Gemini, Bedrock, and local LLMs.
[](https://pypi.org/project/copium-ai/)
[](https://pypi.org/project/copium-ai/)
[](LICENSE)
[](https://github.com/iKislay/copium/actions)
[](https://copium-docs.vercel.app/docs)
<p>
<a href="https://copium-docs.vercel.app/docs">Docs</a> ·
<a href="#get-started-60-seconds">Install</a> ·
<a href="#proof">Proof</a> ·
<a href="#compared-to">Alternatives</a> ·
<a href="#connect-your-ai-agent">Agent Guides</a> ·
<a href="https://github.com/iKislay/copium">GitHub</a>
</p>
---
## What is this?
You know how your AI coding assistant (Claude Code, Cursor, Copilot, etc.) sometimes slows down mid-session, starts forgetting things it read earlier, or just becomes weirdly bad at tasks it was great at ten minutes ago? That's the context window filling up. Every file your agent reads, every command it runs, every tool output it processes — it all piles into a prompt that the AI has to re-read from scratch on every single message. You're paying for all of it, every time.
Copium sits between your agent and the AI provider and compresses everything before it goes out. It's a local proxy — your data never leaves your machine. Same answers. Fraction of the tokens.
The gains are real: **1.4 billion tokens saved** across 50K+ sessions in production.
---
## Get started (60 seconds)
```bash
# Install
pip install "copium-ai[proxy]"
# or with uv (recommended)
uv tool install "copium-ai[proxy]"
# Start the proxy
copium run # listens on http://localhost:8082
# Point your agent at it (pick your tool below)
export ANTHROPIC_BASE_URL=http://localhost:8082 # Claude Code
export OPENAI_API_BASE=http://localhost:8082/v1 # Cursor / Aider / OpenCode
# Watch the savings live
copium dashboard
# or open http://localhost:8787/dashboard in your browser
```
That's it. No config files. No code changes. Copium automatically compresses every request.
---
## Connect your AI agent
### Claude Code
```bash
copium wrap claude
```
That single command starts the proxy and configures Claude Code to route through it. When you're done, `copium unwrap claude` restores everything.
Alternatively, set it manually:
```bash
copium run &
export ANTHROPIC_BASE_URL=http://localhost:8082
claude # or claude-code, or claude --dangerously-skip-permissions
```
### Cursor
```bash
copium run &
# In Cursor settings → OpenAI API Base URL:
# http://localhost:8082/v1
```
Or via environment:
```bash
export OPENAI_API_BASE=http://localhost:8082/v1
cursor .
```
### OpenCode
OpenCode uses the OpenAI-compatible API format:
```bash
copium run &
export OPENAI_BASE_URL=http://localhost:8082/v1
opencode
```
Or set it permanently in your OpenCode config:
```json
{
"openai": {
"baseURL": "http://localhost:8082/v1"
}
}
```
### Aider
```bash
copium wrap aider
# or manually:
aider --openai-api-base http://localhost:8082/v1
```
### Codex (OpenAI)
```bash
copium wrap codex
# Automatically patches ~/.codex/config.toml
# Undo with: copium unwrap codex
```
### GitHub Copilot
```bash
copium wrap copilot
```
This routes Copilot through Copium while keeping your existing auth. Supports both BYOK and subscription modes.
### Mistral / Vibe
```bash
copium wrap vibe
```
### Any HTTP client / custom app
If your tool lets you set a base URL or API endpoint:
```
http://localhost:8082 → Anthropic-compatible
http://localhost:8082/v1 → OpenAI-compatible
http://localhost:8082/bedrock → AWS Bedrock
http://localhost:8082/vertex → Vertex AI (Google Cloud)
```
### As a Python library
If you don't want the proxy at all and just want to compress messages inline:
```python
import json
from copium import compress
# Works with any messages list you'd send to an LLM
data = json.load(open("data.json")) # e.g. 500-item JSON array
result = compress([{"role": "user", "content": json.dumps(data)}])
print(f"Saved {result.compression_ratio:.1%} tokens")
# → Saved 64.8% tokens
```
### As an MCP server
```bash
pip install "copium-ai[mcp]"
```
Then add to your MCP client config:
```json
{
"mcpServers": {
"copium": {
"command": "copium",
"args": ["mcp"]
}
}
}
```
Exposes three tools: `copium_compress`, `copium_retrieve`, `copium_stats`.
---
## How it works
You don't need to understand this to use Copium. But if you're curious:
```
Your agent / app
(Claude Code, Cursor, Aider, OpenCode, your own code...)
| prompts, tool outputs, logs, RAG results, files
v
+----------------------------------------------------+
| Copium (runs locally — your data stays here) |
| ------------------------------------------------- |
| ContentRouter → SmartCrusher | Kompress |
| Session Dedup | Error Compressor |
| Cache Aligner | TOON Encoder |
| Diff Response | Output Compressor |
+----------------------------------------------------+
| compressed prompt (same meaning, fewer tokens)
v
LLM provider (Anthropic, OpenAI, Gemini, Ollama, Bedrock...)
```
Each component targets a specific kind of waste:
| Component | What it removes | Typical savings |
|---|---|---|
| **ContentRouter** | Routes each chunk to the best compressor | 20–60% |
| **SmartCrusher** | Compresses JSON arrays, repeated tool outputs | 40–95% |
| **Session Dedup** | Re-sent file content across conversation turns | 30–70% |
| **Error Compressor** | Verbose stack traces → structured error cards | 50–80% |
| **TOON Encoder** | JSON arrays → pipe-delimited tables | 15–40% |
| **Cache Aligner** | Stabilizes prefixes for provider KV cache hits | 10–20% |
| **Diff Response** | Sends diffs for repeated tool calls | Up to 95% |
| **Output Compressor** | Trims verbose assistant responses | 15–40% |
The pipeline runs in ~52ms median overhead. Your agent doesn't notice it's there.
---
## Proof
### Compression on real content types
| Content Type | Before (tokens) | After (tokens) | Savings |
|---|---:|---:|---:|
| JSON arrays (100 items) | 3,163 | 297 | **90.6%** |
| Build logs (200 lines) | 2,412 | 148 | **93.9%** |
| Shell output (200 lines) | 3,238 | 469 | **85.5%** |
| JSON arrays (500 items) | 9,526 | 1,614 | **83.1%** |
| Repeated tool outputs | 10,000 | 1,500 | **85%** |
| Git diffs | 3,000 | 300 | **90%** |
### Quality preserved — LLM accuracy benchmarks
The most important thing: does the AI still give correct answers?
| Benchmark | Baseline (no compression) | With Copium | Delta |
|---|---:|---:|---|
| HTML Extraction (F1) | 0.958 | 0.919 | −0.039 |
| HTML Recall | — | **0.982** | 98.2% content preserved |
| JSON Needle Finding | 4/4 | **4/4** | 100% accuracy at 87.6% compression |
| GSM8K (Math) | 0.870 | **0.870** | +/−0.000 |
| TruthfulQA (Factual) | 0.530 | **0.560** | +0.030 (improved) |
Run these yourself:
```bash
pip install "copium-ai[evals]" && pytest tests/test_evals/ -v -s
```
### Production telemetry (250+ instances, 50K+ sessions)
| Metric | Value |
|---|---|
| Total tokens saved | **1.4 billion** |
| Median proxy overhead | **52ms** |
| Median compression (all requests) | 4.8% |
| Heavy tool-use sessions | **40–80%** |
Most requests are short conversational turns — the median 4.8% compression is accurate for those. Where Copium pays for itself is in long agentic sessions with accumulated tool outputs, logs, and search results: that's where you see 40–94%.
---
## When does it help?
**You'll see real gains if you:**
- Run AI coding agents daily (Claude Code, Cursor, Codex, etc.)
- Use local LLMs and need to stay within context limits
- Work with verbose tool outputs — build logs, JSON, search results, git diffs
- Want to extend context window life on quantized models (Q4_0, Q8_0)
- Use Copilot or other subscription services and want more out of each turn
**It won't help much if you:**
- Only send short conversational prompts (median savings: 4.8%)
- Already use a provider's native compaction and don't need more
- Work in a sandboxed environment where local processes can't run
---
## Compared to alternatives
Copium runs **locally**, covers **every** content type, works with every major framework, and supports both cloud and local LLMs.
| | Scope | Deploy | Local LLMs | Reversible |
|---|---|---|:---:|:---:|
| **Copium** | All context — tools, RAG, logs, files, history | Proxy, library, MCP | ✅ | ✅ (CCR) |
| [Kompact](https://github.com/kompact) | Prompt text & schemas | Python library | ❌ | ❌ |
| [Claw Compactor](https://github.com/claw) | Prompt text & structure | Python library | ❌ | ❌ |
| [Headroom](https://github.com/chopratejas/headroom) | All context | Proxy, library, middleware, MCP | ❌ | ✅ (CCR) |
| [ContextZip](https://github.com/contextzip) | Session history / JSONL | Python CLI | ✅ | ✅ (Static) |
| [RTK](https://github.com/rtk-ai/rtk) | CLI command outputs | CLI wrapper | ✅ | ❌ |
| [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI commands, MCP tools | CLI wrapper, MCP | ✅ | ❌ |
| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | Text sent to their API | Hosted API call | ❌ | ❌ |
| OpenAI Compaction | Conversation history | Provider-native | ❌ | ❌ |
<details>
<summary><b>vs Kompact</b></summary>
Kompact is a Python library focused strictly on compressing prompt text and JSON schemas. Copium is a full architecture handling streaming tool outputs, multi-turn session deduplication, and provider caching.
| | Copium | Kompact |
|---|---|---|
| **Architecture** | Proxy, MCP, Library | Library only |
| **Tool Outputs** | SmartCrusher (statistical) | Regex/Text truncation |
| **Session Dedup** | ✅ Cross-turn retrieval | ❌ |
| **Performance** | Core logic in Rust | Pure Python |
| **Safety** | Reversible (CCR) | Lossy |
</details>
<details>
<summary><b>vs Claw Compactor</b></summary>
Claw Compactor is a high-quality 14-stage pipeline for compressing prompts, but it's restricted to library deployment and irreversible compression. Copium incorporates similar quality-gated pipelines but wraps them in a zero-code proxy with reversible fail-safes.
| | Copium | Claw Compactor |
|---|---|---|
| **Zero-Code Usage** | ✅ Drop-in Proxy | ❌ Library only |
| **Reversibility** | ✅ Compress-Cache-Retrieve | ❌ Irreversible |
| **Quality Gates** | ✅ Auto-reverts on inflation | ❌ Manual |
| **Provider Support** | Universal (Anthropic, Bedrock, etc) | Manual injection |
</details>
<details>
<summary><b>vs Headroom</b></summary>
Both Copium and Headroom compress AI agent context. Key differences:
| | Copium | Headroom |
|---|---|---|
| **Local LLM support** | ✅ (Ollama, VLLM, llama.cpp) | ❌ |
| **KV cache precision detection** | ✅ (auto-detect Q4_0/Q8_0/FP16) | ❌ |
| **Context paging** | ✅ (virtual memory for LLM context) | ❌ |
| **Telemetry** | Off by default (opt-in) | On by default (opt-out) |
| **CCR integrity checks** | ✅ (SHA-256 verification) | ❌ |
| **Windows support** | ✅ Pre-built wheels (CI tested) | Manual install only |
</details>
<details>
<summary><b>vs ContextZip</b></summary>
ContextZip operates on static conversation archives (e.g., `.jsonl` files) to compress past sessions. Copium operates on live agent traffic in real time.
| | Copium | ContextZip |
|---|---|---|
| **Target** | Live HTTP traffic (Proxy) | Static session files (.jsonl) |
| **Mechanism** | Real-time compression / routing | Post-hoc deduplication |
| **Use Case** | While the agent is actively running | Archiving or resuming past chats |
</details>
<details>
<summary><b>vs RTK</b></summary>
RTK requires you to manually wrap individual CLI commands (`rtk git status`). Copium wraps the entire agent (`copium wrap claude`), automatically capturing and compressing every tool output without changing how you type commands.
</details>
<details>
<summary><b>vs Provider-native compaction</b></summary>
Provider compaction (OpenAI, Anthropic) only compresses **conversation history**. Copium compresses **everything** — tool outputs, logs, RAG results, files — and routes each content type to the best compressor before it ever reaches the provider.
</details>
---
## Local LLM support
If you run Ollama, VLLM, or llama.cpp, Copium has a specific feature you won't find elsewhere: **KV cache precision detection**.
When a quantized model's KV cache is too full, accuracy collapses — not gradually, but off a cliff:
```
Q4_0 KV Cache at 32K context = 2% accuracy (vs 37.9% for FP16)
```
Copium detects your model's quantization type and starts compressing aggressively *before* you hit that cliff.
```bash
copium doctor # detects your local LLM setup and makes recommendations
```
It also supports **cold/hot context paging** — effectively virtual memory for your LLM's context window, cutting context by up to 93% for long sessions.
---
## Configuration
Create `copium.json` in your project root to customize behavior:
```json
{
"mode": "optimize",
"cache_aligner": { "enabled": true },
"session_dedup": {
"enabled": true,
"similarity_threshold": 0.85
},
"error_compressor": {
"enabled": true,
"max_stack_frames": 3,
"preserve_security_warnings": true
}
}
```
Disable specific transforms per request:
```bash
curl -H "X-Copium-Disable: toon,code_compressor" \
http://localhost:8082/v1/chat/completions
```
Environment variables:
```bash
export COPIUM_PORT=8082
export COPIUM_HOST=0.0.0.0
export COPIUM_LOG_LEVEL=debug
export COPIUM_CCR_TTL_SECONDS=1800 # how long compressed data is cached
```
### Compression presets
```bash
copium proxy --preset minimal # Structural transforms only; safest
copium proxy --preset standard # Full stack; recommended (default)
copium proxy --preset aggressive # Maximum savings; more aggressive
copium proxy --preset local-llm # Optimized for Ollama/VLLM/llama.cpp
copium proxy --preset lossless # Zero quality loss transforms only
# Inspect any preset without starting the proxy:
copium preset aggressive
```
### View your savings
```bash
copium stats # All-time summary
copium stats --period session # Current session only
copium stats --json # Machine-readable output
```
## Architecture (for the curious)
The full request pipeline:
```
Request → Cache Aligner → Differential Response → Session Dedup
→ KV Cache Detection → Content Router → Error Compressor
→ Paging → Output Compressor → TOON Encoder → Provider
```
**ContentRouter** decides which compressor to use for each piece of content. It detects the content type (JSON array, log output, code, HTML, search results, git diff) and routes it to the appropriate transform. The routing decision is logged for transparency.
**SmartCrusher** uses statistical analysis — variance-based change point detection, Kneedle algorithm for optimal K, BM25 + embedding relevance scoring — to compress tool output arrays while keeping the items the LLM actually needs. It never generates text; the output contains only items from the original array.
**CCR (Compress-Cache-Retrieve)** makes compression reversible. When SmartCrusher compresses a 1,000-item array down to 20 items, the original 1,000 items are stored locally (SHA-256 verified). The LLM receives a retrieval marker. If it needs more data, it calls `copium_retrieve(hash, query)` and gets the relevant subset. Worst case: the LLM retrieves what it needs. Best case: it never needs to.
**Session Dedup** tracks content hashes (exact SHA-256 + MinHash for near-duplicates) across the entire conversation. If a file read from turn 3 shows up again in turn 15, only a reference marker goes to the LLM. The proxy overhead for this lookup is sub-millisecond.
**TOON Encoder** converts JSON arrays into pipe-delimited tables — the same semantic content, dramatically fewer tokens. `[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]` becomes `name | age\nalice | 30\nbob | 25`. The LLM reads both perfectly; the table uses 60–80% fewer tokens.
**Cache Aligner** stabilizes prompt prefixes so provider KV caches actually hit. Anthropic and OpenAI offer prefix caching (massive cost reduction), but a single changed character busts the cache. Cache Aligner moves dynamic content (dates, session IDs, request hashes) to the end of system messages so the stable prefix stays stable.
---
## Integrations
| Your setup | How to use |
|---|---|
| Any Python app | `compress(messages)` |
| Anthropic / OpenAI SDK | `CopiumClient(original_client=...)` |
| Vercel AI SDK | Copium middleware |
| LiteLLM | Callback integration |
| LangChain | `CopiumChatModel(your_llm)` |
| Agno | `CopiumAgnoModel(your_model)` |
| MCP clients | `pip install "copium-ai[mcp]"` |
| Any HTTP client | `copium run` (proxy mode) |
| Claude Code | `copium wrap claude` |
| Codex | `copium wrap codex` |
| Cursor | Set API base URL in settings |
| OpenCode | `export OPENAI_BASE_URL=http://localhost:8082/v1` |
| Aider | `copium wrap aider` |
| GitHub Copilot | `copium wrap copilot` |
| Mistral Vibe | `copium wrap vibe` |
| AWS Bedrock | `http://localhost:8082/bedrock` |
| Google Vertex AI | `http://localhost:8082/vertex` |
| Ollama | `copium run --backend ollama` |
---
## Documentation
| Start here | Go deeper |
|---|---|
| [Quickstart](https://copium-docs.vercel.app/docs/quickstart) | [Architecture](https://copium-docs.vercel.app/docs/architecture) |
| [Proxy](https://copium-docs.vercel.app/docs/proxy) | [How compression works](https://copium-docs.vercel.app/docs/compression) |
| [MCP tools](https://copium-docs.vercel.app/docs/mcp) | [Benchmarks](https://copium-docs.vercel.app/docs/benchmarks) |
| [Configuration](https://copium-docs.vercel.app/docs/configuration) | [Limitations](https://copium-docs.vercel.app/docs/limitations) |
| [Migration guide](https://copium-docs.vercel.app/docs/migration) | [Presets](https://copium-docs.vercel.app/docs/configuration#presets) |
---
## Contributing
```bash
git clone https://github.com/iKislay/copium.git && cd copium
uv sync && uv run pytest
```
See [CONTRIBUTING.md](CONTRIBUTING.md).
---
## License
Apache 2.0 — see [LICENSE](LICENSE).
---
## Acknowledgments
- **Pichay** (arXiv:2603.09023) — Virtual memory paging for LLM context
- The **r/LocalLLaMA** community — For identifying and stress-testing the precision cliff problem
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available