context

package
v1.6.11 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 4, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

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. Text and thinking blocks use CJK-aware estimation; tool calls and images use byte-based heuristics (JSON args are ASCII-dominant).

func EstimateTotal 

func EstimateTotal(msgs []agentcore.AgentMessage) int

EstimateTotal estimates the total token count for a message list.

Types

type Budget 

type Budget struct {
	Tokens    int
	Window    int
	Threshold int
}

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) ConsecutiveFailures added in v1.6.1 

func (e *ContextEngine) ConsecutiveFailures() int

ConsecutiveFailures returns the current circuit breaker failure count.

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. Includes a circuit breaker: after maxFailures consecutive compression errors, Project skips one cycle, reports the skipped state, then re-arms itself in a half-open state so later calls can retry compression.

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) SetContextWindow added in v1.6.3 

func (e *ContextEngine) SetContextWindow(n int)

SetContextWindow updates the context window size used for threshold calculations.

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) SetReserveTokens added in v1.6.3 

func (e *ContextEngine) SetReserveTokens(n int)

SetReserveTokens updates the prompt headroom reserved when computing the compaction threshold. Pass 0 to restore the engine's built-in default on the next threshold calculation.

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
	// CommitOnProject makes threshold-triggered Project rewrites replace the
	// runtime baseline before the current call continues.
	CommitOnProject bool
	// OnProject is called when Project rewrites the prompt view.
	OnProject func(RewriteEvent)
	// OnRecover is called when RecoverOverflow rewrites the prompt view.
	OnRecover func(RewriteEvent)
	// MaxConsecutiveFailures is the circuit breaker threshold. After this many
	// consecutive Project failures, the engine skips compression and returns
	// the original messages to avoid wasting API calls. 0 = default (3).
	MaxConsecutiveFailures int
}

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

	// Custom summary prompts. Empty strings fall back to the built-in defaults
	// (code-assistant oriented). Set these to override with domain-specific
	// prompts — e.g., novel-writing prompts that preserve narrative continuity.
	SystemPrompt        string
	SummaryPrompt       string
	UpdateSummaryPrompt string
	TurnPrefixPrompt    string
}

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 LightTrimConfig struct {
	KeepRecent    int
	TextThreshold int
	PreserveHead  int
	PreserveTail  int
}

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
	Committed    bool
	TokensBefore int
	TokensAfter  int
	Info         *SummaryInfo
	Steps        []RewriteStep
	// Failures is set when Reason == "circuit_breaker": the consecutive failure
	// count that triggered the bypass.
	Failures int
}

RewriteEvent reports a projection or recovery rewrite that actually changed the active view. Info is populated when the rewrite produced a summary checkpoint. Steps records every strategy attempted during the pipeline run.

type RewriteStep added in v1.6.1 

type RewriteStep struct {
	Name         string
	Applied      bool
	TokensBefore int
	TokensAfter  int
}

RewriteStep records a single strategy execution within the apply pipeline.

type SessionMemoryConfig added in v1.6.3 

type SessionMemoryConfig struct {
	// SeedFn returns the pre-computed session memory text. Called lazily at
	// apply time. Returning ("", nil) makes the strategy a no-op so the
	// pipeline falls through to LLM summarization.
	SeedFn func() (string, error)

	// KeepRecentTokens reserves a recent suffix to keep verbatim. Matches the
	// FullSummaryStrategy field with the same name; defaults to
	// defaultKeepRecentTokens when zero.
	KeepRecentTokens int

	// MaxSeedRunes caps how much of the seed we inject. Oversized memory
	// files can consume the entire post-compact budget. When zero, a
	// conservative default is used; when negative, no cap is enforced.
	MaxSeedRunes int

	// Label, when non-empty, overrides the strategy name reported in
	// observability events. Useful for distinguishing multiple memory
	// sources in multi-project harnesses.
	Label string
}

SessionMemoryConfig configures the SessionMemoryStrategy, a compaction strategy that substitutes a harness-maintained, pre-computed summary for the LLM-generated one produced by FullSummaryStrategy.

When a project-scoped session memory already exists, compaction can skip the synchronous summarization LLM call and reuse the living memory as the ContextSummary body. The harness supplies the seed via SeedFn.

type SessionMemoryStrategy added in v1.6.3 

type SessionMemoryStrategy struct {
	// contains filtered or unexported fields
}

SessionMemoryStrategy emits a ContextSummary checkpoint from a caller- provided seed without invoking the LLM. When no seed is available it is a no-op, so it composes naturally with FullSummaryStrategy as a fallback.

func NewSessionMemory added in v1.6.3 

func NewSessionMemory(cfg SessionMemoryConfig) *SessionMemoryStrategy

NewSessionMemory constructs a SessionMemoryStrategy. SeedFn may be nil; the strategy will simply no-op until a non-nil function is installed via SetSeedFn.

func (*SessionMemoryStrategy) Apply added in v1.6.3 

func (s *SessionMemoryStrategy) Apply(ctx context.Context, _ []agentcore.AgentMessage, view []agentcore.AgentMessage, budget Budget) ([]agentcore.AgentMessage, StrategyResult, error)

Apply replaces history older than KeepRecentTokens with a ContextSummary whose body is the seed text. When no seed is available it returns the view unchanged, allowing a downstream FullSummary strategy to run.

func (*SessionMemoryStrategy) Name added in v1.6.3 

func (s *SessionMemoryStrategy) Name() string

Name reports the strategy label used in RewriteEvent / SummaryInfo.

func (*SessionMemoryStrategy) SetSeedFn added in v1.6.3 

func (s *SessionMemoryStrategy) SetSeedFn(fn func() (string, error))

SetSeedFn swaps the seed provider at runtime (e.g. when the harness re-resolves the current project after a session switch).

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 

type ToolClassifier func(toolName string) bool

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.