memory

type AccessLevel int

type CompressedObservation struct {
	// Summary 压缩后的摘要
	Summary string `json:"summary"`

	// References 保留的引用（URL、文件路径等）
	References []Reference `json:"references,omitempty"`

	// Hash 原始内容的哈希值（用于验证恢复）
	Hash string `json:"hash"`

	// OriginalLength 原始内容长度
	OriginalLength int `json:"original_length"`

	// Recoverable 是否可恢复
	Recoverable bool `json:"recoverable"`

	// ToolName 产生此观察的工具名
	ToolName string `json:"tool_name"`

	// CompressionRatio 压缩比率
	CompressionRatio float64 `json:"compression_ratio"`
}

type CompressionLevel int

type CompressionStats struct {
	OriginalMessages   int           // 原始消息数
	CompressedMessages int           // 压缩后消息数
	OriginalTokens     int           // 原始 Token 数
	CompressedTokens   int           // 压缩后 Token 数
	CompressionRatio   float64       // 压缩比率
	Duration           time.Duration // 压缩耗时
}

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

type ConfidenceConfig struct {
	// DecayHalfLife 置信度衰减半衰期。
	// 记忆经过这个时长后，置信度衰减到原来的50%。
	DecayHalfLife time.Duration

	// MinConfidence 最低置信度阈值。
	// 低于此值的记忆应被剪枝（遗忘）。
	MinConfidence float64

	// CorroborationBoost 每次验证增加的置信度。
	CorroborationBoost float64

	// MaxCorroborationBoost 验证提升的最大累计值。
	MaxCorroborationBoost float64

	// RecencyWeight 最近访问对置信度的权重（0.0-1.0）。
	// 0 表示不考虑访问时间，1 表示完全基于访问时间。
	RecencyWeight float64
}

type ConfidenceTier string

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

type ConflictStrategy int

type ConsolidatedMemory struct {
	Text           string              // 合并后的文本
	Metadata       map[string]any      // 合并后的元数据
	Provenance     *MemoryProvenance   // 合并后的溯源
	SourceMemories []string            // 源记忆 ID 列表
	Reason         ConsolidationReason // 合并原因
	ConsolidatedAt time.Time           // 合并时间
}

type ConsolidationAction struct {
	Operation       ConsolidationOperation
	TargetMemoryID  string              // 目标记忆 ID（用于 update/delete）
	SourceMemoryIDs []string            // 源记忆 ID 列表（用于 merge）
	NewMemory       *ConsolidatedMemory // 新记忆内容（用于 create/update/merge）
	Reason          string              // 操作原因
}

type ConsolidationConfig struct {
	// 相似度阈值（超过此值认为是冗余）
	SimilarityThreshold float64

	// 冲突检测阈值（语义相似但内容矛盾）
	ConflictThreshold float64

	// 最小记忆数量（少于此数量不触发合并）
	MinMemoryCount int

	// 批处理大小（每次处理的记忆数量）
	BatchSize int

	// 自动合并间隔
	AutoConsolidateInterval time.Duration

	// 是否保留原始记忆（合并后标记为已合并，而不是删除）
	PreserveOriginal bool

	// LLM 模型名称
	LLMModel string

	// 最大重试次数
	MaxRetries int
}

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

type ConsolidationOperation string

type ConsolidationReason string

type ConsolidationResult struct {
	Success        bool
	Message        string
	StartTime      time.Time
	EndTime        time.Time
	Duration       time.Duration
	Strategy       string
	MemoryGroups   []MemoryGroup
	MergedCount    int // 合并的记忆数量
	NewMemoryCount int // 生成的新记忆数量
	Errors         []string
}

type ConsolidationStats struct {
	LastConsolidation   time.Time
	ConsolidationCount  int64
	MergedMemoriesCount int64
}

type ConsolidationStrategy interface {
	// Name 返回策略名称
	Name() string

	// ShouldConsolidate 判断是否应该合并这些记忆
	ShouldConsolidate(ctx context.Context, memories []MemoryWithScore) (bool, ConsolidationReason)

	// Consolidate 执行合并
	Consolidate(ctx context.Context, memories []MemoryWithScore, llm LLMProvider) (*ConsolidatedMemory, error)
}

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

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

type ImproveQuality struct {
	MemoryID     string
	CurrentScore float64
	Suggestions  []string
}

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

type Inconsistency struct {
	Type        InconsistencyType // 不一致性类型
	MemoryID1   string            // 第一个记忆 ID
	MemoryID2   string            // 第二个记忆 ID（如果适用）
	Description string            // 描述
	Severity    float64           // 严重程度 (0.0-1.0)
	DetectedAt  time.Time         // 检测时间
}

type InconsistencyType string

type JSONSchema struct {
	Type       string                 `json:"type,omitempty"`       // object, string, number, array, boolean
	Properties map[string]*JSONSchema `json:"properties,omitempty"` // 对象属性（仅 type=object 时有效）
	Items      *JSONSchema            `json:"items,omitempty"`      // 数组元素（仅 type=array 时有效）
	Required   []string               `json:"required,omitempty"`   // 必需字段（仅 type=object 时有效）
	Enum       []any                  `json:"enum,omitempty"`       // 枚举值
	MinLength  *int                   `json:"minLength,omitempty"`  // 最小长度（仅 type=string 时有效）
	MaxLength  *int                   `json:"maxLength,omitempty"`  // 最大长度（仅 type=string 时有效）
	Pattern    string                 `json:"pattern,omitempty"`    // 正则模式（仅 type=string 时有效）
}

type LLMProvider interface {
	// Complete 完成文本生成
	Complete(ctx context.Context, prompt string, options map[string]any) (string, error)
}

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

type LLMSummarizerConfig struct {
	// LLM 配置
	Provider string // LLM 提供商（如 "openai", "anthropic"）
	Model    string // 模型名称
	APIKey   string // API 密钥
	BaseURL  string // API 基础 URL

	// 总结配置
	Level           CompressionLevel // 压缩级别
	MaxSummaryWords int              // 最大总结字数
	PreserveContext bool             // 是否保留上下文信息
	Language        string           // 总结语言（"zh", "en"）

	// Token 配置
	TokenCounter agentext.TokenCounter // Token 计数器
}

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

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

type LineageMetadata struct {
	ID             string   // 记忆ID
	SourceIDs      []string // 来源标识（session/document ID）
	DerivedFromIDs []string // 派生自哪些记忆
	CreatedAt      int64    // Unix timestamp
}

type LineageStats struct {
	TotalMemories    int            // 总记忆数
	RootMemories     int            // 根记忆数（无父记忆）
	DerivedMemories  int            // 派生记忆数（有父记忆）
	MaxDepth         int            // 最大谱系深度
	MemoriesBySource map[string]int // 每个数据源的记忆数
}

type LongTermBridge struct {
	Sessions       session.Service
	SemanticMemory *SemanticMemory
}

type LongTermBridgeConfig struct {
	// MinTokens 用于过滤过短的内容（粗略按单词数统计），<=0 表示不做限制。
	MinTokens int
}

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

type ManagerConfig struct {
	Backend    backends.BackendProtocol
	MemoryPath string // 记忆文件根路径,默认: "/memories/"
}

type MemoryGroup struct {
	Memories       []MemoryWithScore
	ConsolidatedID string
	Reason         ConsolidationReason
}

type MemoryProvenance struct {
	// SourceType 数据来源类型。
	SourceType SourceType `json:"source_type"`

	// Confidence 置信度评分（0.0-1.0）。
	// 基于来源类型、年龄和验证状态计算。
	Confidence float64 `json:"confidence"`

	// Sources 来源标识列表（如 session IDs, document IDs）。
	// 用于追踪记忆的派生关系。
	Sources []string `json:"sources"`

	// CreatedAt 记忆创建时间。
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt 记忆最后更新时间。
	UpdatedAt time.Time `json:"updated_at"`

	// Version 记忆版本号。
	// 每次更新时递增，用于冲突检测和乐观锁。
	Version int `json:"version"`

	// IsExplicit 是否为用户显式指示记住的信息。
	// 显式记忆的初始置信度更高。
	IsExplicit bool `json:"is_explicit,omitempty"`

	// CorroborationCount 被其他来源验证的次数。
	// 多源验证可提升置信度。
	CorroborationCount int `json:"corroboration_count,omitempty"`

	// LastAccessedAt 记忆最后访问时间。
	// 用于计算相关性和实施LRU淘汰。
	LastAccessedAt *time.Time `json:"last_accessed_at,omitempty"`

	// Tags 记忆标签，用于分类和检索。
	Tags []string `json:"tags,omitempty"`
}

type MemoryQuality struct {
	MemoryID  string       // 记忆 ID
	Score     QualityScore // 质量分数
	Issues    []string     // 检测到的问题
	UpdatedAt time.Time    // 更新时间
}

type MemoryScope string

type MemoryWithScore struct {
	DocID      string
	Text       string
	Metadata   map[string]any
	Provenance *MemoryProvenance
	Score      float64 // 与查询的相似度
}

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

type MultiLevelCompressorConfig struct {
	// 消息级压缩配置
	EnableMessageLevel bool
	MessageThreshold   int // 超过多少条消息启用消息级压缩

	// 对话轮次级压缩配置
	EnableTurnLevel bool
	TurnThreshold   int // 超过多少轮对话启用轮次级压缩

	// 会话级压缩配置
	EnableSessionLevel bool
	SessionThreshold   int // 超过多少条消息启用会话级压缩

	// Token 预算
	TokenBudget agentext.TokenBudget
}

type ObservationCompressor interface {
	// Compress 压缩观察结果
	Compress(ctx context.Context, toolName string, output string) (*CompressedObservation, error)

	// CanRecover 检查是否可以恢复原始内容
	CanRecover(compressed *CompressedObservation) bool

	// Recover 恢复原始内容（如果可能）
	Recover(ctx context.Context, compressed *CompressedObservation) (string, error)
}

type ObservationCompressorConfig struct {
	MaxSummaryLength  int
	MinCompressLength int
}

type PersistentPreferenceManager struct {
	*PreferenceManager
	// contains filtered or unexported fields
}

type Preference struct {
	ID          string             // 偏好 ID
	UserID      string             // 用户 ID
	Category    PreferenceCategory // 类别
	Key         string             // 偏好键（如 "theme", "language"）
	Value       string             // 偏好值（如 "dark", "zh"）
	Strength    float64            // 强度 (0.0-1.0)，基于出现频率
	Confidence  float64            // 置信度 (0.0-1.0)
	CreatedAt   time.Time          // 创建时间
	UpdatedAt   time.Time          // 更新时间
	AccessCount int                // 访问次数
	Metadata    map[string]string  // 元数据
}

type PreferenceCategory string

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

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

type PreferenceManagerConfig struct {
	// 强度衰减（每天）
	StrengthDecay float64

	// 最小强度阈值（低于此值被删除）
	MinStrength float64

	// 最大偏好数量（每个用户）
	MaxPreferencesPerUser int

	// 冲突解决策略
	ConflictStrategy ConflictStrategy

	// 是否自动提取偏好
	AutoExtract bool
}

type PreferenceStats struct {
	TotalPreferences     int                        // 总偏好数
	CategoryDistribution map[PreferenceCategory]int // 类别分布
	AverageStrength      float64                    // 平均强度
	HighStrengthCount    int                        // 高强度数量 (>= 0.7)
	MediumStrengthCount  int                        // 中等强度数量 (>= 0.4)
	LowStrengthCount     int                        // 低强度数量 (< 0.4)
}

type PreferenceStorage interface {
	// Save 保存偏好
	Save(ctx context.Context, userID string, preferences []*Preference) error

	// Load 加载偏好
	Load(ctx context.Context, userID string) ([]*Preference, error)

	// Delete 删除用户的所有偏好
	Delete(ctx context.Context, userID string) error

	// List 列出所有用户 ID
	List(ctx context.Context) ([]string, error)
}

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

type QualityDimension string

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

type QualityMetricsConfig struct {
	// 权重配置（各维度的权重，总和应为 1.0）
	AccuracyWeight     float64
	CompletenessWeight float64
	ConsistencyWeight  float64
	TimelinessWeight   float64
	RelevanceWeight    float64

	// 时效性配置
	MaxAge          time.Duration // 最大有效期
	TimelinessDecay float64       // 时效性衰减系数（每天）

	// 质量阈值
	MinQualityThreshold float64 // 最低质量阈值
	WarningThreshold    float64 // 警告阈值

	// 自动清理
	EnableAutoCleanup   bool // 启用自动清理低质量记忆
	AutoCleanupInterval time.Duration
}

type QualityReport struct {
	GeneratedAt time.Time
	Stats       QualityStats

	// 维度分布
	DimensionScores map[QualityDimension]float64

	// 问题统计
	Inconsistencies    []Inconsistency
	InconsistencyCount map[InconsistencyType]int
	TopIssues          []string

	// 建议
	Recommendations []string
}

type QualityScore struct {
	Accuracy     float64 // 准确性 (0.0-1.0)
	Completeness float64 // 完整性 (0.0-1.0)
	Consistency  float64 // 一致性 (0.0-1.0)
	Timeliness   float64 // 时效性 (0.0-1.0)
	Relevance    float64 // 相关性 (0.0-1.0)

	Overall float64 // 综合得分 (0.0-1.0)

	// 元数据
	CalculatedAt time.Time
	Source       string // 评分来源（如 "automatic", "manual", "llm"）
}

type QualityStats struct {
	TotalMemories      int     // 总记忆数
	TotalEvaluations   int64   // 总评估次数
	AverageQuality     float64 // 平均质量
	HighQualityCount   int     // 高质量记忆数 (>= 0.8)
	MediumQualityCount int     // 中等质量记忆数 (>= 0.5)
	LowQualityCount    int     // 低质量记忆数 (< 0.5)
	MemoriesWithIssues int     // 有问题的记忆数
}

type QualityTrend struct {
	Dimension QualityDimension
	Trend     string  // "improving", "declining", "stable"
	Change    float64 // 变化量
	Period    time.Duration
}

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

type Reference struct {
	// Type 引用类型: "file_path", "url", "function", "class", "line_range"
	Type string `json:"type"`

	// Value 引用值
	Value string `json:"value"`

	// Context 上下文信息（可选）
	Context string `json:"context,omitempty"`

	// LineStart 起始行号（可选，用于文件引用）
	LineStart int `json:"line_start,omitempty"`

	// LineEnd 结束行号（可选，用于文件引用）
	LineEnd int `json:"line_end,omitempty"`
}

type ReferenceInfo struct {
	// Reference 基本引用信息
	Reference Reference `json:"reference"`

	// SourceContext 引用来源的上下文
	SourceContext string `json:"source_context,omitempty"`

	// FirstSeen 首次出现时间
	FirstSeen time.Time `json:"first_seen"`

	// LastAccessed 最后访问时间
	LastAccessed time.Time `json:"last_accessed"`

	// AccessCount 访问次数
	AccessCount int `json:"access_count"`

	// ToolName 产生此引用的工具
	ToolName string `json:"tool_name,omitempty"`

	// Metadata 额外元数据
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ReferenceRegistry interface {
	// Register 注册一个引用
	Register(ctx context.Context, ref Reference, sourceContext string) error

	// Lookup 查找引用信息
	Lookup(ctx context.Context, refType, value string) (*ReferenceInfo, error)

	// ListByType 按类型列出引用
	ListByType(ctx context.Context, refType string, limit int) ([]ReferenceInfo, error)

	// ListRecent 列出最近的引用
	ListRecent(ctx context.Context, limit int) ([]ReferenceInfo, error)

	// MarkAccessed 标记引用被访问
	MarkAccessed(ctx context.Context, refType, value string) error

	// GetStats 获取统计信息
	GetStats(ctx context.Context) (*RegistryStats, error)

	// Cleanup 清理过期引用
	Cleanup(ctx context.Context, maxAge time.Duration) (int, error)
}

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

type RegistryStats struct {
	// TotalReferences 总引用数
	TotalReferences int `json:"total_references"`

	// ByType 按类型统计
	ByType map[string]int `json:"by_type"`

	// MostAccessed 最常访问的引用
	MostAccessed []ReferenceInfo `json:"most_accessed,omitempty"`

	// RecentlyAdded 最近添加的引用数
	RecentlyAdded int `json:"recently_added"`
}

type Scope struct {
	// UserID 当前用户ID,用于业务侧记录/审计; 是否叠加到路径中由 Shared 控制。
	UserID string

	// ProjectID 项目标识,为空表示不绑定项目。
	ProjectID string

	// ResourceType 资源类型: "article" | "novel" | "song" | "ppt" | ...
	ResourceType string

	// ResourceID 资源ID,与 ResourceType 配合使用。
	ResourceID string

	// Shared 是否作为全局/共享记忆:
	// - Shared=false: 生成的 namespace 不以 "/" 开头, 会叠加 BaseNamespace(通常是 users/<user-id>)。
	// - Shared=true : 生成的 namespace 以 "/" 开头, 不叠加 BaseNamespace, 落在全局共享空间。
	Shared bool
}

type SearchMatch struct {
	Path       string `json:"path"`
	LineNumber int    `json:"line_number"`
	Line       string `json:"line"`
	Match      string `json:"match"`
}

type SearchOptions struct {
	// Query 搜索关键字,默认作为大小写不敏感的字面量匹配
	Query string
	// Regex 是否将 Query 视为正则表达式
	Regex bool
	// Namespace 可选的命名空间前缀,用于多租户/多资源隔离
	// 例如: "users/alice", "projects/demo", "users/alice/projects/demo"
	// 为空字符串时在整个 MemoryPath 下搜索
	Namespace string
	// Glob 文件过滤模式,例如: "*.md"
	Glob string
	// MaxResults 返回的最大匹配数,<=0 时表示不限制
	MaxResults int
}

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

type SemanticMemoryConfig struct {
	Store          vector.VectorStore
	Embedder       vector.Embedder
	NamespaceScope string // "user" | "project" | "resource" | "global"
	TopK           int

	// EnableProvenance 是否启用记忆溯源追踪。
	EnableProvenance bool

	// ConfidenceCalculator 置信度计算器。
	// 如果为 nil, 使用默认配置。
	ConfidenceCalculator *ConfidenceCalculator

	// LineageManager 谱系管理器。
	// 如果为 nil, 不追踪记忆谱系。
	LineageManager *LineageManager

	// DefaultSourceType 默认的数据源类型。
	DefaultSourceType SourceType
}

type SessionCompressor interface {
	// SummarizeSession 总结整个会话
	SummarizeSession(ctx context.Context, messages []agentext.Message) (string, error)

	// CompressMessages 压缩消息列表
	CompressMessages(ctx context.Context, messages []agentext.Message) ([]agentext.Message, error)

	// GetCompressionStats 获取压缩统计信息
	GetCompressionStats() CompressionStats
}

type SessionManagerConfig struct {
	// 默认作用域
	DefaultScope MemoryScope

	// 是否允许跨会话共享
	EnableSharing bool

	// 是否允许全局记忆
	EnableGlobal bool

	// 记忆过期时间
	MemoryTTL time.Duration

	// 最大共享数量（单个记忆最多共享给多少会话）
	MaxSharedSessions int
}

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

type SessionStats struct {
	TotalMemories     int                 // 总记忆数
	TotalSessions     int                 // 总会话数
	GlobalMemories    int                 // 全局记忆数
	ScopeDistribution map[MemoryScope]int // 作用域分布
}

type SessionSummary struct {
	// 基本信息
	SessionID string    `json:"session_id"`
	Summary   string    `json:"summary"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`

	// 详细信息
	Topics      []string       `json:"topics"`       // 讨论的主题
	KeyPoints   []string       `json:"key_points"`   // 关键要点
	Decisions   []string       `json:"decisions"`    // 做出的决策
	ActionItems []string       `json:"action_items"` // 行动项
	Metadata    map[string]any `json:"metadata"`

	// 统计信息
	MessageCount int `json:"message_count"` // 消息数量
	TokenCount   int `json:"token_count"`   // Token 数量
}

type SessionSummaryConfig struct {
	// Enabled 是否启用会话摘要
	Enabled bool

	// AutoUpdate 是否自动更新摘要
	AutoUpdate bool

	// UpdateInterval 自动更新间隔（消息数量）
	UpdateInterval int

	// MaxSummaryLength 摘要最大长度（字符数）
	MaxSummaryLength int

	// IncludeTopics 是否提取主题
	IncludeTopics bool

	// IncludeKeyPoints 是否提取关键要点
	IncludeKeyPoints bool

	// IncludeDecisions 是否提取决策
	IncludeDecisions bool

	// IncludeActionItems 是否提取行动项
	IncludeActionItems bool

	// SummaryPrompt 自定义摘要提示词
	SummaryPrompt string
}

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

type SharedMemory struct {
	ID         string                 // 记忆 ID
	Content    string                 // 内容
	Metadata   map[string]any         // 元数据
	Scope      MemoryScope            // 作用域
	OwnerID    string                 // 所有者会话 ID
	SharedWith map[string]AccessLevel // 共享给哪些会话（会话ID -> 访问级别）
	CreatedAt  time.Time              // 创建时间
	UpdatedAt  time.Time              // 更新时间

	// 记忆溯源
	Provenance *MemoryProvenance
}

type SourceType string

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

type WorkingMemoryConfig struct {
	Backend    backends.BackendProtocol // 存储后端
	BasePath   string                   // 存储根路径，默认 "/working_memory/"
	Scope      WorkingMemoryScope       // 作用域：thread 或 resource
	Schema     *JSONSchema              // 可选的 JSON Schema 验证
	Template   string                   // 可选的 Markdown 模板
	DefaultTTL time.Duration            // 可选的过期时间（0 表示不过期）
}

type WorkingMemoryData struct {
	Meta    WorkingMemoryMeta `json:"meta"`
	Content string            `json:"content"`
}

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

type WorkingMemoryMeta struct {
	ThreadID   string     `json:"thread_id"`
	ResourceID string     `json:"resource_id"`
	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
}

type WorkingMemoryScope string