How headroomlabs-ai/headroom works
Headroom is a local context-optimization product for AI applications and agents. Its principal workflow accepts prompts or tool output, routes content through compression and cache-preservation logic, then sends the reduced context to an LLM; CCR can retain originals for later retrieval. The repository also exposes a proxy, SDKs, MCP integration, cross-agent memory, agent wrapping, learning, and savings telemetry. Connections below use README statements or indexed imports; several secondary subsystems are documented but their internal wiring was not sampled.
Main entry points: server.py Proxy server · pipeline.py Transform pipeline · content_router.py Content router · client.ts Python and TS SDKs
Components 19
Entry points
- Python and TS SDKs
sdk/typescript/src/client.ts - CLI
headroom/cli/main.py
Context optimization
- Transform pipeline
headroom/transforms/pipeline.py - Content router
headroom/transforms/content_router.py - SmartCrusher
headroom/transforms/smart_crusher.py - Code compressor
headroom/compression/handlers/code_handler.py - Cache alignment
headroom/transforms/cache_aligner.py
Proxy and retrieval
- Proxy server
headroom/proxy/server.py - Provider routes
headroom/providers/proxy_routes.py - CCR retrieval
headroom/ccr/response_handler.py
Agent capabilities
- MCP integration
headroom/integrations/mcp/server.py - Cross-agent memory
headroom/memory/core.py - Agent wrapping
headroom/providers/wrap_registry.py - Session learning
headroom/learn/analyzer.py
State and insights
- CCR store
headroom/cache/compression_store.py - Memory storage routing
headroom/memory/storage_router.py - Session telemetry
headroom/telemetry/session.py
Other components
- Agent or app
- LLM provider
Connections 19
- Agent or app → Python and TS SDKs: uses inline
- Agent or app → Proxy server: sends requests
- Agent or app → CLI: runs commands
- Python and TS SDKs → Transform pipeline: compresses with
- Proxy server → Transform pipeline: uses pipeline
headroom/proxy/server.py - Transform pipeline → Content router: routes content
headroom/transforms/pipeline.py - Content router → SmartCrusher: selects compressor
- Content router → Code compressor: selects compressor
- Transform pipeline → Cache alignment: preserves prefixes
headroom/transforms/pipeline.py - SmartCrusher → CCR store: stores originals
headroom/transforms/smart_crusher.py - Proxy server → Provider routes: registers routes
headroom/proxy/server.py - CCR retrieval → CCR store: retrieves originals
headroom/ccr/response_handler.py - Agent or app → MCP integration: uses tools
- Agent or app → Cross-agent memory: shares memory
- Cross-agent memory → Memory storage routing: routes storage
- Agent or app → Agent wrapping: wraps agent
- Agent or app → Session learning: learns from sessions
- Proxy server → Session telemetry: records sessions
headroom/proxy/server.py - Proxy server → LLM provider: forwards requests