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, which intelligently summarises older turns to reduce token usage before forwarding to the LLM.

Enabling compression

Pass "compression": "true" inside the metadata field of any /v1/chat/completions request:

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