Architecture
One engine does detection, compression, token counting, and recovery. Public front ends call that engine instead of carrying their own compressor. The proxy adds routing and local spend rows around provider traffic.
One core, many front doors
Everything starts with the compression engine. Its stable API is Compress, Retrieve, Detect, and Stats. Public tools wrap that API:
| Front door | What it adds over the engine |
|---|---|
caveman-engine CLI | stdin/stdout + a JSON report |
| Proxy | routes provider traffic and writes local inferred spend rows |
| MCP server | the engine as three Model Context Protocol tools |
| Cavemem · Shrink | memory and tool-catalog compression on top |
| SDKs | gateway client methods; compress() delegates instead of reimplementing |
Because the core is shared, a compressor written once can be reached by CLI, proxy, MCP, and SDK paths. No public tool gets a second compressor copy.
The request path
When the proxy is in the loop, provider traffic runs through five steps.
The proxy matches a provider route, resolves credentials from environment or inbound headers, optionally runs enabled transforms, forwards to the provider, and writes a row to local SQLite. In record mode it never transforms. On transform failure it forwards the original bytes.
The safety ladder
Each transform declares a safety class, S0 through S4.
- S0-S3 cover lower-risk transforms such as metadata handling, provider-native hints, and structural changes guarded by policy.
- S4 is lossy. Engine compressors sit here. S4
RequiresCCR, so a lossy result is emitted only after the original is stored for byte-exact recovery. No store means pass-through.
Honesty rule
"Lossy" here means "smaller model-visible payload," not "destroyed source." An S4 result carries a recovery handle, and Retrieve(handle) returns the original byte-for-byte. How recovery works →
Public boundary
These docs stay on the public side of the codebase.
Public local tools are single-operator and BYOK. They report inferred measurements. Hosted proof, billing, and tenant governance are outside these public docs unless a public package exposes a specific command or contract.
Fail-closed by construction
Unknown inputs take the conservative path. Unknown engine mode becomes record. Low-confidence content becomes text. Unknown grader returns passed: false. Unknown proxy route returns 404. Unknown model price returns zero plus an unpriced: tag.