memory

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Apr 26, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CompactIfNeeded added in v0.4.0 

func CompactIfNeeded(
	ctx context.Context,
	compactor *ConversationCompactor,
	messages []schema.Message,
	threshold int,
) ([]schema.Message, int, bool, error)

CompactIfNeeded checks the estimated token count and compresses if above the threshold. Returns the (possibly compressed) messages, updated token estimate, whether compaction occurred, and any error. This is a convenience for callers (CLI, HTTP handler) to avoid duplicating the check logic.

func DefaultMessageScorer 

func DefaultMessageScorer(messages []schema.Message, index int) float64

DefaultMessageScorer provides a heuristic scoring function. System messages score highest (1000), followed by tool messages and assistant messages with tool calls (100), user messages (50), and plain assistant messages (10). A proportional recency bonus of up to 5% of the base score is added, so recency matters within the same role but does not override role priority.

func DefaultTokenEstimator 

func DefaultTokenEstimator(msg schema.Message) int

DefaultTokenEstimator returns an approximate token count for a message. Uses a simple heuristic: len(text) / 4, with a minimum of 1 for non-empty content.

The minimum-of-1 rule prevents zero-token messages from bypassing budget checks. This means messages with 1-3 characters all estimate as 1 token, which slightly overcounts short messages. This is acceptable for a rough heuristic.

Known limitation: only the text portion of Content is considered. Multimodal content parts (images, etc.) are not accounted for in the estimate.

func EstimateTextTokens added in v0.4.0 

func EstimateTextTokens(text string) int

EstimateTextTokens returns the estimated token count for a plain text string. Uses the same heuristic as DefaultTokenEstimator: len(text) / 4.

Types

type ArchiveFunc 

type ArchiveFunc func(ctx context.Context, entries []Entry) ([]Entry, error)

ArchiveFunc is a function adapter for Archiver.

func (ArchiveFunc) Archive 

func (f ArchiveFunc) Archive(ctx context.Context, entries []Entry) ([]Entry, error)

Archive implements Archiver.

type Archiver 

type Archiver interface {
	Archive(ctx context.Context, entries []Entry) ([]Entry, error)
}

Archiver decides which session memory entries are archived to store.

func ArchiveAll 

func ArchiveAll() Archiver

ArchiveAll returns an archiver that archives all entries.

func ArchiveNone 

func ArchiveNone() Archiver

ArchiveNone returns an archiver that archives no entries.

type BatchStore 

type BatchStore interface {
	BatchGet(ctx context.Context, keys []string) (map[string]any, error)
	BatchSet(ctx context.Context, entries map[string]any, ttl int64) error
}

BatchStore is an optional interface that Store implementations can provide for optimised bulk operations.

type ChainCompressor 

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

ChainCompressor applies multiple compressors in sequence, passing the output of each compressor as input to the next.

func NewChainCompressor 

func NewChainCompressor(compressors ...ContextCompressor) *ChainCompressor

NewChainCompressor creates a ChainCompressor that applies the given compressors in order.

func (*ChainCompressor) Compress 

func (c *ChainCompressor) Compress(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)

Compress applies each compressor in sequence.

type CompressFunc 

type CompressFunc func(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)

CompressFunc is a function adapter for ContextCompressor.

func (CompressFunc) Compress 

func (f CompressFunc) Compress(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)

Compress implements ContextCompressor.

type ContextCompressor 

type ContextCompressor interface {
	Compress(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)
}

ContextCompressor compresses a message history to fit within a token budget.

type ConversationCompactor added in v0.4.0 

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

ConversationCompactor compresses a conversation history by summarizing older messages while preserving protected messages (system prompt and recent turn pairs).

ConversationCompactor is safe for concurrent use; it holds no mutable state.

func NewConversationCompactor added in v0.4.0 

func NewConversationCompactor(summarizer Summarizer, protectedTurns int) *ConversationCompactor

NewConversationCompactor creates a ConversationCompactor. protectedTurns is the number of recent turn pairs (user + assistant) to keep verbatim.

func (*ConversationCompactor) Compact added in v0.4.0 

func (c *ConversationCompactor) Compact(ctx context.Context, messages []schema.Message) ([]schema.Message, int, error)

Compact compresses messages by summarizing eligible (non-protected) messages. Returns the compressed message slice and the estimated token count of the result.

Protected messages: the first message if it is a system message, plus the last protectedTurns user/assistant exchange pairs.

The summary replaces all eligible messages with a single system-role message carrying metadata {"compressed": true, "source_count": N, "strategy": "conversation_compact"}.

func (*ConversationCompactor) EstimateTokens added in v0.4.0 

func (c *ConversationCompactor) EstimateTokens(messages []schema.Message) int

EstimateTokens returns the total estimated token count for a message slice.

func (*ConversationCompactor) Summarizer added in v0.4.0 

func (c *ConversationCompactor) Summarizer() Summarizer

Summarizer returns the underlying summarizer function.

func (*ConversationCompactor) WithMaxInputTokens added in v0.4.0 

func (c *ConversationCompactor) WithMaxInputTokens(n int) *ConversationCompactor

WithMaxInputTokens sets the maximum token count for the summarizer input. If the eligible messages exceed this, the input is truncated with an omission marker. This prevents the summarization call itself from exceeding the context window.

func (*ConversationCompactor) WithTokenEstimator added in v0.4.0 

func (c *ConversationCompactor) WithTokenEstimator(est TokenEstimator) *ConversationCompactor

WithTokenEstimator sets a custom token estimator.

type Entry 

type Entry struct {
	Key       string    `json:"key"`
	Value     any       `json:"value"`
	Scope     Scope     `json:"scope"`
	AgentID   string    `json:"agent_id,omitempty"`
	SessionID string    `json:"session_id,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	TTL       int64     `json:"ttl,omitempty"` // seconds; 0 means no expiry
}

Entry is a single memory item stored in any tier.

type ImportanceRankingCompressor 

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

ImportanceRankingCompressor keeps the most important messages within a token budget, using a scorer function to rank messages by importance. The most important message is always retained regardless of token budget.

func NewImportanceRankingCompressor 

func NewImportanceRankingCompressor(scorer MessageScorer) *ImportanceRankingCompressor

NewImportanceRankingCompressor creates an ImportanceRankingCompressor with the given scorer. Panics if scorer is nil.

func NewImportanceRankingCompressorWithDefaults 

func NewImportanceRankingCompressorWithDefaults() *ImportanceRankingCompressor

NewImportanceRankingCompressorWithDefaults creates a compressor using DefaultMessageScorer.

func (*ImportanceRankingCompressor) Compress 

func (c *ImportanceRankingCompressor) Compress(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)

Compress keeps the most important messages that fit within maxTokens. If maxTokens is 0 or negative, all messages are returned unchanged. The highest-scored message is always retained regardless of budget. Output messages are in chronological order.

func (*ImportanceRankingCompressor) WithTokenEstimator 

func (c *ImportanceRankingCompressor) WithTokenEstimator(est TokenEstimator) *ImportanceRankingCompressor

WithTokenEstimator sets a custom token estimator. Nil values are ignored.

type Manager 

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

Manager orchestrates the three-tier memory system.

func NewManager 

func NewManager(opts ...ManagerOption) *Manager

NewManager creates a Manager with the given options. Defaults: PromoteAll promoter, ArchiveNone archiver.

func (*Manager) ArchiveToStore 

func (mgr *Manager) ArchiveToStore(ctx context.Context) error

ArchiveToStore archives entries from session memory to store memory. Returns an error if archival fails, but callers should not fail the Run.

func (*Manager) Compressor 

func (mgr *Manager) Compressor() ContextCompressor

Compressor returns the context compressor, or nil if not configured.

func (*Manager) PromoteToSession 

func (mgr *Manager) PromoteToSession(ctx context.Context, working Memory) error

PromoteToSession promotes entries from working memory to session memory. Returns an error if promotion fails, but callers should not fail the Run.

func (*Manager) Session 

func (mgr *Manager) Session() Memory

Session returns the session-tier memory, or nil if not configured.

func (*Manager) Store 

func (mgr *Manager) Store() Memory

Store returns the store-tier memory, or nil if not configured.

type ManagerOption 

type ManagerOption func(*Manager)

ManagerOption configures a Manager.

func WithArchiver 

func WithArchiver(a Archiver) ManagerOption

WithArchiver sets the archival strategy.

func WithCompressor 

func WithCompressor(c ContextCompressor) ManagerOption

WithCompressor sets the context compression strategy.

func WithPromoter 

func WithPromoter(p Promoter) ManagerOption

WithPromoter sets the promotion strategy.

func WithSession 

func WithSession(m Memory) ManagerOption

WithSession sets the session-tier memory.

func WithStore 

func WithStore(m Memory) ManagerOption

WithStore sets the store-tier memory.

type MapStore 

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

MapStore is an in-memory Store backed by a plain Go map. It is not safe for concurrent use; callers must provide their own locking.

func NewMapStore 

func NewMapStore() *MapStore

NewMapStore creates a new MapStore.

func (*MapStore) BatchGet 

func (s *MapStore) BatchGet(ctx context.Context, keys []string) (map[string]any, error)

func (*MapStore) BatchSet 

func (s *MapStore) BatchSet(_ context.Context, entries map[string]any, ttl int64) error

func (*MapStore) Clear 

func (s *MapStore) Clear(_ context.Context) error

func (*MapStore) Delete 

func (s *MapStore) Delete(_ context.Context, key string) error

func (*MapStore) Get 

func (s *MapStore) Get(_ context.Context, key string) (any, bool, error)

func (*MapStore) List 

func (s *MapStore) List(_ context.Context, prefix string) ([]StoreEntry, error)

func (*MapStore) Set 

func (s *MapStore) Set(_ context.Context, key string, value any, ttl int64) error

func (*MapStore) SetCreatedAtForTest 

func (s *MapStore) SetCreatedAtForTest(key string, t time.Time)

SetCreatedAtForTest backdates the CreatedAt of the given key. Intended for testing TTL expiry without real sleeps.

type Memory 

type Memory interface {
	// Get returns the value for the given key, or nil if not found.
	Get(ctx context.Context, key string) (any, error)
	// Set stores a value under the given key with an optional TTL in seconds.
	Set(ctx context.Context, key string, value any, ttl int64) error
	// Delete removes the entry for the given key.
	Delete(ctx context.Context, key string) error
	// List returns all entries whose keys have the given prefix.
	List(ctx context.Context, prefix string) ([]Entry, error)
	// Clear removes all entries.
	Clear(ctx context.Context) error
	// BatchGet returns the values for the given keys.
	BatchGet(ctx context.Context, keys []string) (map[string]any, error)
	// BatchSet stores multiple key-value pairs with the given TTL.
	BatchSet(ctx context.Context, entries map[string]any, ttl int64) error
}

Memory is the core interface for a memory tier.

type MessageScorer 

type MessageScorer func(messages []schema.Message, index int) float64

MessageScorer assigns an importance score to a message. Higher scores indicate more important messages. The full message slice is provided so scorers can make context-aware decisions (e.g., keeping tool-call/tool-result pairs together). Parameters: the full messages slice and the index of the message to score.

type PersistentMemory 

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

PersistentMemory is a cross-session persistent in-process memory store. It is safe for concurrent use.

func NewPersistentMemory 

func NewPersistentMemory() *PersistentMemory

NewPersistentMemory creates a new PersistentMemory backed by an in-memory MapStore.

func NewPersistentMemoryWithStore 

func NewPersistentMemoryWithStore(store Store) *PersistentMemory

NewPersistentMemoryWithStore creates a new PersistentMemory backed by the given Store.

func (*PersistentMemory) BatchGet 

func (m *PersistentMemory) BatchGet(ctx context.Context, keys []string) (map[string]any, error)

func (*PersistentMemory) BatchSet 

func (m *PersistentMemory) BatchSet(ctx context.Context, entries map[string]any, ttl int64) error

func (*PersistentMemory) Clear 

func (m *PersistentMemory) Clear(ctx context.Context) error

func (*PersistentMemory) Delete 

func (m *PersistentMemory) Delete(ctx context.Context, key string) error

func (*PersistentMemory) Get 

func (m *PersistentMemory) Get(ctx context.Context, key string) (any, error)

func (*PersistentMemory) List 

func (m *PersistentMemory) List(ctx context.Context, prefix string) ([]Entry, error)

func (*PersistentMemory) Set 

func (m *PersistentMemory) Set(ctx context.Context, key string, value any, ttl int64) error

type PromoteFunc 

type PromoteFunc func(ctx context.Context, entries []Entry) ([]Entry, error)

PromoteFunc is a function adapter for Promoter.

func (PromoteFunc) Promote 

func (f PromoteFunc) Promote(ctx context.Context, entries []Entry) ([]Entry, error)

Promote implements Promoter.

type Promoter 

type Promoter interface {
	Promote(ctx context.Context, entries []Entry) ([]Entry, error)
}

Promoter decides which working memory entries are promoted to session memory.

func PromoteAll 

func PromoteAll() Promoter

PromoteAll returns a promoter that promotes all entries.

func PromoteNone 

func PromoteNone() Promoter

PromoteNone returns a promoter that promotes no entries.

type Scope 

type Scope string

Scope identifies the memory tier an entry belongs to. 

const (
	// ScopeWorking is per-Run working memory, discarded after each run.
	ScopeWorking Scope = "working"
	// ScopeSession is per-session memory, persists across runs within a session.
	ScopeSession Scope = "session"
	// ScopeStore is cross-session persistent memory.
	ScopeStore Scope = "store"
)

type SessionMemory 

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

SessionMemory is a per-session in-process memory store. It is safe for concurrent use.

func NewSessionMemory 

func NewSessionMemory(agentID, sessionID string) *SessionMemory

NewSessionMemory creates a new SessionMemory backed by an in-memory MapStore.

func NewSessionMemoryWithStore 

func NewSessionMemoryWithStore(store Store, agentID, sessionID string) *SessionMemory

NewSessionMemoryWithStore creates a new SessionMemory backed by the given Store.

func (*SessionMemory) BatchGet 

func (m *SessionMemory) BatchGet(ctx context.Context, keys []string) (map[string]any, error)

func (*SessionMemory) BatchSet 

func (m *SessionMemory) BatchSet(ctx context.Context, entries map[string]any, ttl int64) error

func (*SessionMemory) Clear 

func (m *SessionMemory) Clear(ctx context.Context) error

func (*SessionMemory) Delete 

func (m *SessionMemory) Delete(ctx context.Context, key string) error

func (*SessionMemory) Get 

func (m *SessionMemory) Get(ctx context.Context, key string) (any, error)

func (*SessionMemory) List 

func (m *SessionMemory) List(ctx context.Context, prefix string) ([]Entry, error)

func (*SessionMemory) Set 

func (m *SessionMemory) Set(ctx context.Context, key string, value any, ttl int64) error

type SlidingWindowCompressor 

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

SlidingWindowCompressor keeps the last N messages, then delegates to TokenBudgetCompressor for token-based trimming within the window.

func NewSlidingWindowCompressor 

func NewSlidingWindowCompressor(windowSize int) *SlidingWindowCompressor

NewSlidingWindowCompressor creates a compressor that keeps the last windowSize messages. Panics if windowSize is not positive.

func (*SlidingWindowCompressor) Compress 

func (c *SlidingWindowCompressor) Compress(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)

Compress returns the last windowSize messages, optionally trimmed to fit within maxTokens. If maxTokens is 0 or negative, no token budget is applied.

func (*SlidingWindowCompressor) WithTokenEstimator 

func (c *SlidingWindowCompressor) WithTokenEstimator(est TokenEstimator) *SlidingWindowCompressor

WithTokenEstimator sets a custom token estimator for the internal token budget check.

type Store 

type Store interface {
	Get(ctx context.Context, key string) (any, bool, error)
	Set(ctx context.Context, key string, value any, ttl int64) error
	Delete(ctx context.Context, key string) error
	List(ctx context.Context, prefix string) ([]StoreEntry, error)
	Clear(ctx context.Context) error
}

Store is the low-level interface for raw key-value storage backends. Implementations must be safe for use by a single goroutine; the memory tiers provide their own concurrency control when needed.

type StoreEntry 

type StoreEntry struct {
	Key       string
	Value     any
	CreatedAt time.Time
	TTL       int64
}

StoreEntry is a single record returned by Store.List.

type SummarizeAndTruncCompressor 

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

SummarizeAndTruncCompressor splits messages into older and recent parts, summarizes the older messages, and prepends the summary to the recent ones. The keepLastN parameter controls how many recent messages to keep verbatim. When maxTokens > 0, the summary text is truncated to fit the remaining token budget after accounting for the recent messages.

func NewSummarizeAndTruncCompressor 

func NewSummarizeAndTruncCompressor(summarizer Summarizer, keepLastN int, opts ...SummarizeAndTruncOption) *SummarizeAndTruncCompressor

NewSummarizeAndTruncCompressor creates a new SummarizeAndTruncCompressor. Panics if summarizer is nil or keepLastN <= 0.

func (*SummarizeAndTruncCompressor) Compress 

func (c *SummarizeAndTruncCompressor) Compress(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)

Compress summarizes older messages and keeps the last keepLastN messages verbatim. When maxTokens > 0, the summary text is truncated proportionally to fit the remaining token budget after accounting for recent messages.

func (*SummarizeAndTruncCompressor) WithTokenEstimator 

func (c *SummarizeAndTruncCompressor) WithTokenEstimator(est TokenEstimator) *SummarizeAndTruncCompressor

WithTokenEstimator sets a custom token estimator. Nil values are ignored.

type SummarizeAndTruncOption 

type SummarizeAndTruncOption func(*SummarizeAndTruncCompressor)

SummarizeAndTruncOption configures a SummarizeAndTruncCompressor.

func WithSummaryRole 

func WithSummaryRole(role aimodel.Role) SummarizeAndTruncOption

WithSummaryRole sets the role assigned to the summary message. Defaults to aimodel.RoleUser.

type Summarizer 

type Summarizer func(ctx context.Context, messages []schema.Message) (string, error)

Summarizer is a function that summarizes messages into a single text string.

type TokenBudgetCompressor 

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

TokenBudgetCompressor keeps the most recent messages that fit within a token budget. It uses a simple reverse-iteration strategy: starting from the newest message, it accumulates messages until the budget is exhausted.

func NewTokenBudgetCompressor 

func NewTokenBudgetCompressor() *TokenBudgetCompressor

NewTokenBudgetCompressor creates a new TokenBudgetCompressor with DefaultTokenEstimator.

func (*TokenBudgetCompressor) Compress 

func (c *TokenBudgetCompressor) Compress(ctx context.Context, messages []schema.Message, maxTokens int) ([]schema.Message, error)

Compress keeps the most recent messages that fit within maxTokens. If maxTokens is 0 or negative, all messages are returned unchanged. At least one message (the most recent) is always returned for non-empty input.

func (*TokenBudgetCompressor) WithTokenEstimator 

func (c *TokenBudgetCompressor) WithTokenEstimator(est TokenEstimator) *TokenBudgetCompressor

WithTokenEstimator sets a custom token estimator. Nil values are ignored.

type TokenEstimator 

type TokenEstimator func(msg schema.Message) int

TokenEstimator estimates the token count for a message. Implementations can use simple heuristics or real tokenizers depending on accuracy needs.

type WorkingMemory 

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

WorkingMemory is a per-Run in-process memory store. It is not safe for concurrent use (single goroutine per Run).

func NewWorkingMemory 

func NewWorkingMemory(agentID, sessionID string) *WorkingMemory

NewWorkingMemory creates a new WorkingMemory backed by an in-memory MapStore.

func NewWorkingMemoryWithStore 

func NewWorkingMemoryWithStore(store Store, agentID, sessionID string) *WorkingMemory

NewWorkingMemoryWithStore creates a new WorkingMemory backed by the given Store.

func (*WorkingMemory) BatchGet 

func (m *WorkingMemory) BatchGet(ctx context.Context, keys []string) (map[string]any, error)

func (*WorkingMemory) BatchSet 

func (m *WorkingMemory) BatchSet(ctx context.Context, entries map[string]any, ttl int64) error

func (*WorkingMemory) Clear 

func (m *WorkingMemory) Clear(ctx context.Context) error

func (*WorkingMemory) Delete 

func (m *WorkingMemory) Delete(ctx context.Context, key string) error

func (*WorkingMemory) Get 

func (m *WorkingMemory) Get(ctx context.Context, key string) (any, error)

func (*WorkingMemory) List 

func (m *WorkingMemory) List(ctx context.Context, prefix string) ([]Entry, error)

func (*WorkingMemory) Set 

func (m *WorkingMemory) Set(ctx context.Context, key string, value any, ttl int64) error

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.