Class: ContextManager

Defined in: context/manager.ts:162

Manages the agent’s context window — tracks token usage, triggers compaction when the conversation grows too large, and ensures the agent never exceeds the model’s context limit.

The context window is divided into budgets:

  • System prompt (~15%) — always present, never compacted
  • Anchors/pins (~10%) — critical info that survives compaction
  • Conversation history (~75%) — compacted when budget exceeded

When conversation history exceeds its budget, the manager triggers smart windowing (3-zone compaction): recent messages preserved, middle messages summarized, old messages dropped.

Example

const agent = new Agent({
  provider,
  contextManager: new ContextManager({
    maxTokens: 100000,
    budgets: { system: 0.15, anchors: 0.10, conversation: 0.75 },
  }),
});

Constructors

Constructor

new ContextManager(options): ContextManager;

Defined in: context/manager.ts:182

Parameters

Parameter Type
options ContextManagerOptions

Returns

ContextManager

Methods

addToCategory()

addToCategory(category, tokens): void;

Defined in: context/manager.ts:429

Add tokens to a category

Parameters

Parameter Type
category ContextCategory
tokens number

Returns

void

canAddContent()

canAddContent(estimatedTokens, category): PreflightResult;

Defined in: context/manager.ts:892

Check if content can be added to a category

Returns a pre-flight result with recommendations for action.

Parameters

Parameter Type
estimatedTokens number
category ContextCategory

Returns

PreflightResult

categorizeMessages()

categorizeMessages(messages, preserveRecentTurns?): Promise<CategorizedMessages>;

Defined in: context/manager.ts:568

Categorize all messages by type for smart compaction

This method:

  1. Identifies system messages
  2. Separates recent messages (last N turns) that should never be compacted
  3. Identifies tool results in older messages
  4. Classifies remaining older messages as history

Parameters

Parameter Type Description
messages Message[] All messages to categorize
preserveRecentTurns? number Number of recent turns to preserve (default: config value)

Returns

Promise<CategorizedMessages>

categoryNeedsCompaction()

categoryNeedsCompaction(category): boolean;

Defined in: context/manager.ts:437

Check if a specific category needs compaction

Parameters

Parameter Type
category ContextCategory

Returns

boolean

checkAndWarn()

checkAndWarn(): void;

Defined in: context/manager.ts:1320

Check context and emit warning if needed

Returns

void

compact()

compact(messages, saveToFile): Promise<{
  messages: Message[];
  result: CompactionResult;
}>;

Defined in: context/manager.ts:1073

Compact old messages by replacing large content with file references

This is a placeholder - actual implementation requires file system access which will be provided by the Agent or CLI layer.

Parameters

Parameter Type
messages Message[]
saveToFile (content, index) => Promise<string>

Returns

Promise<{ messages: Message[]; result: CompactionResult; }>

compactCategory()

compactCategory(
   messages, 
   category, 
   saveToFile): Promise<{
  messages: Message[];
  result: CompactionResult;
}>;

Defined in: context/manager.ts:448

Compact only a specific category

This is more targeted than full compaction - only affects messages in the specified category, leaving others untouched.

Parameters

Parameter Type
messages Message[]
category ContextCategory
saveToFile (content, index) => Promise<string>

Returns

Promise<{ messages: Message[]; result: CompactionResult; }>

countTokens()

countTokens(messages): Promise<number>;

Defined in: context/manager.ts:224

Count tokens in messages using the provider

Parameters

Parameter Type
messages Message[]

Returns

Promise<number>

createRestorationHintMessage()

createRestorationHintMessage(): Message | undefined;

Defined in: context/manager.ts:370

Create a system message with context restoration hints. Returns undefined if no hints are available.

The caller (Agent) is responsible for injecting this message after compaction or summarization.

Returns

Message | undefined

estimateTokens()

estimateTokens(content): number;

Defined in: context/manager.ts:883

Estimate tokens for a string content

Parameters

Parameter Type
content string

Returns

number

filterContent()

filterContent(content, type): {
  content: string;
  filtered: boolean;
  originalLength: number;
};

Defined in: context/manager.ts:1006

Filter large content before adding to context

Returns the filtered content and metadata about what was done. The caller is responsible for saving to file if needed.

Parameters

Parameter Type
content string
type "tool_result" | "error" | "file"

Returns

{
  content: string;
  filtered: boolean;
  originalLength: number;
}
Name Type Defined in
content string context/manager.ts:1010
filtered boolean context/manager.ts:1011
originalLength number context/manager.ts:1012

findOverBudgetCategories()

findOverBudgetCategories(categorized): ContextCategory[];

Defined in: context/manager.ts:642

Find which categories are over their budget allocation

Parameters

Parameter Type Description
categorized CategorizedMessages Categorized messages from categorizeMessages()

Returns

ContextCategory[]

Array of categories that exceed their budget, sorted by how much they exceed

formatRestorationHints()

formatRestorationHints(): string;

Defined in: context/manager.ts:353

Format context restoration hints based on current verbosity level. Returns empty string if no file tracker is configured or no files have been accessed.

Returns

string

getAllBudgets()

getAllBudgets(): Record<ContextCategory, CategoryBudgetInfo>;

Defined in: context/manager.ts:408

Get budget information for all categories

Returns

Record<ContextCategory, CategoryBudgetInfo>

getCategoryBudget()

getCategoryBudget(category): CategoryBudgetInfo;

Defined in: context/manager.ts:389

Get budget information for a specific category

Parameters

Parameter Type
category ContextCategory

Returns

CategoryBudgetInfo

getConfig()

getConfig(): ContextConfig;

Defined in: context/manager.ts:338

Get the current configuration

Returns

ContextConfig

getFileTracker()

getFileTracker(): FileAccessTracker | undefined;

Defined in: context/manager.ts:345

Get the file access tracker (if configured)

Returns

FileAccessTracker | undefined

getMaxTokens()

getMaxTokens(): number;

Defined in: context/manager.ts:258

Get maximum context tokens

Returns

number

getStats()

getStats(messageCount): ContextStats;

Defined in: context/manager.ts:323

Get context statistics

Parameters

Parameter Type
messageCount number

Returns

ContextStats

getTokenCount()

getTokenCount(): number;

Defined in: context/manager.ts:244

Get current token count (cached)

Returns

number

getTurnCount()

getTurnCount(): number;

Defined in: context/manager.ts:272

Get the current turn count

Returns

number

getUtilization()

getUtilization(): number;

Defined in: context/manager.ts:251

Get context utilization (0.0 - 1.0)

Returns

number

getVerbosityLevel()

getVerbosityLevel(): VerbosityLevel;

Defined in: context/manager.ts:967

Get current verbosity level based on context utilization

Tools should adapt their output based on this level.

Returns

VerbosityLevel

incrementTurn()

incrementTurn(): void;

Defined in: context/manager.ts:265

Increment turn count (call after each assistant response)

Returns

void

isMinimalMode()

isMinimalMode(): boolean;

Defined in: context/manager.ts:985

Check if we’re in minimal mode (critical context pressure)

Returns

boolean

needsCompaction()

needsCompaction(): boolean;

Defined in: context/manager.ts:291

Check if compaction is needed

Returns

boolean

needsEmergencySummarization()

needsEmergencySummarization(): boolean;

Defined in: context/manager.ts:992

Check if emergency summarization is needed

Returns

boolean

needsSummarization()

needsSummarization(): boolean;

Defined in: context/manager.ts:309

Check if summarization is needed (more aggressive than compaction)

Returns

boolean

reset()

reset(): void;

Defined in: context/manager.ts:1341

Reset context manager state (for new conversations)

Returns

void

setTurnCount()

setTurnCount(count): void;

Defined in: context/manager.ts:279

Set the turn count (for restoring from saved state)

Parameters

Parameter Type
count number

Returns

void

shouldFilter()

shouldFilter(tokenCount): boolean;

Defined in: context/manager.ts:316

Check if content should be filtered before adding

Parameters

Parameter Type
tokenCount number

Returns

boolean

smartCompact()

smartCompact(messages, options): Promise<{
  messages: Message[];
  result: SmartCompactionResult;
}>;

Defined in: context/manager.ts:676

Smart compaction that respects category budgets

Strategy:

  1. System messages: Never compacted (critical for agent behavior)
  2. Recent messages: Never compacted (needed for conversation continuity)
  3. Tool results: Save large results to files, replace with references
  4. History: Summarize with LLM

The method compacts categories in order of how much they exceed their budget.

Parameters

Parameter Type
messages Message[]
options SmartCompactOptions

Returns

Promise<{ messages: Message[]; result: SmartCompactionResult; }>

summarize()

summarize(messages, generateSummary): Promise<{
  messages: Message[];
  result: SummarizationResult;
}>;

Defined in: context/manager.ts:1155

Summarize conversation history

This is a placeholder - actual implementation requires LLM call which will be orchestrated by the Agent layer.

Parameters

Parameter Type
messages Message[]
generateSummary (messages) => Promise<string>

Returns

Promise<{ messages: Message[]; result: SummarizationResult; }>

summarizeWithRetry()

summarizeWithRetry(
   messages, 
   generateSummary, 
   options?): Promise<{
  messages: Message[];
  result: SummarizationResult;
}>;

Defined in: context/manager.ts:1218

Summarize with support for multiple rounds and emergency mode

Will perform multiple summarization rounds if needed to reach target utilization. Throws ContextOverflowError if unable to reduce context sufficiently.

Parameters

Parameter Type
messages Message[]
generateSummary (messages) => Promise<string>
options? { emergency?: boolean; maxRounds?: number; targetUtilization?: number; }
options.emergency? boolean
options.maxRounds? number
options.targetUtilization? number

Returns

Promise<{ messages: Message[]; result: SummarizationResult; }>

updateCategoryUsage()

updateCategoryUsage(category, tokens): void;

Defined in: context/manager.ts:420

Update token usage for a category

Parameters

Parameter Type
category ContextCategory
tokens number

Returns

void

updateTokenCount()

updateTokenCount(messages): Promise<number>;

Defined in: context/manager.ts:236

Update token count for messages

Parameters

Parameter Type
messages Message[]

Returns

Promise<number>