memory

type ChangeEntry struct {
	ID                  int64
	UserID              int64
	AgentID             string
	SessionID           string
	Scope               string // "profile", "soul", "constraint", "skill", "compaction"
	Action              string // "create", "update", "delete", "compact"
	Source              ChangeSource
	MemoryVersionBefore *int64
	MemoryVersionAfter  *int64
	BeforeText          string
	AfterText           string
	CreatedAt           string
}

type ChangeSource string

type ChangelogReader interface {
	// ReadChangelog returns the last N changelog entries for a given scope.
	ReadChangelog(ctx context.Context, userID int64, agentID string, scope string, limit int) ([]ChangeEntry, error)
}

type ChangelogWriter interface {
	// WriteChangelog records a memory change.
	WriteChangelog(ctx context.Context, entry ChangeEntry) error
}

type CompactionMode int

type CompactionResult struct {
	LeafSummariesCreated      int
	CondensedSummariesCreated int
	MessagesCompacted         int
	TokensBefore              int
	TokensAfter               int
	Duration                  time.Duration
}

type Compactor interface {
	// NeedsCompaction returns true if the session's context has grown large enough
	// to warrant compaction. threshold is a fraction of the session's token budget
	// (e.g. 0.75 means "compact when context is 75% full").
	NeedsCompaction(ctx context.Context, session Session, threshold float64) bool

	// Compact runs the compaction algorithm on the session.
	// Incremental mode runs a single summarisation pass (fast, called automatically).
	// Full mode runs repeated passes until no further reduction is possible
	// (slow, called on demand e.g. via /compact slash command).
	Compact(ctx context.Context, session Session, mode CompactionMode) (*CompactionResult, error)
}

type ConstraintEntry struct {
	ID        string `json:"id"`
	Text      string `json:"text"`
	CreatedAt string `json:"created_at"`
}

type ConstraintStore interface {
	// GetConstraints returns all active constraints for the (userID, agentID) pair.
	GetConstraints(ctx context.Context, userID int64, agentID string) ([]ConstraintEntry, error)

	// AddConstraint adds a new constraint with a generated UUID-like ID.
	// Returns the updated list of constraints.
	AddConstraint(ctx context.Context, userID int64, agentID string, text string) ([]ConstraintEntry, error)

	// RemoveConstraint removes the constraint with the given ID.
	// Returns the updated list of constraints.
	RemoveConstraint(ctx context.Context, userID int64, agentID string, id string) ([]ConstraintEntry, error)
}

type DescribeResult struct {
	SummaryID       string
	Kind            string     // "leaf" or "condensed"
	Depth           int        // 0 = leaf, 1+ = condensed
	Content         string     // the summary text
	EarliestAt      *time.Time // timestamp of oldest source message
	LatestAt        *time.Time // timestamp of newest source message
	DescendantCount int        // total original messages this summary covers
	ParentIDs       []string   // summaries that contain this one (condensed parents)
	ChildIDs        []string   // summaries or messages this one was built from
}

type ExpandChild struct {
	SummaryID string
	Kind      string
	Depth     int
	Content   string
}

type ExpandMessage struct {
	MessageID int64
	Role      string
	Content   string
	CreatedAt time.Time
}

type ExpandResult struct {
	SummaryID string
	// For leaf summaries: the original source messages.
	Messages []ExpandMessage
	// For condensed summaries: the child summaries.
	Children []ExpandChild
}

type Explorer interface {
	// Describe returns metadata and lineage for a summary ID.
	Describe(ctx context.Context, summaryID string) (*DescribeResult, error)

	// Expand drills into a summary:
	//   - For leaf summaries: returns the original source messages
	//   - For condensed summaries: returns the child summaries
	// tokenCap limits how many tokens of content are returned.
	Expand(ctx context.Context, summaryID string, tokenCap int) (*ExpandResult, error)
}

type LLMSummarizer struct {
	// Generate calls the LLM with the given prompt and returns the response text.
	Generate func(ctx context.Context, prompt string) (string, error)
}

type ListOptions struct {
	AgentID         string // filter by agent (empty = all)
	UserID          int64  // filter by user (0 = all)
	IncludeArchived bool
	Limit           int // 0 = no limit
	Offset          int // skip first N matching results
}

type ProfileStore interface {
	// GetProfile returns the current user profile for the (userID, agentID) pair.
	// Returns ("", nil) if no profile exists yet (not an error).
	GetProfile(ctx context.Context, userID int64, agentID string) (string, error)

	// SetProfile overwrites the user profile for the (userID, agentID) pair.
	// Callers are responsible for merging new content with existing content
	// before calling SetProfile — this method always replaces, never appends.
	SetProfile(ctx context.Context, userID int64, agentID string, content string) error

	// GetAgentSoul returns the agent soul for the (userID, agentID) pair.
	// The soul defines the agent's identity, personality, and behavior as
	// customised by this specific user. Returns ("", nil) if not set.
	GetAgentSoul(ctx context.Context, userID int64, agentID string) (string, error)

	// SetAgentSoul overwrites the agent soul for the (userID, agentID) pair.
	// Callers are responsible for merging; this method always replaces.
	SetAgentSoul(ctx context.Context, userID int64, agentID string, content string) error
}

type Provider interface {
	// Name returns the plugin identifier (e.g. "lcm", "simple").
	// Used in logs and admin UI.
	Name() string

	// Bootstrap ensures the session is initialized and ready for use.
	// Called once at the start of every Pool.Chat call before any Append or Assemble.
	// Implementations use this to create conversation records, initialize caches,
	// or establish remote connections for the session.
	Bootstrap(ctx context.Context, session Session) error

	// Append persists one or more messages to the session's event log.
	// Messages must be appended in the order they arrive.
	// Callers pass all messages from a single turn together so implementations
	// can store them in a single atomic transaction if they choose.
	//
	// Concurrency: implementations MUST be safe for concurrent Append calls
	// on different sessions. Concurrent Append calls on the SAME session
	// MUST be serialised by the implementation (see Concurrency Contract).
	Append(ctx context.Context, session Session, msgs ...ai.Message) error

	// Assemble builds the context window to send to the LLM.
	// budget: maximum number of tokens the returned messages may consume.
	// freshTail: minimum number of recent messages to always include verbatim,
	//   regardless of budget pressure. Implementations MUST honour this.
	// Returns messages in chronological order (oldest first).
	// Older content that does not fit in the budget is either summarised
	// (if the plugin supports Compactor) or omitted.
	Assemble(ctx context.Context, session Session, budget, freshTail int) ([]ai.Message, error)

	// Stats returns basic statistics about a session's memory state.
	// Used by the memory tool's "status" action and by admin endpoints.
	// Returns zero-value stats (not an error) if the session does not exist.
	Stats(ctx context.Context, session Session) (SessionStats, error)

	// Close releases any resources held by the provider (DB connections, caches, etc.).
	// Called when the Pool shuts down. Must be safe to call multiple times.
	Close() error
}

type Reviewer interface {
	// BuildReviewContext returns a text representation of the conversation
	// suitable for passing to a reviewer agent's prompt.
	//
	// since: if non-zero, only include content created after this time.
	//   The provider should include prior context (e.g. summaries from before
	//   this timestamp) to give the reviewer enough background.
	//   If zero, include all content.
	//
	// Returns ("", nil) if there is no content to review.
	BuildReviewContext(ctx context.Context, session Session, since time.Time) (string, error)
}

type SearchQuery struct {
	Text  string      // search term (keyword or natural language depending on plugin)
	Scope SearchScope // which layer of storage to search
	Limit int         // max results (default 20)
}

type SearchResult struct {
	SourceType string    // "message" or "summary"
	SourceID   string    // message ID or summary ID
	Content    string    // snippet of the matching content (truncated at ~500 chars)
	Score      float64   // relevance score: 0 for keyword match, 0.0-1.0 for semantic
	Timestamp  time.Time // when the source was created
}

type SearchScope int

type Searcher interface {
	Search(ctx context.Context, session Session, query SearchQuery) ([]SearchResult, error)
}

type Session struct {
	ID      string // unique session key (e.g. "default:cli:42:main")
	AgentID string // agent this session belongs to (e.g. "default")
	UserID  int64  // internal user ID (0 for anonymous/legacy)
	Channel string // originating channel (e.g. "cli", "telegram")
}

type SessionInfo struct {
	ID         string
	AgentID    string
	UserID     int64
	Channel    string
	Title      string // auto-generated from first message
	CreatedAt  time.Time
	LastActive time.Time
	Archived   bool
}

type SessionManager interface {
	// SaveInfo persists or updates session metadata.
	SaveInfo(ctx context.Context, info SessionInfo) error

	// LoadInfo retrieves metadata for a single session.
	LoadInfo(ctx context.Context, sessionID string) (SessionInfo, error)

	// ListInfo lists sessions matching the options.
	ListInfo(ctx context.Context, opts ListOptions) ([]SessionInfo, error)

	// LoadHistory returns the complete raw message history for a session
	// in chronological order. Used by the admin panel viewer and export.
	LoadHistory(ctx context.Context, sessionID string) ([]ai.Message, error)
}

type SessionSnapshot struct {
	SessionID string
	UserID    int64
	AgentID   string
	Version   int64
	// UpdatedAt is the wall-clock time when this snapshot was last advanced.
	// Used to filter knowledge entries so that knowledge activated after the
	// snapshot was taken does not appear in the frozen session.
	UpdatedAt time.Time
}

type SessionSnapshotStore interface {
	// GetOrCreateSessionSnapshot returns the snapshot for the session, creating it
	// if it doesn't exist. When creating, freezes the current ctx_agent_memory.version.
	GetOrCreateSessionSnapshot(ctx context.Context, sessionID string, userID int64, agentID string) (SessionSnapshot, error)

	// AdvanceSessionSnapshot updates the snapshot version to the current
	// ctx_agent_memory.version for (userID, agentID).
	// Called after front-end memory writes so the current session sees the update.
	AdvanceSessionSnapshot(ctx context.Context, sessionID string, userID int64, agentID string) error
}

type SessionStats struct {
	MessageCount int       // total messages stored for this session
	TokenCount   int       // estimated total tokens across all stored messages
	SummaryCount int       // number of summaries (0 for providers without Compactor)
	OldestAt     time.Time // timestamp of the earliest message (zero if empty)
	NewestAt     time.Time // timestamp of the most recent message (zero if empty)
}

type StaticSummarizer struct {
	Response string
	Err      error
}

type SummarizeOptions struct {
	IsCondensed  bool
	Depth        int
	Aggressive   bool
	Previous     string // previous summary for continuity
	TargetTokens int
}

type Summarizer interface {
	Summarize(ctx context.Context, text string, opts SummarizeOptions) (string, error)
}

type ToolOption func(*toolConfig)

type VersionedConstraintStore interface {
	GetConstraintsAt(ctx context.Context, userID int64, agentID string, version int64) ([]ConstraintEntry, error)
}

type VersionedProfileStore interface {
	GetProfileAt(ctx context.Context, userID int64, agentID string, version int64) (string, error)
	GetAgentSoulAt(ctx context.Context, userID int64, agentID string, version int64) (string, error)
}