memory

type Chunk struct {
	Idx       int
	Text      string
	Embedding []float32
}

type Level string

type Memory struct {
	ID        string `json:"id"`
	Namespace string `json:"namespace"`
	Tier      Tier   `json:"tier"`
	Level     Level  `json:"level,omitempty"`
	Content   string `json:"content"`
	Summary   string `json:"summary,omitempty"`

	// Metadata is arbitrary structured data, persisted as JSON.
	Metadata map[string]any `json:"metadata,omitempty"`
	// Tags are free-form labels used for keyword retrieval and filtering.
	Tags []string `json:"tags,omitempty"`

	// Importance biases decay and ranking; higher survives longer. Range [0,1].
	Importance float64 `json:"importance"`

	CreatedAt      time.Time  `json:"created_at"`
	UpdatedAt      time.Time  `json:"updated_at"`
	LastAccessedAt time.Time  `json:"last_accessed_at"`
	AccessCount    int        `json:"access_count"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`

	// SupersededBy points at the memory that replaced this one during
	// contradiction resolution; non-nil means this record is tombstoned.
	SupersededBy *string `json:"superseded_by,omitempty"`

	// ValidFrom / ValidTo bound the wall-clock interval a fact was true. Both nil
	// means "always" (the common case). ValidTo is stamped when a fact is
	// superseded, so a time-filtered recall (Filter.AsOf) can answer "what was
	// true in March" by surfacing facts valid then even if later replaced.
	ValidFrom *time.Time `json:"valid_from,omitempty"`
	ValidTo   *time.Time `json:"valid_to,omitempty"`

	// Confidence is how corroborated a durable (semantic/procedural) fact is,
	// in [0,1]. It starts low for a fresh or imported fact, grows logistically
	// each time the fact is re-observed, and decays without reinforcement, so a
	// corroborated fact outranks one-off noise. nil means "not tracked" (every
	// short-term memory, and durable memories written before the field existed),
	// treated as fully trusted so existing data is never retroactively penalized.
	Confidence *float64 `json:"confidence,omitempty"`

	// AssessedImportance is how intrinsically important the LLM judged this
	// content to be, in [0.1,0.9]. nil means never assessed (every memory
	// written before the field existed, and every write the assessor did not
	// reach). Invariant: it is cleared whenever a caller supplies an explicit
	// Importance, so a non-nil value always refines a tier-seeded guess and
	// never overrides what a user asked for.
	AssessedImportance *float64 `json:"assessed_importance,omitempty"`

	// LinkedMemoryIDs references related memories (same entity/topic but distinct
	// facts). Populated by the LLM consolidator when a new memory is related but
	// neither a duplicate nor a contradiction. At recall, IncludeLinked expands
	// results 1-hop via these links. Links are advisory — stale links (target
	// superseded) are resolved at recall time.
	LinkedMemoryIDs []string `json:"linked_memory_ids,omitempty"`

	// Embedding is the dense vector for similarity search. It is required when
	// writing to the store and is omitted from API responses.
	Embedding []float32 `json:"-"`

	// EmbedState is the deferred-repair state a write commits alongside the
	// memory: "" for a healthy write, "pending" when it stored without a vector
	// because the embedder was unreachable. The values are store.RepairState's;
	// it is a plain string here only because internal/memory cannot import
	// internal/store.
	//
	// Writing it on the Memory rather than through a separate call is the whole
	// point: the state and the memory it describes commit in one transaction,
	// so there is no window in which a degraded write exists without the record
	// that it needs repairing. On read paths it reflects the stored column, so
	// a caller can tell a memory that will be repaired shortly from one whose
	// repair has given up (see EmbedStuck).
	EmbedState string `json:"embed_state,omitempty"`

	// Chunks are per-segment vectors covering content that runs past the
	// per-item embed budget, so recall can match text the Embedding above does
	// not reach. Optional: a store need not implement store.ChunkStore, and
	// short content has none by design (see internal/chunk).
	//
	// On Upsert, nil means the store decides: existing chunk rows are kept
	// when the content is unchanged (same fingerprint) and cleared when it
	// changed. That default fails safe in both directions — stale chunks make
	// recall return a memory whose text no longer contains the passage that
	// matched it, while missing ones are re-created by the backfill loop, so
	// a caller that rewrites content without recomputing loses nothing
	// durable, and a caller that merely stamps metadata cannot wipe an index
	// it never touched. A non-nil slice replaces the rows exactly as given;
	// an empty non-nil slice is an explicit clear, for callers whose chunks
	// went stale without a content change (reembed: the model changed under
	// them).
	Chunks []Chunk `json:"-"`
}

type Term string

type Tier string