Architecture

Caveman is not one program. It is four pieces that compose, and most people only ever install one of them. This page shows how a single request moves through them and why the pieces are separable.

One request#

The agent decides what to say. The skill has already shaped how it says it. The engine reduces whatever payload is about to leave. The provider bills for what arrives.

The dashed line is the part that makes the rest defensible. Compression here is not a one-way door. Before the engine emits a smaller payload it writes the original bytes to a local store keyed by a hash of those bytes, and the compressed output carries that handle. An agent that needs the part that was removed asks for the handle and gets the original back, byte for byte, in the same turn.

Why the pieces are separable#

Each layer answers a different question, and they fail independently.

Skill

Changes what the agent writes. No process, no config, no network.

Engine

Changes what a payload weighs. A binary you run, or a library you link.

Memory

Changes what you have to say twice. A local SQLite store.

Cloud

Changes what you can prove to someone else. An account, across a network.

Nothing above a layer is required by the layer below it. The skill does not know the engine exists. The engine does not need an account. This is why the licence split follows the same lines rather than cutting across them.

Where the open-core line falls#

The rule that governs new code is one sentence: a module that imports, links, embeds or ships as part of the engine-linked runtime is BSL 1.1 unless a decision record explicitly classifies it as an adoption surface.

The practical effect for you is in the additional use grant. BSL 1.1 here permits internal evaluation, local development, CI, integration, and self-hosted use for your own first-party traffic, production included. What it does not permit is offering Caveman's functionality to third parties as a hosted or embedded service. That boundary is the commercial line, and it is the only one.

Each BSL release converts to Apache 2.0 on the earlier of 21 June 2030 or four years after that version was first distributed.

Content detection#

The engine does not ask you what a payload is. It reads the bytes and decides, then routes to a compressor built for that shape. The types it recognises:

json · log · code · diff · search-result · text · toon · html · a11y · terminal · tabular · config

Two compressors are never chosen automatically and have to be asked for by name: the tool-schema compressor and the TOON encoder. Automatic selection of either would surprise a caller who did not opt in.

When detection is not confident, it answers text, which is the compressor that removes the least. Every unknown case in this system resolves toward doing less, not more.

Failure behaviour#

This is worth stating on its own, because it is the part that decides whether you can leave the thing switched on.

unknown mode          -> record, which never transforms
transform error       -> forward the original bytes
result not smaller    -> keep the original
low-confidence type   -> text
unknown grader        -> passed: false
unknown model price   -> zero, tagged unpriced

Every one of those resolves to the conservative answer. A compression system that is willing to guess is a compression system you have to babysit.