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
	// Injected is the served→injected join's verdict for a recall event's
	// memory: true when a nearby inject report named it as actually reaching
	// model context, false when a report existed but omitted it (the client
	// suppressed it). nil when no report covered the serve — absent means
	// unknown, so old data and non-reporting integrations render unchanged,
	// while false means reported-suppressed. See annotateInjected.
	Injected *bool
	// Filtered marks a hit the recall dropped from its response but still logged:
	// "rank_floor" when the composite floor (min_rank_score) cut it. Empty for a
	// served hit. Lets the feed dim what was filtered instead of hiding it.
	Filtered string
}

type AmbiguousIDError struct {
	Prefix string
	IDs    []string
}

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"`
	// Degraded names the read-set namespaces whose load failed and were skipped,
	// so a caller can tell an empty section from an unreachable one. Empty on a
	// healthy briefing. The primary namespace never appears here: losing it is
	// fatal rather than degrading, because a briefing without the project's own
	// context is not a briefing.
	Degraded []string `json:"degraded,omitempty"`
	// Omitted is the total number of items BriefingOpts.MaxTokens dropped
	// across the four sections (0 without a budget or when everything fit).
	// The briefing has no per-call activity detail for it — this field IS the
	// budget's visibility on this surface.
	Omitted int `json:"omitted,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
	// MaxTokens, when > 0, is a server-enforced token budget across the whole
	// briefing, filled in section order pinned → facts → procedures → recent
	// (fill order IS priority order: pinned fills first, recent starves
	// first), dropping whole tail items — never splitting one — and reporting
	// the drop count in Briefing.Omitted. The first item overall always
	// ships. 0 is unbounded. See applyBriefingBudget.
	MaxTokens int
	// EstimateConcise makes MaxTokens estimate over each item's concise
	// projection (render.BriefingMax) instead of full content — set when the
	// response will ship the concise form (?format=concise), same doctrine as
	// RecallInput.EstimateConcise.
	EstimateConcise bool
}

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 InjectedReport struct {
	// SessionID is the client session the injection happened in; "" when the
	// client did not say.
	SessionID string
	// Surface is the hook surface that reported: "briefing", "prompt" or
	// "pretool". The transport layer validates it; it is recorded verbatim.
	Surface string
	// Source is the free-form client name (e.g. "claude-code"); "" omits it
	// from the event detail, mirroring RecallInput.Source.
	Source string
	// InjectedIDs are the memory ids actually injected, in injection order.
	// May be empty: a suppression-only report still records (as a single
	// memory-less event, the zero-hit recall's precedent).
	InjectedIDs []string
	// TokensEst and Chars are the client's size estimates for what it
	// injected; nil means unreported (the detail key is then absent, not 0).
	TokensEst *int
	Chars     *int
	// Suppressed counts what the client's local gates held back, by reason.
	Suppressed InjectedSuppressed
}

type InjectedSuppressed struct {
	Seen, Cooldown, Budget, Unchanged, Score int
}

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 namespaces" 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)
	// RecallFloored records the candidates one recall's composite floor
	// (min_rank_score) dropped from the response. Called once per recall that
	// floored anything, with the drop count; tierFilter matches RecallResult's
	// label.
	RecallFloored(tierFilter string, n int)
	// 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)
	// InjectedResult records one bucket of a client injection-telemetry
	// report (RecordInjected): surface is the reporting hook surface
	// ("briefing"|"prompt"|"pretool"); result is "injected" or a suppression
	// reason ("suppressed_seen"|"suppressed_cooldown"|"suppressed_budget"|
	// "suppressed_unchanged"|"suppressed_score"); n is how many memories fell
	// in that bucket. Zero buckets are not reported.
	InjectedResult(surface, result string, n int)
	// InjectedTokens adds a report's client-side estimate of the tokens its
	// injections consumed, by surface.
	InjectedTokens(surface string, tokens int)
	// EmbedBackfillPending reports the number of memories still marked
	// pending_embed after one backfill tick (0 once the queue is drained).
	EmbedBackfillPending(n int)
	// ChunkBackfillPending reports the number of long memories still without
	// chunk vectors after one chunk-backfill tick (0 once the queue is
	// drained). Only meaningful with MEMINI_CHUNK_EMBED on.
	ChunkBackfillPending(n int)
	// RepairResult records one deferred-repair outcome. stage is the repair
	// state the row was claimed in ("pending" or "enrich"); result is "ok",
	// "moot" (the row no longer needed the work), "retry" (failed, will run
	// again under backoff), "parked" (failed at the attempt ceiling), or a
	// stage-specific detail ("embedded", "coalesced", "superseded").
	RepairResult(stage, result string)
	// RepairDuration observes one deferred repair's end-to-end execution time.
	RepairDuration(stage string, d time.Duration)
	// RepairDepth reports how many memories are currently in one repair state.
	RepairDepth(state string, n int)
	// RepairOldestAge reports the age in seconds of the oldest memory in one
	// repair state — the signal that the backlog is filling faster than it
	// drains.
	RepairOldestAge(state string, seconds float64)
}

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
	// MinRankScore, when > 0, floors the FINAL ranked (composite) score — the
	// scale the response Score field and the activity feed show — applied after
	// re-ranking, so it changes only which hits reach the response, never the
	// candidate pool the reranker judged or its ordering. It is a distinct floor
	// from the two above: MinScore gates the raw fused (vector+keyword) score
	// pre-rank, the reranker's own MEMINI_RERANK_MIN_SCORE gates the absolute
	// cross-encoder score (never on the wire), and this gates the composite that
	// finalizeRecall re-attaches. Hits it drops are still logged to the activity
	// feed marked as filtered; results added by include_linked expansion are
	// exempt (the floor runs before expansion). Valid range is [0,1); 0 (the
	// zero value) disables it.
	MinRankScore 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
	// DroppedNamespaces (output-only) receives the read-set namespaces whose
	// search failed and were skipped, so a caller can tell "nothing matched"
	// from "part of the corpus was unreachable". Empty on a healthy recall;
	// the primary namespace never appears here because losing it is fatal
	// rather than degrading. nil disables reporting. Same out-param pattern as
	// Degraded.
	DroppedNamespaces *[]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
	// MaxTokens, when > 0, is a server-enforced token budget over the final
	// ranked results: they fill in rank order until the estimated cost
	// (render.ApproxTokens over the shipped content + render.ItemOverheadTokens
	// per item) would exceed it, and the tail is dropped whole — except the
	// first result, which always ships (a non-empty recall never becomes
	// empty by budget). 0 is unbounded. See applyRecallBudget.
	MaxTokens int
	// EstimateConcise makes MaxTokens estimate over the CONCISE projection of
	// each result (summary-or-boundary-cut, render.SearchMax) instead of the
	// full content — set by callers whose response will ship the concise form
	// (REST response_format=concise), so the budget prices what actually goes
	// on the wire. It does NOT change what content ships; the response
	// projection stays the transport layer's job. Meaningless without
	// MaxTokens.
	EstimateConcise bool
	// Omitted (output-only) receives the number of results MaxTokens dropped
	// (0 without a budget or when everything fit). Same out-param pattern as
	// Degraded/ReadSet; nil disables reporting. The count also lands in the
	// recall activity event's detail as budget_omitted.
	Omitted *int
}

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
	// AssessedImportance carries the LLM's own read of how important the content
	// is. Set by the promote/consolidate paths only, never by external callers —
	// those set Importance, which clears the assessment (see below).
	AssessedImportance *float64
	// ClearAssessedImportance forces that clear even when the incoming
	// Importance equals the stored one. Update seeds Importance from the stored
	// row on every edit, so value equality alone cannot distinguish "the caller
	// chose this number" from "the caller touched nothing"; Update sets this
	// when the edit really carried an importance.
	ClearAssessedImportance bool
	// 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
	// EffectiveTier (output-only) receives the tier the write RESOLVED to —
	// the explicit tier when one was given, otherwise the auto-classified or
	// default tier. It is populated as soon as validation succeeds, so it is
	// set even when the value gate drops the write and Remember returns
	// (nil, nil): without it a caller reporting a dropped write back to an
	// agent can only echo the raw input tier, which is "" when the agent
	// omitted it.
	//
	// The caller passes the address of a local memory.Tier; nil disables
	// reporting.
	EffectiveTier *memory.Tier
	// 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"`
	// vectorless degraded writes awaiting repair; a persistently nonzero value
	// means the embedder is down
	PendingEmbed int `json:"pending_embed"`
	// degraded writes whose repair exhausted its attempt ceiling. Unlike
	// PendingEmbed these do NOT fix themselves on the next tick: they stay
	// keyword-only until the sweeper's circuit breaker re-arms them or an
	// operator intervenes. Reported separately precisely because rendering the
	// two identically is what lets a permanently degraded memory hide.
	EmbedStuck    int        `json:"embed_stuck"`
	TotalAccesses int        `json:"total_accesses"`
	AvgImportance float64    `json:"avg_importance"`
	LastWriteAt   *time.Time `json:"last_write_at,omitempty"`
}

type UpdateInput struct {
	Namespace string
	ID        string
	// Home is the caller's personal namespace, and Author the named API key
	// behind the edit — both forwarded to RememberInput. See its docs.
	Home   string
	Author string

	Content *string
	Summary *string
	Tier    *memory.Tier
	Level   *memory.Level
	// Known limitation: an explicit 0 is silently ignored and the stored
	// importance kept, because resolveImportance uses a `!= 0` sentinel on
	// RememberInput.Importance (a float64, not a pointer). Fixing it means
	// pointer-izing that field across every write path. Do not document an
	// update surface as being able to set importance to 0.
	Importance *float64
	Confidence *float64

	// Tags replaces the stored set wholesale: nil keeps it, a non-nil empty
	// slice clears it. Not a *[]string — nil-vs-empty already carries both
	// meanings, and it is the shape both surfaces decode into natively.
	Tags []string

	// Metadata merges into the stored metadata key-by-key rather than replacing
	// it (RFC 7386 style): nil leaves metadata untouched, and an explicit nil
	// value deletes that key. This is the one place Update deliberately differs
	// from RememberInput.Metadata, which replaces wholesale — see mergeMetadata.
	Metadata map[string]any
}

type WriteDedupAction string