rest

type ActivityEvent struct {
	// Detail Kind-specific context — a recall's degraded mode, a supersession's replacement id.
	Detail *map[string]interface{} `json:"detail,omitempty"`

	// Kind The operation an activity event records. Reads: recall, get, briefing. Writes: remember, update, forget, supersede.
	Kind EventKind `json:"kind"`

	// Memories Empty for a recall that matched nothing.
	Memories *[]ActivityMemory `json:"memories,omitempty"`

	// Namespace The namespace the request was made against.
	Namespace string `json:"namespace"`
	OpId      string `json:"op_id"`

	// Query The recall query; absent for every other kind.
	Query *string   `json:"query,omitempty"`
	Time  time.Time `json:"time"`
}

type ActivityMemory struct {
	Id string `json:"id"`

	// Namespace The memory's own namespace, which for a cascading recall may differ from the event's.
	Namespace string `json:"namespace"`

	// Rank 1-based position the memory was served at; absent when not applicable.
	Rank *int `json:"rank,omitempty"`

	// Score Composite relevance score it was served with; recall only.
	Score *float64 `json:"score,omitempty"`

	// Section Which briefing section it appeared under; briefing only.
	Section *string `json:"section,omitempty"`
	Summary string  `json:"summary"`
	Tier    Tier    `json:"tier"`
}

type ActivityResponse struct {
	Events  []ActivityEvent `json:"events"`
	HasMore bool            `json:"has_more"`

	// NextCursor Pass as "before" to fetch the next page; absent on the last page.
	NextCursor *string `json:"next_cursor,omitempty"`
}

type AnswerQuestionJSONRequestBody = AnswerRequest

type AnswerQuestionParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type AnswerRequest struct {
	Levels *[]Level `json:"levels,omitempty"`

	// Limit Caps how many recalled memories ground the answer.
	Limit *int `json:"limit,omitempty"`

	// Metadata Ground only on memories whose top-level metadata contains every listed key=value pair (AND).
	Metadata *map[string]string `json:"metadata,omitempty"`
	Query    string             `json:"query"`

	// Scope Selects the grounding read-set shape, same vocabulary as the recall `scope`: "full" (default) grounds on the request namespace plus its ancestor/home/link cascade; "project" grounds on the request namespace only (no cascade); "everywhere" is "full" plus the request namespace's subtree. "exact" and "subtree" are deprecated aliases ("exact" → "project", "subtree" → "everywhere"). Any other value is rejected with 400. Reaches parity with the MCP `memory_answer` tool's `scope` argument.
	Scope *AnswerRequestScope `json:"scope,omitempty"`

	// Tags Ground only on memories carrying every listed tag (AND).
	Tags  *[]string `json:"tags,omitempty"`
	Tiers *[]Tier   `json:"tiers,omitempty"`
}

type AnswerRequestScope string

type AnswerResponse struct {
	Answer  string         `json:"answer"`
	Sources []ScoredMemory `json:"sources"`
}

type ApiKey struct {
	// CreatedAt Omitted for a source=file key: MEMINI_API_KEYS_FILE entries carry no creation timestamp (the file is the source of truth, not a database row) — always present for source=db.
	CreatedAt *time.Time `json:"created_at,omitempty"`

	// DefaultNamespace Namespace applied when a request presents this key with no explicit X-Memini-Namespace header.
	DefaultNamespace *string `json:"default_namespace,omitempty"`
	Disabled         bool    `json:"disabled"`

	// Home Bound home namespace; omitted/empty means unbound.
	Home *string `json:"home,omitempty"`
	Name string  `json:"name"`

	// Source Where the key is stored: "db" is a row in the api_keys table (mutable via this API); "file" comes from MEMINI_API_KEYS_FILE, loaded once at boot and immutable through this API — update/rotate/ delete all reject a "file" key with 409.
	Source ApiKeySource `json:"source"`
}

type ApiKeySource string

type ApiKeyWithSecret struct {
	// CreatedAt Omitted for a source=file key: MEMINI_API_KEYS_FILE entries carry no creation timestamp (the file is the source of truth, not a database row) — always present for source=db.
	CreatedAt *time.Time `json:"created_at,omitempty"`

	// DefaultNamespace Namespace applied when a request presents this key with no explicit X-Memini-Namespace header.
	DefaultNamespace *string `json:"default_namespace,omitempty"`
	Disabled         bool    `json:"disabled"`

	// Home Bound home namespace; omitted/empty means unbound.
	Home *string `json:"home,omitempty"`
	Name string  `json:"name"`

	// Secret The plaintext credential, shown exactly once, here — it is never stored (only its SHA-256 hash is) and cannot be recovered or displayed again.
	Secret string `json:"secret"`

	// Source Where the key is stored: "db" is a row in the api_keys table (mutable via this API); "file" comes from MEMINI_API_KEYS_FILE, loaded once at boot and immutable through this API — update/rotate/ delete all reject a "file" key with 409.
	Source ApiKeySource `json:"source"`
}

type ApiKeysResponse struct {
	Keys []ApiKey `json:"keys"`
}

type AuthConfig struct {
	// APIKey, when non-empty, is required as "Authorization: Bearer <key>".
	APIKey string
	// APIKeyStore, when non-nil, enables table-key auth alongside (or instead
	// of) APIKey: a bearer that doesn't match APIKey is looked up by hex
	// SHA-256 hash. nil means the backing store predates APIKeyStore, or the
	// feature is simply unused — see apiauth.Config.Authenticate for the full
	// enforcement rules, including when table auth becomes mandatory.
	APIKeyStore store.APIKeyStore
	// FileKeys, when non-nil, enables the declarative MEMINI_API_KEYS_FILE
	// keys (K2b) alongside APIKey/APIKeyStore: checked after APIKey and
	// before APIKeyStore — see apiauth.Config.Authenticate. nil (the default)
	// means the feature is unused, matching a server built before it existed.
	FileKeys *apiauth.FileKeySet
	// NamespaceHeader names the request header carrying the tenant namespace.
	NamespaceHeader string
	// DefaultNamespace is used when the header is absent and the
	// authenticated key (if any) carries no per-key default either.
	DefaultNamespace string
	// HomeHeader names the request header carrying the caller's personal
	// namespace (see service.RecallInput.Home). Unlike NamespaceHeader there
	// is no default: an absent or empty header means no home leg for the
	// request. Ignored outright for a key bound to a home namespace — see
	// homeMiddleware's doc for the deliberate asymmetry with namespace
	// resolution below.
	HomeHeader string
	// RequestTimeout bounds how long a single /v1 request may run
	// (chi/middleware.Timeout, applied only to the /v1 group Mount attaches —
	// never to /mcp, /healthz, /readyz, or /metrics). It cancels the request
	// context once the timeout elapses; handlers that don't observe
	// ctx.Done() are not forcibly aborted, they just run to completion as
	// before (see chi's Timeout doc comment). 0 disables it.
	RequestTimeout time.Duration

	// KeyAuth, when non-nil, is used verbatim as the auth policy instead of
	// New building one from APIKey/APIKeyStore/FileKeys. Set this to share
	// ONE apiauth.Config (and its cache pointer) with another surface mounted
	// in the same process — e.g. MCP's HTTPHandlerWithAuth — so a cache
	// invalidation from a key mutation here (see apikeys.go's Invalidate
	// calls) reaches that surface immediately instead of leaving it to ride
	// out apiauth's table-emptiness cache TTL. nil (the default) preserves
	// pre-existing behavior for callers that don't share a Config.
	KeyAuth *apiauth.Config
	// contains filtered or unexported fields
}

type Briefing struct {
	// Children Direct-child namespace rollups (one segment deeper than the briefed namespace), each aggregating its whole subtree: all-tier live total plus up to 3 pinned and 3 recent-durable highlight memories. Ordered by most-recent write, capped at 10 children; omitted at a leaf namespace.
	Children *[]BriefingChild `json:"children,omitempty"`

	// Facts Durable semantic facts, highest-retention first.
	Facts     *[]BriefingItem `json:"facts,omitempty"`
	Namespace string          `json:"namespace"`

	// Pinned Pinned memories (any tier).
	Pinned *[]BriefingItem `json:"pinned,omitempty"`

	// Procedures Procedural how-to memories, highest-retention first.
	Procedures *[]BriefingItem `json:"procedures,omitempty"`

	// Recent Recent episodic activity, newest first.
	Recent *[]BriefingItem `json:"recent,omitempty"`

	// ScopeHeader A human-readable one-line summary of which namespaces this briefing drew from (its resolved read-set scope), e.g. "Scope: acme/phoenix/api ← acme/phoenix(3) ← acme(4) ← personal(2), +1 link" — primary first, then each cascade leg that contributed durable memories (nearest ancestor first, home last, counts per leg), then a "+K link(s)" suffix for contributing links.
	ScopeHeader *string `json:"scope_header,omitempty"`
}

type BriefingChild struct {
	Namespace string    `json:"namespace"`
	Pinned    *[]Memory `json:"pinned,omitempty"`
	Recent    *[]Memory `json:"recent,omitempty"`

	// Total Live memory count in this child namespace.
	Total int `json:"total"`
}

type BriefingItem struct {
	// From Read-set provenance beyond memory.namespace — same semantics as ScoredMemory.from (see there). Omitted for a primary-namespace item.
	From   *string `json:"from,omitempty"`
	Memory Memory  `json:"memory"`
}

type ChiServerOptions struct {
	BaseURL          string
	BaseRouter       chi.Router
	Middlewares      []MiddlewareFunc
	ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
}

type ClusterAction struct {
	RepresentativeId string   `json:"representative_id"`
	Size             int      `json:"size"`
	TombstonedIds    []string `json:"tombstoned_ids"`
}

type CreateApiKeyJSONRequestBody = CreateApiKeyRequest

type CreateApiKeyRequest struct {
	// DefaultNamespace Namespace applied when a request presents this key with no explicit namespace header.
	DefaultNamespace *string `json:"default_namespace,omitempty"`

	// Disabled Create the key already disabled.
	Disabled *bool `json:"disabled,omitempty"`

	// Home Bind the key to a home namespace.
	Home *string `json:"home,omitempty"`
	Name string  `json:"name"`
}

type DedupReport struct {
	// Actions Per-cluster representative selection. Omitted when no clusters were found.
	Actions       *[]ClusterAction `json:"actions,omitempty"`
	ClustersFound int              `json:"clusters_found"`
	DryRun        bool             `json:"dry_run"`
	MemoriesSeen  int              `json:"memories_seen"`
	Namespaces    int              `json:"namespaces"`
	Tombstoned    int              `json:"tombstoned"`
}

type DedupRequest struct {
	// AllNamespaces Run the pass over every namespace instead of just the request's
	// namespace. Defaults to false (scope to the request namespace).
	AllNamespaces *bool `json:"all_namespaces,omitempty"`

	// DryRun Report what would happen without tombstoning anything.
	DryRun *bool `json:"dry_run,omitempty"`

	// MinClusterSize Smallest cluster acted on. 0 falls back to 2.
	MinClusterSize *int `json:"min_cluster_size,omitempty"`

	// NeighboursPerAnchor Per-anchor vector-search fan-out. 0 falls back to 20.
	NeighboursPerAnchor *int `json:"neighbours_per_anchor,omitempty"`

	// Similarity Cosine-like threshold for cluster membership. Higher = stricter
	// (fewer, tighter clusters). 0 falls back to 0.85.
	Similarity *float64 `json:"similarity,omitempty"`

	// Tiers Restrict the pass to these tiers; empty means all.
	Tiers *[]Tier `json:"tiers,omitempty"`
}

type DeleteByTagResponse struct {
	// Deleted Number of memories deleted
	Deleted int `json:"deleted"`
}

type DeleteLinkJSONBody struct {
	// Dst Target namespace to unlink.
	Dst *string `json:"dst,omitempty"`
}

type DeleteLinkJSONRequestBody DeleteLinkJSONBody

type DeleteLinkParams struct {
	// Dst Target namespace to unlink. Required, via query or JSON body.
	Dst *string `form:"dst,omitempty" json:"dst,omitempty"`

	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type DeleteNamespaceParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type DeleteNamespaceResponse struct {
	// Deleted Number of memories deleted
	Deleted int `json:"deleted"`
}

type Error struct {
	Error *string `json:"error,omitempty"`
}

type EventKind string

type ForgetByTagParams struct {
	// Tag Exact tag a memory must carry to be deleted.
	Tag string `form:"tag" json:"tag"`

	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type ForgetMemoryParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type FsckReport struct {
	DuplicateGroups  *[][]string `json:"duplicate_groups,omitempty"`
	ExpiredPurged    int         `json:"expired_purged"`
	Namespaces       int         `json:"namespaces"`
	ShortTermEvicted int         `json:"short_term_evicted"`
}

type GetBriefingParams struct {
	// PerSection Default cap applied to every section when its dedicated cap is unset. Default 5.
	PerSection *int `form:"per_section,omitempty" json:"per_section,omitempty"`

	// PerSectionPinned Max pinned memories. Overrides per_section. 0 disables the section.
	PerSectionPinned *int `form:"per_section_pinned,omitempty" json:"per_section_pinned,omitempty"`

	// PerSectionFacts Max durable semantic facts. Overrides per_section. 0 disables the section.
	PerSectionFacts *int `form:"per_section_facts,omitempty" json:"per_section_facts,omitempty"`

	// PerSectionProcedures Max procedural how-to memories. Overrides per_section. 0 disables the section.
	PerSectionProcedures *int `form:"per_section_procedures,omitempty" json:"per_section_procedures,omitempty"`

	// PerSectionRecent Max recent episodic entries. Overrides per_section. 0 disables the section.
	PerSectionRecent *int `form:"per_section_recent,omitempty" json:"per_section_recent,omitempty"`

	// Scope "full" (default) briefs the namespace plus its ancestor/home/link cascade; "project" briefs only the namespace (no cascade); "everywhere" is "full" plus namespaces nested under it ("project" also reads "project/agent"). "exact" and "subtree" are deprecated aliases kept for back-compat: "exact" behaves as "project" (its original, pre-cascade meaning) and "subtree" behaves as "everywhere". Any other value is rejected with 400.
	Scope *GetBriefingParamsScope `form:"scope,omitempty" json:"scope,omitempty"`

	// Namespaces Repeatable. Brief exactly these namespaces instead of the default read set (the namespace, its subtree, and the global namespace). An entry ending in "/*" also includes namespaces nested under it. Writes are unaffected.
	Namespaces *[]string `form:"namespaces,omitempty" json:"namespaces,omitempty"`

	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type GetBriefingParamsScope string

type GetMemoryHistoryParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type GetMemoryParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type GetReadSetParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type GetStatsParams struct {
	// AllNamespaces Aggregate counts across every namespace, ignoring the namespace header. Returns a single merged overview (namespace reported as "") so the admin UI's "All projects" view fetches one response instead of one request per namespace.
	AllNamespaces *bool `form:"all_namespaces,omitempty" json:"all_namespaces,omitempty"`

	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type InvalidParamFormatError struct {
	ParamName string
	Err       error
}

type Level string

type ListActivityParams struct {
	// Kind Repeatable and/or comma-separated event-kind filter; omitted means all kinds.
	Kind *[]EventKind `form:"kind,omitempty" json:"kind,omitempty"`

	// Tier Repeatable and/or comma-separated tier filter. Selects whole operations that touched a memory of a listed tier — a matching event is returned with every memory it served, so its counts stay truthful.
	Tier *[]Tier `form:"tier,omitempty" json:"tier,omitempty"`

	// Q Free-text filter, case-insensitive. Selects whole operations whose recall query or any served memory's summary contains it.
	Q *string `form:"q,omitempty" json:"q,omitempty"`

	// Since Only events recorded at or after this instant.
	Since *time.Time `form:"since,omitempty" json:"since,omitempty"`

	// Namespace With all_namespaces=true, restrict the feed to these namespaces (repeatable, exact match); ignored otherwise.
	Namespace *[]string `form:"namespace,omitempty" json:"namespace,omitempty"`

	// Limit Caps the returned events (operations, not rows). Default 50, max 200.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// Before Opaque cursor from a previous response's next_cursor; returns the page of events strictly older than it.
	Before *string `form:"before,omitempty" json:"before,omitempty"`

	// AllNamespaces Aggregate across every namespace, ignoring the namespace header.
	AllNamespaces *bool `form:"all_namespaces,omitempty" json:"all_namespaces,omitempty"`

	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type ListLinksParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type ListMemoriesParams struct {
	// Tier Repeatable and/or comma-separated tier filter; omitted means all tiers.
	Tier *[]Tier `form:"tier,omitempty" json:"tier,omitempty"`

	// Level Repeatable and/or comma-separated level filter; omitted means all levels.
	Level *[]Level `form:"level,omitempty" json:"level,omitempty"`

	// Tag Repeatable and/or comma-separated tag filter; a memory must carry every listed tag (AND).
	Tag *[]string `form:"tag,omitempty" json:"tag,omitempty"`

	// Meta Repeatable metadata filter in "key=value" form; a memory's top-level metadata must contain every listed pair (AND). Only string values match.
	Meta              *[]string `form:"meta,omitempty" json:"meta,omitempty"`
	IncludeExpired    *bool     `form:"include_expired,omitempty" json:"include_expired,omitempty"`
	IncludeSuperseded *bool     `form:"include_superseded,omitempty" json:"include_superseded,omitempty"`

	// Limit Caps the result count; 0 or absent returns all matches.
	Limit *int `form:"limit,omitempty" json:"limit,omitempty"`

	// AllNamespaces Aggregate across every namespace, ignoring the namespace header. The server merges all namespaces and applies limit as a single global cap under the requested sort, so the admin UI's "All projects" view fetches one response instead of one request per namespace.
	AllNamespaces *bool `form:"all_namespaces,omitempty" json:"all_namespaces,omitempty"`

	// Namespace With all_namespaces=true, restrict the aggregate to these namespaces (repeatable, exact match); ignored otherwise. Lets the browser narrow an "All projects" listing without changing the active namespace.
	Namespace *[]string `form:"namespace,omitempty" json:"namespace,omitempty"`

	// MemoryType Repeatable and/or comma-separated metadata.memory_type filter; a memory matches if its type is ANY of the listed values (OR). Distinct from "meta", which ANDs one value per key.
	MemoryType *[]string `form:"memory_type,omitempty" json:"memory_type,omitempty"`

	// CreatedAfter Only memories created at or after this instant.
	CreatedAfter *time.Time `form:"created_after,omitempty" json:"created_after,omitempty"`

	// AccessedAfter Only memories last accessed at or after this instant.
	AccessedAfter *time.Time `form:"accessed_after,omitempty" json:"accessed_after,omitempty"`

	// Sort Column to order by. Defaults to created_at.
	Sort *ListMemoriesParamsSort `form:"sort,omitempty" json:"sort,omitempty"`

	// Order Sort direction. Defaults to desc (newest / highest first).
	Order *ListMemoriesParamsOrder `form:"order,omitempty" json:"order,omitempty"`

	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type ListMemoriesParamsOrder string

type ListMemoriesParamsSort string

type ListResponse struct {
	Memories []Memory `json:"memories"`
}

type Memory struct {
	AccessCount int `json:"access_count"`

	// AutoSuperseded Optional. Present only on POST /v1/memories responses when the write's nearest same-tier candidate scored at/above MEMINI_WRITE_DEDUP_SCORE with MEMINI_WRITE_DEDUP_ACTION="supersede" and the old memory was tombstoned in the background. The caller still receives the new memory.
	AutoSuperseded *bool `json:"auto_superseded,omitempty"`

	// Confidence Corroboration of a durable fact in [0,1]; null when not tracked.
	Confidence     *float64   `json:"confidence,omitempty"`
	Content        string     `json:"content"`
	CreatedAt      time.Time  `json:"created_at"`
	ExpiresAt      *time.Time `json:"expires_at,omitempty"`
	Id             string     `json:"id"`
	Importance     float64    `json:"importance"`
	LastAccessedAt time.Time  `json:"last_accessed_at"`

	// Level Derivation provenance: explicit (user-stated / heuristic) vs deduced (LLM-distilled). Null/omitted when the row predates the tag or when unset.
	Level *Level `json:"level,omitempty"`

	// MergeHint Optional. Returned on POST /v1/memories when the write's nearest same-tier candidate scored at/above MEMINI_WRITE_DEDUP_SCORE and MEMINI_WRITE_DEDUP_ACTION is "hint". The caller can decide whether to merge into the near-duplicate via memory_update.
	MergeHint *MergeHint              `json:"merge_hint,omitempty"`
	Metadata  *map[string]interface{} `json:"metadata,omitempty"`
	Namespace string                  `json:"namespace"`

	// Reinforced Optional. Present only on POST /v1/memories responses when the fact was already known and NO new memory was created: the existing memory was strengthened (reinforced and corroborated) and is what this response returns. Two paths reach it — the exact-restatement fingerprint fast path, and MEMINI_WRITE_DEDUP_ACTION="coalesce" when the incoming phrasing is not richer than the stored one. Without this flag a 201 would read as "created", which is exactly what did not happen, and the id would appear to belong to a memory the caller wrote when it does not.
	Reinforced   *bool     `json:"reinforced,omitempty"`
	Summary      *string   `json:"summary,omitempty"`
	SupersededBy *string   `json:"superseded_by,omitempty"`
	Tags         *[]string `json:"tags,omitempty"`
	Tier         Tier      `json:"tier"`
	UpdatedAt    time.Time `json:"updated_at"`

	// ValidFrom Start of the wall-clock interval the fact was true; null means open ("always, until valid_to"). Used by time-travel (as_of) recall.
	ValidFrom *time.Time `json:"valid_from,omitempty"`

	// ValidTo End of the interval the fact was true; null means open ("still true"). Stamped automatically when a fact is superseded.
	ValidTo *time.Time `json:"valid_to,omitempty"`
}

type MergeHint struct {
	// Score Fused similarity between the new write and the near-duplicate (0..1).
	Score *float64 `json:"score,omitempty"`

	// SimilarContent Preview (≤200 chars) of the near-duplicate memory's content.
	SimilarContent *string `json:"similar_content,omitempty"`

	// SimilarId ID of the near-duplicate memory.
	SimilarId *string `json:"similar_id,omitempty"`
	Tier      *Tier   `json:"tier,omitempty"`
}

type MiddlewareFunc func(http.Handler) http.Handler

type MoveNamespaceJSONBody struct {
	DryRun *bool `json:"dry_run,omitempty"`

	// To Target namespace.
	To string `json:"to"`
}

type MoveNamespaceJSONRequestBody MoveNamespaceJSONBody

type MoveNamespaceParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type Namespace = string

type NamespaceLink struct {
	CreatedAt time.Time `json:"created_at"`
	Dst       string    `json:"dst"`
	Note      *string   `json:"note,omitempty"`
	Src       string    `json:"src"`

	// Tiers Tier restriction on the link; empty/omitted means the durable default (semantic, procedural).
	Tiers *[]Tier `json:"tiers,omitempty"`
}

type NamespaceLinksResponse struct {
	Links []NamespaceLink `json:"links"`
}

type NamespacesResponse struct {
	Namespaces []string `json:"namespaces"`
}

type PutLinkJSONBody struct {
	// Dst Target namespace.
	Dst string `json:"dst"`

	// Note Free-text annotation for operators.
	Note *string `json:"note,omitempty"`

	// Tiers Restrict which tiers cross the link; empty/omitted means the durable default (semantic, procedural) — non-durable tiers never cross a link regardless.
	Tiers *[]Tier `json:"tiers,omitempty"`
}

type PutLinkJSONRequestBody PutLinkJSONBody

type PutLinkParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type ReadSetEntryItem struct {
	Namespace string `json:"namespace"`

	// Origin Why a namespace is in the read-set: "primary" is the request namespace (and its subtree, when expanded), "ancestor" is a path-prefix cascade leg, "home" is the caller's personal namespace, "link" is a stored namespace link, and "call" is an explicit per-call namespace.
	Origin ReadSetOrigin `json:"origin"`

	// Tiers Tier restriction applied to this namespace; omitted means the request's own tier filter, unrestricted beyond that.
	Tiers *[]Tier `json:"tiers,omitempty"`
}

type ReadSetOrigin string

type ReadSetResponse struct {
	Entries []ReadSetEntryItem `json:"entries"`
}

type ReassignMemoryJSONBody struct {
	// To Target namespace.
	To string `json:"to"`
}

type ReassignMemoryJSONRequestBody ReassignMemoryJSONBody

type ReassignMemoryParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type RememberMemoryJSONRequestBody = RememberRequest

type RememberMemoryParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type RememberRequest struct {
	// Confidence Seed corroboration for a durable fact (e.g. a trusted import). Omit to use the default seed; ignored for short-term tiers.
	Confidence *float64 `json:"confidence,omitempty"`
	Content    string   `json:"content"`

	// Id Upserts an existing memory when provided.
	Id         *string  `json:"id,omitempty"`
	Importance *float64 `json:"importance,omitempty"`

	// Level Label the derivation provenance (explicit vs deduced) at write time. Omit to leave unset (default, legacy rows, auto-tagged by service).
	Level    *Level                  `json:"level,omitempty"`
	Metadata *map[string]interface{} `json:"metadata,omitempty"`
	Summary  *string                 `json:"summary,omitempty"`
	Tags     *[]string               `json:"tags,omitempty"`

	// Tier Omit to let the server choose: the content is classified by the marker heuristic (a terse, unhedged decision/preference/problem lands in semantic/procedural, stamped metadata.tier_classified=marker), falling back to working. Classification never picks working (the default) — it only raises to semantic/procedural.
	Tier *Tier `json:"tier,omitempty"`

	// TtlSeconds Overrides the tier default TTL; negative means never expire.
	TtlSeconds *int `json:"ttl_seconds,omitempty"`

	// ValidFrom Start of the interval the fact was true. Defaults to now; backdate it to record a historical fact so time-travel (as_of) recall surfaces it.
	ValidFrom *time.Time `json:"valid_from,omitempty"`

	// ValidTo End of the interval the fact was true (for recording a fact that was true only in the past). Omit for a fact that is still true.
	ValidTo *time.Time `json:"valid_to,omitempty"`

	// Visibility Write-side namespace scoping. Omit or "project" (default) writes to the request namespace itself. "personal" writes to the caller's home namespace (X-Memini-Home header / MEMINI_HOME on the client) instead — an error if no home namespace is configured. Any other value must name an ancestor of the request namespace, either its full path or an unambiguous last path segment (e.g. "acme" for request namespace "acme/phoenix/api"), and the write lands there instead. Ignored for non-durable writes: an episodic/working memory always stays in the request namespace regardless of visibility.
	Visibility *string `json:"visibility,omitempty"`
}

type RenamespaceReport struct {
	// DryRun Whether this was a dry run.
	DryRun *bool `json:"dry_run,omitempty"`

	// Moved Number of memories moved.
	Moved *int `json:"moved,omitempty"`

	// Skipped Memories left in place (no grouping key, or already in place).
	Skipped *int `json:"skipped,omitempty"`

	// Targets Memories moved into each destination namespace.
	Targets *map[string]int `json:"targets,omitempty"`
}

type RequiredHeaderError struct {
	ParamName string
	Err       error
}

type RequiredParamError struct {
	ParamName string
}

type RunDedupJSONRequestBody = DedupRequest

type RunDedupParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type RunFsckParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type ScoredMemory struct {
	// From Read-set provenance beyond memory.namespace: omitted for a hit from the request (primary) namespace — the common case, no annotation needed — the ancestor/home namespace name itself for those two origins ("acme", "personal/kit"), and a prefixed form for a stored link or an explicit per-call namespace ("link:shared/golang", "call:acme/other"). Only populated when the read drew from a resolved read-set (recall/answer); omitted otherwise.
	From   *string `json:"from,omitempty"`
	Memory Memory  `json:"memory"`
	Score  float64 `json:"score"`
}

type SearchMemoriesJSONRequestBody = SearchRequest

type SearchMemoriesParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type SearchRequest struct {
	// AsOf Time-travel recall: return facts whose validity window contained this instant (including ones since superseded), for "what was true then" queries.
	AsOf *time.Time `json:"as_of,omitempty"`

	// ExcludeMetadata Drop memories whose top-level metadata carries any of these key=value pairs (the inverse of metadata). Lets a caller keep its own just-written memories out of recall — e.g. excluding the current session's captured turns so they are not echoed back as memory.
	ExcludeMetadata *map[string]string `json:"exclude_metadata,omitempty"`
	IncludeExpired  *bool              `json:"include_expired,omitempty"`

	// IncludeFreshTurns When true, disable the server-side temporal echo guard for this call: just-captured episodic turn captures (metadata.format="turn" younger than the server's window, default 5m) are NOT dropped. Default (false) drops them — a just-captured turn is live context, not long-term memory, and echoing it back makes the agent parrot itself. Opt in only when you genuinely need fresh turns.
	IncludeFreshTurns *bool    `json:"include_fresh_turns,omitempty"`
	IncludeSuperseded *bool    `json:"include_superseded,omitempty"`
	Levels            *[]Level `json:"levels,omitempty"`
	Limit             *int     `json:"limit,omitempty"`

	// Metadata A memory's top-level metadata must contain every listed key=value pair (AND).
	Metadata *map[string]string `json:"metadata,omitempty"`

	// MinScore Per-call relevance floor on the fused score. Candidates below it are dropped server-side before re-ranking. 0 (or unset) falls back to the server's baked relevance floor (0.1). Only meaningful with score fusion (RRF scores are not comparable to this threshold).
	MinScore *float64 `json:"min_score,omitempty"`

	// Namespaces Search exactly these namespaces instead of the default read set (the request namespace, its subtree, and the global namespace). An entry ending in "/*" also includes namespaces nested under it. Writes are unaffected.
	Namespaces *[]string `json:"namespaces,omitempty"`
	Query      string    `json:"query"`

	// QueryRewrite When true and an LLM is configured, rewrite the query into 2-3 diverse variants before recall and fuse results via RRF. Cheapest read-path LLM lever; opt-in per call.
	QueryRewrite *bool `json:"query_rewrite,omitempty"`

	// Scope "full" (default) searches the request namespace plus its ancestor/home/link cascade; "project" searches only the request namespace (no cascade); "everywhere" is "full" plus the request namespace's subtree, for the multi-agent read-shared-plus-private pattern. "exact" and "subtree" are deprecated aliases kept for back-compat: "exact" behaves as "project" (its original, pre-cascade meaning — the request namespace only) and "subtree" behaves as "everywhere". Any other value is rejected with 400.
	Scope *SearchRequestScope `json:"scope,omitempty"`

	// Tags A memory must carry every listed tag (AND).
	Tags  *[]string `json:"tags,omitempty"`
	Tiers *[]Tier   `json:"tiers,omitempty"`
}

type SearchRequestScope string

type SearchResponse struct {
	// Degraded Set to "keyword_only" when the query embed failed or timed out and this search fell back to keyword-only matching; omitted on a healthy (vector+keyword) search.
	Degraded *string `json:"degraded,omitempty"`

	// Note Human-readable explanation of `degraded`; omitted alongside it on a healthy search.
	Note    *string        `json:"note,omitempty"`
	Results []ScoredMemory `json:"results"`
}

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

type ServerInterface interface {
	// Recent memory activity — what was served or written, and why
	// (GET /v1/activity)
	ListActivity(w http.ResponseWriter, r *http.Request, params ListActivityParams)
	// Recall memories and answer a question grounded on them (requires an LLM)
	// (POST /v1/answer)
	AnswerQuestion(w http.ResponseWriter, r *http.Request, params AnswerQuestionParams)
	// Collapse near-duplicate memories (vector cluster) — tombstone the lower-scored members of each cluster
	// (POST /v1/dedup)
	RunDedup(w http.ResponseWriter, r *http.Request, params RunDedupParams)
	// Run a consistency sweep (purge expired, enforce short-term cap, audit duplicates)
	// (POST /v1/fsck)
	RunFsck(w http.ResponseWriter, r *http.Request, params RunFsckParams)
	// List API keys (name/home/default namespace/created/disabled/source — never a secret or hash)
	// (GET /v1/keys)
	ListApiKeys(w http.ResponseWriter, r *http.Request)
	// Create a new API key, returning its secret exactly once
	// (POST /v1/keys)
	CreateApiKey(w http.ResponseWriter, r *http.Request)
	// Delete an API key
	// (DELETE /v1/keys/{name})
	DeleteApiKey(w http.ResponseWriter, r *http.Request, name string)
	// Update an API key's home namespace, default namespace, and/or disabled state
	// (PATCH /v1/keys/{name})
	UpdateApiKey(w http.ResponseWriter, r *http.Request, name string)
	// Rotate an API key's secret, returning the new secret exactly once
	// (POST /v1/keys/{name}/rotate)
	RotateApiKey(w http.ResponseWriter, r *http.Request, name string)
	// Delete a namespace link
	// (DELETE /v1/links)
	DeleteLink(w http.ResponseWriter, r *http.Request, params DeleteLinkParams)
	// List outgoing namespace links from the request namespace
	// (GET /v1/links)
	ListLinks(w http.ResponseWriter, r *http.Request, params ListLinksParams)
	// Create or replace a namespace link (cross-namespace read edge)
	// (POST /v1/links)
	PutLink(w http.ResponseWriter, r *http.Request, params PutLinkParams)
	// Delete every memory in the namespace carrying a tag
	// (DELETE /v1/memories)
	ForgetByTag(w http.ResponseWriter, r *http.Request, params ForgetByTagParams)
	// List memories in a namespace (backs the admin UI browser)
	// (GET /v1/memories)
	ListMemories(w http.ResponseWriter, r *http.Request, params ListMemoriesParams)
	// Remember (store) a memory
	// (POST /v1/memories)
	RememberMemory(w http.ResponseWriter, r *http.Request, params RememberMemoryParams)
	// Forget (delete) a memory
	// (DELETE /v1/memories/{id})
	ForgetMemory(w http.ResponseWriter, r *http.Request, id string, params ForgetMemoryParams)
	// Fetch a memory by ID
	// (GET /v1/memories/{id})
	GetMemory(w http.ResponseWriter, r *http.Request, id string, params GetMemoryParams)
	// The full version chain (supersession lineage) of a memory
	// (GET /v1/memories/{id}/history)
	GetMemoryHistory(w http.ResponseWriter, r *http.Request, id string, params GetMemoryHistoryParams)
	// Move a single memory to a different namespace
	// (POST /v1/memories/{id}/reassign)
	ReassignMemory(w http.ResponseWriter, r *http.Request, id string, params ReassignMemoryParams)
	// Tombstone a memory, recording it was replaced by `by`.
	// (POST /v1/memories/{id}/supersede)
	SupersedeMemory(w http.ResponseWriter, r *http.Request, id string, params SupersedeMemoryParams)
	// Delete every memory in the request namespace
	// (DELETE /v1/namespaces)
	DeleteNamespace(w http.ResponseWriter, r *http.Request, params DeleteNamespaceParams)
	// List the distinct namespaces holding memories
	// (GET /v1/namespaces)
	ListNamespaces(w http.ResponseWriter, r *http.Request)
	// Layered session-start briefing for the request namespace
	// (GET /v1/namespaces/briefing)
	GetBriefing(w http.ResponseWriter, r *http.Request, params GetBriefingParams)
	// Relocate every memory in the request namespace to another namespace
	// (POST /v1/namespaces/move)
	MoveNamespace(w http.ResponseWriter, r *http.Request, params MoveNamespaceParams)
	// Resolve the structural read-set for the request namespace
	// (GET /v1/namespaces/read-set)
	GetReadSet(w http.ResponseWriter, r *http.Request, params GetReadSetParams)
	// Split the request namespace by metadata keys
	// (POST /v1/namespaces/split)
	SplitNamespace(w http.ResponseWriter, r *http.Request, params SplitNamespaceParams)
	// Recall memories via hybrid (vector + keyword) search
	// (POST /v1/search)
	SearchMemories(w http.ResponseWriter, r *http.Request, params SearchMemoriesParams)
	// Per-namespace overview (counts by tier, accesses, importance)
	// (GET /v1/stats)
	GetStats(w http.ResponseWriter, r *http.Request, params GetStatsParams)
}

type ServerInterfaceWrapper struct {
	Handler            ServerInterface
	HandlerMiddlewares []MiddlewareFunc
	ErrorHandlerFunc   func(w http.ResponseWriter, r *http.Request, err error)
}

type SplitNamespaceJSONBody struct {
	// By Metadata keys to group by. Defaults to import_source_namespace, user_id, agent_id, run_id, project.
	By     *[]string `json:"by,omitempty"`
	DryRun *bool     `json:"dry_run,omitempty"`
}

type SplitNamespaceJSONRequestBody SplitNamespaceJSONBody

type SplitNamespaceParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type Stats struct {
	AvgImportance float64 `json:"avg_importance"`

	// ByMemoryType Live count per typed-extraction memory_type (decision/preference/problem).
	ByMemoryType *map[string]int `json:"by_memory_type,omitempty"`
	ByTier       map[string]int  `json:"by_tier"`
	Expired      int             `json:"expired"`
	LastWriteAt  *time.Time      `json:"last_write_at,omitempty"`

	// LowConfidenceDurable Live durable memories whose decayed confidence is below the demote floor — reclaimable, uncorroborated debris.
	LowConfidenceDurable int    `json:"low_confidence_durable"`
	Namespace            string `json:"namespace"`
	Superseded           int    `json:"superseded"`

	// Total Live memories (excludes expired/superseded)
	Total         int `json:"total"`
	TotalAccesses int `json:"total_accesses"`
}

type SupersedeMemoryJSONRequestBody = SupersedeRequest

type SupersedeMemoryParams struct {
	// XMeminiNamespace Tenant/agent namespace; falls back to the server default.
	XMeminiNamespace *Namespace `json:"X-Memini-Namespace,omitempty"`
}

type SupersedeRequest struct {
	// By ID of the memory that replaces the target.
	By string `json:"by"`
}

type Tier string

type TooManyValuesForParamError struct {
	ParamName string
	Count     int
}

type UnescapedCookieParamError struct {
	ParamName string
	Err       error
}

type Unimplemented struct{}

type UnmarshalingParamError struct {
	ParamName string
	Err       error
}

type UpdateApiKeyJSONRequestBody = UpdateApiKeyRequest

type UpdateApiKeyRequest struct {
	// DefaultNamespace Omit to leave the current default unchanged; an explicit empty string clears it.
	DefaultNamespace *string `json:"default_namespace,omitempty"`

	// Disabled Omit to leave the current disabled state unchanged.
	Disabled *bool `json:"disabled,omitempty"`

	// Home Omit to leave the current binding unchanged; an explicit empty string clears it.
	Home *string `json:"home,omitempty"`
}