Repository navigation
v0.8.9
Compression is now actually lossless
A sweep of 12 token-saving projects on GitHub (sqz, headroom, caveman,
context-mode, repomix, paritok, leanctx, toonify, …) found that mcptoon already
does six of the things they do. What it did not do was live up to its own claim that a
compressed result is always retrievable. Three measured ways it wasn't:
| Hole | What happened | Now |
|---|---|---|
| A payload over 1 MB was refused by the store, and the notice only appended a retrieve hint when a handle existed | 1,416,690 bytes compressed to 218 tokens, the notice said -52 items · 8 strings cut, and there was nowhere to go — with nothing to distinguish it from a bug |
Anything that fits the store is stored. Anything that cannot is refused and said out loud: original not stored — this view is all there is |
| The default 300-second TTL unlinked the file on read | Five minutes after a tool call the dropped detail was gone permanently | No timer expiry by default. The store is bounded by bytes instead (MCPTOON_CCR_MAX_BYTES, default 200 MB), evicted oldest-first. MCPTOON_CCR_TTL still works if you want the old behaviour — note ttl=0 now means never expire |
mcptoon_retrieve answered found: false for four unrelated situations |
A model could not tell "you mistyped the handle" from "that data is gone", so it retried the same typo | Each reports a status — ok / bad-handle / never-stored / expired / unreadable — with a sentence that changes what to do next |
New: a result you already received is not sent twice
The CCR handle is a hash of the payload, so "have I already sent this exact thing?" was
always answerable — nobody asked. Now the second send is a one-line reference that still
carries the handle, so a model that needs the original can still fetch it.
Measured on a 60-row search result (14,980-byte payload, cl100k_base): first send 286
tokens, repeat 50 tokens (body 1,420 characters, reference 167).
Honest scope: this is a saving per repeat, not per call. A result that never repeats
saves nothing. It is scoped to one conversation — a fresh session saying "same as before"
would point at something the model never saw:
- stdio — one process, one conversation
serve --listen— session from theMcp-Session-Idheader, thread-local so
concurrent agents cannot overwrite each other- no session header — de-duplication is switched off, because that process may be
serving several agents and telling one of them it saw another's payload would be a wrong
answer dressed up as a saving - one-shot CLI run — never de-duplicates; it has no earlier turn
The rule is now a test
tests/test_ccr_lossless.py walks the four boundaries (just stored, past the TTL, over
1 MB, after eviction) plus session isolation, and asserts the property that makes the word
mean something: for every piece of information withheld from the model, either the
handle returns it byte-identical, or the notice says there is nothing to return. A
compressed view with neither is a test failure, not a judgment call.
tests/test_ccr_http_session.py drives a real HTTP server with concurrent agents to prove
they do not share a session.
Housekeeping
- 1825 passed, 2 skipped · ruff clean · zero dependencies (43 files scanned)
- wheel 341,580 bytes = 334 KB
- 24,857 lines of Python across 43 modules
Note: this release changes a default — stored originals no longer expire on a timer.
If you were relying on the 5-minute TTL to bound disk, set MCPTOON_CCR_TTL (seconds) or
lower MCPTOON_CCR_MAX_BYTES.