memory

type Filter struct {
	CreatedBy string
	Persona   string
	Dimension string
	Category  string
	Status    string
	Source    string
	EntityURN string
	Since     *time.Time
	Until     *time.Time
	Limit     int
	Offset    int
	// OrderBy overrides the default ordering ("created_at DESC").
	// Must be a valid SQL ORDER BY clause (e.g. "last_verified ASC NULLS FIRST").
	OrderBy string
}

type HybridQuery struct {
	Embedding []float32
	QueryText string
	Limit     int
	Persona   string
	Status    string
}

type LexicalQuery struct {
	QueryText string
	Limit     int
	Persona   string
	Status    string
}

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

type Record struct {
	ID             string          `json:"id" example:"mem_a1b2c3d4e5f6"`
	CreatedAt      time.Time       `json:"created_at" example:"2026-03-18T08:11:08Z"`
	UpdatedAt      time.Time       `json:"updated_at" example:"2026-03-18T08:11:08Z"`
	CreatedBy      string          `json:"created_by" example:"sarah.chen@example.com"`
	Persona        string          `json:"persona" example:"admin"`
	Dimension      string          `json:"dimension" example:"knowledge"`
	Content        string          `json:"content" example:"The daily_sales table in the retail schema is partitioned by date."`
	Category       string          `json:"category" example:"business_context"`
	Confidence     string          `json:"confidence" example:"high"`
	Source         string          `json:"source" example:"user"`
	EntityURNs     []string        `json:"entity_urns"`
	RelatedColumns []RelatedColumn `json:"related_columns"`
	Embedding      []float32       `json:"embedding,omitempty"`
	// EmbeddingModel records the provider model that produced Embedding
	// (e.g. "nomic-embed-text"); EmbeddingTextHash is the SHA-256 of the
	// content fed to the embedder. They are the breadcrumbs the indexjobs
	// memory consumer uses to dedup re-embeds and detect model-swap gaps.
	// The synchronous write path stamps both when the embedder is healthy;
	// they are empty/nil on rows embedded before the column existed or
	// saved during an embedder outage (the reconciler later backfills).
	EmbeddingModel    string         `json:"embedding_model,omitempty"`
	EmbeddingTextHash []byte         `json:"embedding_text_hash,omitempty"`
	Metadata          map[string]any `json:"metadata"`
	Status            string         `json:"status" example:"active"`
	StaleReason       string         `json:"stale_reason,omitempty"`
	StaleAt           *time.Time     `json:"stale_at,omitempty"`
	LastVerified      *time.Time     `json:"last_verified,omitempty"`
}

type RecordUpdate struct {
	Content    string
	Category   string
	Confidence string
	Dimension  string
	Metadata   map[string]any
	Embedding  []float32
	// EmbeddingModel and EmbeddingTextHash travel with Embedding: when an
	// update re-embeds changed content, the write path stamps the model
	// and content hash alongside the new vector so the row's breadcrumbs
	// stay consistent with the embedding the indexjobs consumer dedups on.
	EmbeddingModel    string
	EmbeddingTextHash []byte
}

type RelatedColumn struct {
	URN       string `json:"urn" example:"urn:li:dataset:(urn:li:dataPlatform:trino,hive.sales.orders,PROD)"`
	Column    string `json:"column" example:"amount"`
	Relevance string `json:"relevance" example:"direct"`
}

type ScoredRecord struct {
	Record Record
	Score  float64
}

type Snippet struct {
	ID         string    `json:"id"`
	Content    string    `json:"content"`
	Dimension  string    `json:"dimension"`
	Category   string    `json:"category"`
	Confidence string    `json:"confidence"`
	CreatedAt  time.Time `json:"created_at"`
}

type StalenessConfig struct {
	Interval  time.Duration
	BatchSize int
}

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

type Store interface {
	// Insert creates a new memory record.
	Insert(ctx context.Context, record Record) error

	// Get retrieves a single memory record by ID.
	Get(ctx context.Context, id string) (*Record, error)

	// Update modifies fields on an existing memory record.
	Update(ctx context.Context, id string, updates RecordUpdate) error

	// Delete soft-deletes a memory record by setting status to archived.
	Delete(ctx context.Context, id string) error

	// List returns memory records matching the filter with pagination.
	List(ctx context.Context, filter Filter) ([]Record, int, error)

	// VectorSearch performs cosine similarity search over embeddings.
	VectorSearch(ctx context.Context, query VectorQuery) ([]ScoredRecord, error)

	// HybridSearch fuses cosine similarity with a lexical full-text
	// signal for higher-quality recall on identifier-heavy content.
	HybridSearch(ctx context.Context, query HybridQuery) ([]ScoredRecord, error)

	// LexicalSearch ranks by Postgres full-text relevance only, the
	// graceful-degradation path when no embedding provider is available.
	LexicalSearch(ctx context.Context, query LexicalQuery) ([]ScoredRecord, error)

	// EntityLookup returns active memories linked to a DataHub URN.
	EntityLookup(ctx context.Context, urn string, persona string) ([]Record, error)

	// MarkStale flags memory records as stale with a reason.
	MarkStale(ctx context.Context, ids []string, reason string) error

	// MarkVerified updates the last_verified timestamp for records.
	MarkVerified(ctx context.Context, ids []string) error

	// Supersede marks an old record as superseded by a new one.
	Supersede(ctx context.Context, oldID, newID string) error
}

type VectorQuery struct {
	Embedding []float32
	Limit     int
	MinScore  float64
	Persona   string
	Status    string
}