Manage long conversations

Every model has a context window, and long-running sessions eventually fill it. A conversation that has been going all afternoon, or an agent that just pulled back three enormous tool results, will push the earliest turns toward the edge.

AXL handles this for you. It preserves session history and compacts it when the conversation outgrows the window. Most agents never need to think about this - the defaults are reasonable, and the failure mode you are trying to avoid (recent conversation crowded out by a giant tool result from twenty minutes ago) is exactly what they are tuned against.

Tune it when large tool results or very long sessions start to crowd out recent turns:

Tool results

Large tool output is the usual reason a conversation fills up. In agent.toml:

[context]
tool_result_budget_chars = 100000   # collapsible tool output to accumulate before reclaiming; 0 (the default) is off
keep_recent_results = 6             # newest results always kept whole

Older results are collapsed before any compaction runs. The budget governs how much collapsible output accumulates first: results inside keep_recent_results are never touched and never count toward it. Once the collapsible remainder passes the budget, a single pass takes it down to half, so one pass covers many steps.

Set the budget well above a single tool result. Collapsing rewrites history, which costs the whole cached prompt prefix, so a budget near one result's size pays that on nearly every step.

The system prompt is built for the same cache: everything stable sits in a prefix, and the first thing past the stable boundary is a UTC current-date line - without one, a model guesses today's date from its training data. It is date-only, so it churns the cached prefix at most once a day.

Compaction

When the conversation approaches the window, older turns are summarized to free space. It fires predictively, before the next call would overflow, and summaries are incremental: a later compaction merges into the prior summary rather than re-summarizing from scratch.

compaction.toml beside agent.toml, all fields optional:

threshold             = 0.85   # fraction of the window that triggers it; 0.0 disables
preserve_recent_turns = 4      # recent turns kept verbatim (minimum 1)
summary_max_tokens    = 4096   # cap on the summary itself (minimum 256)
chars_per_token       = 4.0    # estimate used for the budget prediction

Lower threshold to compact sooner and leave more headroom. Raise preserve_recent_turns when the agent keeps losing the thread of what was just said.

threshold also sets how much history is loaded per turn: the loader's window is derived from it and always sits above it, so compaction is what bounds a long session. Compaction summarizes what it removes and persists the result, which leaves stored history append-only between compactions - and an append does not disturb the prompt cache, where re-reading history costs a fraction of resending it. A loader that trimmed first would instead drop the oldest turn outright, hold the total below compaction's trigger so it never fired, and move the start of the conversation on every request.

Watching it happen

Compaction emits data-compaction events on the session stream, and the rewritten transcript is what GET /history returns afterwards. If an agent seems to forget something mid-conversation, those two together show what was summarized away.

Context files

*.context.md files hold instructions that should always be present. They inherit down the directory tree, so a file at agents/support/support.context.md applies to every agent beneath that directory - a place for a shared tone of voice or a house style.

What belongs where

Good context is durable and broadly applicable. The rule of thumb:

Instructions that apply to every run go in a context file.
Facts about a specific person go in memory.
Searchable knowledge goes in RAG.
Procedures the agent only sometimes needs go in skills.

Putting a large document in a context file works, but it is expensive, and it competes for room with the conversation the user is actually having.

Give an agent memory - the per-user half of remembering things.
Add reusable skills - detailed instructions loaded only when relevant.
- exact fields and defaults.