Workspace

Dictionaries: compressing small messages

3 day streakD

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.

CurrentLesson 5 of 616 min

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.

Figure 5.1

Small messages with and without a dictionary

  1. 100 B message96%42%
  2. 300 B message68%29%
  3. 1 KB message52%27%
  4. 3 KB message43%28%
  5. 10 KB message36%31%
Compressed alone (share of original)With a trained dictionary
Compressed size for messages of increasing size, compressed alone and with a trained dictionary. The dictionary helps most where messages are smallest. Values are illustrative; train and measure on your own samples.
train.shShell
# 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 -c

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

Worked exampleShipping a new version of a JavaScript bundle
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

Messaging

Facebook built zstd dictionary support for compressing many small, similar messages and records.

Databases

Some databases train per-table zstd dictionaries to compress small rows and values.

Web performance

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.

A good place to start

Explore a pattern

A little guidance

Start with a pattern, read through a problem, and mark it solved when the idea clicks. Save anything you want to revisit.

New tutorials are added one at a time. Your bookmarks and solved checkmarks stay in this browser.

Explore the roadmap