How the Context Tracker Maintains Compressed Content Awareness in Headroom Conversations

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. 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). 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.

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) 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:

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, 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.
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}