oneringaiv2
Documentation/Context Management
v2.0.0-beta.1Snapshot bebdcd1Markdown ↗

Context Management

Context Management

Manage context windows and compaction strategies

ApproximateTokenEstimator class

📍 src/infrastructure/context/estimators/ApproximateEstimator.ts:14

Methods

estimateTokens()

Estimate tokens for text with content-type awareness

typescript
estimateTokens(text: string, contentType: TokenContentType = 'mixed'): number

Parameters:

  • text: string
  • contentType: TokenContentType (optional) (default: 'mixed')

Returns: number

estimateDataTokens()

Estimate tokens for structured data (always uses 'mixed' estimation)

typescript
estimateDataTokens(data: unknown, contentType: TokenContentType = 'mixed'): number

Parameters:

  • data: unknown
  • contentType: TokenContentType (optional) (default: 'mixed')

Returns: number

estimateImageTokens()

Estimate tokens for an image using tile-based model (matches OpenAI pricing).

  • detail='low': 85 tokens
  • detail='high' with known dimensions: 85 + 170 per 512×512 tile
  • Unknown dimensions: 1000 tokens (conservative default)
typescript
estimateImageTokens(width?: number, height?: number, detail?: string): number

Parameters:

  • width: number | undefined (optional)
  • height: number | undefined (optional)
  • detail: string | undefined (optional)

Returns: number

SummarizeCompactor class

📍 src/infrastructure/context/compactors/SummarizeCompactor.ts:108

SummarizeCompactor - LLM-based context compaction

Uses AI to intelligently summarize content, preserving semantic meaning while significantly reducing token count.

Constructor

constructor

typescript
constructor(estimator: ITokenEstimator, config: SummarizeCompactorConfig)

Parameters:

  • estimator: ITokenEstimator
  • config: SummarizeCompactorConfig
Methods

canCompact()

Check if this compactor can handle the component

typescript
canCompact(component: IContextComponent): boolean

Parameters:

  • component: IContextComponent

Returns: boolean

compact()

Compact the component by summarizing its content

typescript
async compact(
    component: IContextComponent,
    targetTokens: number
  ): Promise<IContextComponent>

Parameters:

  • component: IContextComponent
  • targetTokens: number

Returns: Promise<IContextComponent>

estimateSavings()

Estimate how many tokens could be saved by summarization

typescript
estimateSavings(component: IContextComponent): number

Parameters:

  • component: IContextComponent

Returns: number

Properties
Property Type Description
name name: "summarize" -
priority priority: 5 -

TruncateCompactor class

📍 src/infrastructure/context/compactors/TruncateCompactor.ts:11

Constructor

constructor

typescript
constructor(private estimator: ITokenEstimator)

Parameters:

  • estimator: ITokenEstimator
Methods

canCompact()

typescript
canCompact(component: IContextComponent): boolean

Parameters:

  • component: IContextComponent

Returns: boolean

compact()

typescript
async compact(component: IContextComponent, targetTokens: number): Promise<IContextComponent>

Parameters:

  • component: IContextComponent
  • targetTokens: number

Returns: Promise<IContextComponent>

estimateSavings()

typescript
estimateSavings(component: IContextComponent): number

Parameters:

  • component: IContextComponent

Returns: number

Properties
Property Type Description
name name: "truncate" -
priority priority: 10 -

CompactionResult interface

📍 src/core/context/utils/ContextUtils.ts:76

Result of a compaction operation

Properties
Property Type Description
components components: IContextComponent[]; Updated components after compaction
log log: string[]; Log of compaction actions taken
tokensFreed tokensFreed: number; Total tokens freed

ContextBudget interface

📍 src/core/context/types.ts:28

Context budget information

Properties
Property Type Description
total total: number; Total available tokens
reserved reserved: number; Reserved tokens for response
used used: number; Currently used tokens
available available: number; Available tokens remaining
utilizationPercent utilizationPercent: number; Utilization percentage (used / (total - reserved))
status `status: 'ok' 'warning'
breakdown breakdown: Record<string, number>; Token breakdown by component

ContextManagerConfig interface

📍 src/core/context/types.ts:71

Context manager configuration

Properties
Property Type Description
maxContextTokens maxContextTokens: number; Maximum context tokens for the model
compactionThreshold compactionThreshold: number; Threshold to trigger compaction (0.0 - 1.0)
hardLimit hardLimit: number; Hard limit - must compact before this (0.0 - 1.0)
responseReserve responseReserve: number; Reserve space for response (0.0 - 1.0)
estimator `estimator: 'approximate' 'tiktoken'
autoCompact autoCompact: boolean; Enable automatic compaction
strategy? `strategy?: 'proactive' 'aggressive'
strategyOptions? strategyOptions?: Record<string, unknown>; Strategy-specific options

IContextCompactor interface

📍 src/core/context/types.ts:184

Abstract interface for compaction strategies

Methods

canCompact()

Check if this compactor can handle the component

typescript
canCompact(component: IContextComponent): boolean;

Parameters:

  • component: IContextComponent

Returns: boolean

compact()

Compact the component to target size

typescript
compact(component: IContextComponent, targetTokens: number): Promise<IContextComponent>;

Parameters:

  • component: IContextComponent
  • targetTokens: number

Returns: Promise<IContextComponent>

estimateSavings()

Estimate savings from compaction

typescript
estimateSavings(component: IContextComponent): number;

Parameters:

  • component: IContextComponent

Returns: number

Properties
Property Type Description
name readonly name: string; Compactor name
priority readonly priority: number; Priority order (lower = run first)

IContextComponent interface

📍 src/core/context/types.ts:8

Core types for context management system

Properties
Property Type Description
name name: string; Unique name for this component
content `content: string unknown;`
priority priority: number; Priority for compaction (higher = compact first)
compactable compactable: boolean; Whether this component can be compacted
metadata? metadata?: Record<string, unknown>; Additional metadata for compaction strategies

IContextStrategy interface

📍 src/core/context/types.ts:210

Context management strategy - defines the overall approach to managing context

Methods

shouldCompact()

Decide if compaction is needed based on current budget

typescript
shouldCompact(budget: ContextBudget, config: ContextManagerConfig): boolean;

Parameters:

  • budget: ContextBudget
  • config: ContextManagerConfig

Returns: boolean

compact()

Execute compaction using available compactors

typescript
compact(
    components: IContextComponent[],
    budget: ContextBudget,
    compactors: IContextCompactor[],
    estimator: ITokenEstimator
  ): Promise<{
    components: IContextComponent[];
    log: string[];
    tokensFreed: number;
  }>;

Parameters:

  • components: IContextComponent[]
  • budget: ContextBudget
  • compactors: IContextCompactor[]
  • estimator: ITokenEstimator

Returns: Promise<{ components: IContextComponent[]; log: string[]; tokensFreed: number; }>

prepareComponents()?

Optional: Prepare components before budget calculation Use this for strategies that pre-process context (e.g., rolling window)

typescript
prepareComponents?(components: IContextComponent[]): Promise<IContextComponent[]>;

Parameters:

  • components: IContextComponent[]

Returns: Promise<IContextComponent[]>

postProcess()?

Optional: Post-process after compaction Use this for strategies that need cleanup or optimization

typescript
postProcess?(
    components: IContextComponent[],
    budget: ContextBudget
  ): Promise<IContextComponent[]>;

Parameters:

  • components: IContextComponent[]
  • budget: ContextBudget

Returns: Promise<IContextComponent[]>

getMetrics()?

Optional: Get strategy-specific metrics

typescript
getMetrics?(): Record<string, unknown>;

Returns: Record<string, unknown>

Properties
Property Type Description
name readonly name: string; Strategy name

ITokenEstimator interface

📍 src/core/context/types.ts:123

Abstract interface for token estimation

Methods

estimateTokens()

Estimate token count for text

typescript
estimateTokens(text: string, contentType?: TokenContentType): number;

Parameters:

  • text: string
  • contentType: TokenContentType | undefined (optional)

Returns: number

estimateDataTokens()

Estimate tokens for structured data

typescript
estimateDataTokens(data: unknown, contentType?: TokenContentType): number;

Parameters:

  • data: unknown
  • contentType: TokenContentType | undefined (optional)

Returns: number

estimateImageTokens()?

Estimate tokens for an image.

typescript
estimateImageTokens?(width?: number, height?: number, detail?: string): number;

Parameters:

  • width: number | undefined (optional)
  • height: number | undefined (optional)
  • detail: string | undefined (optional)

Returns: number

PreparedContext interface

📍 src/core/context/types.ts:54

Context preparation result

Properties
Property Type Description
components components: IContextComponent[]; Prepared components
budget budget: ContextBudget; Current budget
compacted compacted: boolean; Whether compaction occurred
compactionLog? compactionLog?: string[]; Compaction log if compacted

TokenContentType type

📍 src/core/context/types.ts:118

Content type for more accurate token estimation Named differently from TokenContentType in Content.ts to avoid conflicts

typescript
type TokenContentType = 'code' | 'prose' | 'mixed'

createEstimator function

📍 src/infrastructure/context/estimators/index.ts:11

Create token estimator from name

typescript
export function createEstimator(name: string): ITokenEstimator

DEFAULT_CONTEXT_CONFIG const

📍 src/core/context/types.ts:100

Default configuration

Properties
Property Type Description
maxContextTokens 128000 -
compactionThreshold 0.75 -
hardLimit 0.9 -
responseReserve 0.15 -
estimator 'approximate' -
autoCompact true -
strategy 'proactive' -
strategyOptions {} -
Documentation snapshot · 2026-11-02Suggest a correction ↗

Search documentation

Type to search the v2 documentation.

↑ ↓ to navigate Esc to close