Context and compaction
Context assembly selects the content supplied to generation. Compaction changes that input independently of the run outcome and the stored conversation history.
Context from the latest user message
The current generation path takes client context from the latest user message. Resend relevant current context on each user message that needs it; an earlier message is not a persistent context setting.
append-message stores a message without starting generation. If a subsequent user message becomes the latest one, its context is the one considered for generation. Appending context does not guarantee that the next reply will use it.
History strategies
Three strategies control how message history is trimmed before each generation: CONTEXT_STRATEGY_WINDOWING (default, drops old messages), CONTEXT_STRATEGY_COMPACTION (summarizes old messages, keeping the gist), and CONTEXT_STRATEGY_NONE (full history). Selective exclusion of images, files, tool results, and reasoning composes with any strategy.
For threshold calculations, modes, pending records and failure effects, use the compaction semantics and failure behavior below. The context-management guide walks through a compaction task.
Pending compaction records
compactionInProgress: true means a compaction is recorded as pending. It can be queued, running or stale. Inspect the record and reconcile within a bounded wait; neither this flag nor conversation inactivity proves completion.
Live compaction updates (Preview)
If your deployment has a supported conversation update transport, use CompactionStarted, CompactionCompleted and CompactionFailed as cues to refresh the compaction record. These events appear on conversations/{id}/compaction; see streaming availability.
Compaction failure effects
| Mode | Failure effect |
|---|---|
COMPACTION_MODE_SYNC | The send call fails. No generation runs. Retry the send after the underlying issue is resolved. |
COMPACTION_MODE_ASYNC | The current turn proceeds with uncompacted context and can succeed or fail independently. The failure is visible via compactions[].status = "COMPACTION_STATUS_FAILED" and the CompactionFailed realtime event (Preview). |
For a synchronous failure, resolve the summarizer/configuration problem before retrying the rejected send. For an asynchronous failure, first inspect the original run because that turn can still have completed. Do not resend a user question merely to retry background compaction.
Strategy updates
Use windowing when the customer no longer needs older details in later replies. It avoids a summarizer call and excludes older messages from model input; its default window is 100 messages.
Choose before storing an explicit strategy: the current update path rejects switching to another strategy. Updates within the selected strategy are separate. Use the settings reference to configure the chosen path.
Compaction threshold estimates
Use the context settings reference for exact configuration fields. The estimate uses the latest available assistant usage.promptTokens plus estimates for newer content. Until usage is available, it falls back to roughly four characters per token, 1,000 tokens per image and size-based file/audio estimates.
A percentage threshold uses the resolved model window, with a current 128,000-token fallback when positive metadata is unavailable. That fallback is not proof of the actual provider limit. The threshold is checked before generation after applying the selected strategy and does not include every later request change. Changed prompts, tools or models can also make an earlier measured count a poor predictor.
Synchronous and asynchronous compaction
Synchronous compaction finishes the summary and reassembles context before generation, so the next answer waits for the summary. The compaction recipe uses this mode when the answer needs the new summary.
Use COMPACTION_MODE_ASYNC only when the current answer can use uncompacted context. Inspect that run independently and wait for the compaction record before assuming a later turn has a summary. Background acceptance does not promise uninterrupted concurrent messaging; compaction can still delay other messages.
Stale pending compactions
A compaction stuck in COMPACTION_STATUS_PENDING for more than 10 minutes is marked COMPACTION_STATUS_FAILED on the next send. Refresh its record before deciding whether another compaction is needed; pending does not necessarily mean it is still running.
Content exclusion
selectiveExclusionConfig strips specific content types from the assembled context before it is sent to the model. It composes with any strategy — including NONE — and is applied per-request. It never mutates stored message history.
Excluding tool results removes resultJson while retaining the call. Excluding an image can leave an empty message, which is then omitted from model input. Files and reasoning can also be excluded; use the settings reference for those options.