memory

type BudgetConfig struct {
	// MaxTokens is the total token budget.
	MaxTokens int
	// EntityProfileBudget is the budget reserved for entity profile (phase 1).
	EntityProfileBudget int
	// GraphBudget is the budget reserved for graph neighborhood (phase 2).
	GraphBudget int
}

type ContextForOpts struct {
	AgentID    string
	EntityName string
	Topic      string // FTS query for relevant memories
	MaxTokens  int    // total budget
}

type Edge struct {
	ID             string
	AgentID        string
	SourceID       string
	TargetID       string
	Relation       string // USES, FOLLOWS, KNOWS_ABOUT, PARENT_OF, WORKS_AT, etc.
	PropertiesJSON string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

type Embedder interface {
	// Embed returns a vector embedding for the given text.
	Embed(ctx context.Context, text string) ([]float32, error)

	// EmbedBatch returns embeddings for multiple texts. Implementations
	// should batch API calls where possible for efficiency.
	EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)

	// Dimensions returns the dimensionality of embeddings produced.
	Dimensions() int

	// Model returns the model identifier. Stored with each embedding so that
	// model changes don't corrupt recall (incompatible vector spaces).
	Model() string
}

type Entity struct {
	ID             string
	AgentID        string
	Name           string
	EntityType     string // person, tool, pattern, concept, project, device, etc.
	PropertiesJSON string
	Owner          string
	CreatedAt      time.Time
	UpdatedAt      time.Time
}

type EntityIDRole struct {
	ID   string
	Role string // RoleAbout, RoleMentions, etc.
}

type EntityRecall struct {
	Entity          *Entity
	Memories        []ScoredMemory
	EdgesOut        []*Edge
	EdgesIn         []*Edge
	EntityNames     map[string]string // ID -> name lookup for edge endpoints
	TotalTokensUsed int
	TotalCandidates int
}

type GraphMemoryStore interface {
	// Entity CRUD (mutable)
	CreateEntity(ctx context.Context, entity *Entity) (*Entity, error)
	GetEntity(ctx context.Context, agentID, name string) (*Entity, error)
	UpdateEntity(ctx context.Context, entity *Entity) (*Entity, error)
	ListEntities(ctx context.Context, agentID, entityType string, limit, offset int) ([]*Entity, int, error)
	SearchEntities(ctx context.Context, agentID, query string, limit int) ([]*Entity, error)
	DeleteEntity(ctx context.Context, agentID, name string) error

	// Edge CRUD (mutable, UNIQUE on source+target+relation)
	Relate(ctx context.Context, edge *Edge) (*Edge, error) // upsert
	Unrelate(ctx context.Context, sourceID, targetID, relation string) error
	Neighbors(ctx context.Context, entityID string, relation string, direction string, depth int) ([]*Edge, error)
	ListEdgesFrom(ctx context.Context, entityID string) ([]*Edge, error)
	ListEdgesTo(ctx context.Context, entityID string) ([]*Edge, error)

	// Memory (append-only, immutable content)
	Remember(ctx context.Context, mem *Memory) (*Memory, error)
	GetMemory(ctx context.Context, agentID, memoryID string) (*Memory, error)
	Recall(ctx context.Context, opts RecallOpts) ([]*Memory, error)
	Forget(ctx context.Context, memoryID string) error                                  // soft-delete: set expires_at
	Supersede(ctx context.Context, oldMemoryID string, newMem *Memory) (*Memory, error) // creates SUPERSEDES lineage
	Consolidate(ctx context.Context, memoryIDs []string, consolidated *Memory) (*Memory, error)
	GetLineage(ctx context.Context, memoryID string) ([]*MemoryLineage, error)

	// Access tracking (the only allowed mutation on memories)
	TouchMemories(ctx context.Context, memoryIDs []string) error

	// Salience management
	DecayAll(ctx context.Context, agentID string, decayFactor float64) error

	// Composite query
	ContextFor(ctx context.Context, opts ContextForOpts) (*EntityRecall, error)

	// Vector similarity search (returns memories ordered by cosine similarity).
	// Implementations: SQLite uses brute-force in Go; PostgreSQL uses pgvector HNSW.
	// Returns nil, nil if embeddings are not enabled for this store.
	VectorRecall(ctx context.Context, opts VectorRecallOpts) ([]*Memory, error)

	// Stats
	GetStats(ctx context.Context, agentID string) (*GraphStats, error)

	Close() error
}

type GraphStats struct {
	EntityCount       int
	EdgeCount         int
	MemoryCount       int
	ActiveMemoryCount int
	TotalMemoryTokens int
	MemoriesByType    map[string]int
}

type Memory struct {
	ID                string
	AgentID           string
	Content           string
	Summary           string
	MemoryType        string // fact, preference, decision, experience, failure, observation, consolidation
	Source            string // conversation, observation, manual, agent
	SourceID          string
	Owner             string
	MemoryAgentID     string
	Tags              []string
	Salience          float64
	TokenCount        int
	SummaryTokenCount int
	AccessCount       int
	EntityIDs         []string
	EntityRoles       []EntityIDRole // takes precedence over EntityIDs when present
	PropertiesJSON    string
	Embedding         []float32 // vector embedding for semantic search (nil = not embedded)
	EmbeddingModel    string    // model that produced the embedding (for compatibility checks)
	// EventDate is the absolute ISO date (YYYY-MM-DD) when the fact this
	// memory describes occurred, computed by the extractor from the session
	// date and the user's relative time phrase. Empty when the memory has no
	// temporal dimension, or when the extractor could not resolve an absolute
	// date (see EventDateConfidence).
	EventDate string
	// EventDateConfidence is "exact", "approximate", "ambiguous", or empty.
	// "ambiguous" signals the extractor saw a time cue but deliberately chose
	// not to fabricate a date; consumers should treat the memory as undated.
	EventDateConfidence string
	CreatedAt           time.Time
	AccessedAt          *time.Time // nil = never accessed
	ExpiresAt           *time.Time // nil = never expires
	IsSuperseded        bool
}

type MemoryLineage struct {
	NewMemoryID  string
	OldMemoryID  string
	RelationType string // SUPERSEDES or CONSOLIDATES
	CreatedAt    time.Time
}

type RecallOpts struct {
	AgentID     string
	Query       string   // FTS search query
	MemoryType  string   // filter (empty = all)
	EntityIDs   []string // scope to entities (empty = all)
	Tags        []string // filter by tags
	MinSalience float64
	MaxTokens   int // 0 = no limit
	Limit       int // max results
}

type SalienceConfig struct {
	DecayRate          float64
	BoostAmount        float64
	MinSalience        float64
	ConsolidationDecay float64
}

type ScoredMemory struct {
	Memory           *Memory
	ComputedSalience float64
	RelevanceScore   float64
	CombinedScore    float64
	UsedSummary      bool // true if summary used instead of full content
}

type TokenCounter interface {
	CountTokens(text string) int
}

type VectorRecallOpts struct {
	AgentID   string
	Embedding []float32 // query vector
	Model     string    // only match embeddings from this model (required)
	Limit     int       // max results (default: 20)
	Threshold float32   // minimum cosine similarity (default: 0.0)
}