memory

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

type HybridMemoryConfig struct {
	// MaxShortTermMessages is the number of messages to keep in short-term memory
	// MaxShortTermMessages 是短期内存中保留的消息数
	MaxShortTermMessages int

	// LongTermThreshold is when to move messages to long-term (0 = disabled)
	// LongTermThreshold 是何时将消息移动到长期存储（0 = 禁用）
	LongTermThreshold int

	// VectorDB is the vector database for long-term storage
	// VectorDB 是用于长期存储的向量数据库
	VectorDB vectordb.VectorDB

	// Embedder generates embeddings for vector search
	// Embedder 生成向量搜索的嵌入
	Embedder vectordb.EmbeddingFunction

	// CollectionName is the vector DB collection name
	// CollectionName 是向量数据库集合名称
	CollectionName string

	// Default search options
	// 默认搜索选项
	DefaultVectorWeight float64
	DefaultTextWeight   float64
	DefaultMinScore     float64
}

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

type Memory interface {
	// Add appends a message to memory for a specific user
	// Add 为特定用户添加消息到内存
	// userID can be empty string for non-multi-tenant scenarios
	// userID 可以为空字符串（非多租户场景）
	Add(message *types.Message, userID ...string)

	// GetMessages returns all messages for a specific user
	// GetMessages 返回特定用户的所有消息
	// userID can be empty string for non-multi-tenant scenarios
	// userID 可以为空字符串（非多租户场景）
	GetMessages(userID ...string) []*types.Message

	// Clear removes all messages for a specific user (or all users if userID is empty)
	// Clear 删除特定用户的所有消息（如果userID为空则删除所有用户）
	Clear(userID ...string)

	// Size returns the number of messages for a specific user
	// Size 返回特定用户的消息数量
	Size(userID ...string) int
}

type SearchOptions struct {
	// Limit is the maximum number of results to return
	// Limit 是返回的最大结果数
	Limit int

	// MinScore is the minimum relevance score (0-1)
	// MinScore 是最小相关性分数（0-1）
	MinScore float64

	// VectorWeight is the weight for vector similarity (default: 0.7)
	// VectorWeight 是向量相似度的权重（默认：0.7）
	VectorWeight float64

	// TextWeight is the weight for text similarity (default: 0.3)
	// TextWeight 是文本相似度的权重（默认：0.3）
	TextWeight float64

	// FilterByRole limits search to specific message roles
	// FilterByRole 将搜索限制为特定消息角色
	FilterByRole []types.Role

	// IncludeRecent indicates whether to always include recent messages
	// IncludeRecent 表示是否始终包含最近的消息
	IncludeRecent bool

	// RecentCount is the number of recent messages to include
	// RecentCount 是要包含的最近消息数
	RecentCount int
}

type SearchResult struct {
	Message     *types.Message `json:"message"`
	Score       float64        `json:"score"`        // Combined relevance score (0-1)
	VectorScore float64        `json:"vector_score"` // Vector similarity score
	TextScore   float64        `json:"text_score"`   // Text similarity score
	Source      string         `json:"source"`       // "short_term" or "long_term"
}

type SearchableMemory interface {
	Memory

	// Search searches for relevant messages using hybrid vector + text search
	// Search 使用混合向量+文本搜索查找相关消息
	// Returns messages sorted by relevance score (descending)
	// 返回按相关性分数排序的消息（降序）
	Search(ctx context.Context, query string, limit int, userID ...string) ([]SearchResult, error)

	// SearchWithOptions searches with advanced options
	// SearchWithOptions 使用高级选项搜索
	SearchWithOptions(ctx context.Context, query string, options SearchOptions, userID ...string) ([]SearchResult, error)
}