store

type DocumentTracker interface {
	// IsDocumentProcessed checks if a document with the given hash has been processed.
	// hash: SHA-256 hash of the document text (content-based identity)
	// Returns true if the document has been processed, false otherwise.
	IsDocumentProcessed(ctx context.Context, hash string) (bool, error)

	// MarkDocumentProcessed records that a document has been successfully processed.
	// hash: SHA-256 hash of document text (content-based identity)
	// source: Optional source identifier (metadata only, does not affect identity)
	// chunkCount: Number of chunks generated from this document
	// Uses INSERT OR REPLACE to support upsert semantics.
	MarkDocumentProcessed(ctx context.Context, hash, source string, chunkCount int) error

	// GetProcessedDocumentCount returns the total number of processed documents tracked.
	GetProcessedDocumentCount(ctx context.Context) (int64, error)

	// ClearProcessedDocuments removes all document tracking records.
	// This does NOT delete nodes or edges - only clears the processed_documents table.
	// Useful for forcing a full reprocess without losing the knowledge graph.
	ClearProcessedDocuments(ctx context.Context) error
}

type Edge struct {
	ID        string    // Unique identifier (UUID)
	SourceID  string    // Source node ID
	Relation  string    // Relationship type (USES, DEPENDS_ON, etc.)
	TargetID  string    // Target node ID
	Weight    float64   // Relationship weight (default 1.0, reserved for future ranking)
	CreatedAt time.Time // Timestamp of creation
}

type GraphStore interface {
	// AddNode adds or updates a node in the graph.
	// Uses upsert semantics (INSERT OR REPLACE by ID).
	AddNode(ctx context.Context, node *Node) error

	// GetNode retrieves a node by its ID.
	// Returns (nil, nil) if the node is not found (no error).
	GetNode(ctx context.Context, id string) (*Node, error)

	// FindNodesByName searches for nodes by name using case-insensitive matching.
	// Returns all matching nodes ordered deterministically (by created_at, then id).
	// Callers must handle ambiguity when multiple matches are returned.
	FindNodesByName(ctx context.Context, name string) ([]*Node, error)

	// FindNodeByName is a convenience method that returns a single node if and only if
	// exactly one node matches the name (case-insensitive).
	// Returns an error if zero matches (not found) or multiple matches (ambiguous).
	FindNodeByName(ctx context.Context, name string) (*Node, error)

	// AddEdge adds or updates an edge in the graph.
	// Uses upsert semantics (INSERT OR REPLACE by ID).
	// If Edge.ID is empty, a new UUID will be generated.
	AddEdge(ctx context.Context, edge *Edge) error

	// GetEdges retrieves all edges incident to a node (both incoming and outgoing).
	// This is direction-agnostic: returns edges where the node is either source or target.
	// Returns an empty slice if no edges are found.
	// Cognee-aligned: treats adjacency as undirected for discovery.
	GetEdges(ctx context.Context, nodeID string) ([]*Edge, error)

	// GetNeighbors retrieves all nodes adjacent to a given node, up to the specified depth.
	// Depth=1 returns direct neighbors only (Cognee-aligned default).
	// Depth>1 recursively traverses the graph (gognee extension).
	// Traversal is direction-agnostic (treats edges as undirected).
	// Returns unique nodes only (no duplicates).
	GetNeighbors(ctx context.Context, nodeID string, depth int) ([]*Node, error)

	// NodeCount returns the total number of nodes in the graph.
	NodeCount(ctx context.Context) (int64, error)

	// EdgeCount returns the total number of edges in the graph.
	EdgeCount(ctx context.Context) (int64, error)

	// Close releases any resources held by the store (e.g., database connections).
	Close() error
}

type ListMemoriesOptions struct {
	Offset          int
	Limit           int     // Default 50, max 100
	Status          *string // Filter by status (Active, Superseded, Pinned, etc.) (M10)
	RetentionPolicy *string // Filter by retention_policy (M10)
	Pinned          *bool   // Filter pinned only (M10)
	OrderBy         string  // "created_at", "updated_at", "access_count", "last_accessed_at" (M10)
	OrderDesc       bool    // Default true (newest/highest first) (M10)
}

type MemoryRecord struct {
	ID              string                 `json:"id"`
	Topic           string                 `json:"topic"`
	Context         string                 `json:"context"`
	Decisions       []string               `json:"decisions,omitempty"`
	Rationale       []string               `json:"rationale,omitempty"`
	Metadata        map[string]interface{} `json:"metadata,omitempty"`
	CreatedAt       time.Time              `json:"created_at"`
	UpdatedAt       time.Time              `json:"updated_at"`
	Version         int                    `json:"version"`
	DocHash         string                 `json:"doc_hash"`
	Source          string                 `json:"source,omitempty"`
	Status          string                 `json:"status"`           // "pending", "complete", "Active", "Superseded", "Archived", "Pinned" (M3: Plan 021)
	AccessCount     int                    `json:"access_count"`     // M1: Plan 021 - Number of times this memory was accessed
	LastAccessedAt  *time.Time             `json:"last_accessed_at"` // M1: Plan 021 - Timestamp of last access
	AccessVelocity  float64                `json:"access_velocity"`  // M1: Plan 021 - Computed access frequency (accesses / days since creation)
	SupersededBy    *string                `json:"superseded_by"`    // M3: Plan 021 - ID of memory that supersedes this one (nullable)
	RetentionPolicy string                 `json:"retention_policy"` // M6: Plan 021 - Retention policy: permanent, decision, standard, ephemeral, session
	RetentionUntil  *time.Time             `json:"retention_until"`  // M6: Plan 021 - Explicit expiration timestamp (nullable)
	Pinned          bool                   `json:"pinned"`           // M9: Plan 021 - Whether this memory is pinned
	PinnedAt        *time.Time             `json:"pinned_at"`        // M9: Plan 021 - When this memory was pinned
	PinnedReason    *string                `json:"pinned_reason"`    // M9: Plan 021 - Why this memory was pinned (nullable)
}

type MemoryStore interface {
	// AddMemory creates a new memory record.
	AddMemory(ctx context.Context, record *MemoryRecord) error

	// GetMemory retrieves a memory by ID, including provenance information.
	GetMemory(ctx context.Context, id string) (*MemoryRecord, error)

	// ListMemories returns paginated memory summaries.
	ListMemories(ctx context.Context, opts ListMemoriesOptions) ([]MemorySummary, error)

	// UpdateMemory applies partial updates to a memory.
	UpdateMemory(ctx context.Context, id string, updates MemoryUpdate) error

	// DeleteMemory removes a memory and its provenance links.
	DeleteMemory(ctx context.Context, id string) error

	// GetMemoriesByNodeID returns all memory IDs that reference a given node.
	GetMemoriesByNodeID(ctx context.Context, nodeID string) ([]string, error)

	// CountMemories returns the total number of memories in the store.
	CountMemories(ctx context.Context) (int64, error)

	// UpdateMemoryAccess increments access tracking for a single memory.
	UpdateMemoryAccess(ctx context.Context, id string) error

	// BatchUpdateMemoryAccess increments access tracking for multiple memories.
	BatchUpdateMemoryAccess(ctx context.Context, ids []string) error

	// RecordSupersession records that one memory supersedes another (M3: Plan 021).
	RecordSupersession(ctx context.Context, supersedingID, supersededID, reason string) error

	// GetSupersessionChain retrieves the full chain of supersessions for a memory (M3: Plan 021).
	GetSupersessionChain(ctx context.Context, memoryID string) ([]SupersessionRecord, error)

	// GetSupersedingMemory returns the ID of the memory that supersedes this one, if any (M3: Plan 021).
	GetSupersedingMemory(ctx context.Context, memoryID string) (*string, error)

	// GetSupersededMemories returns the IDs of memories this one supersedes (M3: Plan 021).
	GetSupersededMemories(ctx context.Context, memoryID string) ([]string, error)
}

type MemorySummary struct {
	ID              string    `json:"id"`
	Topic           string    `json:"topic"`
	Preview         string    `json:"preview"` // Truncated context
	CreatedAt       time.Time `json:"created_at"`
	UpdatedAt       time.Time `json:"updated_at"`
	DecisionCount   int       `json:"decision_count"`
	Status          string    `json:"status"`
	RetentionPolicy string    `json:"retention_policy"` // M10: Plan 021
	Pinned          bool      `json:"pinned"`           // M10: Plan 021
	AccessCount     int       `json:"access_count"`     // M10: Plan 021
	SupersededBy    *string   `json:"superseded_by"`    // M10: Plan 021
}

type MemoryUpdate struct {
	Topic     *string
	Context   *string
	Decisions *[]string
	Rationale *[]string
	Metadata  *map[string]interface{}
	Status    *string
}

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

type Node struct {
	ID             string                 // Unique identifier (UUID)
	Name           string                 // Entity name
	Type           string                 // Entity type (Person, Concept, System, etc.)
	Description    string                 // Brief description
	Embedding      []float32              // Vector embedding for semantic search
	CreatedAt      time.Time              // Timestamp of creation
	LastAccessedAt *time.Time             // Timestamp of last access (for decay tracking)
	Metadata       map[string]interface{} // Additional metadata as JSON
}

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

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

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

type SearchResult struct {
	ID    string  // Node ID
	Score float64 // Cosine similarity score (0-1, higher is more similar)
}

type SupersessionRecord struct {
	ID            string    `json:"id"`
	SupersedingID string    `json:"superseding_id"`   // New memory that replaces old one
	SupersededID  string    `json:"superseded_id"`    // Old memory being replaced
	Reason        string    `json:"reason,omitempty"` // Optional explanation
	CreatedAt     time.Time `json:"created_at"`
}

type VectorStore interface {
	// Add adds or updates a vector for the given ID.
	Add(ctx context.Context, id string, embedding []float32) error

	// Search finds the most similar vectors to the query.
	// Returns up to topK results sorted by similarity score (descending).
	Search(ctx context.Context, query []float32, topK int) ([]SearchResult, error)

	// Delete removes a vector from the store.
	Delete(ctx context.Context, id string) error
}