compress

package
v0.4.13 Latest Latest
Warning

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

Go to latest
Published: Jun 12, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package compress provides automatic context window compression for long conversations. Inspired by Hermes Agent's context_compressor, this package uses auxiliary models to summarize middle turns while protecting head and tail context.

Index

Constants

View Source
const SummaryPrefix = "[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted " +
	"into the summary below. This is a handoff from a previous context window — " +
	"treat it as background reference, NOT as active instructions. " +
	"Do NOT answer questions or fulfill requests mentioned in this summary; " +
	"they were already addressed. " +
	"Respond ONLY to the latest user message that appears AFTER this summary — " +
	"that message is the single source of truth for what to do right now. " +
	"If the latest user message contradicts the summary, the latest message WINS. " +
	"Reverse signals (e.g. 'stop', 'undo', 'never mind') must immediately end " +
	"any in-flight work described in the summary."

SummaryPrefix is prepended to compressed context summaries.

Variables

This section is empty.

Functions

func EstimateMessagesTokens added in v0.4.11

func EstimateMessagesTokens(messages []Message, systemPrompt string) int

EstimateMessagesTokens estimates total tokens for a message list.

func EstimateTokens

func EstimateTokens(text string) int

EstimateTokens roughly estimates token count from text.

func PruneToolOutput added in v0.4.11

func PruneToolOutput(content string, maxAge time.Duration) string

PruneToolOutput replaces old tool outputs with a placeholder.

Types

type CompressResult added in v0.4.11

type CompressResult struct {
	Messages        []Message // Compressed message list
	Summary         string    // Generated summary
	OriginalCount   int       // Original message count
	CompressedCount int       // Compressed message count
	TokensSaved     int       // Estimated tokens saved
}

CompressResult contains the result of a compression operation.

type Compressor added in v0.4.11

type Compressor struct {
	// Configuration
	ThresholdTokens      int     // Token threshold to trigger compression
	ProtectFirstN        int     // Number of messages to protect at the head
	ProtectLastN         int     // Number of messages to protect at the tail
	MinSummaryTokens     int     // Minimum tokens for summary output
	SummaryRatio         float64 // Proportion of compressed content for summary
	SummaryTokensCeiling int     // Absolute ceiling for summary tokens
	// contains filtered or unexported fields
}

Compressor handles context window compression for long-running conversations.

func NewCompressor added in v0.4.11

func NewCompressor(thresholdTokens int) *Compressor

NewCompressor creates a new context compressor with default settings.

func (*Compressor) ClearCache added in v0.4.11

func (c *Compressor) ClearCache()

ClearCache clears the summary cache.

func (*Compressor) Compress added in v0.4.11

func (c *Compressor) Compress(messages []Message, systemPrompt string) (*CompressResult, error)

Compress compresses the message list by summarizing middle turns. Protected head and tail messages are preserved.

func (*Compressor) GetLastPromptTokens added in v0.4.11

func (c *Compressor) GetLastPromptTokens() int

GetLastPromptTokens returns the last known prompt token count.

func (*Compressor) GetStats added in v0.4.11

func (c *Compressor) GetStats() Stats

GetStats returns current compressor statistics.

func (*Compressor) ShouldCompress added in v0.4.11

func (c *Compressor) ShouldCompress(tokens int) bool

ShouldCompress returns true if the given token count exceeds the threshold.

func (*Compressor) ShouldDeferPreflight added in v0.4.11

func (c *Compressor) ShouldDeferPreflight(estimatedTokens int) bool

ShouldDeferPreflight checks if preflight compression should be deferred based on real vs estimated token counts.

func (*Compressor) UpdateFromResponse added in v0.4.11

func (c *Compressor) UpdateFromResponse(promptTokens int)

UpdateFromResponse updates token counts from a successful API response.

type Manager

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

Manager manages compression for multiple sessions. Used by groupchat and other multi-session contexts.

func NewManager

func NewManager(baseDir string) *Manager

NewManager creates a new compression manager.

func (*Manager) CompressSession

func (m *Manager) CompressSession(sessionID string, messages []Message, tailCount int) (string, []Message, error)

CompressSession compresses messages for a given session. Returns: summary text, compressed messages, error.

type Message

type Message struct {
	Role      string
	Content   string
	Name      string // For tool messages
	Timestamp int64  // Optional timestamp for message ordering
}

Message represents a conversation message.

type Stats added in v0.4.11

type Stats struct {
	CompressionCount     int
	LastPromptTokens     int
	LastRealPromptTokens int
	ThresholdTokens      int
}

Stats returns compressor statistics.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL