Smart Compaction & Checkpoints
Relevant source files
The following files were used as context for generating this wiki page:
Smart Compaction is a context management system designed to preserve critical session state, decisions, and progress across lossy LLM context compaction events. While standard compaction often loses nuanced reasoning or specific file states, Smart Compaction utilizes a system of hooks and checkpoints to ensure continuity and state recovery. Sources: optimization-checklist.md:364-375, coaching-scripts.md:144-150
This system operates by capturing a structured markdown checkpoint of the session state immediately before a compaction event occurs. These checkpoints are stored locally and re-injected into the fresh context after compaction completes, effectively bridging the gap between a bloated history and a lean, reset context window. Sources: optimization-checklist.md:377-385, SKILL.md:214-222
Architecture and Hook Integration
The Smart Compaction system relies on a sequence of lifecycle hooks to manage the lifecycle of a checkpoint. These hooks are triggered by the environment (e.g., Claude Code) during specific session events. Sources: implementation-playbook.md:149-165, optimization-checklist.md:377-383
Lifecycle Flow
The following diagram illustrates how Smart Compaction interacts with the session lifecycle to maintain state:
The diagram shows the transition from an active session through a compaction trigger, the capture of state, and the subsequent restoration of that state into the new context window. Sources: optimization-checklist.md:377-383, SKILL.md:214-222
Components of Smart Compaction
The system is composed of several functional parts:
- PreCompact Hook: Captures decisions, files, errors, and agent state into a markdown file. Sources: optimization-checklist.md:377-380
- SessionStart Hook: Restores state post-compact by injecting the checkpoint. Sources: optimization-checklist.md:381-382
- Checkpoints Directory: Stored at
~/.claude/token-optimizer/checkpoints/. It is auto-cleaned, keeping either the last 50 checkpoints or those from the last 7 days. Sources: optimization-checklist.md:386 - Compact Instructions: A specific section in
CLAUDE.mdor.claude/settings.jsonthat guides the LLM on what content must survive the compaction process. Sources: implementation-playbook.md:218-230
Checkpoint Data Model
Checkpoints are structured markdown snapshots of the current work state. They typically include several key fields to ensure the LLM understands the project's current status upon resumption. Sources: optimization-checklist.md:377-380, implementation-playbook.md:220-227
| Field | Description | Source |
|---|---|---|
| Task Context | Description of the current high-level goal and progress. | implementation-playbook.md:221 |
| Active Decisions | Nuanced "why" behind specific architectural or logic choices. | implementation-playbook.md:224 |
| Modified Files | Paths to files currently being edited and their specific state. | implementation-playbook.md:222 |
| Error/Test State | Recent error sequences or test results to prevent repeat failures. | implementation-playbook.md:223 |
| Agent State | Metadata about subagents dispatched during the session. | optimization-checklist.md:378 |
Session Continuity: Cold-Resume-Lean
A specialized extension of the checkpoint system is the Cold-Resume-Lean feature. This allows for reopening forgotten or "cold" sessions cheaply without using a full --resume command, which avoids expensive cache-rewrites. Sources: SKILL.md:211-218
Functionality
- Selection: If a user names a topic, a keyword-match winner is used. If vague, the most recent same-project session is selected. Sources: SKILL.md:219-221
- Token-Free Reconstruction: The process reads local checkpoints and session logs only, avoiding LLM subprocess costs during the reconstruction phase. Sources: SKILL.md:222-224
- Project Isolation: Continuity is limited to same-project files based on path-prefix vs CWD, preventing cross-project data leaks. Sources: SKILL.md:225
Manual Controls
Users can interact with cold sessions via CLI commands:
# List cold sessions
python3 $MEASURE_PY resume-lean
# Print the lean block for a specific session
python3 $MEASURE_PY resume-lean <session_id> --print
Sources: SKILL.md:228-229
Implementation and Configuration
Implementation of Smart Compaction requires both hook installation and the configuration of specific instructions for the LLM. Sources: optimization-checklist.md:387-391
Setup Procedure
- Installation: Run
python3 $MEASURE_PY setup-smart-compactto install the necessary hooks. Sources: optimization-checklist.md:389 - Instruction Generation: Run
python3 $MEASURE_PY compact-instructionsto generate project-specific guidance. Sources: optimization-checklist.md:390 - Configuration: Add the generated output to
.claude/settings.jsonunder thecompactInstructionskey. Sources: optimization-checklist.md:391
Compact Instructions Template
The instructions guide the LLM's behavior during the actual compaction event to ensure it produces a useful summary:
## Compact Instructions
When compacting this conversation, always preserve:
- Current task context and progress
- File paths being modified and their state
- Test results and error messages
- Active constraints and decisions made
- User preferences expressed in this session
Sources: implementation-playbook.md:221-227
Conclusion
Smart Compaction and Checkpoints represent a critical advancement in session management, moving from simple token reduction to quality-aware state preservation. By leveraging lifecycle hooks to capture structured snapshots, the system prevents information loss during compaction and enables "lean" session resumes, significantly extending the productive life of a single context window. Sources: optimization-checklist.md:392-395, coaching-scripts.md:151-158