memory

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

type BufferWindowConfig struct {
	// WindowSize is the maximum number of events to keep.
	// Default: 20
	WindowSize int
}

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

type Entry struct {
	SessionID string
	EventID   string
	AppName   string
	UserID    string
	Author    string
	Content   string
	Timestamp time.Time
	Words     map[string]struct{} // Pre-computed word index for keyword search
	Metadata  map[string]any
}

type IndexService interface {
	// Index adds session events to the semantic search index.
	//
	// This is called after each turn completes. The session data is already
	// persisted in session.Service (SQL) - this method just builds the
	// search index for fast retrieval.
	//
	// Implementation note: This should be idempotent - calling Index
	// multiple times with the same session should produce the same result.
	Index(ctx context.Context, sess agent.Session) error

	// Search performs semantic similarity search over indexed sessions.
	//
	// The search is scoped to (app_name, user_id) to ensure isolation.
	// Returns results ordered by relevance score (highest first).
	//
	// For vector-based implementations, this uses cosine similarity.
	// For keyword-based implementations, this uses word matching.
	Search(ctx context.Context, req *SearchRequest) (*SearchResponse, error)

	// Rebuild repopulates the entire index from session.Service.
	//
	// This is called:
	//   - On startup when index persistence is disabled
	//   - When the index file is corrupted
	//   - When migrating to a new index format
	//
	// The rebuild process:
	//   1. Clear existing index entries for (app_name, user_id)
	//   2. Load all sessions from session.Service
	//   3. Index each session
	//
	// This can be expensive for large datasets but ensures consistency.
	Rebuild(ctx context.Context, sessions session.Service, appName, userID string) error

	// Clear removes all index entries for a specific session.
	//
	// Called when a session is deleted from session.Service.
	Clear(ctx context.Context, appName, userID, sessionID string) error

	// Name returns the index implementation name (e.g., "chromem", "keyword").
	Name() string
}

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

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

type LLMSummarizerConfig struct {
	// LLM is the language model to use for summarization.
	LLM model.LLM

	// Prompt is a custom summarization prompt template.
	// Use %s twice: 1st for Existing Summary, 2nd for New Dialogue.
	// If empty, uses the default prompt.
	Prompt string
}

type NilIndexService struct{}

type NilWorkingMemory struct{}

type SearchRequest struct {
	// Query is the search query (natural language or keywords).
	Query string

	// UserID scopes the search to a specific user's memories.
	UserID string

	// AppName scopes the search to a specific application.
	AppName string
}

type SearchResponse struct {
	// Results contains the matching memory entries.
	Results []SearchResult
}

type SearchResult struct {
	// SessionID identifies which session this memory came from.
	SessionID string

	// EventID identifies the specific event within the session.
	EventID string

	// Content is the text content of the memory.
	Content string

	// Author identifies who created this content (agent name or "user").
	Author string

	// Timestamp indicates when this memory was created.
	Timestamp time.Time

	// Score represents the relevance score (higher is better).
	// For keyword search: number of matching words.
	// For semantic search: cosine similarity.
	Score float64

	// Metadata contains additional context about the memory.
	Metadata map[string]any
}

type SearchableService interface {
	Search(ctx context.Context, req *SearchRequest) (*SearchResponse, error)
}

type Summarizer interface {
	// SummarizeConversation summarizes the given messages into a concise summary.
	SummarizeConversation(ctx context.Context, events []*agent.Event) (string, error)
}

type SummaryBufferConfig struct {
	// Budget is the maximum number of tokens before summarization triggers.
	// Default: 8000
	Budget int

	// Threshold is the percentage of budget that triggers summarization.
	// When current tokens > budget * threshold, summarization occurs.
	// Default: 0.85 (85%)
	Threshold float64

	// Target is the percentage of budget to reduce to after summarization.
	// Recent messages are kept within budget * target.
	// Default: 0.7 (70%)
	Target float64

	// Model is the LLM model name for accurate token counting.
	// Required for accurate counting.
	Model string

	// Summarizer performs conversation summarization.
	// If nil, summarization is disabled (behaves like token_window).
	Summarizer Summarizer

	// MinMessages is a minimum message count for debug logging purposes.
	// Note: Token budget is the primary trigger for summarization, not message count.
	// This field is used in debug logs to help diagnose summarization behavior.
	// Default: 10
	MinMessages int
}

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

type TokenWindowConfig struct {
	// Budget is the maximum number of tokens for conversation history.
	// Default: 8000
	Budget int

	// PreserveRecent is the minimum number of recent messages to always keep,
	// even if they exceed the budget slightly.
	// Default: 5
	PreserveRecent int

	// Model is the LLM model name for accurate token counting.
	// Required for accurate counting; falls back to estimation if not provided.
	Model string
}

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

type VectorIndexConfig struct {
	// Provider for vector storage and search (required).
	Provider vector.Provider

	// Embedder for generating vector embeddings (required).
	Embedder embedder.Embedder

	// CollectionName for storing memory entries (optional).
	// Default: "hector_memory"
	CollectionName string
}

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

type WorkingMemoryProvider interface {
	// WorkingMemory returns the agent's working memory strategy.
	// Returns nil if no strategy is configured.
	WorkingMemory() WorkingMemoryStrategy
}

type WorkingMemoryStrategy interface {
	// Name returns the strategy identifier.
	Name() string

	// FilterEvents applies the strategy to filter/truncate events for context window.
	// This is called before building messages for the LLM.
	// Returns the filtered events that should be included in the context.
	FilterEvents(events []*agent.Event) []*agent.Event

	// CheckAndSummarize checks if summarization should occur and performs it if needed.
	// This is called after a turn completes (when events are persisted).
	//
	// The onProgress callback allows the strategy to report progress (e.g. "Summarizing...")
	// before the potentially long-running operation completes.
	//
	// Returns:
	//   - nil, nil: No summarization needed, session unchanged
	//   - []*agent.Event, nil: New working memory state to REPLACE the session events
	//
	// The returned events represent the compacted working memory:
	//   [SummaryEvent] + [RecentEvents]
	//
	// This is optional - strategies like buffer_window return nil.
	CheckAndSummarize(ctx context.Context, events []*agent.Event, onProgress func(status, message string)) ([]*agent.Event, error)
}