Version an AI system's behaviour

tovio behavioral snapshot --model-id <id> --prompts <path-or-text>tovio behavioral list

Captures the behavioural surface of an AI system alongside the code, as a content-addressed object attached to your commit.

The problem it solves

An AI system's behaviour is not determined by its code alone. Change a system prompt, add a tool, or swap a retrieval index and the system behaves differently while the source diff looks trivial or empty. Ordinary version control does not capture that; this does.

When an agent starts behaving differently, the question is "what changed". Without behavioural snapshots the honest answer is often "we do not know" — the prompt was edited in a console, or a tool was added out of band.

The six descriptors

Every one is optional. An omitted descriptor is recorded as empty rather than as unknown, so a partial snapshot is still well-defined and still reproducible.

Path or literal — the rule

The five hashed descriptors take either a path or a literal string. If the value names a file that exists, its bytes are read and hashed; otherwise the string itself is hashed. So --prompts ./prompts/system.md and --prompts "You are a helpful assistant." are both valid, and a typo'd path silently becomes a literal — worth checking, since the two hash differently.

--policy-version is the exception: it is stored verbatim, not hashed, so it is the one field whose value you can read back.

What is stored — and what is not

The snapshot stores hashes, not contents. Your prompt text never enters the object store, which is what makes it safe to snapshot a prompt containing customer data or a proprietary system message.

The consequence is worth internalising: a later diff can tell you that the prompts changed, and never how. Keep the prompts themselves under version control in the repository if you want the text as well as the fingerprint — then the hash and the file agree, and you get both.

Snapshotting moves your commit

A snapshot is attached by rewriting the current commit with the snapshot linked, and advancing your lane to it. The tree, message, author, parents and change ID are all unchanged — but the commit address changes. Expect it, and take the snapshot before you push rather than after.

What to snapshot, and when

Before a release, before a prompt change you expect to matter, and on a schedule if prompts are edited outside the repository.

Snapshot deliberately rather than on every commit. Each snapshot object records the commit it is linked to, so re-running the command with identical descriptors still writes a new object and still advances your lane — it is not an idempotent no-op, and putting it in a loop or an unconditional CI step will walk your lane tip forward every time.

Then compare

tovio behavioral diff <commit-a> <commit-b>

Tool catalogs are hashed independently

Separately from the --tools descriptor you supply here, an agent working over MCP records a canonical provenance hash of the tool catalog it was actually offered. So what an agent could reach is recorded rather than reconstructed, whether or not anyone remembered to take a snapshot.