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>
