Dictionaries: compressing small messages
A 300-byte message barely compresses alone, because the codec has no history. Give it a trained dictionary and it does. Then see how HTTP now uses the previous response as the dictionary for the next.
LZ77 finds repeats in what it has already seen. At the start of a short message, it has seen nothing. A 300-byte tool result is full of patterns common to every tool result, but none repeated within itself, so it barely compresses, and the codec's own headers eat the gain.
A dictionary is shared history agreed in advance. Both sides load it before compressing or decompressing, so back-references can point into it. The first {"type":"tool_result","tool_use_id": in a message becomes a single match.
Small messages with and without a dictionary
- 100 B message
- 300 B message
- 1 KB message
- 3 KB message
- 10 KB message
# Train a 110 KB dictionary on 10,000 real samples, one per file
zstd --train samples/*.json -o tool-results.dict
# Compress and decompress with it
zstd -D tool-results.dict message.json -o message.json.zst
zstd -D tool-results.dict -d message.json.zst
# Compare: one sample alone versus with the dictionary
zstd -c samples/0001.json | wc -c
zstd -c -D tool-results.dict samples/0001.json | wc -cVersion dictionaries and store their ID with the data. A message compressed with dictionary v3 can only be read with v3.
Brotli takes the same idea to the web: it ships with a built-in dictionary of about 120 KB of common words and HTML, CSS and JavaScript fragments. That is why Brotli does so well on small text files where gzip struggles.
Shared dictionaries over HTTP
RFC 9842, published in September 2025, standardises compression dictionary transport. A server marks a response as usable as a dictionary with a Use-As-Dictionary header. Later, the browser advertises it with Available-Dictionary, and the server can send the new version compressed against the old one, with content encodings dcb (Brotli) or dcz (zstd).
- app.v1.js, compressed normally
- ≈ 100 KB
- app.v2.js changes a few functions
- Full download would again be ≈ 100 KB
- Compressed against v1 as the dictionary
- ≈ 1 KB delta (the RFC's own example)
Users who already have v1 download about 1% of the bytes. Browser support was Chromium-led as of June 2026.
Go deeperDictionaries for agent traffic
Agent systems send and store millions of small, similar messages: tool calls, tool results, trace spans. A dictionary trained on a day's traffic can cut their stored size several-fold compared with compressing each alone, and zstd's dictionary decompression is fast enough for hot paths.
The same caution applies as with any compression of mixed data: a dictionary built from one tenant's data must not be used to compress another tenant's secrets, or the length-oracle attack in the next lesson becomes possible.
Where you will meet it
Facebook built zstd dictionary support for compressing many small, similar messages and records.
Some databases train per-table zstd dictionaries to compress small rows and values.
Large sites experiment with dictionary transport so returning users download only deltas of updated bundles.
Words to know
- Dictionary
- Pre-shared data that compressor and decompressor both load as history.
- Training
- Building a dictionary from representative samples.
- Use-As-Dictionary
- Response header marking a resource as a future compression dictionary.
Check yourself
Answer out loud before you open each one.
Why does a 300-byte message barely compress alone?
The codec has no history to find repeats in, and its headers offset small gains.
What must both sides share to use a dictionary?
The exact same dictionary, identified by version or hash.
What does RFC 9842 let a server do?
Compress a response against a previous response the client already has, sending only the differences.
Try it
Collect 1,000 of your agent's tool results as separate files, train a zstd dictionary on 900, and measure the size of the other 100 with and without it.