Architecture

Caveman is not one program. Most people install the skill, the proxy, or both, and never touch the rest. This page shows how a single request moves through the pieces and why they are separable.

It describes the caveman repository. The Agent SDK is a different repository with a different job: it is how you build an agent, not how you make an existing one cheaper, and nothing on this page is required to use it.

One request#

The agent decides what to say. The skill has already shaped how it says it. When the request is wrapped, it goes to the local proxy on loopback; the engine reduces whatever payload is about to leave; the provider bills for what arrives. Without the proxy, the engine is a binary you call yourself.

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.

Proxy

Changes the base URL and what a payload weighs. A loopback process that routes and records, plus the engine binary it calls to compress.

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 proxy exists. The proxy 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.