# headroomlabs-ai/headroom architecture

> Architecture diagram of the GitHub repository headroomlabs-ai/headroom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/headroomlabs-ai/headroom
- Repository: https://github.com/headroomlabs-ai/headroom
- Video tour (about a minute): https://gitdiagram.com/headroomlabs-ai/headroom/video

## Overview

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: [`headroom/proxy/server.py`](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/proxy/server.py) (Proxy server), [`headroom/transforms/pipeline.py`](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/pipeline.py) (Transform pipeline), [`headroom/transforms/content_router.py`](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/content_router.py) (Content router), [`sdk/typescript/src/client.ts`](https://github.com/headroomlabs-ai/headroom/blob/main/sdk/typescript/src/client.ts) (Python and TS SDKs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_sdk["Python and TS SDKs<br/>[client.ts]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_optimize["Context optimization"]
  node_pipeline["Transform pipeline<br/>[pipeline.py]"]
  node_content_router["Content router<br/>[content_router.py]"]
  node_smart_crusher["SmartCrusher<br/>[smart_crusher.py]"]
  node_code_compressor["Code compressor<br/>[code_handler.py]"]
  node_cache_aligner["Cache alignment<br/>[cache_aligner.py]"]
end

subgraph group_proxy["Proxy and retrieval"]
  node_proxy_server["Proxy server<br/>[server.py]"]
  node_provider_routes["Provider routes<br/>[proxy_routes.py]"]
  node_ccr_handler["CCR retrieval"]
end

subgraph group_agent["Agent capabilities"]
  node_mcp["MCP integration<br/>[server.py]"]
  node_memory["Cross-agent memory<br/>[core.py]"]
  node_agent_wrap["Agent wrapping<br/>[wrap_registry.py]"]
  node_learning["Session learning<br/>[analyzer.py]"]
end

subgraph group_ops["State and insights"]
  node_compression_store[("CCR store")]
  node_memory_storage["Memory storage routing<br/>[storage_router.py]"]
  node_telemetry["Session telemetry<br/>[session.py]"]
end

node_agent_user(("Agent or app"))
node_llm(("LLM provider"))

node_agent_user -->|"uses inline"| node_sdk
node_agent_user -->|"sends requests"| node_proxy_server
node_agent_user -->|"runs commands"| node_cli
node_sdk -.->|"compresses with"| node_pipeline
node_proxy_server -->|"uses pipeline"| node_pipeline
node_pipeline -->|"routes content"| node_content_router
node_content_router -->|"selects compressor"| node_smart_crusher
node_content_router -->|"selects compressor"| node_code_compressor
node_pipeline -->|"preserves prefixes"| node_cache_aligner
node_smart_crusher -->|"stores originals"| node_compression_store
node_proxy_server -->|"registers routes"| node_provider_routes
node_ccr_handler -->|"retrieves originals"| node_compression_store
node_agent_user -->|"uses tools"| node_mcp
node_agent_user -->|"shares memory"| node_memory
node_memory -.->|"routes storage"| node_memory_storage
node_agent_user -->|"wraps agent"| node_agent_wrap
node_agent_user -->|"learns from sessions"| node_learning
node_proxy_server -->|"records sessions"| node_telemetry
node_proxy_server -->|"forwards requests"| node_llm

click node_sdk "https://github.com/headroomlabs-ai/headroom/blob/main/sdk/typescript/src/client.ts"
click node_cli "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/cli/main.py"
click node_proxy_server "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/proxy/server.py"
click node_provider_routes "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/providers/proxy_routes.py"
click node_pipeline "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/pipeline.py"
click node_content_router "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/content_router.py"
click node_smart_crusher "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/smart_crusher.py"
click node_code_compressor "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/compression/handlers/code_handler.py"
click node_cache_aligner "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/cache_aligner.py"
click node_compression_store "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/cache/compression_store.py"
click node_ccr_handler "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/ccr/response_handler.py"
click node_mcp "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/integrations/mcp/server.py"
click node_memory "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/memory/core.py"
click node_memory_storage "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/memory/storage_router.py"
click node_agent_wrap "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/providers/wrap_registry.py"
click node_learning "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/learn/analyzer.py"
click node_telemetry "https://github.com/headroomlabs-ai/headroom/blob/main/headroom/telemetry/session.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_cli toneBlue
class node_pipeline,node_content_router,node_smart_crusher,node_code_compressor,node_cache_aligner toneAmber
class node_proxy_server,node_provider_routes,node_ccr_handler toneMint
class node_mcp,node_memory,node_agent_wrap,node_learning toneRose
class node_compression_store,node_memory_storage,node_telemetry,node_agent_user,node_llm toneIndigo
```

## Components

### Entry points

- [Python and TS SDKs](https://github.com/headroomlabs-ai/headroom/blob/main/sdk/typescript/src/client.ts): `sdk/typescript/src/client.ts`
- [CLI](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/cli/main.py): `headroom/cli/main.py`

### Context optimization

- [Transform pipeline](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/pipeline.py): `headroom/transforms/pipeline.py`
- [Content router](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/content_router.py): `headroom/transforms/content_router.py`
- [SmartCrusher](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/smart_crusher.py): `headroom/transforms/smart_crusher.py`
- [Code compressor](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/compression/handlers/code_handler.py): `headroom/compression/handlers/code_handler.py`
- [Cache alignment](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/transforms/cache_aligner.py): `headroom/transforms/cache_aligner.py`

### Proxy and retrieval

- [Proxy server](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/proxy/server.py): `headroom/proxy/server.py`
- [Provider routes](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/providers/proxy_routes.py): `headroom/providers/proxy_routes.py`
- [CCR retrieval](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/ccr/response_handler.py): `headroom/ccr/response_handler.py`

### Agent capabilities

- [MCP integration](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/integrations/mcp/server.py): `headroom/integrations/mcp/server.py`
- [Cross-agent memory](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/memory/core.py): `headroom/memory/core.py`
- [Agent wrapping](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/providers/wrap_registry.py): `headroom/providers/wrap_registry.py`
- [Session learning](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/learn/analyzer.py): `headroom/learn/analyzer.py`

### State and insights

- [CCR store](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/cache/compression_store.py): `headroom/cache/compression_store.py`
- [Memory storage routing](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/memory/storage_router.py): `headroom/memory/storage_router.py`
- [Session telemetry](https://github.com/headroomlabs-ai/headroom/blob/main/headroom/telemetry/session.py): `headroom/telemetry/session.py`

### Other components

- **Agent or app**
- **LLM provider**

## Connections

- 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 (evidence: `headroom/proxy/server.py`)
- Transform pipeline → Content router: routes content (evidence: `headroom/transforms/pipeline.py`)
- Content router → SmartCrusher: selects compressor
- Content router → Code compressor: selects compressor
- Transform pipeline → Cache alignment: preserves prefixes (evidence: `headroom/transforms/pipeline.py`)
- SmartCrusher → CCR store: stores originals (evidence: `headroom/transforms/smart_crusher.py`)
- Proxy server → Provider routes: registers routes (evidence: `headroom/proxy/server.py`)
- CCR retrieval → CCR store: retrieves originals (evidence: `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 (evidence: `headroom/proxy/server.py`)
- Proxy server → LLM provider: forwards requests