Agents
What an agent is made of, and why the agent row holds almost nothing.
An agent in Coldcache is a name and a pointer. All behaviour lives in its versions. The agent row carries a slug, a display name, a stable pointer and a counter — nothing that could change how a run behaves.
The version body
Five fields make up a version, and all five are hashed together into the body hash that gives the version its identity.
| Field | What it does |
|---|---|
| system_prompt | The instructions. Loaded into a fresh context on every run. |
| tool_config | Web search on/off, max searches, domain allowlist. |
| output_schema | A JSON Schema, or null for free text. Validated on every run; the result is recorded as schema_valid. |
| model_settings | Provider, exact model id, temperature, max tokens, effort. |
| memory_policy | off, chat, or scoped. Defaults to off. |
Output schemas
When a version declares a schema, Coldcache appends a formatting instruction to the prompt and validates the response itself, on every provider. That is deliberate: native structured-output modes differ across Claude, ChatGPT and Gemini, and an agent version is supposed to behave the same way wherever you point it.
Invalid output is not discarded. The run stores the raw text, the parse result, and the list of validation errors — a 12% schema-failure rate on a version is a number you want to see, not an exception you want swallowed.
Reference documents
A version can carry documents — a checklist, a spec, a style guide. They are read on every run of that version, and each document's content hash is folded into the version body hash. Swapping the checklist therefore mints a new version instead of silently changing how the agent behaves.
Text is extracted once at upload and sent verbatim to every provider, so the same version reads the same characters on Claude, ChatGPT and Gemini. Files are stored content-addressed by sha256: uploading the same bytes twice is one file, and replacing a file with an edited one of the same name shows up in the diff because the hash moved.
Accepted: PDF (with a text layer), txt, md, csv, tsv, json, log, html, xml, yaml — 20 MB each. A scanned PDF with no text layer is flagged as failed rather than silently contributing nothing; OCR is not supported yet.
Memory
Memory is off by default and is part of the version body, so enabling it is a version bump that shows up in the diff and in the chat header.
| Mode | Behaviour |
|---|---|
| off | Every run starts from an empty context. Even earlier turns in the same chat are not loaded. |
| chat | Prior turns of this chat are replayed into context. Still nothing crosses a chat boundary. |
| scoped | A named key-value store the agent may read and write, with a TTL. |