memory

type Backend interface {
	Retain(context.Context, Scope, RetainRequest) (RetainResult, error)
	Recall(context.Context, Scope, RecallRequest) (RecallResult, error)
	Forget(context.Context, Scope, string) error
}

type CausalLink struct {
	TargetIndex  int    `json:"target_index"`
	RelationType string `json:"relation_type"`
}

type Checkpoint struct {
	ID              string    `json:"id"`
	CreatedAt       time.Time `json:"created_at"`
	CiphertextBytes int64     `json:"ciphertext_bytes"`
	SHA256          string    `json:"sha256"`
}

type CheckpointAuthority interface {
	UploadURL(context.Context, Checkpoint) (CheckpointURL, error)
	DownloadURL(context.Context, string) (CheckpointURL, error)
	List(context.Context) ([]Checkpoint, error)
	Delete(context.Context, string) error
}

type CheckpointStore interface {
	Put(context.Context, Checkpoint, io.Reader) error
	Open(context.Context, string) (io.ReadCloser, error)
	List(context.Context) ([]Checkpoint, error)
	Delete(context.Context, string) error
}

type CheckpointURL struct {
	URL     string
	Headers http.Header
}

type ConsolidationAction struct {
	ObservationID string   `json:"observation_id,omitempty"`
	Text          string   `json:"text"`
	SourceFactIDs []string `json:"source_fact_ids"`
	Reason        string   `json:"reason"`
}

type ConsolidationDelete struct {
	ObservationID string `json:"observation_id"`
	Reason        string `json:"reason"`
}

type ConsolidationPlan struct {
	Creates []ConsolidationAction `json:"creates"`
	Updates []ConsolidationAction `json:"updates"`
	Deletes []ConsolidationDelete `json:"deletes"`
}

type ConsolidationResult struct {
	Processed int `json:"processed"`
	Created   int `json:"created"`
	Updated   int `json:"updated"`
	Deleted   int `json:"deleted"`
}

type Consolidator interface {
	Consolidate(context.Context, []Fact, []Observation) (ConsolidationPlan, error)
}

type Embedder interface {
	// ModelID must change when the model, dimensions, or preprocessing changes.
	ModelID() string
	Embed(context.Context, []string) ([][]float32, error)
}

type ExtractedChunk struct {
	Index int    `json:"index"`
	Text  string `json:"text"`
}

type ExtractedFact struct {
	// Metadata is supplied by the extractor; document metadata takes precedence.
	Metadata        map[string]string `json:"metadata,omitempty"`
	SourceChunk     *ExtractedChunk   `json:"source_chunk,omitempty"`
	Text            string            `json:"text"`
	Where           string            `json:"where,omitempty"`
	Type            string            `json:"type"`
	Entities        []string          `json:"entities"`
	OccurredStart   *time.Time        `json:"occurred_start,omitempty"`
	OccurredEnd     *time.Time        `json:"occurred_end,omitempty"`
	CausalRelations []CausalLink      `json:"causal_relations,omitempty"`
}

type Extractor interface {
	Extract(context.Context, RetainRequest) ([]ExtractedFact, error)
}

type Fact struct {
	ID            string            `json:"id"`
	ChunkID       string            `json:"chunk_id,omitempty"`
	DocumentID    string            `json:"document_id"`
	Text          string            `json:"text"`
	Type          string            `json:"type"`
	Entities      []string          `json:"entities"`
	Context       string            `json:"context,omitempty"`
	MentionedAt   time.Time         `json:"mentioned_at"`
	Where         string            `json:"where,omitempty"`
	OccurredStart *time.Time        `json:"occurred_start,omitempty"`
	OccurredEnd   *time.Time        `json:"occurred_end,omitempty"`
	Metadata      map[string]string `json:"metadata,omitempty"`
}

type FactEmbedder interface {
	EmbedFacts(context.Context, []ExtractedFact, time.Time) ([][]float32, error)
}

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

type MentalModel struct {
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	SourceQuery   string    `json:"source_query"`
	Content       string    `json:"content"`
	SourceFactIDs []string  `json:"source_fact_ids"`
	RefreshedAt   time.Time `json:"refreshed_at"`
	IsStale       bool      `json:"is_stale"`
}

type Observation struct {
	ID             string     `json:"id"`
	Text           string     `json:"text"`
	SourceFactIDs  []string   `json:"source_fact_ids"`
	ProofCount     int        `json:"proof_count"`
	UpdatedAt      time.Time  `json:"updated_at"`
	IsStale        bool       `json:"is_stale"`
	MentionedAt    time.Time  `json:"mentioned_at"`
	OccurredStart  *time.Time `json:"occurred_start,omitempty"`
	OccurredEnd    *time.Time `json:"occurred_end,omitempty"`
	SourceMemories []Fact     `json:"source_memories,omitempty"`
}

type ObservationReconciler interface {
	ReconcileObservations(context.Context, string, string) (ObservationReconciliation, error)
}

type ObservationReconciliation struct {
	Action string `json:"action"`
	Text   string `json:"text"`
	Reason string `json:"reason"`
}

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

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

type ProviderConfig struct {
	BaseURL             string
	APIKey              string
	ExtractionModel     string
	EmbeddingModel      string
	EmbeddingModelID    string
	EmbeddingBaseURL    string
	EmbeddingAPIKey     string
	EmbeddingDimensions int
	RerankModel         string
	Client              *http.Client
	// ExtractionOptions supplies provider-specific sampling/reasoning controls.
	// Core model, messages and response schema cannot be overridden.
	ExtractionOptions map[string]any
}

type RecallRequest struct {
	Query          string          `json:"query"`
	IncludeChunks  bool            `json:"include_chunks,omitempty"`
	MaxChunkTokens int             `json:"max_chunk_tokens,omitempty"`
	Limit          int             `json:"limit,omitempty"`
	MaxTokens      int             `json:"max_tokens,omitempty"`
	Types          []string        `json:"types,omitempty"`
	QueryTimestamp time.Time       `json:"query_timestamp,omitempty"`
	TemporalWindow *TemporalWindow `json:"temporal_window,omitempty"`
}

type RecallResult struct {
	Results              []Result               `json:"results"`
	Chunks               map[string]SourceChunk `json:"chunks,omitempty"`
	EstimatedChunkTokens int                    `json:"estimated_chunk_tokens,omitempty"`
	// EstimatedTokens includes JSON result framing. A caller may supply an exact
	// tokenizer; the default uses Hindsight's o200k_base encoding.
	EstimatedTokens int `json:"estimated_tokens"`
	// Nil means the reference server did not expose its reranking configuration.
	Reranked *bool `json:"reranked,omitempty"`
}

type ReflectBackend interface {
	ReflectMemory(context.Context, Scope, ReflectRequest) (ReflectResult, error)
}

type ReflectRequest struct {
	Query            string   `json:"query"`
	Directives       []string `json:"directives,omitempty"`
	MaxSteps         int      `json:"max_steps,omitempty"`
	MaxContextTokens int      `json:"max_context_tokens,omitempty"`
}

type ReflectResult struct {
	Answer         string   `json:"answer"`
	MemoryIDs      []string `json:"memory_ids"`
	ObservationIDs []string `json:"observation_ids"`
	MentalModelIDs []string `json:"mental_model_ids"`
	SourceFactIDs  []string `json:"source_fact_ids"`
	Steps          int      `json:"steps"`
}

type ReflectionMessage struct {
	Role       string               `json:"role"`
	Content    string               `json:"content,omitempty"`
	ToolCalls  []ReflectionToolCall `json:"tool_calls,omitempty"`
	ToolCallID string               `json:"tool_call_id,omitempty"`
}

type ReflectionModel interface {
	ReflectionStep(context.Context, []ReflectionMessage, string) (ReflectionMessage, error)
}

type ReflectionToolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

type Reranker interface {
	Rerank(context.Context, string, []string) ([]float64, error)
}

type Result struct {
	Fact
	Score       float64        `json:"score"`
	SourceRanks map[string]int `json:"source_ranks,omitempty"`
}

type RetainRequest struct {
	DocumentID string            `json:"document_id"`
	Content    string            `json:"content"`
	Context    string            `json:"context,omitempty"`
	Timestamp  time.Time         `json:"timestamp,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

type RetainResult struct {
	DocumentID string `json:"document_id"`
	FactCount  int    `json:"fact_count"`
	Unchanged  bool   `json:"unchanged"`
}

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

type SQLiteConfig struct {
	Path        string
	Extractor   Extractor
	Embedder    Embedder
	Reranker    Reranker
	CountTokens TokenCounter
	// MaxObservations bounds each bank; zero leaves it unlimited.
	MaxObservations int
	// CandidateLimit bounds each retrieval arm before RRF (default 100).
	CandidateLimit int
	// RerankerMaxCandidates caps the fused pool before reranking and combined
	// scoring, matching Hindsight's default of 300. It is independent of the
	// per-arm retrieval limit: changing it also changes rank normalization.
	RerankerMaxCandidates int
}

type Scope struct {
	AppID  string `json:"app_id"`
	BankID string `json:"bank_id"`
}

type SourceChunk struct {
	ID         string `json:"id"`
	DocumentID string `json:"document_id"`
	Index      int    `json:"chunk_index"`
	Text       string `json:"text"`
	Truncated  bool   `json:"truncated"`
}

type TemporalWindow struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

type TokenCounter func(string) int