# Twigg: context control Two documents govern what a turn carries to the model. Both are published per namespace from the dashboard or customer API and versioned. Neither travels on a request: a run resolves them for its own scope. Publishing makes a new version; old versions stay listed and any can be made active again. ## Context budget A budget decides how much history a turn may carry and how hard the service works to make it fit. Set it with `POST /api/v1/config/budgets` or in Dashboard → Configuration → Context window, per namespace and per model; it resolves server-side, so it never travels on a request. A budget caps total estimated input, including instructions, tools, and history. Text uses a local tokenizer with a 20% safety margin across providers, without a provider token-count request. This is an estimate for context fitting; billing uses the provider's reported usage. It is `(context_window - reserved_output) × (1 - headroom)`, lowered by an optional token ceiling. Output defaults to the smaller of 16,384 tokens and the model's output limit; a request can specify its own output limit. | option | meaning | |---|---| | `version` | Required schema version: `3`. | | `headroom` | Required fraction left unused after output reservation; default policy uses 0.10. | | `max_history_tokens` | Optional ceiling of at least 32,000 tokens. `null` uses the available model budget. | | `history_mode` | `summarize` (default) keeps one saved prefix summary plus recent original history. `drop_oldest` omits the oldest history between the anchor and recent exchange, without summary calls. | | `eager_compaction` | `{"mode":"off"}` or `{"mode":"at_fill","at":0.8}` (default). Prepare summaries after a run reaches the selected fill. Must be off in drop-oldest mode. | Summarization rolls the earlier checkpoint and newly aged history into a new checkpoint when needed. Older checkpoints and original messages remain saved. Switching to a smaller window may generate missing summaries; a larger window can use an earlier checkpoint or restore all originals. Summaries are lossy: older details may lose fidelity as a conversation continues. Tool arguments, results, names, errors and call identifiers are available to the summarizer. Media contributes attachment descriptions, and reasoning signatures are excluded. Your retention options still control original parts replayed to the model, including tool truncation, media, reasoning and anchors. Changing retention does not rewrite saved summaries. Drop-oldest reports `history_dropped` with the omitted ordinal range. Neither mode deletes stored history. Instructions, tools, the anchor and the current exchange must themselves fit; otherwise the request reports a capacity error. The service supports chat models with context windows of at least 128,000 tokens. Checkpoint size, cadence, source chunk size and compression ratios are internal platform policy, not customer options. Read current defaults with `GET /api/v1/config/defaults` using your API key. A budget can be the scope's default for every model, or tagged to specific models. A tag at a level beats that level's untagged budget. The stream says which answered with a `context_budget_resolved_at` warning. ## Retention policy A retention policy says what a part looks like when it is replayed to the model at a given point in the context. It is what stops large images, files and tool results being replayed verbatim once they are far down the history. Author it per namespace with `POST /api/v1/config/retention` or in the dashboard; it applies to every run in that scope. It never changes what is stored: a pruned attachment is still in your ledger and still comes back from `/history`. It stops being sent, and stops being billed, on every subsequent turn. What you can express: - **Attachments**: a boundary for everything, per MIME family (`image/*`), or for one exact type. - **Reasoning**: one boundary. - **Tool payloads**: a rule for all tools, a name prefix (`gh_*`), or one tool, with results and arguments treated separately. - **Failed calls**: an override that replaces the matched rule when a tool returned an error. - **Prose**: separate treatments for what you sent and what the model replied. Thresholds keep, they do not cut. A threshold is a share of the assembled window measured back from the newest part, and higher keeps more: `1` replays however old, `0` never replays, `0.25` replays within the newest quarter. The current turn is exempt from retention pruning. New attachments must still pass that model's format, carrier and size/count checks before the turn is accepted. The platform default for media is `0`: sent once, never replayed. Rules match first-hit, in list order. A broad rule above a narrow one makes the narrow one dead, and the backend refuses to publish that arrangement. Truncation is `keep` (never cut), `always` (cut to a size) or `over` (cut only past a threshold), keeping `head`, `tail` or `head_and_tail`. `mark_truncations` is on by default; a model that cannot tell output was cut will invent the missing middle. `anchor_parts` holds the first N parts verbatim, never compacted and never truncated. ## Compaction When history no longer fits, Twigg summarizes an older prefix and keeps recent history verbatim. There is no fixed 40,000-token guarantee: the retained amount depends on the model window, output reservation, budget and retention settings. The current exchange and any configured anchor remain protected; if they cannot fit with the required summary, the request returns a capacity error. Saved summaries can be reused, and original history remains available. Increasing the budget can restore original messages without rewriting existing summaries. Compaction currently uses OpenAI's `gpt-5-6-luna`, regardless of the model selected for the chat turn. History selected for summarisation is sent to OpenAI. The compaction model is platform-selected and cannot currently be configured by customers. Compaction is a real model call and is billed as its own `compaction` line, at the same rates as inference, so you can see what context management costs. It is allowed to run at zero balance. A `compacting` event precedes the wait it describes, and `done.compaction` reports what was generated. ## Where a policy lives | scope | handle | meaning | |---|---|---| | Organisation | `namespace: null` | The default every chat resolves against when nothing nearer is published. | | Namespace | `acme/proj-7` | Set on the chat at creation. Resolution walks up from here. | | Model tag | budget only | A budget tagged to specific models. Beats the level's untagged budget. | A request-level tool with the same name as a saved tool takes precedence for that request. This replacement does not emit a `tool_shadowed` warning; that warning covers shadowing while resolving saved tool bundles. A request-level `system` prompt is appended after the resolved instructions, never in place of them. It is not stored with the chat, so send it on every request it should apply to, and it counts against the context budget like the saved instructions. Policies do not merge. Instructions and tool bundles do, with an explicit `append` or `replace` mode. Resolution that was legal but worth knowing about arrives as `config_warnings` at the head of the stream: `retention_policy_overridden` names the displaced level, `context_budget_resolved_at` names the level and model tag that answered. ## Model attachment capabilities Read `media` from the model catalogue before sending attachments. `user`, `tool_result` and `assistant` have separate MIME allowlists and byte/count limits. An empty MIME list means unsupported; `configured: false` means model-specific support has not been configured, and legacy adapter behaviour applies. For configured models, unsupported new attachments return HTTP 422 before the turn is persisted. Prompt text is limited to 500,000 Unicode characters per part, and a published system-instruction body is limited to 131,072 UTF-8 bytes. The deployment-wide HTTP body limit can reject a large request earlier with HTTP 413; base64 encoding contributes to that size. Retention runs first when preparing history. Retained attachments that the chosen model cannot accept become text markers with `media_unsupported` or `media_limit_exceeded` translation warnings. Count limits include history, with newest attachments retained first. Stored bytes remain intact, so switching back to a compatible model can replay them when your retention policy keeps them. This also applies to provider calls used for compaction. The live [model catalogue](https://api.twigg.ai/v1/catalogue/models.md) lists the current formats and limits; provider and model names alone do not imply support. ## Using an agent or want app-level control? You can also configure these using the API. Set system prompts, saved tools, context budgets and retention policies directly from your application or agent, using the same validation and versioning as the dashboard. - **System prompts** — `POST /api/v1/config/instructions` publishes and activates an instruction version. - **Saved tools** — `POST /api/v1/config/tools` publishes reusable tool definitions. - **Retention and truncation** — `POST /api/v1/config/retention` controls how history is replayed. - **Context budgets** — `POST /api/v1/config/budgets` configures history and compaction settings, with optional model-specific budgets. ### Start with a namespace Authenticate with `Authorization: Bearer `. Every read and change is restricted to the organisation associated with that key; another organisation's configuration version IDs return `404 not_found`. Set `namespace` in the publish body, or in the query string for listing and resolution. Omit it for organisation-wide scope. A chat inherits settings from the namespace chosen at creation. For example, publish instructions for one namespace: ```bash curl -X POST 'https://api.twigg.ai/api/v1/config/instructions' \ -H "Authorization: Bearer $TWIGG_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "namespace": "acme/proj-7", "mode": "append", "body": "You are a helpful support assistant. Ask before changing customer data." }' ``` ### Inspect, restore and track usage Read starting policies with `GET /api/v1/config/defaults`. Use `GET /api/v1/config/resolved` and `GET /api/v1/config/resolved-budget` to inspect the effective settings and their sources before changing anything. Configuration lists provide version history. The `/{id}/activate` operations restore a previous version; DELETE operations withdraw an override without deleting its history. Query namespace usage with `GET /api/v1/usage?range=7d&namespace=acme/proj-7`. This includes descendants within your organisation. Add `group_by=namespace` for a breakdown, or omit `namespace` for organisation-wide usage. Reports lag ingestion and may be cached for three minutes. ### Scope and request settings For budgets, an empty `model_ids` list selects the scope default; otherwise supply model UUIDs from the catalogue. Multi-model publishing applies each model separately, so a later failure can leave earlier models updated. Budgets control how much of a model's window is used, not its maximum window size. Per-request `tools` still apply only to that response request and override saved tools with the same name. `max_tokens` controls that request's output limit, not a persistent policy. Your application executes tool calls and returns the results. ### Keep it in a file To keep configuration in your repository and apply it from CI, use the `@twigg/cli` package: declare instructions, tools, budgets and retention per namespace in `twigg.config.yaml` (or `.json`, `.ts`), then run `npx twigg config plan` to review the changes and `npx twigg config apply` to publish them. `npx twigg config pull` writes what is configured today. See [SDKs](https://twigg.ai/docs/sdks#cli). See the [API reference](https://twigg.ai/docs/api) for every endpoint and schema. You can also manage these settings in [Dashboard → Configuration](https://twigg.ai/dashboard/configuration). API-key clients use `/api/v1/config`; dashboard routes under `/v1/config` remain session-authenticated.