How compaction works
Compaction is how Buffaly reduces old session timeline context while preserving enough information for the Buffaly agent to continue long-running work safely.
Use this page when a session was shortened, context grew too large, provider-backed compaction needs configuration, or you need recovery evidence before continuing work.
Quick answer
Compaction is timeline housekeeping for long sessions. It is not deleting all history, and it is not a replacement for durable artifacts, task files, committed changes, or validation evidence.
What compaction does
A session accumulates user messages, assistant messages, tool calls, tool results, lifecycle rows, and final answers. Compaction reduces the active context that must be replayed into the next turn.
It should preserve
- Recent and boundary context.
- Current goal, phase, blockers, and next step.
- Enough summary to continue safely.
It should not replace
- Task artifacts, Plan, or Scratch.
- Committed source or wiki files.
- Validation after resuming.
If a detail must survive compaction, ask Buffaly to write it to the right durable place: a task artifact, Plan.md, Scratch.md, a committed source file, or another explicit artifact.
When compaction runs
Source behavior shows two important paths: manual compaction through a session compaction workflow, and host recovery when a provider reports context pressure such as compaction needed, context_length_exceeded, or context length.
Do not assume every installation compacts at the same moment. Ask Buffaly to inspect the configured compaction feature, running session status, token counts, and recent lifecycle rows.
Settings and thresholds
| Setting | Verified meaning |
|---|---|
| MaxConversationTokens | Maximum conversation token budget; defaults to 100000 if less than or equal to zero. |
| TriggerTokens | Token count where compaction should be considered; capped to MaxConversationTokens. |
| TargetFreeTokens | Desired free-token amount after compaction, with lower and upper bounds. |
| TargetConversationTokens | Computed target active conversation size after compaction. |
| CompactionEngine | Provider-kind string. It must exactly match the enum token and casing. |
CompactionEngine values fail fast. Use exact values such as LocalAutomatic.Provider options
Provider kind controls whether compaction is local and deterministic or provider-backed. The source names these provider kinds; it does not mean every provider is configured or healthy in every installation.
LocalAutomatic
Default local deterministic engine.
LocalManual
Manual local provider path; verify in the running instance.
ResponsesApi
Provider-backed option; verify provider credentials and model behavior.
CodexApi
Codex-backed option; verify Codex backend credentials and provider state.
How to configure compaction safely
- Inspect current
Compaction Featuresettings from the running environment. - Confirm
CompactionEngineexactly matchesLocalAutomatic,LocalManual,ResponsesApi, orCodexApi. - Confirm token thresholds fit the active model/backend.
- For provider-backed modes, verify provider credentials separately.
- Back up current settings when supported before applying changes.
- Inspect lifecycle/status evidence after triggering or waiting for compaction.
How to verify compaction ran
Ask for verified evidence rather than a status guess.
- Lifecycle rows or logs mentioning compaction start, success, or failure.
- Status fields such as original/compacted message counts and token counts.
- Archive snapshot path for the pre-compaction epoch.
- Advanced compaction epoch or reset token usage.
- Intact Plan, Scratch, task artifacts, and session artifacts.
Session history and artifacts
| Layer | Relationship to compaction |
|---|---|
| Timeline | Compaction works on timeline rows and may summarize older middle detail. |
| Session history | History/search tools can recover details no longer active in context. |
| Artifacts | Session files remain durable evidence users can inspect. |
| Plan/Scratch/Tasks | These preserve route, working notes, and acceptance criteria. |
| Repository/wiki files | Final deliverables should be written and committed outside session artifacts when assigned. |
Failure modes and recovery
Context length errors
Preserve Plan, Scratch, and task state before compacting or recovering.
Stalled compaction
Inspect worker status, lifecycle rows, logs, provider/auth state, and archive snapshots.
Provider failure
Verify provider credentials/backend before changing thresholds; consider LocalAutomatic for recovery.
Missing context after resume
Re-read task artifacts, Plan, Scratch, session artifacts, commits, and relevant session history.