Context management
Context management controls what Jazz sends to the model on each request: conversation messages, instructions, tool definitions, and tool results.
Each model has a context window, the amount of text it can receive in one request. As a conversation grows, Jazz makes room by removing older tool output and summarizing older messages. The agent’s saved work state keeps the task’s objective and decisions available.
Managing conversation history
Jazz manages context automatically. By default:
| Context used | Action |
|---|---|
| 50% | Replace older large tool results with retrieval pointers, keeping recent results intact |
| 70% | Warn that the context is filling and ask the agent to save its findings |
| 80% | Summarize older history while keeping system instructions, pinned messages, and recent exchanges |
| 95% | Trim older messages if the history still exceeds the limit |
These percentages use the model’s effective context window, lowered by the agent’s
llm.maxContextTokens when configured. The warning and compaction thresholds can be changed in
Jazz configuration.
Compaction replaces older exchanges with a summary so the agent can continue the same task.
Jazz shows when it happens. It uses an additional model call and can lose detail; llm.summarizerModel
selects the model for that call. The agent can also request compaction with summarize_context.
Trimming removes older messages without summarizing them. Jazz uses it when compaction cannot free enough space or the summarizer fails. Tool calls and their results stay paired, and Jazz tells you when history is discarded.
Keeping findings available
Work state records the task’s objective, decisions, open questions, and next step. Todos track progress and verification. Both survive compaction.
Jazz saves large tool outputs separately. When an older output is removed from context, or an
output is too long to show whole, the agent can read the saved copy a page at a time with
retrieve_tool_result. If saving failed, it must rerun the tool.
Use memory for facts needed across conversations and files or the scratchpad for longer drafts and research material.
Setting run limits
A run defaults to 100 iterations, where each iteration is a model call and any tools it requests.
Cost, token, and duration caps are unset until you configure them. Set limits globally,
in a workflow, or for one jazz run invocation.
Jazz warns the agent as its budgets fill, giving it time to consolidate findings and finish. Iteration, cost, and token limits are checked between iterations, so an in-flight call can cross them. A duration cap interrupts running work at its deadline.
See Budgets for configuration, enforcement, and spend reporting.
Detecting stalled work
Jazz monitors repeated tool calls. If fewer than 40% of the last ten calls have distinct
names and arguments, it asks the agent to change approach. If repetition continues through
another full window, Jazz stops the run and reports stalled: true in jazz run --json.
Calls with different arguments count as different work. This detects exact repetition; it may miss an agent repeating the same approach with slightly different arguments.
Continuing beyond a run
Goals continue an objective across successive turns. Remote handoff moves a conversation to your SSH server so it can continue after you close your laptop.
Adjust the context limit
For an agent that reads many large files, set llm.maxContextTokens in its config to compact
earlier. For example:
{ "llm": { "maxContextTokens": 64000 } }Choose a limit no larger than the model’s supported window. Earlier compaction reduces the history sent per request, but may require the agent to retrieve or reread more details. See Agent configuration for the full file format.