- New `compress()` function: HTTP client calling POST /v1/compress on the proxy
- HeadroomClient: reusable client with retry, fallback, auth support
- Vercel AI SDK adapter: headroomMiddleware() for wrapLanguageModel()
- OpenAI SDK adapter: withHeadroom() Proxy wrapper
- Anthropic SDK adapter: withHeadroom() Proxy wrapper
- Format converters: Vercel AI SDK ↔ OpenAI message format round-trip
- POST /v1/compress proxy endpoint: compression without LLM call
- 90 TypeScript tests (84 unit + 6 integration) + 9 Python tests
- Zero runtime dependencies, all framework peers optional
- Updated README, proxy docs, integration guide, and 6 other doc pages
- New docs/typescript-sdk.md with full SDK documentation
- Removed docs/superpowers/ from tracking (.gitignore)
- Remove CrewAI and OpenAI Agents SDK claims (not implemented)
- Upgrade LangChain from "Experimental" to "Stable" (fully implemented)
- Fix latency FAQ: "1-5ms" → accurate "15-200ms" with cost-benefit context
- Create docs/strands.md (README linked to it but file didn't exist)
- Align docs/index.md with compress() function API (was showing stale class API)
- Add Strands, MCP, Integration Guide to mkdocs nav
- Note stale v0.3.7 benchmarks in LATENCY_BENCHMARKS.md
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Introduces dual-mode optimization (cost_savings vs token_headroom) to address
low compression rates in long Claude Code sessions caused by prefix freeze
consuming all messages.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- SharedContext: compressed inter-agent context sharing via put()/get()
over existing CCR compression pipeline. Zero new dependencies.
- README rewrite: lead with "any agent" positioning, not just coding
agents. Add headroom wrap, SharedContext, MCP tools to Quick Start.
Reorder integration table: universal first, coding shortcuts last.
Update compression pipeline references (LLMLingua → Kompress).
- Fix proxy cleanup in headroom wrap: don't kill shared proxy if other
clients are still using it (was orphaning terminals 2-N).
- New docs: docs/shared-context.md
The Docker example in proxy.md used the wrong package name and lacked
build-essential, causing install failures on slim images. hnswlib (a
core dependency) requires a C++ compiler to build from source.
- Fix proxy.md Docker example: headroom[proxy] -> headroom-ai[proxy],
add build-essential install/cleanup pattern
- Add troubleshooting entry for C++ compilation errors with solutions
for Linux and macOS environments
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
hnswlib requires C++ compilation and is only used by the memory
subsystem - it belongs in the [memory] extra, not core dependencies.
Installing headroom-ai on slim Docker images or any environment
without build tools would fail at the hnswlib build step.
Also fixes docs/quickstart.md and docs/troubleshooting.md which
referenced the wrong PyPI package name `headroom` (an unrelated
package) instead of `headroom-ai`.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Analyzes past conversation history to find tool call failure patterns,
correlates each failure with what eventually succeeded, and writes
specific project-level learnings to CLAUDE.md and MEMORY.md.
Key design:
- Success correlation: extracts the diff between failed and successful
inputs as the learning (not generic advice)
- Generic architecture: tool-agnostic ToolCall model with pluggable
Scanner/Writer adapters (Claude Code first, extensible to Cursor/Codex)
- 5 analyzers: Environment, Structure, Commands, Retries, Cross-Session
- Dry-run by default, --apply to write, --all for all projects
Also fixes mypy errors in litellm_callback, asgi, langchain chat_model,
and anthropic provider (AsyncClient typing, ToolCall arg-type, int cast).
- Add `headroom mcp install` to configure ~/.claude/mcp.json
- Add `headroom mcp uninstall` to remove configuration
- Add `headroom mcp status` to check setup
- Add `headroom mcp serve` for MCP server (called by Claude Code)
- Add `mcp` optional dependency in pyproject.toml
- Add docs/mcp.md with full documentation
- Add 22 integration tests for MCP CLI
- Fix mypy errors in trained_router.py (None check, type annotation)
- Update README with subscription user instructions
This enables CCR (Compress-Cache-Retrieve) for subscription users who
don't have API access. MCP is Claude's official extension mechanism
that works with subscriptions.
Usage:
pip install "headroom-ai[mcp]"
headroom mcp install
headroom proxy # Terminal 1
claude # Terminal 2
Rename client/response variables to be unique per provider branch
to avoid type inference conflicts. Use getattr for Anthropic content
block text access to handle union types.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add mkdocs.yml with Material theme (indigo, professional)
- Add docs/index.md landing page with quick install
- Add GitHub Actions workflow for auto-deployment
- Remove old docs/README.md (replaced by index.md)
Updates across multiple docs to reflect the new message-level compression
with TOIN + CCR integration:
- docs/ccr.md: Add CCR-enabled components table, message-level CCR section
- docs/ARCHITECTURE.md: Expand Transform 6 with TOIN + CCR integration details
- docs/configuration.md: Add CCR integration config and marker format
- docs/proxy.md: Add CCR integration note for context management
- docs/README.md: Update to reference IntelligentContextManager as default
Also adds examples/test_intelligent_context_toin_ccr.py for scale testing
the TOIN + CCR integration with real API calls.
IntelligentContext is a message-level compressor that drops low-value
messages. This change adds bidirectional TOIN integration:
- Dropped messages stored in CCR for potential retrieval
- Drops recorded to TOIN for cross-user learning
- Retrieval feedback improves future importance scoring
When messages are dropped and users retrieve them via CCR, TOIN learns
to score those patterns higher next time. This creates a feedback loop
that improves drop decisions across all users.
Changes:
- Add _create_message_signature() for TOIN pattern tracking
- Add _get_compression_store() for CCR integration
- Add _store_dropped_in_ccr() to store dropped messages
- Add _record_drops_to_toin() to record drops for learning
- Update marker to include CCR reference when available
- Update docs with TOIN + CCR integration section
- Update tests to accept both marker formats
Previously, only SmartCrusher (JSON arrays) recorded compressions to TOIN.
Now all compression strategies record to TOIN for cross-user learning:
- CODE_AWARE: AST-based code compression
- SEARCH: grep/ripgrep results
- LOG: build/test output
- LLMLINGUA: ML-based text compression
- TEXT: heuristic text compression
Changes:
- Add _create_content_signature() for non-JSON content types
- Add _record_to_toin() method to ContentRouter
- Update _apply_strategy_to_content() to record after compression
- Update docs/transforms.md with TOIN integration section
This enables the feedback loop where TOIN learns from retrieval patterns
across all content types, not just JSON arrays.
Co-Authored-By: Claude <noreply@anthropic.com>
ContentRouter now routes purely based on content analysis instead of
relying on hardcoded tool name mappings. This makes the router work
with any MCP tool regardless of naming convention.
Changes:
- Remove generate_source_hint() function and _strategy_from_hint() method
- Remove source_hint parameter from compress() method
- Remove _get_tool_source_hint() from IntelligentContextManager
- Update tests to remove source hint test cases
- Update docs to document content detection approach
- Update Quick Start to use with_memory() API (replaces with_fast_memory)
- Add hierarchical scoping section (USER → SESSION → AGENT → TURN)
- Add temporal versioning section with supersession examples
- Add comparison with state of the art (Letta, Mem0) with feature matrices
- Document Memory API for direct access (.memory.search, .add, .get_all)
- Add advanced HierarchicalMemory API usage examples
- Update configuration options for embedders and storage
- Add protocol-based architecture diagram
- Update memory categories (PREFERENCE, FACT, CONTEXT, ENTITY, DECISION, INSIGHT)
- Add troubleshooting and best practices sections
Replace static "first 3 + last 2" preservation with intelligent anchor
selection that adapts to data patterns and array size.
Key changes:
- Add AnchorSelector class for dynamic position-based preservation
- Add AnchorConfig for configurable anchor allocation (budget ratio,
strategy weights, information density scoring)
- Add content-based deduplication to prevent wasting slots on identical
items using SHA256 hashing
- Add _fill_remaining_slots() to maximize output when dedup reduces items
- Support data pattern detection (TIME_SERIES, SEARCH_RESULTS, LOGS, GENERIC)
- Support query-aware anchor adjustment for back-heavy patterns
Enterprise hardening:
- Thread-safe: No shared state modified
- O(n) performance for dedup and slot filling
- Fault-tolerant serialization with fallbacks
- Configurable via dedup_identical_items flag
52 tests covering adversarial positions, size adaptation, pattern-aware
anchoring, query-aware selection, information density, coverage metrics,
edge cases, and preservation guarantees.
Add comprehensive macOS deployment support for running headroom proxy as a
persistent background service using LaunchAgent. This enables automatic startup,
crash recovery, and proper lifecycle management for local development environments.
Files added:
- examples/deployment/macos-launchagent/com.headroom.proxy.plist.template
- examples/deployment/macos-launchagent/install.sh (shellcheck-clean)
- examples/deployment/macos-launchagent/uninstall.sh (shellcheck-clean)
- examples/deployment/macos-launchagent/shell-integration.sh (bash + zsh)
- examples/deployment/macos-launchagent/README.md
- docs/macos-deployment.md
Key features:
- Configurable port via HEADROOM_PROXY_PORT environment variable (default: 8787)
- Automated installation and uninstallation scripts
- Shell integration supporting both bash and zsh
- Comprehensive documentation with troubleshooting guide
- All shell scripts are shellcheck-clean (zero errors, warnings, or info messages)
Files modified:
- .gitignore: Added CLAUDE.md to prevent committing local config
- docs/README.md: Added Deployment & Operations section with navigation entry
AI review: Pending (will be run by pre-commit hook)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Documents what the integration optimizes (messages, tool calls, streaming)
and what operates outside the optimization boundary (agent memory, knowledge
bases, agent teams). Includes best practices and future improvement plans.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Features:
- with_fast_memory(): Zero-latency inline extraction (Letta-style)
- Memory extracted as part of LLM response, no extra API calls
- Semantic retrieval with local embeddings (sub-50ms)
- with_memory(): Background extraction for non-blocking memory
- SQLite + FTS5 storage with vector similarity search
- Multi-user isolation by user_id
Memory enables temporal compression - extract key facts instead of
carrying full conversation history (4000 tokens → 50 tokens).
Includes:
- Comprehensive test suite (71 new tests)
- Documentation (docs/memory.md)
- Benchmark examples comparing approaches
- E2E test with LLM-as-judge evaluation
CodeAwareCompressor:
- Tree-sitter based AST parsing for Python, JS, TS, Go, Rust, Java, C, C++
- Preserves imports, signatures, type annotations, error handlers
- Guarantees syntactically valid output
- Uses tree-sitter-language-pack for broad language support
ContentRouter:
- Intelligent compression orchestrator
- Auto-routes content to optimal compressor based on type detection
- Source hint support for high-confidence routing
Custom Model Configuration:
- HEADROOM_MODEL_LIMITS env var and ~/.headroom/models.json support
- Pattern-based inference for unknown models (opus/sonnet/haiku tiers)
- Support for Claude 4.5, Claude 4, o3, o3-mini
- Graceful fallback - never crashes on unknown models
Integrate Microsoft's LLMLingua-2 ML-based compression as an opt-in
feature for the proxy server, with excellent developer experience.
Features:
- New CLI flags: --llmlingua, --llmlingua-device, --llmlingua-rate
- ProxyConfig options: llmlingua_enabled, llmlingua_device, llmlingua_target_rate
- Smart startup hints when llmlingua is available but not enabled
- Helpful error messages when enabled but not installed
- LLMLinguaCompressor inserted before RollingWindow in pipeline
Why opt-in:
- Heavy dependencies (~2GB torch, transformers)
- 10-30s cold start for model loading
- ~1GB RAM when loaded
- Default proxy stays lightweight (<5ms overhead)
Tests:
- 26 new tests in test_proxy_llmlingua.py covering config, setup,
banner status, CLI args, DevEx messages, and edge cases
Documentation:
- Updated README.md with proxy integration section
- Updated docs/proxy.md with LLMLingua CLI options
- Updated docs/transforms.md with LLMLinguaCompressor reference
- Updated docs/ARCHITECTURE.md with pipeline and file structure
- Updated CHANGELOG.md with new feature
- Fix 34 mypy errors across 17 files with type annotations and casts
- Add type: ignore comments for legitimate dynamic patterns
- Handle None operands with (value or 0) pattern
- Cast return values to proper types (int, float, str, bool)
- Add EstimatingTokenCounter imports where needed
- Use getattr() for potentially missing attributes
- Fix flaky test_paraphrase_match with more distinct semantic examples
- Add mlx to mypy ignore list (broken third-party stubs)
- Renamed package from 'headroom' to 'headroom-ai' (PyPI name conflict)
- Fixed numpy/jinja2 imports to be lazy (core install no longer crashes)
- Fixed SQLite default path (now uses temp directory)
- Fixed f-string {tool} crash in proxy server
- Updated README with correct package name and examples
- Added quickstart and troubleshooting docs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
