Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs: fix stale API references, retired class imports, and incorrect examples
Patrick Ancillotti0375f7f0aa59
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 944be6c22..bd05a8e04 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,30 @@ All notable changes to Headroom will be documented in this file.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).+## [Unreleased]++### Documentation++- Fix stale API references: removed `IntelligentContextConfig`, `ScoringWeights`, and `RollingWindowConfig` from all docs (these classes no longer exist); context management is now automatic.+- Fix `SmartCrusherConfig` field names: removed fabricated fields (`keep_first`, `keep_last`, `relevance_threshold`, `anomaly_std_threshold`, `preserve_errors`, `relevance_tier`); replaced with real fields from source (`variance_threshold`, `uniqueness_threshold`, `similarity_threshold`, `preserve_change_points`, `first_fraction`, `last_fraction`, `dedup_identical_items`, `use_feedback_hints`).+- Fix `EmbeddingScorer` constructor: `model=` -> `model_name=`, default model updated to `BAAI/bge-small-en-v1.5`.+- Fix `memory.add()` examples: remove non-existent `category=` parameter.+- Fix `headroom learn` CLI reference: remove non-existent `--claude-dir PATH`; add actual `--agent`, `--model`, `--workers` flags.+- Fix import path: `from headroom.compression import compress` -> `from headroom import compress`; mark `UniversalCompressor` examples as Advanced/Internal API.+- Mark "Message-level CCR via IntelligentContext" section as retired in `ccr.mdx`.+- Fix CHANGELOG footer links: `headroom-sdk/headroom` -> `chopratejas/headroom`.+- Note `pip install "headroom-ai[llmlingua]"` extra was removed in 0.9.x.+- Fix proxy command: `python -m headroom.proxy.server --port 8787` -> `headroom proxy --port 8787`.+- Add "opt-in; disabled by default" caveat to source code 40-70% savings claims.+- Add missing extras to installation docs: `memory`, `relevance`, `image`, `reports`, `otel`, `voice`.+- Update `README.md` extras mention to include `[code]`, `[memory]`, `[relevance]`, `[image]`.+- Fix telemetry description in `llms.txt`: "No telemetry by default" -> "Anonymous telemetry enabled by default; set `HEADROOM_TELEMETRY=off` to disable".+- Update `EmbedderBackend.LOCAL` recommendation to `EmbedderBackend.ONNX` with note that LOCAL requires PyTorch (~2 GB).+- Fix CCR acronym: "Cross-Conversation Retrieval" -> "Compress-Cache-Retrieve" in `api-reference.mdx` (including `ccrHashes` field description).+- Remove `IntelligentContext` from pipeline diagram in `how-compression-works.mdx`; update to 2-stage pipeline: `CacheAligner` -> `ContentRouter`.+- Remove retired `rolling_window_config` field from `HeadroomClient` Python constructor table in `api-reference.mdx`; add note that `rolling_window` was removed in 0.9.x.+- docs: fix stale API references, retired class imports, wrong field names, and incomplete extras table+## [0.22.4](https://github.com/chopratejas/headroom/compare/v0.22.3...v0.22.4) (2026-05-26)@@ -280,7 +304,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Device selection: `--llmlingua-device` (auto/cuda/cpu/mps)- Custom compression rate: `--llmlingua-rate`- Helpful startup hints when llmlingua is available but not enabled- - Install with: `pip install headroom-ai[llmlingua]`+ - ~~Install with: `pip install headroom-ai[llmlingua]`~~ (the `[llmlingua]` extra was removed in 0.9.x)- **Code-Aware Compression** (AST-based, syntax-preserving)- `CodeAwareCompressor` transform using tree-sitter for AST parsing- Supports Python, JavaScript, TypeScript, Go, Rust, Java, C, C++@@ -418,12 +442,12 @@ New in 0.2.0 - run Headroom as a proxy server:```bash# Start the proxy-python -m headroom.proxy.server --port 8787+headroom proxy --port 8787# Use with Claude CodeANTHROPIC_BASE_URL=http://localhost:8787 claude```-[Unreleased]: https://github.com/headroom-sdk/headroom/compare/v0.2.0...HEAD-[0.2.0]: https://github.com/headroom-sdk/headroom/compare/v0.1.0...v0.2.0-[0.1.0]: https://github.com/headroom-sdk/headroom/releases/tag/v0.1.0+[Unreleased]: https://github.com/chopratejas/headroom/compare/v0.2.0...HEAD+[0.2.0]: https://github.com/chopratejas/headroom/compare/v0.1.0...v0.2.0+[0.1.0]: https://github.com/chopratejas/headroom/releases/tag/v0.1.0diff --git a/README.md b/README.mdindex 0094f4529..a2583ad44 100644--- a/README.md+++ b/README.md@@ -97,7 +97,7 @@ headroom proxy --port 8787 # drop-in proxy, zero code changesheadroom stats```-Granular extras: `[proxy]`, `[mcp]`, `[ml]`, `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.+Granular extras: `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.## Proof@@ -208,7 +208,7 @@ npm install headroom-ai # TypeScript / Nodedocker pull ghcr.io/chopratejas/headroom:latest```-Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-base), `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.+Granular extras: `[proxy]`, `[mcp]`, `[ml]` (Kompress-base), `[code]`, `[memory]`, `[relevance]`, `[image]`, `[agno]`, `[langchain]`, `[evals]`. Requires **Python 3.10+**.Using `pipx`? Choose a supported interpreter explicitly:diff --git a/docs/content/docs/api-reference.mdx b/docs/content/docs/api-reference.mdxindex 342460064..4f5835e96 100644--- a/docs/content/docs/api-reference.mdx+++ b/docs/content/docs/api-reference.mdx@@ -46,7 +46,6 @@ const client = new HeadroomClient({store_url: { type: 'str | None', description: 'Storage URL for metrics database', default: 'None' },smart_crusher_config: { type: 'SmartCrusherConfig', description: 'Compression settings', default: 'Default config' },cache_aligner_config: { type: 'CacheAlignerConfig', description: 'Cache alignment settings', default: 'Default config' },- rolling_window_config: { type: 'RollingWindowConfig', description: 'Context window settings', default: 'Default config' },enable_cache_optimizer: { type: 'bool', description: 'Enable provider-specific cache optimization', default: 'True' },enable_semantic_cache: { type: 'bool', description: 'Enable query-level semantic caching', default: 'False' },model_context_limits: { type: 'dict[str, int]', description: 'Override context limits per model', default: '{}' },@@ -235,13 +234,16 @@ if not result["valid"]:<TypeTable type={{min_tokens_to_crush: { type: 'int', description: 'Minimum tokens before applying compression', default: '200' },- max_items_after_crush: { type: 'int', description: 'Maximum items to keep after compression', default: '50' },- keep_first: { type: 'int', description: 'Always keep first N items', default: '3' },- keep_last: { type: 'int', description: 'Always keep last N items', default: '2' },- relevance_threshold: { type: 'float', description: 'Minimum relevance score to keep', default: '0.3' },- anomaly_std_threshold: { type: 'float', description: 'Std devs for anomaly detection', default: '2.0' },- preserve_errors: { type: 'bool', description: 'Always keep error items', default: 'True' },- relevance_tier: { type: '"bm25" | "embedding" | "hybrid"', description: 'Relevance scoring method', default: '"bm25"' },+ min_items_to_analyze: { type: 'int', description: 'Minimum items before analyzing for compression', default: '5' },+ max_items_after_crush: { type: 'int', description: 'Maximum items to keep after compression', default: '15' },+ variance_threshold: { type: 'float', description: 'Variance threshold for analysis', default: '2.0' },+ uniqueness_threshold: { type: 'float', description: 'Uniqueness threshold for deduplication', default: '0.1' },+ similarity_threshold: { type: 'float', description: 'Similarity threshold for grouping', default: '0.8' },+ preserve_change_points: { type: 'bool', description: 'Preserve significant change points in data', default: 'True' },+ use_feedback_hints: { type: 'bool', description: 'Use TOIN feedback hints for scoring', default: 'True' },+ dedup_identical_items: { type: 'bool', description: 'Deduplicate identical items', default: 'True' },+ first_fraction: { type: 'float', description: 'Fraction of items to keep from the start', default: '0.3' },+ last_fraction: { type: 'float', description: 'Fraction of items to keep from the end', default: '0.15' },}} />```python@@ -249,12 +251,9 @@ from headroom import SmartCrusherConfigconfig = SmartCrusherConfig(min_tokens_to_crush=200,- max_items_after_crush=50,- keep_first=3,- keep_last=2,- relevance_threshold=0.3,- anomaly_std_threshold=2.0,- preserve_errors=True,+ max_items_after_crush=15,+ variance_threshold=2.0,+ preserve_change_points=True,)```@@ -318,109 +317,7 @@ config = CacheAlignerConfig(</Tab><Tab value="Python">-<TypeTable type={{- enabled: { type: 'bool', description: 'Enable/disable rolling window', default: 'True' },- max_tokens: { type: 'int', description: 'Maximum token budget', default: '100000' },- preserve_system: { type: 'bool', description: 'Never drop system messages', default: 'True' },- preserve_recent_turns: { type: 'int', description: 'Always keep last N turns', default: '5' },- drop_oldest_first: { type: 'bool', description: 'Drop oldest messages first', default: 'True' },-}} />--```python-from headroom import RollingWindowConfig--config = RollingWindowConfig(- max_tokens=100000,- preserve_system=True,- preserve_recent_turns=5,- drop_oldest_first=True,-)-```--</Tab>-</Tabs>--### IntelligentContextConfig--<Tabs groupId="lang" items={['TypeScript', 'Python']}>-<Tab value="TypeScript">--<TypeTable type={{- enabled: { type: 'boolean', description: 'Enable intelligent context management' },- keepSystem: { type: 'boolean', description: 'Never drop system messages' },- keepLastTurns: { type: 'number', description: 'Protect last N user turns' },- outputBufferTokens: { type: 'number', description: 'Reserve tokens for model output' },- useImportanceScoring: { type: 'boolean', description: 'Use semantic scoring vs position-only' },- scoringWeights: { type: 'ScoringWeights', description: 'Custom importance weights' },- recencyDecayRate: { type: 'number', description: 'Exponential decay lambda' },- toinIntegration: { type: 'boolean', description: 'Use TOIN patterns if available' },- toinConfidenceThreshold: { type: 'number', description: 'TOIN confidence threshold' },- compressThreshold: { type: 'number', description: 'Try compression first if less than this fraction over budget' },- summarizationEnabled: { type: 'boolean', description: 'Enable summarization of dropped messages' },- summarizationModel: { type: 'string | null', description: 'Model to use for summarization' },- summaryMaxTokens: { type: 'number', description: 'Maximum tokens for summary' },- summarizeThreshold: { type: 'number', description: 'Threshold for triggering summarization' },-}} />--</Tab>-<Tab value="Python">--<TypeTable type={{- enabled: { type: 'bool', description: 'Enable intelligent context management', default: 'False' },- keep_system: { type: 'bool', description: 'Never drop system messages', default: 'True' },- keep_last_turns: { type: 'int', description: 'Protect last N user turns', default: '2' },- output_buffer_tokens: { type: 'int', description: 'Reserve tokens for model output', default: '4000' },- use_importance_scoring: { type: 'bool', description: 'Use semantic scoring vs position-only', default: 'True' },- scoring_weights: { type: 'ScoringWeights', description: 'Custom importance weights', default: 'Default weights' },- toin_integration: { type: 'bool', description: 'Use TOIN patterns if available', default: 'True' },- recency_decay_rate: { type: 'float', description: 'Exponential decay lambda', default: '0.1' },- compress_threshold: { type: 'float', description: 'Try compression first if less than this fraction over budget', default: '0.1' },-}} />--```python-from headroom.config import IntelligentContextConfig, ScoringWeights--config = IntelligentContextConfig(- enabled=True,- keep_system=True,- keep_last_turns=2,- output_buffer_tokens=4000,- use_importance_scoring=True,- scoring_weights=ScoringWeights(),- toin_integration=True,-)-```--</Tab>-</Tabs>--### ScoringWeights--<Tabs groupId="lang" items={['TypeScript', 'Python']}>-<Tab value="TypeScript">--<TypeTable type={{- recency: { type: 'number', description: 'Exponential decay from conversation end' },- semanticSimilarity: { type: 'number', description: 'Embedding cosine similarity to recent context' },- toinImportance: { type: 'number', description: 'TOIN retrieval rate' },- errorIndicator: { type: 'number', description: 'TOIN field semantics error detection' },- forwardReference: { type: 'number', description: 'Messages referenced by later messages' },- tokenDensity: { type: 'number', description: 'Unique tokens / total tokens' },-}} />--</Tab>-<Tab value="Python">--<TypeTable type={{- recency: { type: 'float', description: 'Exponential decay from conversation end', default: '0.20' },- semantic_similarity: { type: 'float', description: 'Embedding cosine similarity to recent context', default: '0.20' },- toin_importance: { type: 'float', description: 'TOIN retrieval rate', default: '0.25' },- error_indicator: { type: 'float', description: 'TOIN field semantics error detection', default: '0.15' },- forward_reference: { type: 'float', description: 'Messages referenced by later messages', default: '0.15' },- token_density: { type: 'float', description: 'Unique tokens / total tokens', default: '0.05' },-}} />--Weights are automatically normalized to sum to 1.0.+Context management is now automatic. Headroom handles rolling window behavior internally based on the model's context limit and the `headroom_keep_turns` / `headroom_output_buffer_tokens` per-request overrides. The `RollingWindowConfig`, `IntelligentContextConfig`, and `ScoringWeights` classes no longer exist as public API.</Tab></Tabs>@@ -439,10 +336,9 @@ Weights are automatically normalized to sum to 1.0.cacheAligner: { type: 'CacheAlignerConfig', description: 'Cache aligner configuration' },rollingWindow: { type: 'RollingWindowConfig', description: 'Rolling window configuration' },cacheOptimizer: { type: 'CacheOptimizerConfig', description: 'Cache optimizer configuration' },- ccr: { type: 'CCRConfig', description: 'CCR (Cross-Conversation Retrieval) configuration' },+ ccr: { type: 'CCRConfig', description: 'CCR (Compress-Cache-Retrieve) configuration' },prefixFreeze: { type: 'PrefixFreezeConfig', description: 'Prefix freeze configuration' },contentRouterEnabled: { type: 'boolean', description: 'Enable content-type routing' },- intelligentContext: { type: 'IntelligentContextConfig', description: 'Intelligent context management configuration' },generateDiffArtifact: { type: 'boolean', description: 'Generate diff artifacts for debugging' },}} />@@ -457,7 +353,7 @@ from headroom import HeadroomConfigconfig = HeadroomConfig()config.smart_crusher.min_tokens_to_crush = 100config.cache_aligner.enabled = True-config.rolling_window.preserve_recent_turns = 3+# Note: rolling_window was removed in 0.9.x — use headroom_keep_turns per-request instead```</Tab>@@ -503,7 +399,7 @@ config.rolling_window.preserve_recent_turns = 3tokensSaved: { type: 'number', description: 'Tokens removed by compression' },compressionRatio: { type: 'number', description: 'Ratio of tokens after to tokens before' },transformsApplied: { type: 'string[]', description: 'Names of transforms that were applied' },- ccrHashes: { type: 'string[]', description: 'CCR hashes for cross-conversation retrieval' },+ ccrHashes: { type: 'string[]', description: 'CCR hashes for Compress-Cache-Retrieve' },compressed: { type: 'boolean', description: 'Whether compression was actually applied' },}} />@@ -623,7 +519,7 @@ Semantic similarity scoring (requires `headroom-ai[relevance]`):from headroom import EmbeddingScorer, embedding_availableif embedding_available():- scorer = EmbeddingScorer(model="all-MiniLM-L6-v2")+ scorer = EmbeddingScorer(model_name="BAAI/bge-small-en-v1.5")scores = scorer.score_items(items, query)```@@ -669,22 +565,6 @@ window = RollingWindow(config)result = window.apply(messages, max_tokens=100000)```-### IntelligentContextManager--```python-from headroom.transforms import IntelligentContextManager-from headroom.config import IntelligentContextConfig--config = IntelligentContextConfig(- keep_system=True,- keep_last_turns=2,- use_importance_scoring=True,-)--manager = IntelligentContextManager(config, toin=toin)-result = manager.apply(messages, tokenizer, model_limit=128000)-```-### TransformPipeline```pythondiff --git a/docs/content/docs/ccr.mdx b/docs/content/docs/ccr.mdxindex 061e41a9e..3aed20814 100644--- a/docs/content/docs/ccr.mdx+++ b/docs/content/docs/ccr.mdx@@ -164,24 +164,7 @@ response = client.chat.completions.create(## Message-level CCR-CCR is not limited to tool outputs. When IntelligentContext drops low-importance messages to fit the context budget, those messages are also stored in CCR:--```-100-message conversation (50K tokens)- -> IntelligentContext scores messages by importance- -> Drops 60 low-scoring messages- -> Dropped messages cached with hash=def456- -> Marker inserted: "60 messages dropped, retrieve: def456"-```--The marker includes the CCR reference so the LLM can recover earlier context:--```-[Earlier context compressed: 60 message(s) dropped by importance scoring.-Full content available via ccr_retrieve tool with reference 'def456'.]-```--When users retrieve dropped messages via CCR, TOIN learns those message patterns are important and scores them higher in future sessions -- improving drop decisions across all users.+> **Retired:** The "Message-level CCR via IntelligentContext" feature (where `IntelligentContext` would store dropped messages in CCR with a retrieval marker) was part of the `IntelligentContextConfig` API that was removed in 0.9.x. Context management is now handled automatically by the pipeline without a separate configurable IntelligentContext stage. Tool-output CCR via SmartCrusher and ContentRouter remains fully supported.## CCR-enabled components@@ -189,7 +172,6 @@ When users retrieve dropped messages via CCR, TOIN learns those message patterns|---|---|---|| **SmartCrusher** | JSON arrays (tool outputs) | Stores original array, marker includes hash || **ContentRouter** | Code, logs, search results, text | Stores original content by strategy |-| **IntelligentContext** | Messages (conversation turns) | Stores dropped messages, marker includes hash |## Why CCR mattersdiff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex 8027c283c..eabd41348 100644--- a/docs/content/docs/configuration.mdx+++ b/docs/content/docs/configuration.mdx@@ -132,11 +132,12 @@ config = SmartCrusherConfig(# Minimum tokens before applying compressionmin_tokens_to_crush=200,- # Relevance scoring tier: "bm25" (fast) or "embedding" (accurate)- relevance_tier="bm25",+ # Fraction of items always kept from the start/end+ first_fraction=0.3,+ last_fraction=0.15,- # Always keep items with these field values- preserve_fields=["error", "warning", "failure"],+ # Variance threshold for statistical analysis+ variance_threshold=2.0,)```@@ -159,73 +160,22 @@ config = CacheAlignerConfig()```-## RollingWindow Configuration+## Context Window Management-Control context window management when messages exceed model limits:+Context management is now automatic. Use per-request overrides to control behavior:```python-from headroom.transforms import RollingWindowConfig--config = RollingWindowConfig(- # Minimum turns to always keep- min_keep_turns=3,-- # Reserve tokens for output- output_buffer_tokens=4000,-- # Drop oldest tool outputs first- prefer_drop_tool_outputs=True,-)-```--## IntelligentContext Configuration--Semantic-aware context management with importance scoring:--```python-from headroom.config import IntelligentContextConfig, ScoringWeights--# Customize scoring weights (must sum to 1.0, or will be normalized)-weights = ScoringWeights(- recency=0.20, # Newer messages score higher- semantic_similarity=0.20, # Similarity to recent context- toin_importance=0.25, # TOIN-learned retrieval patterns- error_indicator=0.15, # TOIN-learned error field types- forward_reference=0.15, # Messages referenced by later messages- token_density=0.05, # Information density-)--config = IntelligentContextConfig(- enabled=True,- keep_system=True, # Never drop system messages- keep_last_turns=2, # Protect last N user turns- output_buffer_tokens=4000, # Reserve for model output- use_importance_scoring=True,- scoring_weights=weights,- toin_integration=True, # Use TOIN patterns if available- recency_decay_rate=0.1, # Exponential decay lambda- compress_threshold=0.1, # Try compression first if <10% over budget+response = client.chat.completions.create(+ model="gpt-4o",+ messages=messages,+ # Reserve tokens for model output+ headroom_output_buffer_tokens=4000,+ # Keep last N turns uncompressed+ headroom_keep_turns=3,)```-### Scoring Weights--<TypeTable type={{- recency: { type: 'float', description: 'Exponential decay from conversation end', default: '0.20' },- semantic_similarity: { type: 'float', description: 'Embedding cosine similarity to recent context', default: '0.20' },- toin_importance: { type: 'float', description: 'TOIN retrieval_rate (high retrieval = important)', default: '0.25' },- error_indicator: { type: 'float', description: 'TOIN field_semantics error detection', default: '0.15' },- forward_reference: { type: 'float', description: 'Count of later messages referencing this one', default: '0.15' },- token_density: { type: 'float', description: 'Unique tokens / total tokens', default: '0.05' },-}} />--Weights are automatically normalized to sum to 1.0:--```python-weights = ScoringWeights(recency=1.0, toin_importance=1.0)-normalized = weights.normalized()-# recency=0.5, toin_importance=0.5, others=0.0-```+The `RollingWindowConfig`, `IntelligentContextConfig`, and `ScoringWeights` classes were removed in 0.9.x. Context management now happens automatically inside the pipeline.## Proxy Configurationdiff --git a/docs/content/docs/context-management.mdx b/docs/content/docs/context-management.mdxindex cd71ba0ec..d31c2f501 100644--- a/docs/content/docs/context-management.mdx+++ b/docs/content/docs/context-management.mdx@@ -3,11 +3,11 @@ title: Context Managementdescription: Intelligent importance-based context management that scores messages by learned patterns, with rolling window fallback and output buffer reservation.----When conversations grow beyond a model's context window, Headroom decides which messages to keep and which to drop. Instead of naively removing the oldest messages, **IntelligentContext** scores every message by learned importance and drops the least valuable ones first.+When conversations grow beyond a model's context window, Headroom decides which messages to keep and which to drop. Instead of naively removing the oldest messages, the pipeline scores every message by learned importance and drops the least valuable ones first.-## IntelligentContext+## How It Works-IntelligentContext is a message-level compressor. It analyzes your conversation, assigns an importance score to each message, and removes low-scoring messages until the conversation fits within the token budget.+The context management stage analyzes your conversation, assigns an importance score to each message, and removes low-scoring messages until the conversation fits within the token budget.Dropped messages are not lost -- they are stored in [CCR](/docs/ccr) for on-demand retrieval by the LLM.@@ -74,57 +74,16 @@ The last N user/assistant turns are always preserved, ensuring the model has imm## Configuration+Context management is now automatic. Use per-request overrides to control behavior:+<Tabs groupId="lang" items={['TypeScript', 'Python']}><Tab value="TypeScript">```ts twoslashimport { compress } from "headroom-ai";-import type {- IntelligentContextConfig,- ScoringWeights,- RollingWindowConfig,- HeadroomConfig,-} from "headroom-ai";--// Scoring weights (normalized automatically)-const scoringWeights: ScoringWeights = {- recency: 0.20,- semanticSimilarity: 0.20,- toinImportance: 0.25,- errorIndicator: 0.15,- forwardReference: 0.15,- tokenDensity: 0.05,-};--// IntelligentContext configuration-const intelligentContext: IntelligentContextConfig = {- enabled: true,- keepSystem: true,- keepLastTurns: 2,- outputBufferTokens: 4000,- useImportanceScoring: true,- scoringWeights,- toinIntegration: true,- recencyDecayRate: 0.1,- compressThreshold: 0.1,-};--// Rolling window fallback-const rollingWindow: RollingWindowConfig = {- enabled: true,- keepSystem: true,- keepLastTurns: 3,- outputBufferTokens: 4000,-};--// Full configuration-const config: HeadroomConfig = {- intelligentContext,- rollingWindow,-};const result = await compress(messages, {model: "gpt-4o",- config,+ tokenBudget: 32000,});console.log(`Compressed: ${result.tokensBefore} -> ${result.tokensAfter}`);@@ -133,31 +92,8 @@ console.log(`Compressed: ${result.tokensBefore} -> ${result.tokensAfter}`);<Tab value="Python">```pythonfrom headroom import HeadroomClient, OpenAIProvider-from headroom.config import IntelligentContextConfig, ScoringWeightsfrom openai import OpenAI-# Customize scoring weights-weights = ScoringWeights(- recency=0.20,- semantic_similarity=0.20,- toin_importance=0.25,- error_indicator=0.15,- forward_reference=0.15,- token_density=0.05,-)--context_config = IntelligentContextConfig(- enabled=True,- keep_system=True, # Never drop system messages- keep_last_turns=2, # Protect last 2 user turns- output_buffer_tokens=4000, # Reserve for model output- use_importance_scoring=True,- scoring_weights=weights,- toin_integration=True, # Use TOIN patterns- recency_decay_rate=0.1, # Exponential decay lambda- compress_threshold=0.1, # Try compression first if <10% over budget-)-client = HeadroomClient(original_client=OpenAI(),provider=OpenAIProvider(),@@ -175,6 +111,8 @@ response = client.chat.completions.create(</Tab></Tabs>+> **Note:** The `IntelligentContextConfig`, `ScoringWeights`, and `RollingWindowConfig` classes were removed in 0.9.x. Context management is now handled automatically inside the pipeline.+## How scoring improves over timeIntelligentContext integrates with TOIN (Tool-Output Intelligence Network) to learn from real usage:diff --git a/docs/content/docs/failure-learning.mdx b/docs/content/docs/failure-learning.mdxindex 7b0777083..072dd8929 100644--- a/docs/content/docs/failure-learning.mdx+++ b/docs/content/docs/failure-learning.mdx@@ -122,7 +122,9 @@ Options:--project PATH Project directory to analyze (default: current directory)--all Analyze all discovered projects--apply Write recommendations (default: dry-run)- --claude-dir PATH Path to .claude directory (default: ~/.claude)+ --agent TEXT Agent to analyze (e.g. claude, codex, gemini)+ --model TEXT LLM model to use for analysis+ --workers INT Number of parallel workers```## Real-World Resultsdiff --git a/docs/content/docs/how-compression-works.mdx b/docs/content/docs/how-compression-works.mdxindex e36143ee1..92e0ec557 100644--- a/docs/content/docs/how-compression-works.mdx+++ b/docs/content/docs/how-compression-works.mdx@@ -10,18 +10,17 @@ Headroom automatically detects what kind of content you're sending and routes itEvery request flows through three stages:```-┌──────────────┐ ┌────────────────┐ ┌─────────────────────┐-│ CacheAligner │────>│ ContentRouter │────>│ IntelligentContext │-│ │ │ │ │ │-│ Stabilize │ │ Detect type & │ │ Score messages & │-│ prefix for │ │ route to best │ │ fit within token │-│ cache hits │ │ compressor │ │ budget │-└──────────────┘ └────────────────┘ └─────────────────────┘+┌──────────────┐ ┌────────────────┐+│ CacheAligner │────>│ ContentRouter │+│ │ │ │+│ Stabilize │ │ Detect type & │+│ prefix for │ │ route to best │+│ cache hits │ │ compressor │+└──────────────┘ └────────────────┘```1. **CacheAligner** extracts dynamic content (dates, user context) from your system prompt so the static prefix stays cacheable across requests.2. **ContentRouter** inspects each tool output and routes it to the optimal compressor -- SmartCrusher for JSON arrays, CodeAwareCompressor for source code, LogCompressor for build output, and so on.-3. **IntelligentContext** scores every message by importance (recency, semantic relevance, error indicators) and drops the lowest-value messages to fit within the model's context window.## Content Type Detection@@ -30,7 +29,7 @@ The router auto-detects content type by analyzing structure and patterns. No man| Content Type | Detection Signal | Compressor | Typical Savings ||---|---|---|---|| JSON arrays | Valid JSON with array elements | SmartCrusher | 70-90% |-| Source code | Syntax patterns, indentation, keywords | CodeAwareCompressor | 40-70% |+| Source code | Syntax patterns, indentation, keywords | CodeAwareCompressor | 40-70% (opt-in; disabled by default) || Search results | `file:line:content` format | SearchCompressor | 80-95% || Build/test logs | Timestamps, log levels, pytest/npm markers | LogCompressor | 85-95% || Diffs | Unified diff format | DiffCompressor | 60-80% |@@ -57,7 +56,7 @@ console.log(`Compression ratio: ${result.compressionRatio}`);</Tab><Tab value="Python">```python-from headroom.compression import compress+from headroom import compressresult = compress(content)print(result.compressed)@@ -85,6 +84,7 @@ console.log(`Transforms: ${result.transformsApplied.join(", ")}`);</Tab><Tab value="Python">```python+# Advanced / Internal API -- prefer `from headroom import compress` for typical usefrom headroom.compression import UniversalCompressor, UniversalCompressorConfigconfig = UniversalCompressorConfig(@@ -130,6 +130,7 @@ Headroom doesn't blindly truncate. It identifies what matters in each content tyFor multiple contents, batch compression is more efficient:```python+# Advanced / Internal API -- prefer `from headroom import compress` for typical usefrom headroom.compression import UniversalCompressorcompressor = UniversalCompressor()diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdxindex cb8633ba2..6afd7e368 100644--- a/docs/content/docs/index.mdx+++ b/docs/content/docs/index.mdx@@ -45,7 +45,7 @@ print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")| Content type | What happens | Typical savings ||---|---|---|| JSON arrays (tool outputs) | Statistical analysis keeps errors, anomalies, boundaries | 70--90% |-| Source code | AST-aware compression preserves signatures, collapses bodies | 40--70% |+| Source code | AST-aware compression preserves signatures, collapses bodies | 40--70% (opt-in; disabled by default) || Build/test logs | Keeps failures and errors, drops passing noise | 80--95% || Search results | Ranks by relevance, keeps top matches | 60--80% || Plain text | ModernBERT token classification removes redundancy | 30--50% |diff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdxindex 08b82e260..acd9ce878 100644--- a/docs/content/docs/installation.mdx+++ b/docs/content/docs/installation.mdx@@ -30,6 +30,12 @@ pip install "headroom-ai[all]"| `proxy` | Proxy server, MCP tools, HTTP API | `pip install "headroom-ai[proxy]"` || `ml` | Kompress (ModernBERT text compression, requires PyTorch) | `pip install "headroom-ai[ml]"` || `code` | CodeCompressor (tree-sitter AST parsing) | `pip install "headroom-ai[code]"` |+| `memory` | Persistent memory (hnswlib, sqlite-vec, sentence-transformers) | `pip install "headroom-ai[memory]"` |+| `relevance` | fastembed-based relevance scoring (BAAI/bge-small-en-v1.5, ONNX) | `pip install "headroom-ai[relevance]"` |+| `image` | Image compression (Pillow, ONNX runtime, OCR) | `pip install "headroom-ai[image]"` |+| `reports` | HTML/Markdown report generation (Jinja2) | `pip install "headroom-ai[reports]"` |+| `otel` | OpenTelemetry exporter (OTLP) | `pip install "headroom-ai[otel]"` |+| `voice` | Voice/audio support | `pip install "headroom-ai[voice]"` || `mcp` | MCP server tools (`headroom_compress`, `headroom_retrieve`, `headroom_stats`) | `pip install "headroom-ai[mcp]"` || `langchain` | LangChain `HeadroomChatModel` wrapper | `pip install "headroom-ai[langchain]"` || `agno` | Agno `HeadroomAgnoModel` wrapper | `pip install "headroom-ai[agno]"` |diff --git a/docs/content/docs/memory.mdx b/docs/content/docs/memory.mdxindex 352d59b5b..cd4468cc8 100644--- a/docs/content/docs/memory.mdx+++ b/docs/content/docs/memory.mdx@@ -112,7 +112,6 @@ for memory in results:# Add a memory manuallyclient.memory.add("User is a senior engineer",- category="fact",importance=0.9,)@@ -174,10 +173,11 @@ This gives you an audit trail, the ability to debug why the LLM made certain dec```pythonfrom headroom.memory import MemoryConfig, EmbedderBackend-# Local embeddings (recommended -- fast, free, private)+# ONNX embeddings (recommended -- fast, free, private; ~30 MB int8-quantized)+# Note: EmbedderBackend.LOCAL requires PyTorch (~2 GB); use ONNX instead.config = MemoryConfig(- embedder_backend=EmbedderBackend.LOCAL,- embedder_model="all-MiniLM-L6-v2",+ embedder_backend=EmbedderBackend.ONNX,+ embedder_model="BAAI/bge-small-en-v1.5",)# OpenAI embeddings (higher quality, costs money)diff --git a/docs/content/docs/smart-crusher.mdx b/docs/content/docs/smart-crusher.mdxindex b318fa826..1c787f639 100644--- a/docs/content/docs/smart-crusher.mdx+++ b/docs/content/docs/smart-crusher.mdx@@ -89,12 +89,11 @@ from headroom import SmartCrusher, SmartCrusherConfigconfig = SmartCrusherConfig(min_tokens_to_crush=200, # Only compress if > 200 tokens- max_items_after_crush=50, # Keep at most 50 items- keep_first=3, # Always keep first 3 items- keep_last=2, # Always keep last 2 items- relevance_threshold=0.3, # Keep items with relevance > 0.3- anomaly_std_threshold=2.0, # Keep items > 2 std dev from mean- preserve_errors=True, # Always keep error items+ max_items_after_crush=15, # Keep at most 15 items+ first_fraction=0.3, # Keep first 30% of items+ last_fraction=0.15, # Keep last 15% of items+ variance_threshold=2.0, # Statistical variance threshold+ preserve_change_points=True, # Keep significant transitions)crusher = SmartCrusher(config)@@ -108,12 +107,16 @@ compressed = crusher.crush(tool_output, query="find payment failures")| Option | Default | Description ||---|---|---|| `min_tokens_to_crush` | `200` | Only compress arrays with more than this many tokens |-| `max_items_after_crush` | `50` | Maximum items to keep after compression |-| `keep_first` | `3` | Always keep the first N items |-| `keep_last` | `2` | Always keep the last N items |-| `relevance_threshold` | `0.3` | Minimum relevance score to keep an item |-| `anomaly_std_threshold` | `2.0` | Standard deviation threshold for anomaly detection |-| `preserve_errors` | `True` | Always keep items containing error states |+| `min_items_to_analyze` | `5` | Minimum items before analyzing for compression |+| `max_items_after_crush` | `15` | Maximum items to keep after compression |+| `variance_threshold` | `2.0` | Statistical variance threshold for analysis |+| `uniqueness_threshold` | `0.1` | Uniqueness threshold for deduplication |+| `similarity_threshold` | `0.8` | Similarity threshold for grouping |+| `preserve_change_points` | `True` | Preserve significant transitions in data |+| `first_fraction` | `0.3` | Fraction of items always kept from the start |+| `last_fraction` | `0.15` | Fraction of items always kept from the end |+| `dedup_identical_items` | `True` | Deduplicate identical items |+| `use_feedback_hints` | `True` | Use TOIN feedback hints for scoring |## Example: Before and Afterdiff --git a/llms.txt b/llms.txtindex cd006b021..c4deb7936 100644--- a/llms.txt+++ b/llms.txt@@ -64,4 +64,4 @@ The canonical, always-current documentation index lives at the docs site below.## Licensing-Apache 2.0. Use commercially, modify, redistribute. Data stays on the user's machine when running the library, proxy, or MCP server locally. No telemetry by default.+Apache 2.0. Use commercially, modify, redistribute. Data stays on the user's machine when running the library, proxy, or MCP server locally. Anonymous telemetry enabled by default; set `HEADROOM_TELEMETRY=off` to disable.diff --git a/tests/test_provider_proxy_routes.py b/tests/test_provider_proxy_routes.pyindex dc069b807..2f5d154c8 100644--- a/tests/test_provider_proxy_routes.py+++ b/tests/test_provider_proxy_routes.py@@ -422,6 +422,7 @@ def test_v1_models_falls_back_to_synthetic_list_under_chatgpt_auth(monkeypatch)synthesize an OpenAI-compatible response with the known-supportedCodex/ChatGPT model set instead, so Codex's model-picker refresh succeeds."""+class FakeAsyncClient:async def get(self, url, **kwargs): # type: ignore[no-untyped-def]return httpx.Response(403, json={"error": "forbidden"})@@ -458,6 +459,7 @@ def test_v1_models_get_single_dynamic_under_chatgpt_auth() -> None:"""The single-model variant (`/v1/models/{id}`) is also called byCodex for some flows. It should use the Codex registry first sodynamically exposed model slugs validate consistently."""+class FakeAsyncClient:def __init__(self) -> None:self.calls = 0