Checkpoint History & Token Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Checkpoint History and Token Management system is the core architectural component responsible for managing the conversation state and context window efficiency of the AI agent. It ensures that the agent maintains a persistent and accurate record of interactions while proactively managing the Large Language Model's (LLM) token limits through advanced compaction, pruning, and summarization strategies. Sources: packages/harness/src/checkpoint-history.ts, AGENTS.md:47-49
This system enables the agent to handle long-running sessions by dynamically "compacting" older parts of the conversation into summaries. This process allows the agent to retain critical context, such as user profiles, technical discoveries, and current goals, without exceeding the fixed context window of the underlying model. Sources: packages/harness/src/checkpoint-history.ts:476-485, packages/harness/src/compaction-prompts.ts:10-30
Core Architecture
CheckpointHistory Class
The CheckpointHistory class serves as the primary manager for message persistence and context analysis. It maintains an internal list of CheckpointMessage objects, which include metadata such as unique IDs, timestamps, and summary flags. Sources: packages/harness/src/checkpoint-history.ts:182-205, packages/harness/src/compaction-types.test.ts:46-55
The diagram illustrates the CheckpointHistory class structure and its relationship with individual checkpoint messages.
Sources: packages/harness/src/checkpoint-history.ts:182-205
Message Lifecycle and Persistence
Messages added to the history are assigned a unique UUID and a timestamp. If a SessionStore is provided, messages are automatically persisted to a JSONL file format, allowing for session recovery and hydration. Sources: packages/harness/src/checkpoint-history.ts:223-238, packages/harness/src/checkpoint-history.ts:1175-1191
| Function | Role | Data Source |
|---|---|---|
addUserMessage | Adds a user turn; supports original content for translations. | checkpoint-history.ts:254-269 |
addModelMessages | Adds assistant/tool turns; validates tool call/result sequences. | checkpoint-history.ts:271-295 |
hydrateMessages | Restores history from a list of persisted MessageLine objects. | checkpoint-history.ts:1208-1221 |
Token and Context Management
Usage Tracking
The system tracks context usage through two modes: estimated and actual.
- Estimated: Uses a heuristic-based token counter (
estimateTokens) to calculate usage when provider feedback is unavailable. Sources: packages/harness/src/token-utils.ts:5-15, packages/harness/src/checkpoint-history.ts:422-430 - Actual: Updates internal state based on
inputTokensandoutputTokensreported by the AI SDK after a completion. Sources: packages/harness/src/checkpoint-history.ts:344-370
Compaction Strategy
Compaction is the process of summarizing history to free up tokens. It follows a multi-stage logic:
- Trigger Check: Evaluates if the
currentUsageTokensexceed thethresholdRatioof thecontextLimit. Sources: packages/harness/src/checkpoint-history.ts:446-465 - Split Selection: Identifies a "split point" in the history, ensuring that tool-call and tool-result pairs are not separated. Sources: packages/harness/src/checkpoint-history.ts:983-1010
- Summarization: Uses a specialized summarizer (LLM-based or session-memory based) to create a structured summary. Sources: packages/harness/src/checkpoint-history.ts:476-520, packages/harness/src/compaction-prompts.ts:10-30
The flow of the compaction trigger and execution logic.
Sources: packages/harness/src/checkpoint-history.ts:446-550
Overflow Recovery
When the context limit is hard-reached (e.g., a massive tool result), the system triggers handleContextOverflow. This initiates a sequence of recovery strategies:
- Pruning: Aggressively strips large tool outputs using
pruneToolOutputs. Sources: packages/harness/src/checkpoint-history.ts:758-795 - Compaction: Runs a standard compaction cycle. Sources: packages/harness/src/checkpoint-history.ts:805-812
- Aggressive Compaction: Summarizes almost all active history. Sources: packages/harness/src/checkpoint-history.ts:814-821
- Truncation: The "nuclear option" that removes the oldest messages regardless of summaries until the budget is met. Sources: packages/harness/src/checkpoint-history.ts:1120-1160
Data Models and Configuration
Compaction Configuration
Compaction behavior is governed by the CompactionConfig interface. Sources: packages/harness/src/compaction-types.test.ts:105-180
| Option | Type | Default | Description |
|---|---|---|---|
contextLimit | number | 0 | Hard token limit for the context window. |
keepRecentTokens | number | 2000 | Minimum tokens to preserve at the end of history. |
reserveTokens | number | 2000 | Tokens reserved for the model's next response. |
thresholdRatio | number | 0.5 | Usage percentage that triggers auto-compaction. |
summarizeFn | Function | undefined | The callback used to generate summary text. |
CheckpointMessage Structure
Each message in history is wrapped in a metadata container. Sources: packages/harness/src/compaction-types.test.ts:46-75
export interface CheckpointMessage {
id: string; // Unique UUID
createdAt: number; // Timestamp in MS
isSummary: boolean; // True if the message represents a summary
isSummaryMessage?: boolean; // True for the actual assistant summary text
message: ModelMessage; // The underlying role and content (Vercel AI SDK)
originalContent?: string; // Optional raw input for translation tasks
}
Sources: packages/harness/src/compaction-types.test.ts:46-75
Conclusion
The Checkpoint History and Token Management system provides the resilience required for complex, multi-turn AI interactions. By combining surgical pruning of large data structures with semantic summarization of conversational flow, it ensures that the agent's context remains relevant and manageable, preventing the "forgetting" or "crashing" behaviors typically associated with token limit exhaustion in large-scale LLM applications. Sources: packages/harness/src/checkpoint-history.ts:1223-1268, packages/harness/src/checkpoint-history-edge-cases.test.ts:450-480