> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Context compression

> How context compression compacts JSON and trims long conversations, the three modes and their thresholds, and where to set the organization default and project overrides.

Context compression shrinks a request before Gateway sends it to the model, with no application change. Turn it on when long conversations approach a model's context window or input tokens drive your cost.

## How it works

When a request's token count exceeds the mode's threshold, Gateway applies two steps in order, stopping once it fits:

1. **Lossless compaction** re-encodes JSON in tool schemas, tool call arguments, and tool results more compactly, without changing content
2. **Message trimming** removes messages from the middle of the conversation, always keeping system messages and the start and end

A request that still doesn't fit (say, system messages alone fill the window) is sent anyway. Unrecognized models skip compression.

## Modes

Thresholds apply to the model's effective input limit: its context window minus 15% reserved for output.

| Mode                    | Compresses when the request exceeds                                                   | Compresses down to               | Use it for                                 |
| ----------------------- | ------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------ |
| **Context window only** | The effective input limit                                                             | 95% of the effective input limit | A safety net against context window errors |
| **Cost optimization**   | The target ratio of the effective input limit (default 70%, settable from 10% to 95%) | The target ratio                 | Cutting input tokens on every long request |
| **None**                | Never                                                                                 |                                  | Turning compression off                    |

For a 128K-token model on **Cost optimization** at 70%, compression starts above about 76K tokens (128K × 0.85 × 0.7).

## Configuration

Set the organization default under **Configure → Request settings → Defaults** in the [dashboard](https://gateway.merge.dev/configuration/request-settings), and override it on a project's **Configuration** tab. A project override wins, so a project set to **Disabled** doesn't compress even when the organization does. With neither set, requests aren't compressed.

## Next steps

#### [Cost governance and savings](/merge-gateway/cost/cost-governance-and-savings)

Combine compression with other savings levers

#### [Prompt caching](/merge-gateway/capabilities/prompt-caching)

Reduce input cost for repeated context

#### [Projects](/merge-gateway/cost/projects)

Override compression for one workload