memory

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Jul 31, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package memory provides working memory management, compaction strategies, and procedural memory for agent sessions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewCompactionStrategy 

func NewCompactionStrategy(name string, cfg CompactionConfig, deps CompactionDeps) sdkagent.CompactionStrategy

NewCompactionStrategy creates a CompactionStrategy by name. Returns an sdkagent.CompactionStrategy for use with ContextWindow.SetStrategy.

Types

type CompactionConfig 

type CompactionConfig struct {
	SlidingWindow struct {
		KeepFirst int
		KeepLast  int
	}
	Summarization struct {
		BlockSize           int
		KeepLast            int
		ObservationTruncate int // max chars for observations in summary blocks (default: 500)
	}
	Hierarchical struct {
		DistantRatio float64
		MiddleRatio  float64
		RecentRatio  float64
	}
}

CompactionConfig holds configuration for compaction strategies.

type CompactionDeps 

type CompactionDeps struct {
	TokenCounter llm.TokenCounter
	// Summarize calls the LLM to summarize a block of text.
	// Used by SummarizationStrategy and HierarchicalStrategy.
	Summarize func(ctx context.Context, text string) (string, error)
	// MaxSummarizeTokens is the maximum token count for text sent to summarization.
	// Defaults to 16000 if zero.
	MaxSummarizeTokens int
}

CompactionDeps — external dependencies needed by some strategies.

type CompactionResult 

type CompactionResult = sdkagent.CompactionResult

CompactionResult is an alias for sdkagent.CompactionResult.

type CompactionThresholds 

type CompactionThresholds struct {
	PredictivePercent int // Context fill % that triggers predictive compaction
	WarningPercent    int // Context fill % that triggers warning-level compaction
	EmergencyPercent  int // Context fill % that triggers emergency compaction
}

CompactionThresholds configures when context compaction triggers.

func DefaultCompactionThresholds 

func DefaultCompactionThresholds() CompactionThresholds

DefaultCompactionThresholds returns sensible defaults for context window compaction triggers.

type ContextWindow 

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

ContextWindow — managed representation of the LLM context window.

func NewContextWindow 

func NewContextWindow(cfg ContextWindowConfig) *ContextWindow

NewContextWindow creates a new ContextWindow from the given config. Use SetHistoryMutation() to configure history mutation separately.

func (*ContextWindow) AddStep 

func (cw *ContextWindow) AddStep(step sdkagent.Step)

AddStep appends a step to the history and updates the token tracker. The token estimate is approximate — it concatenates content strings without accounting for LLM message framing overhead (~4 tokens/message). The ContextTokenTracker.Correct() method compensates by adjusting delta based on actual API-reported token usage, so estimates converge over time.

func (*ContextWindow) AvailableTokens 

func (cw *ContextWindow) AvailableTokens() int

AvailableTokens returns the number of tokens remaining in the context window.

func (*ContextWindow) BuildPrompt 

func (cw *ContextWindow) BuildPrompt() []llm.Message

BuildPrompt assembles the full prompt in priority order.

func (*ContextWindow) CheckFill 

func (cw *ContextWindow) CheckFill() sdkagent.FillCheck

CheckFill returns the current fill status.

func (*ContextWindow) Compact 

func (cw *ContextWindow) Compact(ctx context.Context) *CompactionResult

Compact compresses the step history using the configured strategy. Returns a CompactionResult with before/after fill percentages, or nil if no compaction occurred.

func (*ContextWindow) CorrectTokenCount 

func (cw *ContextWindow) CorrectTokenCount(apiInputTokens int)

CorrectTokenCount updates the tracker with the actual API input token count.

func (*ContextWindow) EffectiveMax 

func (cw *ContextWindow) EffectiveMax() int

EffectiveMax returns the effective maximum token count for the context window, accounting for output limit and safety margin.

NOTE: This is the ongoing tracking formula used during the agent loop to manage context growth. It differs from Router.validateContextWindow (which is a last-chance guard before API submission) — the slight numeric divergence from integer vs float rounding is intentional and acceptable.

func (*ContextWindow) FillPercent 

func (cw *ContextWindow) FillPercent() float64

FillPercent returns the current fill percentage of the context window.

func (*ContextWindow) OutputLimit 

func (cw *ContextWindow) OutputLimit() int

OutputLimit returns the model's maximum output token limit.

func (*ContextWindow) SeedSteps 

func (cw *ContextWindow) SeedSteps(steps []sdkagent.Step)

SeedSteps sets the step history directly, bypassing AddStep's per-step tracker delta. It performs a wholesale replacement of the window contents: the step history, compaction state, and token tracker are all reset, then the cumulative token delta is recalculated for the seeded batch so fill accounting stays approximately correct until the next CorrectTokenCount correction from the API.

SeedSteps is used to resume an executor from a checkpoint: the seeded steps appear in BuildPrompt as proper assistant+tool messages, and a resumed executor's step counter continues from len(steps) instead of starting fresh. Any prior compaction state (compactedMessages/ compactedThroughIndex) is cleared because the seeded history replaces the window contents wholesale.

Passing nil or an empty slice clears any existing step history.

func (*ContextWindow) SetHistoryMutation 

func (cw *ContextWindow) SetHistoryMutation(m HistoryMutation)

SetHistoryMutation configures regular history mutation (tool result eviction, step status eviction, dedup). Must be called before the first BuildPrompt.

func (*ContextWindow) SetPlan 

func (cw *ContextWindow) SetPlan(planText string)

SetPlan sets the plan content (system message in prompt). The caller is responsible for formatting the plan text.

func (*ContextWindow) SetPriorConversation 

func (cw *ContextWindow) SetPriorConversation(msgs []llm.Message)

SetPriorConversation sets messages from previous exchanges that should appear in the prompt between the system message(s) and the current task content. This gives the agent dialogue context for follow-up messages. Pass nil or an empty slice to clear prior conversation.

func (*ContextWindow) SetStrategy 

func (cw *ContextWindow) SetStrategy(s sdkagent.CompactionStrategy)

SetStrategy changes the compaction strategy.

func (*ContextWindow) SetTask 

func (cw *ContextWindow) SetTask(task string)

SetTask sets the task content (user message in prompt). The caller is responsible for formatting the task, including any criteria or context. SetTask reverts to the text-only prompt path: any content blocks set by a prior SetTaskWithBlocks call are cleared so BuildPrompt emits a plain text user message.

func (*ContextWindow) SetTaskWithBlocks added in v0.5.0 

func (cw *ContextWindow) SetTaskWithBlocks(task string, blocks []llm.ContentBlock)

SetTaskWithBlocks sets the task content along with structured content blocks (e.g. text + images) for the user message. When blocks is non-empty, BuildPrompt emits a Message carrying ContentBlocks alongside the task text; providers render the blocks and, if they contain no text block, fall back to the task text (via llm.NormalizeContentBlocks) so the instruction always reaches the model. Pass nil or an empty slice to revert to the legacy text-only SetTask path. The caller is responsible for formatting the task text and encoding any image blocks (base64 without the "data:" prefix).

func (*ContextWindow) Tracker 

func (cw *ContextWindow) Tracker() *llm.ContextTokenTracker

Tracker returns the underlying ContextTokenTracker.

func (*ContextWindow) VulnerableOutputs 

func (cw *ContextWindow) VulnerableOutputs() []sdkagent.VulnerableOutput

VulnerableOutputs returns the list of tool outputs that will be pruned on the next pruning cycle. These are non-protected outputs outside the KeepLastN window. Returns nil when pruning is inactive (KeepLastN <= 0, below threshold, or no steps).

type ContextWindowConfig 

type ContextWindowConfig struct {
	// SystemPrompt is the system prompt rendered at the start of every
	// prompt build. May contain a prompt.CacheBreakMarker.
	SystemPrompt string

	// ModelMeta describes the target model. If ContextWindow is 0 (unknown
	// model), a fallback of 128000 is used — a zero ContextWindow would
	// disable compaction entirely (EffectiveMax returns 0, CheckFill returns
	// "ok"), causing unbounded conversation growth until the API rejects the
	// request. If OutputLimit is 0, a fallback of 4096 is used.
	ModelMeta llm.ModelMetadata

	// Tracker counts tokens for fill tracking. nil disables token accounting
	// (compaction and fill warnings are silently disabled).
	Tracker *llm.ContextTokenTracker

	// Thresholds configures the compaction trigger percentages.
	Thresholds CompactionThresholds

	// Strategy is the compaction algorithm. nil disables compaction.
	Strategy sdkagent.CompactionStrategy

	// SafetyMarginPercent is the percentage of the context window reserved
	// as safety margin. Values <= 0 use the default (5).
	SafetyMarginPercent int

	// InjectionDefenseEnabled gates prompt-injection defense wrapping
	// (<untrusted-content> tags around tool outputs).
	InjectionDefenseEnabled bool

	// Pruning configures tool-output pruning. Zero value leaves pruning
	// disabled (ThresholdPercent 0) with a default placeholder text.
	Pruning ToolOutputPruning
}

ContextWindowConfig configures a ContextWindow. Zero-value fields fall back to sensible defaults (see field comments); only ModelMeta is meaningfully required in practice.

type HierarchicalStrategy 

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

HierarchicalStrategy divides steps into 3 zones with different compression levels: - Distant (oldest): aggressive summarization (large blocks) - Middle: moderate summarization (smaller blocks) - Recent: kept verbatim

func NewHierarchicalStrategy 

func NewHierarchicalStrategy(distant, middle, recent float64, observationTruncate int, summarizer func(ctx context.Context, text string) (string, error), tokenCounter llm.TokenCounter, maxSummarizeTokens int) *HierarchicalStrategy

NewHierarchicalStrategy creates a new HierarchicalStrategy. distant, middle, recent are the fractions of steps in each zone. They will be normalized to sum to 1.0 if they don't already. observationTruncate is the max chars for observations in summary blocks (default: 500 if <= 0). tokenCounter is optional; if provided, blocks are truncated to maxSummarizeTokens. maxSummarizeTokens defaults to 16000 if zero.

func (*HierarchicalStrategy) Compact 

func (h *HierarchicalStrategy) Compact(ctx context.Context, steps []sdkagent.Step, budgetTokens int) []llm.Message

Compact divides steps into 3 zones: - Distant (oldest): aggressive summarization (large blocks, ~15 steps per summary) - Middle: moderate summarization (smaller blocks, ~5 steps per summary) - Recent: kept verbatim

func (*HierarchicalStrategy) SetLogger 

func (h *HierarchicalStrategy) SetLogger(l *slog.Logger)

SetLogger sets the logger for the strategy. If nil, slog.Default() is used.

type HistoryMutation 

type HistoryMutation struct {
	// ToolResultEvictionStep is the number of steps after which a tool result
	// is replaced with a cache reference. 0 disables eviction (full results
	// kept indefinitely, subject to pruning/compaction).
	ToolResultEvictionStep int
	// EvictStepStatus enables immediate eviction of update_checklist results
	// (pure bookkeeping, no information loss). Also matches the legacy
	// set_step_status name for old session history.
	EvictStepStatus bool
	// DedupRepeatedReads replaces duplicate file-read results (same path +
	// mtime) with a reference to the earlier result's cache hash.
	DedupRepeatedReads bool
	// Logger is an optional logger for mutation diagnostics.
	Logger *slog.Logger
}

HistoryMutation configures regular (non-emergency) mutation of step history to reduce O(n²) replay cost. Unlike emergency compaction (triggered by fill %), history mutation runs on every BuildPrompt call and replaces old tool results with cache references, evicts bookkeeping outputs, and deduplicates repeated reads. Information is preserved via ToolResultCache — the LLM can retrieve evicted content via tool_result_read.

type SlidingWindowStrategy 

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

SlidingWindowStrategy keeps the first K and last N steps, removing the middle.

func NewSlidingWindowStrategy 

func NewSlidingWindowStrategy(keepFirst, keepLast int) *SlidingWindowStrategy

NewSlidingWindowStrategy creates a new SlidingWindowStrategy.

func (*SlidingWindowStrategy) Compact 

func (s *SlidingWindowStrategy) Compact(ctx context.Context, steps []sdkagent.Step, budgetTokens int) []llm.Message

Compact implements CompactionStrategy. It keeps the first K and last N steps, inserting a summary message in between for any omitted steps.

type SummarizationStrategy 

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

SummarizationStrategy groups the oldest steps into blocks and uses an LLM to summarize each block into a compact summary message.

func NewSummarizationStrategy 

func NewSummarizationStrategy(blockSize, keepLast, observationTruncate int, summarizer func(ctx context.Context, text string) (string, error), tokenCounter llm.TokenCounter, maxSummarizeTokens int) *SummarizationStrategy

NewSummarizationStrategy creates a new SummarizationStrategy. blockSize is the number of steps per summary block. keepLast is the number of recent steps to preserve verbatim. observationTruncate is the max chars for observations in summary blocks (default: 500 if <= 0). summarizer is the function to call for LLM summarization. tokenCounter is optional; if provided, blocks are truncated to maxSummarizeTokens. maxSummarizeTokens defaults to 16000 if zero.

func (*SummarizationStrategy) Compact 

func (s *SummarizationStrategy) Compact(ctx context.Context, steps []sdkagent.Step, budgetTokens int) []llm.Message

Compact takes steps that need compaction, groups oldest into blocks of blockSize, summarizes each block via the LLM summarizer, returns compacted steps. Recent steps (within keepLast) are preserved verbatim. Summary blocks become single messages with Role="system" and Content=summarized text.

func (*SummarizationStrategy) SetLogger 

func (s *SummarizationStrategy) SetLogger(l *slog.Logger)

SetLogger sets the logger for the strategy. If nil, slog.Default() is used.

type ToolOutputPruning 

type ToolOutputPruning struct {
	KeepLastN        int
	ProtectedTools   []string
	PlaceholderText  string
	ThresholdPercent float64      // Context fill % below which pruning is skipped (default: 50)
	Logger           *slog.Logger // Optional logger for pruning diagnostics
}

ToolOutputPruning configures selective pruning of old tool outputs.

func DefaultToolOutputPruning 

func DefaultToolOutputPruning() ToolOutputPruning

DefaultToolOutputPruning returns sensible defaults for tool output pruning.

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.