Core concepts
The vocabulary you need to use GiState effectively.
Gist
A gist is a compressed, versioned representation of conversation state. Each gist has a unique g_id, a target model (v_target), a snapshot (the actual state graph), a parent hash for lineage, and a checksum of its contents.
Lineage
Gists form a directed acyclic graph (DAG) via parent_hash references. Every refine, merge, or fork creates a new node linked to its parent(s).
This is Git-style versioning for context state. You can branch, merge, and checkout any historical point.
Checkpoints
A checkpoint is a gist written as a conversation goes: every few turns (the cadence is in Settings), on request, and whenever the conversation moves to another model. Each checkpoint folds the previous state together with the turns since it, so the newest checkpoint is the whole session on its own. Continuing from it, or handing it to another model, carries everything, including the exact values, names, files and constraints the session settled.
When you switch models in the console, the turns since the last checkpoint are saved under the incoming model before it answers. The state card then shows the handoff as a checkpoint on the new model, and the new model continues from one complete state.
Every checkpoint comes with a receipt: the exact details the saved turns settled (addresses, paths, versions, ports, amounts, quantities, dates and ids) that are in the state it became, checked word for word without a model. A detail that did not come through is named on the checkpoint, and Put them back adds it, with the line it came from, through the handoff review. The receipt is returned as fidelity with the checkpoint, by /refine, and by GET /gists.
Your instructions
What every model should know about you or do, written once under Settings. They go with every message after the saved state, on whichever model answers, and with every Work task, and are billed as part of each message's input. From the API: GET and PUT /api/v1/account/instructions; a turn sent with instructions: false leaves them out.
Truth registry
Each gist carries a truth registry: a set of authoritative facts with confidence scores. When merging two gists, the truth registry arbitrates contradictions.
Facts with higher confidence override lower-confidence ones. Identical facts increment confidence. Conflicting equal-confidence facts trigger a structured conflict response.
Handoff review
Before a state is carried into another model you can read it in four parts: the current objective and decisions, what was rejected or superseded, the constraints that must survive, and the open questions with the next action. Corrections are saved as a new checkpoint; the original is kept.
Branching
Under any reply or message in the console, Branch opens a new session with the conversation up to that point. It continues from a copy of the saved state as it stood there, with the session's files as they were then, so another direction or another model can go on while the original stays as it was. Branching is free. From the API: POST /api/v1/projects/:project_id/branch with the g_id to continue from.
A branch with work of its own can be merged back into the session it came from: its saved state becomes a short note, shown beside what changed since the branch started, which is saved there as a new checkpoint (billed like one). The branch stays.
Compare
Compare sends one message to up to four models side by side, each on the conversation's saved state. Nothing is saved until you keep an answer; the conversation then goes on from it, with that model, and its files are saved. Another answer can become a branch of its own. Each answer is billed as a reply. A turn sent with files: "read" shows the model the session's files without saving any, and POST /api/v1/files/capture saves a kept answer's files.
Importing history
A ChatGPT or Claude data export is read in your browser; each conversation you pick becomes a session whose saved state continues it on any model. An account's first three are free (POST /api/v1/import/free, see GET /api/v1/import/allowance); after that, a conversation is saved like any other, through /refine with its messages, and billed like any save.
Spend ceiling
Your balance is always the limit: every call reserves its maximum cost before it runs. You can also set an account-wide ceiling for any rolling 6 hours, from Edit on any key. Past it, new requests are refused with SAFETY_FUSE_TRIPPED until the window moves on, which stops a runaway agent. There is no ceiling unless you set one.
Models
GiState offers the current models from Anthropic, OpenAI and Google. The list follows the providers on its own: a new model appears once the provider serves it, is priced, and answers a test request; prices follow the providers' own; and a model leaves on its retirement date. GET /api/v1/pricing/models returns the list with each model's price, capabilities and published benchmark scores.
Provider keys
By default every save, merge, and continuation runs on GiState's own provider keys, and you never need an LLM provider key. Usage is billed in US dollars against your account balance, at the model's own rate plus a margin.
You can also add your own Anthropic, OpenAI or Google key under Settings → Provider keys. Calls to that provider then run on your key: the provider bills you directly, and GiState charges its fee (a share of the provider's list price, published with the model prices, plus the per-operation fee). Each provider can be switched back to GiState's keys at any time, and one request can choose with key_source: "own" or "gistate". With Only my keys on, GiState's keys are never used. A key your provider refuses, or an account out of credit, fails the call with a BYOK_* error and nothing is charged; it is never retried on GiState's keys unless you send it again that way.
Compression, storage, and replay all happen server-side. To resume work in another model, you continue the conversation through GiState rather than carrying a prompt out. On your own key, your provider account handles the requests GiState makes for you, and its own logging and retention settings apply to them.
What things cost
Your balance is US dollars. Every operation is charged against it in integer micros (one millionth of a dollar), so a charge is exact rather than rounded into an invented unit.
A charge is the provider's own cost for the call times a margin that narrows as models get more expensive, plus a small flat fee that varies by operation: merging weighs more than a save, a chat turn less. Token-heavy work costs more than short work. Every response tells you what it cost: charged_usd and charged_usd_micros.
Handoffs are the exception. When your state is carried into a different model, that portion of the prompt is billed at exactly what the provider charged, with no margin. Moving between models is the point of GiState, so it is not a toll.
Wallet and provider balances
Money you add lands in your wallet. From there you can move part of it to a specific provider — say $10 to Anthropic. Calls to that provider then spend that balance instead of your wallet, which caps what any one provider can consume without capping the others.
Anything you do not move stays in the wallet and covers every provider you have not funded. So a fresh account with no transfers behaves exactly as before: one balance, spent by everything.
Funding a provider is one-way. That money is forwarded to the provider to buy the capacity your calls will use, so it leaves GiState and cannot be withdrawn, refunded, or moved to a different provider. It is the same arrangement as buying prepaid credit from that provider directly. Unspent wallet balance stays refundable — see the Refund Policy.
When a provider balance runs out, the call is refusedwith 402 PROVIDER_BUDGET_EXCEEDED rather than quietly falling back to your wallet — being stopped is the reason to set the limit in the first place. Turn on provider overflow in Settings if you would rather work continued from wallet balance instead.
GET /account/allocations returns the wallet, every provider balance, and the overflow setting. POST /account/allocations/{provider}/fund moves money.