---
title: "Message compression"
description: "Summarise older turns in long threads to reduce token usage before forwarding to the LLM."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message compression

For long-running threads, the accumulated conversation history can grow large and consume a significant portion of the model's context window. Truememory supports opt-in message compression via [Headroom](https://github.com/chopratejas/headroom), which intelligently summarises older turns to reduce token usage before forwarding to the LLM.

## Enabling compression

Pass `"compression": "true"` inside the [`metadata`](/ai-gateway/features/custom-metadata/) field of any `/v1/chat/completions` request:

```bash
curl -X POST https://your-tie-host/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Agent-Id: chatbot" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Continue our discussion..."}],
    "thread_id": "my-long-thread",
    "metadata": {"compression": "true"}
  }'
```

The flag is **per-request** — you can enable it selectively (e.g. only after a thread reaches a certain length) rather than on every call.

## How it works

1. Truememory replays the thread history as usual
2. Before forwarding to the LLM, the assembled message array is passed through Headroom's compression algorithm, which summarises older turns into a compact representation while preserving recent context
3. The compressed messages are sent to the LLM provider — the `usage` token counts in the response reflect what was actually sent

Compression is applied **after** all Truememory processing (persona injection, memory retrieval, cache markers) so none of those features are affected.

## Behaviour on failure

If Headroom compression fails for any reason (library not available, network error, unexpected format), Truememory automatically falls back to sending the uncompressed message history. The request always completes — compression failure is never surfaced as an error to the caller.

## When to use it

| Scenario | Recommendation |
|----------|----------------|
| Short threads (< ~20 turns) | Not needed — Headroom is a no-op on short histories |
| Long threads approaching context limits | Enable compression to reduce token usage and cost |
| Latency-sensitive requests | Compression adds a small synchronous overhead — profile if P99 matters |

:::note
Compression uses the OpenAI tokeniser internally to estimate token counts. For non-OpenAI models (Anthropic, Gemini, etc.) the compression boundaries may be slightly miscalibrated — the result is still correct, but the trimming threshold may be off by a small margin.
:::

Source: https://truememory-docs.mvstg.com/ai-gateway/features/message-compression/index.mdx