# How the Context Tracker Maintains Compressed Content Awareness in Headroom Conversations

> Learn how Headroom's Context Tracker uses SharedContext to cache compressed conversation snippets, allowing agents fast access to compact data without re-compression.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: internals
- Published: 2026-06-16

---

**The Headroom Context Tracker uses the `SharedContext` class to cache compressed conversation snippets alongside their original text, enabling downstream agents to retrieve compact representations without re-compressing or re-transmitting data to the LLM.**

The Context Tracker is a core component of the Headroom SDK that solves the token bottleneck in multi-agent conversations. By maintaining compressed content awareness through an in-memory cache with TTL-based eviction, the tracker ensures that agents can reuse previously compressed context efficiently. This implementation lives in the `SharedContext` class within the `chopratejas/headroom` TypeScript SDK.

## Core Architecture

The Context Tracker is implemented by the **`SharedContext`** class in [`sdk/typescript/src/shared-context.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/shared-context.ts). It maintains an in-memory `Map<string, ContextEntry>` that stores both original and compressed representations of conversation pieces, along with metadata including token counts, timestamps, and agent identifiers.

### Storing Compressed Entries via `put()`

When agents need to cache conversation history, they call `SharedContext.put()`. This method first sends the raw text to the Headroom compression proxy via `HeadroomClient.compress()` (defined in [`sdk/typescript/src/client.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/client.ts)). The proxy returns a `CompressResult` containing the compressed payload, token counts, and applied transforms.

The method then constructs a `ContextEntry` object that encapsulates:
- The original uncompressed string
- The compressed payload
- Metadata (original/compressed token counts, timestamp, agent identifier)

This entry is written to the internal Map. According to the source code, the `put()` implementation spans lines 53-100 in [`shared-context.ts`](https://github.com/chopratejas/headroom/blob/main/shared-context.ts).

### TTL-Based Eviction with `evictExpired()`

To maintain fresh context, the tracker implements automatic expiration. The private method `evictExpired()` (lines 73-80) removes entries whose age exceeds the configured TTL. By default, entries expire after 1 hour. This method is invoked on every read and write operation, ensuring stale data never accumulates.

### Capacity Management via `evictIfFull()`

The tracker enforces a hard limit on memory usage through the `maxEntries` configuration (default 100). When the cache reaches capacity, `evictIfFull()` (lines 82-86) discards the oldest entry using a FIFO strategy to make room for new data. This prevents unbounded memory growth during long-running conversations.

## Retrieving Compressed and Original Content

The `SharedContext.get()` method (lines 8-18) provides flexible access to cached content while automatically validating TTL before returning data.

### Accessing Compressed Payloads

By default, `SharedContext.get(key)` returns the compressed representation. This allows agents to inject space-efficient context into LLM prompts without additional compression overhead.

### Accessing Full Text

When agents require the original uncompressed text—such as for display or debugging—they pass the `{ full: true }` option: `SharedContext.get(key, { full: true })`. Both retrieval paths trigger TTL validation, ensuring expired entries are purged before access.

## Integration with the Headroom Compression Client

The `SharedContext` constructor initializes a `HeadroomClient` instance (lines 42-48) using configuration options including base URL, API key, and timeouts. The client's `compress()` method (lines 35-68 in [`sdk/typescript/src/client.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/client.ts)) performs an HTTP POST to `/v1/compress` on the Headroom proxy, returning a structured `CompressResult` that the tracker stores verbatim.

This architecture decouples the caching logic from the compression service, allowing the tracker to maintain awareness of compressed state while the client handles the actual token reduction algorithms.

## Monitoring Compression Efficiency

Developers can audit cache performance via `SharedContext.stats()` (lines 44-64). This method aggregates token counts across all stored entries, returning:
- Total entries count
- Original token count vs. compressed token count
- Absolute tokens saved
- Percentage savings

This visibility helps tune the `maxEntries` and `ttl` parameters for specific conversation patterns.

## Practical Implementation Example

The following example demonstrates initializing a tracker with custom TTL and capacity limits, storing conversation history, and retrieving both compressed and original formats:

```typescript
import { SharedContext } from "headroom-ai";

// Create a tracker with a custom model and a 30-minute TTL
const ctx = new SharedContext({
  model: "gpt-4o",
  ttl: 1800,          // seconds
  maxEntries: 200,
});

// Store a large piece of conversation history
await ctx.put("session-123", largeText, { agent: "assistant" });

// Later in the same or a different agent:
const compressed = ctx.get("session-123");               // → compressed string
const original   = ctx.get("session-123", { full: true }); // → original string

// Inspect statistics
console.log(ctx.stats());
// { entries: 1, totalOriginalTokens: 4500, totalCompressedTokens: 1200, totalTokensSaved: 3300, savingsPercent: 73.3 }

```

## Summary

- The Context Tracker is implemented by the **`SharedContext`** class in [`sdk/typescript/src/shared-context.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/shared-context.ts), using an in-memory Map to store `ContextEntry` objects.
- **Compression awareness** is maintained by caching both original and compressed payloads via `put()`, which delegates to `HeadroomClient.compress()` at [`sdk/typescript/src/client.ts`](https://github.com/chopratejas/headroom/blob/main/sdk/typescript/src/client.ts).
- **Automatic eviction** ensures freshness through TTL checking (default 1 hour) via `evictExpired()`, while `evictIfFull()` enforces a default cap of 100 entries.
- **Flexible retrieval** allows agents to fetch either compressed (`get(key)`) or original (`get(key, { full: true })`) content.
- **Statistics tracking** via `stats()` provides visibility into token savings and cache utilization.

## Frequently Asked Questions

### How does the Context Tracker prevent stale data from accumulating?

The tracker implements automatic TTL-based eviction through the private `evictExpired()` method, which runs on every read and write operation. Entries older than the configured TTL (default 3600 seconds) are immediately purged from the internal Map, ensuring only fresh context remains available.

### What happens when the cache reaches its maximum capacity?

When the number of stored entries hits `maxEntries` (default 100), the `evictIfFull()` method automatically removes the oldest entry to make room for new data. This FIFO eviction strategy prevents memory leaks while maintaining the most recent conversation context.

### Can agents retrieve the original uncompressed text after compression?

Yes. While `SharedContext.get(key)` returns the compressed payload by default, passing `{ full: true }` as the second argument returns the original uncompressed string. Both retrieval methods validate TTL before returning data, ensuring expired entries are filtered out.

### How does the tracker integrate with the Headroom compression service?

The `SharedContext` constructor instantiates a `HeadroomClient` that handles HTTP communication with the Headroom proxy. When `put()` is called, the client sends the text to `/v1/compress` and receives a `CompressResult`, which the tracker stores alongside the original content to maintain compressed awareness without additional API calls.