service

type ActivityEvent struct {
	OpID      string
	Kind      store.EventKind
	Time      time.Time
	Namespace string
	Query     string
	Detail    map[string]any
	// Actor/ActorKind are who performed the operation — see store.Event. Empty
	// on a legacy row that predates attribution.
	Actor     string
	ActorKind string
	Memories  []ActivityMemory
}

type ActivityMemory struct {
	ID        string
	Namespace string
	Summary   string
	Tier      memory.Tier
	Rank      int
	Score     *float64
	Section   string // briefing only
}

type AnswerInput struct {
	Namespace string
	// Home is the caller's personal namespace, merged read-only into every
	// recall this answer performs (prefetch, gate, and any tool-loop
	// searches) — same semantics as RecallInput.Home.
	Home  string
	Query string
	// Limit caps how many recalled memories are given to the reader (default 10).
	Limit int
	Tiers []memory.Tier
	// Levels restricts grounding to memories whose derivation level matches one of
	// the listed values; empty means no level constraint.
	Levels   []memory.Level
	Tags     []string
	Metadata map[string]string
	// Reasoning selects the answer strategy: empty/minimal is single-shot;
	// low/medium/high run the bounded tool loop (see ReasoningLevel). Falls
	// back to single-shot when the configured LLM client can't do tool calls.
	Reasoning ReasoningLevel
	// Scope selects the grounding read-set shape, same vocabulary and
	// semantics as RecallInput.Scope: "" or "full" (default: Namespace +
	// ancestors + home + links), "project" (Namespace only, no cascade), or
	// "everywhere" (full + subtree). Threads into every recall this answer
	// performs — single-shot, expand's per-rewrite recalls, and the agentic
	// loop's prefetch and search_memory/recall_as_of tool recalls — the same
	// way Home does. An unrecognized value is an invalid-input error,
	// rejected up front before any LLM call.
	Scope string
	// ReadSet (output-only) is set to the STRUCTURAL read-set this answer can
	// draw from — same out-param pattern as RecallInput.ReadSet, but resolved
	// once up front (see Answer) with the tier-independent default cascade
	// (ResolveReadSetInfo semantics), NOT filtered by Tiers and NOT narrowed
	// by Scope. A namespace's origin (primary/ancestor/home/link) is a
	// structural property: tiers decide what gets SEARCHED, not what a
	// namespace IS, and the agentic tool loop overrides tiers per
	// search_memory call (tier="durable"), so its inner recalls can legally
	// reach cascade legs a Tiers-filtered resolution would have skipped.
	// Scope-independence keeps the labels correct too: Scope "project"
	// shrinks the inner recalls' reach (a structural superset is harmless for
	// labeling), and Scope "everywhere" only adds subtree members — which
	// carry origin "primary" and render with no "from" annotation, exactly
	// what an absent-from-the-map namespace renders anyway (see ReadSetFrom).
	// The caller passes the address of a local slice; nil disables reporting.
	ReadSet *[]ReadSetEntry
}

type AnswerResult struct {
	Answer  string
	Sources []store.Scored
}

type Briefing struct {
	Namespace string `json:"namespace"`
	// ScopeHeader is a one-line, human-readable summary of the read-set this
	// briefing drew from: the primary namespace, then each cascade leg that
	// actually contributed durable memories (nearest ancestor first, home
	// last), then a "+K link(s)" suffix counting contributing links. See
	// scopeHeader for the exact format and edge-case decisions.
	ScopeHeader string           `json:"scope_header,omitempty"`
	Facts       []*memory.Memory `json:"facts,omitempty"`      // semantic, highest-retention first
	Procedures  []*memory.Memory `json:"procedures,omitempty"` // procedural, highest-retention first
	Recent      []*memory.Memory `json:"recent,omitempty"`     // episodic, newest first
	Pinned      []*memory.Memory `json:"pinned,omitempty"`     // tagged pinned, any tier
	// Children summarizes the direct child namespaces (one segment deeper)
	// under the primary namespace, each aggregating its whole subtree —
	// most-recent write first, capped at childRollupMaxChildren. Empty at a
	// leaf namespace.
	Children []ChildSummary `json:"children,omitempty"`
	// ChildrenTruncated is the number of direct children omitted by the
	// childRollupMaxChildren cap (0 when everything fit). The REST wire shape
	// (T6) has no dedicated field for it, so renderers surface it themselves
	// (MCP appends an "… and N more" note; REST returns just the capped array).
	ChildrenTruncated int `json:"children_truncated,omitempty"`
}

type BriefingOpts struct {
	Pinned     *int
	Facts      *int
	Procedures *int
	Recent     *int
	// Namespaces, when non-empty, REPLACES the default read set (namespace,
	// subtree, ancestors, home, and links) with exactly these namespaces —
	// same replace-not-extend semantics as RecallInput.Namespaces. Each is
	// read with all tiers.
	Namespaces []string
	// Subtree expands the briefing to namespace and every namespace nested
	// under it, same semantics as RecallInput.Subtree. Ignored when Namespaces
	// is set.
	Subtree bool
	// Home is the caller's personal namespace, merged read-only into the
	// default read set — durable tiers only. See RecallInput.Home.
	Home string
	// Scope selects the read-set shape, same semantics as RecallInput.Scope:
	// "" or "full" (default), "project" (bare), or "everywhere" (+ subtree).
	// Ignored when Namespaces is set. An unrecognized value is an
	// invalid-input error.
	Scope string
	// ReadSet (output-only) is set to the resolved read-set this briefing
	// drew from, with per-leg origin — same out-param pattern as
	// RecallInput.ReadSet. The caller passes the address of a local slice;
	// nil disables reporting.
	ReadSet *[]ReadSetEntry
}

type ChildSummary struct {
	NS     string           `json:"namespace"`
	Total  int              `json:"total"`
	Pinned []*memory.Memory `json:"pinned,omitempty"`
	Recent []*memory.Memory `json:"recent,omitempty"`
}

type ConsolidateMode string

type DedupInput struct {
	// Similarity gates cluster membership. 0 falls back to the package
	// default (0.85). Negative disables the pass and Dedup returns an empty
	// report without erroring.
	Similarity float64
	// MinClusterSize is the smallest cluster acted on. 0 falls back to 2.
	MinClusterSize int
	// Tiers restricts the pass to these tiers; nil/empty means all tiers.
	Tiers []memory.Tier
	// Namespaces restricts the pass to these namespaces; nil/empty means every
	// namespace. API callers scope this to the request's namespace; only an
	// explicit all-namespaces request leaves it empty.
	Namespaces []string
	// NeighboursPerAnchor bounds the per-anchor vector-search fan-out.
	// 0 falls back to 20.
	NeighboursPerAnchor int
	// DryRun reports what would be done without tombstoning anything.
	DryRun bool
}

type EventsInput struct {
	// Namespace restricts the feed to one namespace; "" means every namespace.
	Namespace string
	// Namespaces narrows an all-namespaces feed to these namespaces (OR);
	// ignored when Namespace is set.
	Namespaces []string
	// Kinds restricts to these event kinds; empty means all.
	Kinds []store.EventKind
	// Actor restricts to events performed by the named API key (exact match);
	// empty means no constraint.
	Actor string
	// Tiers restricts to operations that touched a memory of one of these tiers.
	Tiers []memory.Tier
	// Text restricts to operations whose query or a served memory's summary
	// contains it, case-insensitively.
	Text string
	// Since restricts to events at or after the instant.
	Since time.Time
	// Before/BeforeID is the keyset cursor from a previous page.
	Before   time.Time
	BeforeID int64
	// Limit caps the returned operations (not rows); <= 0 uses the default.
	Limit int
}

type EventsPage struct {
	Events       []ActivityEvent
	NextBefore   time.Time
	NextBeforeID int64
	HasMore      bool
}

type ListInput struct {
	Namespace string
	Tiers     []memory.Tier
	// Levels restricts the listing to memories whose derivation level matches one
	// of the listed values; empty means no level constraint.
	Levels []memory.Level
	// Tags narrows the listing to memories carrying every listed tag (AND).
	Tags []string
	// Metadata narrows the listing to memories whose top-level metadata contains
	// each listed key=value string pair (AND).
	Metadata map[string]string
	// MemoryTypes narrows to memories whose metadata.memory_type is any of the
	// listed values (OR) — the multi-select the browser's type filter needs,
	// which Metadata's AND-one-value-per-key semantics cannot express.
	MemoryTypes []string
	// CreatedAfter/AccessedAfter narrow to memories created / last accessed at or
	// after the instant. Zero means no constraint.
	CreatedAfter      time.Time
	AccessedAfter     time.Time
	IncludeExpired    bool
	IncludeSuperseded bool
	// Sort orders the listing; the zero value is newest-created first.
	Sort store.Sort
	// Limit caps the result count; <= 0 returns all matches.
	Limit int
	// AllNamespaces lists across every namespace instead of in.Namespace, with
	// Limit applied as a single global cap under Sort. Backs the admin UI's
	// "All projects" view.
	AllNamespaces bool
	// Namespaces, with AllNamespaces, restricts the aggregate to these namespaces
	// (exact match); empty means every namespace. Ignored without AllNamespaces.
	Namespaces []string
}

type MergeHint struct {
	// SimilarID is the id of the near-duplicate memory. Empty when unknown.
	SimilarID string
	// SimilarContent is a preview of the near-duplicate memory's content.
	SimilarContent string
	// Score is the fused similarity (0..1) between the new write and the
	// near-duplicate.
	Score float64
	// Tier is the tier of the near-duplicate.
	Tier memory.Tier
}

type Metrics interface {
	// ConsolidateResult records one consolidation outcome: one of
	// "gated", "new", "update", "supersede", "noop", "error", "dropped".
	ConsolidateResult(result string)
	// ConsolidateQueueDepth reports the current async queue depth.
	ConsolidateQueueDepth(depth int)
	// RememberResult records the outcome of a Remember call: result is
	// "ok"|"error" and tier is the memory's tier.
	RememberResult(result, tier string)
	// RecallResult records the outcome of a Recall call. result is
	// "ok"|"error"; tierFilter is one of "all"|"working"|"episodic"|
	// "semantic"|"procedural"|"mixed"; hitsBucket is a pre-bucketed
	// count of returned memories: "0"|"1"|"2-5"|"6-20"|"21+".
	RecallResult(result, tierFilter, hitsBucket string)
	// ForgetResult records the outcome of a Forget call: "ok"|"not_found"|"error".
	ForgetResult(result string)
	// SupersedeResult records the outcome of a Supersede call:
	// "ok"|"not_found"|"error". Supersede tombstones a memory (sets
	// superseded_by) rather than deleting it; the maintenance sweeper
	// hard-deletes tombstoned rows after TombstoneTTL.
	SupersedeResult(result string)
	// PromoteResult records one Promote batch: result is "ok"|"error";
	// facts is the number of semantic facts written.
	PromoteResult(result string, facts int)
	// FsckResult records one fsck pass: "ok"|"error". Counters for the
	// work done (purged, evicted, duplicate groups) are exposed separately
	// via the store's maintenance metrics.
	FsckResult(result string)
	// OpDuration observes end-to-end latency for a public operation
	// (e.g. "recall", "answer").
	OpDuration(op string, d time.Duration)
	// AnswerResult records one Answer call: "ok" or "error".
	AnswerResult(result string)
	// RerankResult records one recall rerank attempt: backend is the reranker's
	// label ("llm"|"cross_encoder"); result is "ok" or "fallback".
	RerankResult(backend, result string)
	// RecallDegraded records one recall that fell back to keyword-only search
	// because the query embed failed or timed out. reason is "embed_timeout" or
	// "embed_error".
	RecallDegraded(reason string)
	// RememberDegraded records one write that stored without a vector (embedding
	// omitted, keyword-searchable only, marked pending_embed) because the content
	// embed failed or timed out. reason is "embed_timeout" or "embed_error".
	RememberDegraded(reason string)
	// WriteSanitized records one ingestion content-hygiene action: "cleaned"
	// (unambiguous corruption stripped from content) or "quarantined"
	// (script-salad downranked when corruption quarantine is enabled).
	WriteSanitized(action string)
	// ReinforceResult records one best-effort recall reinforcement write:
	// "ok" or "error".
	ReinforceResult(result string)
	// DedupTombstoned records the total memories tombstoned by one one-shot
	// Service.Dedup call. Called once per call.
	DedupTombstoned(n int)
	// CorroborateResult records one corroboration-routing attempt on a fresh
	// short-term write: "corroborated" (durable fact reinforced), "cooldown"
	// (match found but inside the per-fact window), "miss" (no durable
	// neighbour at or above the threshold), or "error".
	CorroborateResult(result string)
	// ContradictResult records one contradiction-routing attempt on a fresh
	// durable write: "contradicted" (stale fact invalidated), "no_signal" (a
	// near neighbour, but the detector saw no value/polarity change), "cooldown"
	// (match inside the per-fact window), "miss" (no durable neighbour at or
	// above the threshold, or an untracked-confidence row), or "error".
	ContradictResult(result string)
	// TierClassified records an omitted-tier write the marker classifier
	// routed to a durable tier; tier is "semantic" or "procedural".
	TierClassified(tier string)
	// EmbedBackfillPending reports the number of memories still marked
	// pending_embed after one backfill tick (0 once the queue is drained).
	EmbedBackfillPending(n int)
}

type Option func(*Service)

type ReadSetEntry struct {
	NS     string
	Origin string
	Tiers  []memory.Tier
}

type ReasoningLevel string

type RecallInput struct {
	Namespace string
	Query     string
	// Source is the "why" behind this recall — which integration or code path
	// asked for it (documented vocabulary: "pretool", "session_start", "mcp",
	// "ui", "api", "answer", "doctor"). It is recorded verbatim in the recall
	// event's detail (including the zero-hit sentinel), never validated, so an
	// unknown value from a fail-soft client is logged rather than rejected.
	// "" means the caller supplied none (the event omits it).
	Source string
	Tiers  []memory.Tier
	// Levels restricts recall to memories whose derivation level matches one of the
	// listed values; empty means no level constraint.
	Levels []memory.Level
	// Tags narrows recall to memories carrying every listed tag (AND).
	Tags []string
	// Metadata narrows recall to memories whose top-level metadata contains each
	// listed key=value string pair (AND).
	Metadata map[string]string
	// ExcludeMetadata drops memories whose top-level metadata contains every
	// listed key=value pair (AND), applied after Metadata. Lets a caller exclude
	// its own session's just-captured turns from auto-recall.
	ExcludeMetadata map[string]string
	// ExcludeIDs drops memories with the listed ids, before ranking and Limit,
	// so an excluded hit never consumes a result slot. Lets a long-lived client
	// keep memories it has already injected out of recall and still receive the
	// next-best fresh hits. Capped at maxRecallExcludeIDs entries.
	ExcludeIDs []string
	// IncludeFreshTurns, when true, disables the server-side temporal echo
	// guard for this call: just-captured episodic turns (metadata.format="turn"
	// younger than the server's turnEchoWindow) are NOT dropped. Default
	// (false) means the guard fires — a just-captured turn is still live
	// context and must not be recalled back as long-term memory. Opt out only
	// when a caller genuinely needs fresh turns (e.g. a "what did I just say"
	// debug query).
	IncludeFreshTurns bool
	// QueryRewrite, when true and an LLM answerer is configured, rewrites the
	// query into 2-3 diverse variants before recall and fuses the results via
	// RRF. Cheapest read-path LLM lever; opt-in per call. No-op when no answerer
	// is configured (falls through to single-query recall).
	QueryRewrite bool
	Limit        int
	// IncludeExpired / IncludeSuperseded relax the default live-only filter.
	IncludeExpired    bool
	IncludeSuperseded bool
	// AsOf, when non-zero, runs time-travel recall: it returns the facts whose
	// validity window contained AsOf (including ones since superseded), instead
	// of only currently-live memories.
	AsOf time.Time
	// Subtree expands recall to Namespace and every namespace nested under it
	// ("project" also reads "project/agent-a", "project/agent-b", ...), for the
	// multi-agent "read shared + private" pattern. Default (false) is exact scope,
	// so cross-agent recall never happens unless asked for.
	Subtree bool
	// Namespaces, when non-empty, REPLACES the default read set (Namespace +
	// ancestors + home + links, optionally + subtree) with exactly these
	// namespaces — no cascade merge, no subtree of Namespace unless an entry
	// spells it with "/*". Wins over Scope regardless of its value. An entry
	// ending in "/*" also includes every namespace nested under it. Max 16
	// entries; each is searched with the request's own tier filter (Tiers).
	Namespaces []string
	// Home is the caller's personal namespace (from the X-Memini-Home
	// header), merged read-only into the default read set — durable tiers
	// only, like an ancestor. Empty means no home leg.
	Home string
	// Scope selects the read-set shape: "" or "full" (default: Namespace +
	// ancestors + home + links), "project" (Namespace only, no cascade), or
	// "everywhere" (full + subtree). An unrecognized value is an invalid-input
	// error. Namespaces, when set, replaces the cascade outright regardless of
	// Scope (explicit beats scope). Subtree (legacy) still works standalone;
	// Scope "everywhere" is equivalent to Subtree: true.
	Scope string
	// MinScore, when > 0, overrides the server's default recallMinScore for
	// this call. Lets a caller request a stricter relevance floor per
	// integration (e.g. the pre-tool-use hook only injects highly-relevant
	// hits). 0 (the zero value) falls back to the server-wide gate. Only
	// meaningful with score fusion; RRF scores are not comparable to [0,1].
	MinScore float64
	// MinSemanticScore, when > 0, overrides the server's default
	// recallMinSemanticScore (the absolute vector-relevance gate) for this call.
	// 0 falls back to the server-wide gate.
	MinSemanticScore float64
	// SemanticReserve, when > 0, overrides the server's default
	// recallSemanticReserve (durable-tier slot reservation) for this call. 0
	// falls back to the server-wide value.
	SemanticReserve int
	// Degraded (output-only) is set to the degradation reason
	// ("embed_error"/"embed_timeout") when this recall fell back to
	// keyword-only search because the query embed failed or timed out. The
	// caller passes the address of a local string; it is left untouched
	// (empty) on a healthy recall. nil disables reporting. Same out-param
	// pattern as MergeHint/AutoSuperseded on RememberInput.
	Degraded *string
	// ReadSet (output-only) is set to the resolved read-set — every namespace
	// this recall searched, with the origin recorded when that leg was
	// appended during resolution (primary/ancestor/home/link/call) and any
	// per-namespace tier restriction. The caller passes the address of a
	// local slice; it is left untouched (nil) when ReadSet is nil. Same
	// out-param pattern as Degraded — lets MCP/REST render read-set
	// provenance (e.g. "from: acme") without a second resolveReadSet call.
	ReadSet *[]ReadSetEntry
	// IncludeLinked, when true, expands recall to include memories linked to
	// any result via LinkedMemoryIDs (1-hop expansion). Linked memories that
	// are superseded are skipped. Default (false) is no expansion.
	IncludeLinked bool
}

type RememberInput struct {
	Namespace string
	// Home is the caller's personal namespace (X-Memini-Home / MEMINI_HOME).
	// Consumed by resolveVisibility when Visibility is "personal".
	Home string
	// Visibility steers which namespace the write actually lands in: ""/
	// "project" (default) is Namespace itself; "personal" is Home; anything
	// else must name an ancestor of Namespace (by exact path or unambiguous
	// last segment). See resolveVisibility for the full resolution and the
	// tier clamp (episodic/working writes always stay in Namespace).
	Visibility string
	Content    string
	Tier       memory.Tier
	Summary    string
	Tags       []string
	Metadata   map[string]any
	Importance float64
	// TTL overrides the tier default. A negative TTL means "never expire".
	TTL *time.Duration
	// ID upserts an existing memory when set; otherwise a new ID is generated.
	ID string
	// Confidence overrides the seed corroboration for a durable fact (e.g. a
	// trusted import). nil uses the default seed. Ignored for short-term tiers.
	Confidence *float64
	// ValidFrom / ValidTo set the interval the fact was true, for recording
	// historical facts that time-travel (AsOf) recall can surface. ValidFrom
	// defaults to now (or the existing row on update); ValidTo defaults to open.
	ValidFrom *time.Time
	ValidTo   *time.Time
	// Level labels the derivation provenance at write time: explicit (user-stated
	// or heuristic) vs deduced (LLM-distilled). Empty string means legacy/unknown
	// and falls through to "no constraint" in filter operations.
	Level memory.Level
	// MergeHint (output-only) is set to a non-nil MergeHint when the write's
	// nearest same-tier candidate landed in the merge-hint band. The caller
	// passes the address of a local `*MergeHint`; after the call it holds the
	// hint (or remains nil). nil disables hint reporting.
	MergeHint *MergeHint
	// AutoSuperseded (output-only) is set to true when the write triggered a
	// background supersede. The caller passes the address of a local bool.
	// nil disables reporting.
	AutoSuperseded *bool
	// Reinforced (output-only) is set to true when the write did NOT create a new
	// memory: the fact was already known, so the existing memory was strengthened
	// (reinforced/corroborated) and returned instead.
	//
	// This matters because Remember returns a non-nil Memory on those paths, so a
	// caller cannot otherwise tell "I stored a new fact" from "that was already
	// known". Two paths reach it: the exact-restatement fingerprint fast path, and
	// the write-dedup coalesce action when the incoming phrasing is not richer
	// than the stored one. An agent told `stored: true` in either case believes it
	// created something it did not, and the id it gets back belongs to a memory it
	// did not write — which is exactly the memory it would then go and clobber.
	//
	// The caller passes the address of a local bool; nil disables reporting.
	Reinforced *bool
	// Author names the NAMED API key that authenticated this write (set by
	// the REST/MCP handlers from the request principal — see
	// internal/api/rest's principalFromContext / internal/apiauth.Principal).
	// "" for the admin key or an unauthenticated/auth-disabled request, which
	// stamp no author at all. stampAuthor writes this into
	// metadata["author"], but only when the caller hasn't already set one —
	// see its doc.
	Author string
}

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

type Stats struct {
	Namespace    string              `json:"namespace"`
	Total        int                 `json:"total"`                    // live memories (excludes expired/superseded)
	ByTier       map[memory.Tier]int `json:"by_tier"`                  // live count per tier
	ByMemoryType map[string]int      `json:"by_memory_type,omitempty"` // live count per metadata.memory_type (typed extractions)
	Expired      int                 `json:"expired"`                  // past-TTL, not yet swept
	Superseded   int                 `json:"superseded"`               // contradiction-tombstoned
	// uncorroborated durable debris (confidence below the demote floor); unbounded
	// by short-term caps, so a growing value signals reclaimable bloat
	LowConfidenceDurable int        `json:"low_confidence_durable"`
	TotalAccesses        int        `json:"total_accesses"`
	AvgImportance        float64    `json:"avg_importance"`
	LastWriteAt          *time.Time `json:"last_write_at,omitempty"`
}

type WriteDedupAction string