Compaction and project memory

A long session eventually fills the context window. Compaction compresses old history into a summary instead of truncating it, so the decisions and constraints in that history stay available to the model. At any moment a long session holds three records: the goal (when enabled), the recent transcript verbatim, and the compacted history behind it.

Context compaction

Primary compaction knobs (settings → Models → Compaction, or config.yml):

• Threshold (compaction.threshold): when auto-compaction runs. The unit is part of the value:

  • auto (the default) triggers at the model’s context window minus the reserve, so it adapts to whatever model you are on.
  • 85% is a percent of the current model’s window, so the trigger moves with the model.
  • 170000 is an absolute token amount and triggers at the same point on every model. When the amount is larger than the current model’s window it is honored up to one token below the window and you get a warning (once per model context window, so switching to a smaller-window model warns again).

  You can also compact on demand with /compact.

• Type (compaction.strategy): summary, the sole strategy. It rewrites old history into an in-place LLM summary on the current branch.

• Model (compaction.model): the models that perform LLM compaction, tried in order. Unset uses your interactive model. See Fallback models and Models, helpers, and profiles.

/compact <focus> steers a run with an “Additional focus:” directive. The most recent user, assistant, and tool messages stay verbatim up to compaction.keepRecentTokens (default 10,000 tokens).

Use /handoff <focus> when you explicitly want a new session. Handoff is not a compaction strategy, and automatic maintenance never selects it.

Compaction and handoff both append a <files> block that lists the files read and modified. The block is generated from the session messages, not by the model, so it is identical whichever model wrote the summary. Handoff also writes the todo list into the replacement session as a persisted todo entry, so reopening that session restores it.

Stored legacy strategy names such as handoff, snap, soft, and remote migrate to summary. A legacy off value also disables compaction.

Fallback models

compaction.model is an ordered list, not one model:

compaction:
  model: anthropic/claude-opus-4-1,anthropic/claude-sonnet-4-5,anthropic/claude-haiku-4-5

Compaction tries the first entry. If you are not signed in to it, or its context window cannot hold the history being summarized, veyyon moves on to the second, then the third. A single model is written as a plain value (model: anthropic/claude-sonnet-4-5). In /settings, the compaction model row is the same list: add a fallback, and press Enter on any entry to move it up.

Falling back is never quiet. When compaction runs on anything other than your first choice, you get a warning in the session stating both models and the reason:

Compacted with anthropic/haiku-4-5. anthropic/opus-4-1 was skipped: it is not authenticated.

You see that once per distinct reason, not once per compaction.

compaction.modelFallbackStrategy sets what happens after your list runs out:

• auto (the default) stays on models you named: your main model, the same-provider compaction sibling its catalog row recommends, then your defaultModel.
• any-model keeps going past those to the largest context window you have credentials for, whichever provider that is. Compaction almost never fails, at the cost of summarizing on a provider you did not choose for this session and being billed for it there.
• configured-only stops at the models you listed. Compaction fails with the reason instead. Use it when summary quality takes priority over the session continuing.

With compaction.model unset, configured-only means your interactive model and nothing else.

Compaction fires unattended, so any-model is the one setting here that can spend money on an account you were not using: a session on one provider can summarize on another provider’s key and report that provider’s billing error as a compaction failure.

Shake and duplicate elision

Shake is a lighter reducer than compaction. Instead of summarizing history, it drops heavy content out of the live context and leaves a short placeholder in its place. Whole tool results and large fenced or XML blocks are replaced with a marker such as [shaken ~1200 tokens; recover: artifact://42 (region 3)]. The full text is saved as a session artifact first, so you can always read it back with read artifact://42. Nothing is lost; the content is no longer resent on every turn. Run it on demand with /shake.

Shake also removes redundancy. When you read the same unchanged file twice, or run the same command twice and get the same output, every copy but the newest contains no new information. Shake finds each earlier tool result whose tool, arguments, and output are identical to a later one, and elides the earlier copies through the same artifact path. The newest copy stays in place. This runs even for recent results that the size-based pass would otherwise keep, because a duplicate is redundant however recent it is. Results from a protected tool (such as skill), error results, and results already elided are never deduplicated.

The match is exact. If a command’s output changes between runs, both runs are kept, because the later one is new information rather than a repeat.

Duplicate elision runs on its own before in-place compaction. Whenever automatic maintenance runs because context crossed the threshold or overflowed, it first runs this lossless Tier-0 pass. If dropping duplicates brings a threshold trigger back under the bar, compaction is skipped and history stays intact apart from the elided copies. Overflow recovery still finishes compaction because the prompt must be rebuilt to fit the window, but it starts from the smaller deduplicated history.

Memory backends

When memory.backend is mnemopi or hindsight, compaction can request pre-compaction context from the active memory backend so summaries retain project facts. See Memory.

Goals

Goal cards and budgets: /goal, /guided-goal, and the goal tool. Structure: Goal state and long sessions. Commands: Plan mode and goals.