Documentation
¶
Overview ¶
Package context provides strategy-driven context compression for agentcore: prompt projection, summary checkpoints, overflow recovery, and usage estimation.
engine := context.NewDefaultEngine(model, 128000) agent := agentcore.NewAgent( agentcore.WithModel(model), agentcore.WithContextManager(engine), )
Index ¶
- func ContextConvertToLLM(msgs []agentcore.AgentMessage) []agentcore.Message
- func ContextEstimateAdapter(msgs []agentcore.AgentMessage) (tokens, usageTokens, trailingTokens int)
- func EstimateTokens(msg agentcore.AgentMessage) int
- func EstimateTotal(msgs []agentcore.AgentMessage) int
- type Budget
- type ContextEngine
- func (e *ContextEngine) Compact(ctx context.Context, msgs []agentcore.AgentMessage, _ agentcore.CompactReason) (agentcore.ContextCommitResult, error)
- func (e *ContextEngine) ContextWindow() int
- func (e *ContextEngine) ConvertToLLM(msgs []agentcore.AgentMessage) []agentcore.Message
- func (e *ContextEngine) EstimateContext(msgs []agentcore.AgentMessage) (tokens, usageTokens, trailingTokens int)
- func (e *ContextEngine) Project(ctx context.Context, msgs []agentcore.AgentMessage) (agentcore.ContextProjection, error)
- func (e *ContextEngine) RecoverOverflow(ctx context.Context, msgs []agentcore.AgentMessage, _ error) (agentcore.ContextRecoveryResult, error)
- func (e *ContextEngine) SetProjectHook(fn func(RewriteEvent))
- func (e *ContextEngine) SetRecoverHook(fn func(RewriteEvent))
- func (e *ContextEngine) Snapshot() *agentcore.ContextSnapshot
- func (e *ContextEngine) Sync(msgs []agentcore.AgentMessage)
- func (e *ContextEngine) Usage() *agentcore.ContextUsage
- type ContextSummary
- type ContextUsageEstimate
- type EngineConfig
- type ForceCompactionStrategy
- type FullSummaryConfig
- type FullSummaryStrategy
- func (s *FullSummaryStrategy) Apply(ctx context.Context, _ []agentcore.AgentMessage, view []agentcore.AgentMessage, ...) ([]agentcore.AgentMessage, StrategyResult, error)
- func (s *FullSummaryStrategy) ForceApply(ctx context.Context, _ []agentcore.AgentMessage, view []agentcore.AgentMessage, ...) ([]agentcore.AgentMessage, StrategyResult, error)
- func (s *FullSummaryStrategy) Name() string
- func (s *FullSummaryStrategy) SetPostSummaryHooks(hooks ...PostSummaryHook)
- type LightTrimConfig
- type LightTrimStrategy
- type PostSummaryHook
- type RewriteEvent
- type Strategy
- type StrategyResult
- type SummaryInfo
- type ToolClassifier
- type ToolResultMicrocompactConfig
- type ToolResultMicrocompactStrategy
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContextConvertToLLM ¶
func ContextConvertToLLM(msgs []agentcore.AgentMessage) []agentcore.Message
ContextConvertToLLM converts AgentMessages to LLM Messages, handling ContextSummary by wrapping it as a user message with XML tags. For all other message types, it delegates to DefaultConvertToLLM behavior.
func ContextEstimateAdapter ¶
func ContextEstimateAdapter(msgs []agentcore.AgentMessage) (tokens, usageTokens, trailingTokens int)
ContextEstimateAdapter adapts EstimateContextTokens to the agentcore.ContextEstimateFn signature used by agent runtime options.
func EstimateTokens ¶
func EstimateTokens(msg agentcore.AgentMessage) int
EstimateTokens estimates the token count for a single message. Uses chars/4 approximation (conservative overestimate).
func EstimateTotal ¶
func EstimateTotal(msgs []agentcore.AgentMessage) int
EstimateTotal estimates the total token count for a message list.
Types ¶
type Budget ¶
Budget describes the current context pressure seen by a strategy. Threshold is the maximum token estimate allowed before a rewrite is needed.
type ContextEngine ¶
type ContextEngine struct {
// contains filtered or unexported fields
}
ContextEngine implements agentcore.ContextManager with a strategy-driven prompt projection pipeline.
func NewDefaultEngine ¶
func NewDefaultEngine(model agentcore.ChatModel, contextWindow int) *ContextEngine
NewDefaultEngine creates a ContextEngine with the default rewrite pipeline: tool-result microcompact, light trim, then full summary.
This is the recommended entry point for applications that want context management without custom strategy wiring.
engine := context.NewDefaultEngine(model, 128000) agentcore.WithContextManager(engine)
func NewEngine ¶
func NewEngine(cfg EngineConfig) *ContextEngine
NewEngine constructs a ContextEngine from an explicit strategy pipeline.
func (*ContextEngine) Compact ¶
func (e *ContextEngine) Compact(ctx context.Context, msgs []agentcore.AgentMessage, _ agentcore.CompactReason) (agentcore.ContextCommitResult, error)
Compact performs a forced rewrite suitable for explicit committed actions such as /compact. The caller should replace its runtime baseline with the returned Messages when Changed is true.
func (*ContextEngine) ContextWindow ¶
func (e *ContextEngine) ContextWindow() int
ContextWindow implements agentcore.ContextWindower.
func (*ContextEngine) ConvertToLLM ¶
func (e *ContextEngine) ConvertToLLM(msgs []agentcore.AgentMessage) []agentcore.Message
ConvertToLLM implements agentcore.ContextLLMConverter.
func (*ContextEngine) EstimateContext ¶
func (e *ContextEngine) EstimateContext(msgs []agentcore.AgentMessage) (tokens, usageTokens, trailingTokens int)
EstimateContext implements agentcore.ContextEstimator.
func (*ContextEngine) Project ¶
func (e *ContextEngine) Project(ctx context.Context, msgs []agentcore.AgentMessage) (agentcore.ContextProjection, error)
Project builds the prompt view for one LLM call without committing a new runtime baseline.
func (*ContextEngine) RecoverOverflow ¶
func (e *ContextEngine) RecoverOverflow(ctx context.Context, msgs []agentcore.AgentMessage, _ error) (agentcore.ContextRecoveryResult, error)
RecoverOverflow performs a forced rewrite after a provider reports context overflow. When ShouldCommit is true, CommitMessages should become the new runtime baseline before retrying.
func (*ContextEngine) SetProjectHook ¶
func (e *ContextEngine) SetProjectHook(fn func(RewriteEvent))
SetProjectHook installs the callback fired when Project rewrites the prompt view due to context pressure.
func (*ContextEngine) SetRecoverHook ¶
func (e *ContextEngine) SetRecoverHook(fn func(RewriteEvent))
SetRecoverHook installs the callback fired when RecoverOverflow rewrites the prompt view after a provider overflow error.
func (*ContextEngine) Snapshot ¶
func (e *ContextEngine) Snapshot() *agentcore.ContextSnapshot
Snapshot returns the latest active view snapshot remembered by the engine.
func (*ContextEngine) Sync ¶
func (e *ContextEngine) Sync(msgs []agentcore.AgentMessage)
Sync records msgs as the current runtime baseline and resets the active view remembered by the engine to that baseline.
func (*ContextEngine) Usage ¶
func (e *ContextEngine) Usage() *agentcore.ContextUsage
Usage returns the latest effective usage remembered by the engine.
type ContextSummary ¶
type ContextSummary struct {
Summary string
TokensBefore int
ReadFiles []string
ModifiedFiles []string
Timestamp time.Time
}
ContextSummary is a compacted context summary message. It implements AgentMessage but is NOT a Message, so DefaultConvertToLLM will filter it out. Use ContextConvertToLLM to handle it.
func (ContextSummary) GetRole ¶
func (c ContextSummary) GetRole() agentcore.Role
func (ContextSummary) GetTimestamp ¶
func (c ContextSummary) GetTimestamp() time.Time
func (ContextSummary) HasToolCalls ¶
func (c ContextSummary) HasToolCalls() bool
func (ContextSummary) TextContent ¶
func (c ContextSummary) TextContent() string
func (ContextSummary) ThinkingContent ¶
func (c ContextSummary) ThinkingContent() string
type ContextUsageEstimate ¶
type ContextUsageEstimate struct {
// Tokens is the total estimated context tokens (UsageTokens + TrailingTokens).
Tokens int
// UsageTokens is the token count derived from the last LLM-reported Usage.
UsageTokens int
// TrailingTokens is the chars/4 estimate for messages after the last Usage.
TrailingTokens int
// LastUsageIndex is the index of the last assistant message with Usage, or -1 if none.
LastUsageIndex int
}
ContextUsageEstimate holds the hybrid token estimation result. It combines LLM-reported Usage data with chars/4 estimation for trailing messages to approximate current context-window occupancy.
func EstimateContextTokens ¶
func EstimateContextTokens(msgs []agentcore.AgentMessage) ContextUsageEstimate
EstimateContextTokens uses a hybrid approach: actual Usage from the last non-aborted assistant message, plus chars/4 estimates for trailing messages. This approximates the current context window occupancy.
type EngineConfig ¶
type EngineConfig struct {
// ContextWindow is the model's maximum supported context window.
ContextWindow int
// ReserveTokens is the minimum prompt headroom to preserve. When zero, a
// conservative default is used.
ReserveTokens int
// Strategies are applied in order until the projected view fits.
Strategies []Strategy
// OnProject is called when Project rewrites the prompt view.
OnProject func(RewriteEvent)
// OnRecover is called when RecoverOverflow rewrites the prompt view.
OnRecover func(RewriteEvent)
}
EngineConfig configures the default strategy-driven ContextEngine. ContextWindow is required. Strategies run in order until the projected view drops below the threshold implied by ContextWindow and ReserveTokens.
type ForceCompactionStrategy ¶
type ForceCompactionStrategy interface {
Strategy
ForceApply(ctx context.Context, transcript []agentcore.AgentMessage, view []agentcore.AgentMessage, budget Budget) ([]agentcore.AgentMessage, StrategyResult, error)
}
ForceCompactionStrategy is used for explicit /compact and overflow recovery. It can choose to run even when the regular threshold is not crossed. ForceApply should base its rewrite on the full transcript-quality input required by the strategy rather than on a previously degraded prompt view.
type FullSummaryConfig ¶
type FullSummaryConfig struct {
// Model performs the actual summary generation.
Model agentcore.ChatModel
// StripImages controls whether images are removed before summarization.
// Nil defaults to true.
StripImages *bool
// KeepRecentTokens reserves a recent suffix to keep verbatim.
KeepRecentTokens int
// PostSummaryHooks inject lightweight reminder messages after the summary.
PostSummaryHooks []PostSummaryHook
}
FullSummaryConfig controls ContextSummary checkpoint generation. KeepRecentTokens reserves a recent suffix of messages to keep verbatim. PostSummaryHooks may inject lightweight reminder messages after the summary.
type FullSummaryStrategy ¶
type FullSummaryStrategy struct {
// contains filtered or unexported fields
}
FullSummaryStrategy rewrites older context into a ContextSummary checkpoint while keeping a recent suffix of messages verbatim.
func NewFullSummary ¶
func NewFullSummary(cfg FullSummaryConfig) *FullSummaryStrategy
NewFullSummary constructs the terminal summary strategy used when lighter rewrites are insufficient. Model is required for actual summarization.
func (*FullSummaryStrategy) Apply ¶
func (s *FullSummaryStrategy) Apply(ctx context.Context, _ []agentcore.AgentMessage, view []agentcore.AgentMessage, budget Budget) ([]agentcore.AgentMessage, StrategyResult, error)
func (*FullSummaryStrategy) ForceApply ¶
func (s *FullSummaryStrategy) ForceApply(ctx context.Context, _ []agentcore.AgentMessage, view []agentcore.AgentMessage, budget Budget) ([]agentcore.AgentMessage, StrategyResult, error)
func (*FullSummaryStrategy) Name ¶
func (s *FullSummaryStrategy) Name() string
func (*FullSummaryStrategy) SetPostSummaryHooks ¶
func (s *FullSummaryStrategy) SetPostSummaryHooks(hooks ...PostSummaryHook)
SetPostSummaryHooks replaces the hook list used to inject lightweight reminder messages after a summary checkpoint is produced.
type LightTrimConfig ¶
type LightTrimStrategy ¶
type LightTrimStrategy struct {
// contains filtered or unexported fields
}
func NewLightTrim ¶
func NewLightTrim(cfg LightTrimConfig) *LightTrimStrategy
func (*LightTrimStrategy) Apply ¶
func (s *LightTrimStrategy) Apply(_ context.Context, _ []agentcore.AgentMessage, view []agentcore.AgentMessage, _ Budget) ([]agentcore.AgentMessage, StrategyResult, error)
func (*LightTrimStrategy) Name ¶
func (s *LightTrimStrategy) Name() string
type PostSummaryHook ¶
type PostSummaryHook func(ctx context.Context, info SummaryInfo, kept []agentcore.AgentMessage) ([]agentcore.AgentMessage, error)
PostSummaryHook injects lightweight reminder messages after a summary checkpoint is produced. Hooks must be side-effect free and should not perform I/O such as file reads or tool execution.
type RewriteEvent ¶
type RewriteEvent struct {
Reason string
Strategy string
Changed bool
TokensBefore int
TokensAfter int
Info *SummaryInfo
}
RewriteEvent reports a projection or recovery rewrite that actually changed the active view. Info is populated when the rewrite produced a summary checkpoint.
type Strategy ¶
type Strategy interface {
Name() string
Apply(ctx context.Context, transcript []agentcore.AgentMessage, view []agentcore.AgentMessage, budget Budget) ([]agentcore.AgentMessage, StrategyResult, error)
}
Strategy rewrites the current prompt view using the full transcript and current token budget.
transcript is the runtime baseline remembered by the engine. view is the current projected view after any earlier strategies in the pipeline.
type StrategyResult ¶
type StrategyResult struct {
Applied bool
TokensSaved int
Name string
Info *SummaryInfo
}
StrategyResult reports whether a strategy rewrote the prompt view. Info is populated when the strategy produced a summary checkpoint.
type SummaryInfo ¶
type SummaryInfo struct {
TokensBefore int
TokensAfter int
MessagesBefore int
MessagesAfter int
CompactedCount int // number of messages summarized
KeptCount int // number of messages retained verbatim
IsSplitTurn bool
IsIncremental bool // updated an existing summary
SummaryLen int // summary length in runes
Duration time.Duration // wall time including LLM calls
ReadFiles []string // files read during compacted conversation
ModifiedFiles []string // files modified during compacted conversation
}
SummaryInfo holds details about a completed compaction for observability.
type ToolClassifier ¶
ToolClassifier returns true when a tool result can be aggressively rewritten by tool-result microcompact strategies.
type ToolResultMicrocompactConfig ¶
type ToolResultMicrocompactConfig struct {
Classifier ToolClassifier
KeepRecent int
ClearedMessage string
IdleThreshold time.Duration
}
type ToolResultMicrocompactStrategy ¶
type ToolResultMicrocompactStrategy struct {
// contains filtered or unexported fields
}
func NewToolResultMicrocompact ¶
func NewToolResultMicrocompact(cfg ToolResultMicrocompactConfig) *ToolResultMicrocompactStrategy
func (*ToolResultMicrocompactStrategy) Apply ¶
func (s *ToolResultMicrocompactStrategy) Apply(_ context.Context, _ []agentcore.AgentMessage, view []agentcore.AgentMessage, _ Budget) ([]agentcore.AgentMessage, StrategyResult, error)
func (*ToolResultMicrocompactStrategy) Name ¶
func (s *ToolResultMicrocompactStrategy) Name() string