Choosing an Integration and Operating It Safely

Headroom’s technical design becomes useful only when its state and control points fit the way an application actually sends context. This chapter turns the earlier model into an operating choice: who owns message assembly, forwarded-byte replay, CCR retrieval, measurement, and data boundaries? The result should be a deployment that can demonstrate its benefit and explain its failures, not merely one that returns a smaller request.

The right starting point is not the package name. It is the place where the application can observe or control the message path without breaking the agent’s assumptions.

Choose by control point, not by package label

A team that wants the least application change will usually begin with the proxy. A local Headroom proxy accepts supported provider-shaped requests, applies the shared pipeline, and forwards the result. Existing clients can point their provider base URL at it. Because the proxy can sit around the provider call, it is also the place where session cache state, provider usage, CCR tool wiring, and response handling can be coordinated.

A Python application that already owns its messages may prefer the direct compress() function. It receives a transformed list and metrics, then sends that list with its existing provider client. This gives the application more control over which requests are optimized, but it also leaves more responsibility with the caller. If the application uses CCR markers outside the full proxy path, it must provide or implement the retrieval behavior rather than assuming that a marker automatically creates a model-facing tool.

The TypeScript SDK is a different boundary from the Python function. The project’s TypeScript compression path calls a running local Headroom proxy over HTTP; it does not embed the Python compressor inside the Node process. That can be convenient for a Node application that wants a library-shaped interface, but it adds a service dependency and makes the proxy’s availability, route exposure, and configuration part of the application’s runtime design.

Framework callbacks and ASGI middleware place the transformation inside an existing Python application or gateway. LiteLLM can call Headroom before sending to any of its supported providers, and an ASGI middleware can intercept recognized LLM routes. These paths are attractive when one gateway already owns provider selection. They also require care about where CCR markers go: a callback that only changes messages and forwards them needs a marker-free contract unless the same process or downstream path can inject and resolve retrieval.

MCP changes the control point again. Instead of compressing every eligible request invisibly at the provider edge, the model can call headroom_compress when it decides that a large file, log, JSON result, or search output should be reduced. It can call headroom_retrieve later for the original and headroom_stats for session information. This is useful when explicit tool use is part of the agent’s design, but those tool calls and results also become context in the agent session. Frequent MCP calls can therefore add visible interaction overhead even while they save tokens inside the content being compressed.

Two adjacent features solve continuity problems at a different level. SharedContext is an application-owned store for inter-agent handoffs: one agent puts content under a key, another receives the compressed form, and the second can request the original explicitly. Persistent memory carries selected facts across conversations using scoped storage and semantic retrieval. Neither should be described as a transparent substitute for the proxy’s per-request cache and CCR lifecycle. Their keys, retention, and owners are different.