Chat Context
chat/context
Section titled “chat/context”Classes
Section titled “Classes”ContextWindowManager
Section titled “ContextWindowManager”Defined in: chat/context.ts:192
Stateless context window manager. Takes messages and returns the subset that fits within a token budget.
Example
Section titled “Example”const manager = new ContextWindowManager({ maxTokens: 4096, reservedTokens: 500, strategy: "sliding-window",});
const result = manager.fitMessages(messages);// result.messages — trimmed to fit budget// result.totalTokens — estimated token usage// result.wasTruncated — whether messages were removedConstructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ContextWindowManager(
config):ContextWindowManager
Defined in: chat/context.ts:198
Parameters
Section titled “Parameters”config
Section titled “config”Returns
Section titled “Returns”Accessors
Section titled “Accessors”availableBudget
Section titled “availableBudget”Get Signature
Section titled “Get Signature”get availableBudget():
number
Defined in: chat/context.ts:209
Available token budget after reserving tokens
Returns
Section titled “Returns”number
Methods
Section titled “Methods”estimateMessageTokens()
Section titled “estimateMessageTokens()”estimateMessageTokens(
message):number
Defined in: chat/context.ts:218
Estimate tokens for a single message.
Parameters
Section titled “Parameters”message
Section titled “message”Message to estimate
Returns
Section titled “Returns”number
Estimated token count
fitMessages()
Section titled “fitMessages()”fitMessages(
messages):ContextWindowResult
Defined in: chat/context.ts:227
Fit messages within the token budget using the configured strategy.
Parameters
Section titled “Parameters”messages
Section titled “messages”readonly ChatMessage<unknown>[]
All messages to consider
Returns
Section titled “Returns”Result with fitted messages and metadata
fitMessagesAsync()
Section titled “fitMessagesAsync()”fitMessagesAsync(
messages):Promise<ContextWindowResult>
Defined in: chat/context.ts:265
Async variant of fitMessages that supports async summarization. When strategy is “summarize-placeholder” and a summarizer is configured, calls the summarizer with removed messages and replaces the placeholder text. Falls back to static placeholder if summarizer throws. For other strategies, behaves identically to fitMessages().
Parameters
Section titled “Parameters”messages
Section titled “messages”readonly ChatMessage<unknown>[]
Returns
Section titled “Returns”Promise<ContextWindowResult>
fitMessagesWithUsage()
Section titled “fitMessagesWithUsage()”fitMessagesWithUsage(
messages,lastPromptTokens,modelContextWindow):ContextWindowResult
Defined in: chat/context.ts:314
Trim messages using real token usage data from the previous API call.
Uses average-based algorithm: avgTokensPerMessage = lastPromptTokens / messageCount.
Removes oldest non-system messages until freed budget brings usage under modelContextWindow.
Parameters
Section titled “Parameters”messages
Section titled “messages”readonly ChatMessage<unknown>[]
All messages in the session
lastPromptTokens
Section titled “lastPromptTokens”number
Real prompt tokens from the last API response
modelContextWindow
Section titled “modelContextWindow”number
Model’s total context window size in tokens
Returns
Section titled “Returns”Result with fitted messages and metadata
Interfaces
Section titled “Interfaces”ContextStats
Section titled “ContextStats”Defined in: chat/context.ts:155
Context usage statistics for a session.
Returned by IChatRuntime.getContextStats().
When real usage data is available (after the first API response),
realPromptTokens and realCompletionTokens contain actual token counts.
modelContextWindow is the model’s context window from listModels().
Properties
Section titled “Properties”availableBudget
Section titled “availableBudget”availableBudget:
number
Defined in: chat/context.ts:163
Available token budget (maxTokens − reservedTokens)
modelContextWindow?
Section titled “modelContextWindow?”
optionalmodelContextWindow:number
Defined in: chat/context.ts:169
Model’s context window in tokens from listModels() (undefined if not available)
realCompletionTokens?
Section titled “realCompletionTokens?”
optionalrealCompletionTokens:number
Defined in: chat/context.ts:167
Real completion tokens from the last API response (undefined before first response)
realPromptTokens?
Section titled “realPromptTokens?”
optionalrealPromptTokens:number
Defined in: chat/context.ts:165
Real prompt tokens from the last API response (undefined before first response)
removedCount
Section titled “removedCount”removedCount:
number
Defined in: chat/context.ts:159
Number of messages removed by trimming
totalTokens
Section titled “totalTokens”totalTokens:
number
Defined in: chat/context.ts:157
Estimated total tokens in the trimmed context (heuristic, kept for backward compat)
wasTruncated
Section titled “wasTruncated”wasTruncated:
boolean
Defined in: chat/context.ts:161
Whether context was truncated
ContextWindowConfig
Section titled “ContextWindowConfig”Defined in: chat/context.ts:99
Configuration for the context window manager.
Properties
Section titled “Properties”estimation?
Section titled “estimation?”
optionalestimation:TokenEstimationOptions
Defined in: chat/context.ts:119
Token estimation options.
maxTokens
Section titled “maxTokens”maxTokens:
number
Defined in: chat/context.ts:101
Maximum token budget for the context window
reservedTokens?
Section titled “reservedTokens?”
optionalreservedTokens:number
Defined in: chat/context.ts:108
Tokens reserved for system prompt and response generation. Subtracted from maxTokens to get available budget.
Default
Section titled “Default”0strategy?
Section titled “strategy?”
optionalstrategy:OverflowStrategy
Defined in: chat/context.ts:114
Strategy for handling overflow when messages exceed budget.
Default
Section titled “Default”"truncate-oldest"summarizer?
Section titled “summarizer?”
optionalsummarizer:ContextSummarizer
Defined in: chat/context.ts:126
Optional async summarizer for the summarize-placeholder strategy. When provided, replaces the static placeholder with a generated summary. Falls back to static placeholder if summarizer throws.
ContextWindowResult
Section titled “ContextWindowResult”Defined in: chat/context.ts:134
Result of context window trimming.
Properties
Section titled “Properties”messages
Section titled “messages”messages:
ChatMessage<unknown>[]
Defined in: chat/context.ts:136
Messages that fit within the budget
removedCount
Section titled “removedCount”removedCount:
number
Defined in: chat/context.ts:140
Number of messages removed
totalTokens
Section titled “totalTokens”totalTokens:
number
Defined in: chat/context.ts:138
Total estimated tokens for included messages
wasTruncated
Section titled “wasTruncated”wasTruncated:
boolean
Defined in: chat/context.ts:142
Whether any messages were truncated
TokenEstimationOptions
Section titled “TokenEstimationOptions”Defined in: chat/context.ts:16
Options for token estimation.
Properties
Section titled “Properties”charsPerToken?
Section titled “charsPerToken?”
optionalcharsPerToken:number
Defined in: chat/context.ts:22
Characters per token ratio. Lower = more conservative (fewer messages fit).
Default
Section titled “Default”4Type Aliases
Section titled “Type Aliases”ContextSummarizer()
Section titled “ContextSummarizer()”ContextSummarizer = (
removedMessages) =>Promise<string>
Defined in: chat/context.ts:94
Async summarizer function for the summarize-placeholder strategy. Receives removed messages and returns a summary string. When configured, replaces the static placeholder text with actual summary.
Parameters
Section titled “Parameters”removedMessages
Section titled “removedMessages”readonly ChatMessage[]
Returns
Section titled “Returns”Promise<string>
OverflowStrategy
Section titled “OverflowStrategy”OverflowStrategy =
"truncate-oldest"|"sliding-window"|"summarize-placeholder"
Defined in: chat/context.ts:82
Overflow strategy type
Functions
Section titled “Functions”estimateTokens()
Section titled “estimateTokens()”estimateTokens(
message,options?):number
Defined in: chat/context.ts:45
Estimate token count for a single chat message.
Uses character-based heuristic: Math.ceil(charCount / charsPerToken).
Counts:
- Text content (string or text parts)
- Serialized tool calls and tool results
- Thinking blocks
- Role overhead (~4 tokens)
Parameters
Section titled “Parameters”message
Section titled “message”Chat message to estimate
options?
Section titled “options?”Estimation options
Returns
Section titled “Returns”number
Estimated token count
Example
Section titled “Example”const tokens = estimateTokens(message);const conservative = estimateTokens(message, { charsPerToken: 3 });