mem-os-python 1.6.27__py3-none-any.whl

memos/_js/types.d.ts

@@ -0,0 +1,2474 @@
+/**
+ * MemOS — Universal memory layer for AI agents.
+ *
+ * Core type definitions. Every interface and type in the system
+ * is defined here to provide a single source of truth for the
+ * data model across modules.
+ *
+ * @module @memos/types
+ */
+import type { CompressionLevel } from "./compression.js";
+import type { ImportanceConfig } from "./importance.js";
+/**
+ * Semantic category for a memory node.
+ *
+ * - `fact`          — A discrete piece of information.
+ * - `preference`    — A user or agent preference.
+ * - `context`       — Conversational or situational context.
+ * - `relationship`  — An observed relationship between entities.
+ * - `entity`        — A named entity (person, place, thing).
+ * - `custom`        — Application-defined type.
+ */
+export type MemoryType = "fact" | "preference" | "context" | "relationship" | "entity" | "custom";
+/**
+ * Provenance source for a memory node.
+ *
+ * - `user_input`     — Stated directly by the user. Highest trust.
+ * - `agent_inferred` — Inferred by an agent from context.
+ * - `tool_output`    — Returned by a tool call (treated as untrusted
+ *   for agent consumption — see the provenance-trust layer).
+ * - `external_data`  — Imported from an external source.
+ * - `system`         — Generated by the system itself.
+ */
+export type MemorySource = "user_input" | "agent_inferred" | "tool_output" | "external_data" | "system";
+/**
+ * Default trust score for each provenance source.
+ */
+export declare const DEFAULT_TRUST_SCORES: Record<MemorySource, number>;
+/**
+ * Provenance tier — the trust channel a memory arrived through, assigned
+ * at write time and stored as a column. Ordered highest-trust first:
+ *
+ * - `user-verified` — explicitly confirmed by the user. Never assigned
+ *   automatically — only via an explicit `provenance` option or
+ *   `verify()`.
+ * - `user`          — ordinary user statements (default for
+ *   `source: "user_input"` writes).
+ * - `tool-output`   — results returned by tools (`source: "tool_output"`).
+ * - `chat`          — model-generated content (`source: "agent_inferred"`
+ *   or `"system"`).
+ * - `imported`      — bulk imports (`source: "external_data"`).
+ *
+ * See `src/provenance.ts` for the default rule, trust multipliers, and
+ * the read-time trust policy.
+ */
+export type ProvenanceTier = "user-verified" | "user" | "tool-output" | "chat" | "imported";
+/**
+ * A single unit of memory stored in the graph.
+ */
+/**
+ * Which retrieval pool a memory belongs to — the multi-granularity
+ * structure from the LongMemEval-V2 design lessons:
+ * - `event`      — raw statements as they were captured (the default; every
+ *                  legacy memory reads as `event`).
+ * - `note`       — distilled summaries produced by consolidation
+ *                  (`summarizeCluster` writes here).
+ * - `procedure`  — workflow/procedural knowledge ("how to" steps).
+ * - `visual`     — image memories (the node is `type: "fact"` with
+ *                  `metadata.image` present); multi-stream packs search
+ *                  this as a dedicated stream.
+ * Pools are queryable via `SearchFilter.pool` and searched as separate
+ * streams by multi-stream context packs.
+ */
+export type MemoryPool = "event" | "note" | "procedure" | "visual";
+/**
+ * Typed multi-scope keys for isolating memories per user, agent, and run.
+ * Composed into the underlying namespace string in fixed order
+ * (`u:alice/a:coder/r:r1`) — see `src/scope.ts`. Hierarchical by default:
+ * querying `{ user: "alice" }` surfaces every memory Alice's agents and
+ * runs stored.
+ */
+export interface MemoryScope {
+    /** Owner of the memories (e.g. end-user id). */
+    user?: string;
+    /** Which agent produced them. */
+    agent?: string;
+    /** Which session/run produced them. */
+    run?: string;
+}
+export interface MemoryNode {
+    /** Globally unique identifier (UUID v4). */
+    id: string;
+    /** Raw text content of the memory. */
+    content: string;
+    /** Extractive summary (auto-generated if not supplied). */
+    summary: string;
+    /** Semantic type of this memory. */
+    type: MemoryType;
+    /** Arbitrary metadata bag. Must be JSON-serialisable. */
+    metadata: Record<string, unknown>;
+    /**
+     * Base importance score in [0, 1]. Set at write time (default 0.5) or
+     * manually via `update`. Lifecycle decisions (eviction, archival)
+     * derive an *effective* importance from this base plus recency decay
+     * and access reinforcement — see `computeEffectiveImportance` in
+     * `src/importance.ts`.
+     */
+    importance: number;
+    /** Creation timestamp (Unix ms). */
+    createdAt: number;
+    /** Last-modified timestamp (Unix ms). */
+    updatedAt: number;
+    /** Number of times this node has been retrieved. */
+    accessCount: number;
+    /** Timestamp of last access (Unix ms). */
+    lastAccessed: number;
+    /** Custom tags for categorisation. */
+    tags: string[];
+    /** TTL expiration as Unix timestamp (seconds). null = no expiration. */
+    expiresAt: number | null;
+    /** Namespace for grouping memories (experimental). */
+    namespace: string;
+    /**
+     * Temporal validity start (Unix ms). When set, the memory is
+     * considered "active" from this point in time. null = always valid.
+     */
+    validFrom: number | null;
+    /**
+     * Temporal validity end (Unix ms). When set, the memory becomes
+     * "historical" (excluded from default search) after this time.
+     * null = no expiry. Superseded memories keep their validTo so the
+     * history is queryable via `searchTemporal`.
+     */
+    validTo: number | null;
+    /**
+     * Where this memory originated. Used for provenance and trust
+     * scoring.
+     * - `user_input`     — Stated directly by the user. Highest trust.
+     * - `agent_inferred` — Inferred by an agent from context. Lower trust.
+     * - `external_data`  — Imported from an external source (API, file, etc.).
+     * - `system`         — Generated by the system itself.
+     */
+    source: MemorySource;
+    /**
+     * Provenance tier — the trust channel this memory arrived through
+     * (`user-verified` > `user` > `tool-output` > `chat` > `imported`).
+     * Assigned at write time from `CreateMemoryInput.provenance` or the
+     * source-derived default (see `resolveProvenance` in
+     * `src/provenance.ts`); backfilled as `"user"` for legacy rows.
+     */
+    provenance: ProvenanceTier;
+    /**
+     * Write-gate quarantine flag. When the local-heuristic classifier
+     * (`screenWrite` in `src/quarantine.ts`) flags instruction-like
+     * content, the memory is still stored (add-only) but quarantined:
+     * excluded from recall by default until reviewed via
+     * `memos quarantine list|release`.
+     */
+    quarantined: boolean;
+    /** Unix ms when the memory was quarantined. null when never. */
+    quarantinedAt: number | null;
+    /** `;`-joined quarantine signal codes. null when never quarantined. */
+    quarantineReason: string | null;
+    /**
+     * Retrieval pool this memory belongs to (multi-granularity retrieval).
+     * Optional for backward compatibility with custom storage adapters;
+     * treated as `"event"` when absent.
+     */
+    pool?: MemoryPool;
+    /**
+     * Harness that wrote this memory (`"claude-code"`, `"cline"`,
+     * `"codex"`, `"gemini-cli"`, `"openclaw"`, or `"unknown"`). Stamped
+     * at write time by `store()` via `detectHarness()`; optional for
+     * backward compatibility with node literals and custom storage
+     * adapters — reads as `"unknown"` when absent. Legacy rows are
+     * backfilled as `"unknown"` by the schema migration.
+     */
+    harness?: string;
+    /**
+     * Trust score in [0, 1]. Influences retrieval ranking. Starts at
+     * 1.0 for `user_input`, 0.7 for `agent_inferred`, 0.5 for
+     * `external_data`, 0.3 for `system`. Can be manually adjusted via
+     * `memos.setTrust()`.
+     */
+    trustScore: number;
+    /**
+     * Dynamic confidence score in [0, 1]. Reflects how sure the system
+     * is that this memory is still true, given new observations.
+     * - Reinforced when new observations agree (confidence goes up)
+     * - Revised when new observations partially conflict (confidence goes down)
+     * - Superseded when new facts clearly replace old ones (marked historical)
+     * Stored in metadata as `confidence` and `evidenceCount`.
+     */
+    confidence?: number;
+    /** Number of evidence events (reinforces + revisions) that touched this memory. */
+    evidenceCount?: number;
+}
+/**
+ * Partial input accepted when creating a new memory.
+ * Only `content` is required; everything else has defaults.
+ */
+export interface CreateMemoryInput {
+    content: string;
+    type?: MemoryType;
+    metadata?: Record<string, unknown>;
+    summary?: string;
+    importance?: number;
+    /** TTL in seconds from now. */
+    ttl?: number;
+    /** Custom tags. */
+    tags?: string[];
+    /** Namespace (experimental). */
+    namespace?: string;
+    /**
+     * Typed multi-scope isolation. Composed into the namespace string
+     * (fixed order user → agent → run); takes precedence over `namespace`
+     * when both are supplied.
+     */
+    scope?: MemoryScope;
+    /** Temporal validity start (Unix ms). null = always valid. */
+    validFrom?: number | null;
+    /** Temporal validity end (Unix ms). null = no expiry. */
+    validTo?: number | null;
+    /** Provenance source. Default: `user_input`. */
+    source?: MemorySource;
+    /**
+     * Provenance tier override (`user-verified` > `user` > `tool-output` >
+     * `chat` > `imported`). When omitted, the tier is derived from
+     * `source` via the default rule (see `resolveProvenance` in
+     * `src/provenance.ts`): `user_input` → `user`, `tool_output` →
+     * `tool-output`, `agent_inferred`/`system` → `chat`, `external_data` →
+     * `imported`. `user-verified` is never assigned automatically.
+     */
+    provenance?: ProvenanceTier;
+    /**
+     * Write-gate screening: when true (default), the local-heuristic
+     * classifier (`screenWrite`) runs on `content` and flags
+     * instruction-like payloads by storing them quarantined (excluded
+     * from recall until reviewed). Set to false to bypass screening for
+     * trusted bulk operations. No LLM is ever consulted on this path.
+     */
+    quarantineScreen?: boolean;
+    /**
+     * Retrieval pool for this memory. Default: `"event"`. Use `"procedure"`
+     * for workflow/how-to knowledge — multi-stream context packs search
+     * procedures with a dedicated query stream.
+     */
+    pool?: MemoryPool;
+    /**
+     * One line of write-time context describing the situation this memory
+     * was captured in (e.g. "stated while debugging the deploy pipeline").
+     * Stored in `metadata.context`, prepended to the embedded text, and
+     * included in context packs. When absent, the optional
+     * `MemOSConfig.enrichMemory` hook is consulted.
+     */
+    context?: string;
+    /** Trust score [0, 1]. Overrides the default for the chosen source. */
+    trustScore?: number;
+    /**
+     * Harness attribution override (e.g. `"claude-code"`, `"cline"`).
+     * When omitted, `store()` stamps the harness detected from the
+     * environment via `detectHarness()` (see `src/harness.ts`).
+     */
+    harness?: string;
+    /**
+     * Dynamic confidence score [0, 1] for the confidence state machine.
+     * Used to track how sure the system is that this memory is still true.
+     * If omitted, defaults to INITIAL_CONFIDENCE (0.5).
+     */
+    confidence?: number;
+    /**
+     * Evidence count for the confidence state machine.
+     * Number of reinforce/revise events this memory has accumulated.
+     * If omitted, defaults to 0 for manually stored items.
+     */
+    evidenceCount?: number;
+    /**
+     * When true, apply the Hermes-style retain pre-filter (v1.6.26) before
+     * writing: low-signal content (acknowledgements, chit-chat, near-empty
+     * text) is skipped so long-term memory isn't flooded with noise that would
+     * later bloat context-packs. Default: false (write always).
+     */
+    filterRetain?: boolean;
+    /**
+     * When true, run the evidence state machine before writing:
+     * content that confirms an existing memory reinforces it (confidence ↑)
+     * instead of writing a duplicate node, and content that contradicts it
+     * supersedes the old version. Default: false — store() appends a new
+     * node every time (use dedupe()/consolidate() for explicit merging).
+     */
+    evidenceLearning?: boolean;
+    /**
+     * Reference time (Unix ms) for this write. Overrides `Date.now()` as
+     * the write timestamp AND as the reference time for deterministic
+     * temporal parsing (event extraction / update resolution). Primarily
+     * a testing hook — omit in production so the wall clock is used.
+     */
+    now?: number;
+}
+/**
+ * Partial update for an existing memory node.
+ */
+export interface UpdateMemoryInput {
+    content?: string;
+    summary?: string;
+    type?: MemoryType;
+    metadata?: Record<string, unknown>;
+    importance?: number;
+    tags?: string[];
+    namespace?: string;
+    /** Access count for Ebbinghaus reinforcement. */
+    accessCount?: number;
+    /** Last access time (Unix ms) for Ebbinghaus reinforcement. */
+    lastAccessed?: number;
+    /** Temporal validity start (Unix ms). */
+    validFrom?: number | null;
+    /** Temporal validity end (Unix ms). */
+    validTo?: number | null;
+    /** Provenance source. */
+    source?: MemorySource;
+    /** Provenance tier override (see `CreateMemoryInput.provenance`). */
+    provenance?: ProvenanceTier;
+    /**
+     * Quarantine flag. Set explicitly by `releaseFromQuarantine` (false)
+     * or administrative quarantine (true); the write gate sets it via
+     * `store()`, not via `update()`.
+     */
+    quarantined?: boolean;
+    /** Unix ms when the memory was quarantined. null clears it. */
+    quarantinedAt?: number | null;
+    /** `;`-joined quarantine signal codes. null clears it. */
+    quarantineReason?: string | null;
+    /** Trust score [0, 1]. */
+    trustScore?: number;
+    /** Dynamic confidence [0, 1] — updated by the evidence state machine. */
+    confidence?: number;
+    /** Evidence count — updated by the evidence state machine. */
+    evidenceCount?: number;
+}
+/**
+ * Semantic relation between two memory nodes.
+ *
+ * - `relates_to`     — General association.
+ * - `contradicts`    — The target contradicts the source.
+ * - `supports`       — The target supports the source.
+ * - `derived_from`   — The source was derived from the target.
+ * - `part_of`        — The source is a part of the target.
+ * - `custom`         — Application-defined relation.
+ */
+export type EdgeRelation = "relates_to" | "contradicts" | "supports" | "derived_from" | "part_of" | "temporal_precedes" | "custom";
+/**
+ * A directed, weighted edge connecting two memory nodes.
+ */
+export interface MemoryEdge {
+    /** Globally unique identifier (UUID v4). */
+    id: string;
+    /** Source node ID. */
+    sourceId: string;
+    /** Target node ID. */
+    targetId: string;
+    /** Semantic relation label. */
+    relation: EdgeRelation;
+    /** Edge weight in [0, 1]. */
+    weight: number;
+    /** Arbitrary metadata bag. */
+    metadata: Record<string, unknown>;
+    /**
+     * Transaction/ingest time (Unix ms): when MemOS learned the fact.
+     * This is the bitemporal transaction-time axis — it is never renamed
+     * or repurposed; event-time validity lives in `validFrom`/`validTo`.
+     */
+    createdAt: number;
+    /**
+     * Event-time validity start (Unix ms): when the fact became true in the
+     * world. `null`/undefined = open-ended (still true, or unknown).
+     */
+    validFrom?: number | null;
+    /**
+     * Event-time validity end (Unix ms): when the fact ceased to be true.
+     * `null`/undefined = open-ended (still true). Supersession stamps this
+     * instead of deleting the row, preserving add-only history for as-of
+     * (time-travel) reads.
+     */
+    validTo?: number | null;
+}
+/**
+ * Input for creating a new edge.
+ */
+export interface CreateEdgeInput {
+    sourceId: string;
+    targetId: string;
+    relation?: EdgeRelation;
+    weight?: number;
+    metadata?: Record<string, unknown>;
+    /**
+     * Event-time validity start (Unix ms): when the fact became true in the
+     * world. `null`/undefined = open-ended.
+     */
+    validFrom?: number | null;
+    /**
+     * Event-time validity end (Unix ms): when the fact ceased to be true.
+     * `null`/undefined = open-ended.
+     */
+    validTo?: number | null;
+}
+/**
+ * Filter criteria for searching memories.
+ */
+export interface SearchFilter {
+    /** Full-text search query. */
+    query?: string;
+    /** Filter by memory type. */
+    type?: MemoryType;
+    /** Minimum importance threshold [0, 1]. */
+    minImportance?: number;
+    /** Maximum importance threshold [0, 1]. */
+    maxImportance?: number;
+    /** Metadata key-value filter. */
+    metadata?: Record<string, unknown>;
+    /** Limit the number of results. */
+    limit?: number;
+    /** Offset for pagination. */
+    offset?: number;
+    /** Sort field. */
+    sortBy?: "importance" | "createdAt" | "updatedAt" | "accessCount" | "relevance" | "trustScore";
+    /** Sort direction. */
+    sortOrder?: "asc" | "desc";
+    /** Filter by tags (AND logic — node must have ALL specified tags). */
+    tags?: string[];
+    /** Filter by namespace. */
+    namespace?: string;
+    /**
+     * Filter by an explicit list of namespaces (OR logic). Composes with
+     * `namespace` / `namespacePrefix` (OR'd together) when several are set.
+     * Useful for multi-scope reads, e.g. `["project:alpha", "project:beta"]`.
+     */
+    namespaces?: string[];
+    /**
+     * Scoped-space union (company-brain container semantics): when any
+     * namespace constraint is present (`namespace`, `namespaces`, or
+     * `namespacePrefix`), also include the shared `default` namespace in
+     * the result set. `MemOS.search` enables this by default for
+     * scope-filtered searches; pass `false` explicitly for the legacy
+     * exclusive behavior. Unscoped searches are unaffected.
+     */
+    includeSharedScope?: boolean;
+    /**
+     * Typed multi-scope filter. Composed into a namespace prefix; with the
+     * default `"hierarchical"` match, `{ user: "alice" }` surfaces every
+     * memory stored under Alice's agents and runs. Set
+     * `scopeMatch: "exact"` to require the identical namespace string.
+     */
+    scope?: MemoryScope;
+    /** How `scope` matches stored namespaces. Default `"hierarchical"`. */
+    scopeMatch?: "exact" | "hierarchical";
+    /** Internal: pre-composed LIKE prefix for namespace matching. */
+    namespacePrefix?: string;
+    /**
+     * Filter by retrieval pool. Pass a single pool or a list (OR logic).
+     * Memories written before pools existed read as `"event"`.
+     */
+    pool?: MemoryPool | MemoryPool[];
+    /**
+     * Filter by authoring harness. Pass a harness slug stamped at write
+     * time (`"claude-code"`, `"cline"`, …) or `"all"` (default) for the
+     * behavior-preserving cross-harness recall. `"unknown"` matches
+     * unattributed rows, including everything written before harness
+     * attribution existed.
+     */
+    harness?: string;
+    /** Filter by provenance source. */
+    source?: MemorySource;
+    /** Filter by provenance tier. */
+    provenance?: ProvenanceTier;
+    /** Minimum trust score [0, 1]. */
+    minTrustScore?: number;
+    /**
+     * Quarantine visibility. Quarantined memories are excluded from
+     * recall by default (`includeQuarantined` unset or false) — the
+     * write-gate guarantee. Pass `true` to include them (review flows);
+     * `quarantinedOnly: true` returns only quarantined rows (equivalent
+     * to `memos quarantine list`).
+     */
+    includeQuarantined?: boolean;
+    /** When true, return only quarantined memories (the review queue). */
+    quarantinedOnly?: boolean;
+    /**
+     * When true (default), exclude memories whose `validTo` is in the
+     * past (i.e. historical/superseded memories). Set to false to
+     * include historical memories.
+     */
+    includeHistorical?: boolean;
+    /**
+     * FTS term-join operator for the keyword leg.
+     *
+     * - `"AUTO"` (default): run the precision `AND` query first; when it
+     *   matches nothing, relax to an `OR` query so partial-term matches
+     *   still surface. Precise, and the historical default.
+     * - `"AND"`: every query term must appear (forced precision).
+     * - `"OR"`: any term may appear (forced recall — useful for
+     *   multi-evidence retrieval where relevant facts rarely share every
+     *   query term; noisier for single-fact queries).
+     */
+    ftsOperator?: "AUTO" | "AND" | "OR";
+    /**
+     * When true, expand the top base results with their "session siblings" —
+     * other memories sharing the same `sessionId` (or `instanceId`) metadata
+     * value. Multi-hop / multi-evidence answers typically live across many turns
+     * of one conversation, so once a single relevant turn is retrieved, pulling
+     * its conversation neighbours into the ranking materially raises All-Evidence
+     * Recall. Deterministic, model-free, and ON by default (override with
+     * `config.experimental.sessionExpansion`); injected siblings are ranked
+     * behind every organically-retrieved result, so head ordering never moves
+     * and only the empty tail is filled.
+     */
+    sessionExpansion?: boolean;
+    /** Timestamp filter (Unix ms): only return memories valid at this time. */
+    validAt?: number;
+    /**
+     * How many candidates each hybrid-search leg fetches before fusion.
+     * Overrides the default `max(limit * 4, 20)`. Higher values widen the
+     * recall pool (useful when a reranker or expansion stage narrows
+     * afterwards) at linear scan cost.
+     */
+    candidateDepth?: number;
+    /**
+     * Drop results whose stored embedding is a near-duplicate (cosine >=
+     * `experimental.searchDedupThreshold`, default 0.95) of an
+     * already-selected result. Near-duplicates waste top-K slots that
+     * distinct evidence needs — multi-evidence questions score one node per
+     * duplicate otherwise. Off by default.
+     */
+    semanticDedup?: boolean;
+    /**
+     * Per-query override for the PPR-lite graph expansion
+     * (`config.fusion.graphExpansion`). `true` forces expansion on for this
+     * query, `false` disables it (byte-identical to the pre-expansion
+     * pipeline); `undefined` falls back to the fusion-config default (off).
+     * `contextPack`
+     * forwards its own `graphExpansion: false` through this flag.
+     */
+    graphExpansion?: boolean;
+}
+/**
+ * Options for `MemOS.semanticSearch()`. Accepts every `SearchFilter` field
+ * (namespace, tags, type, limit, …) plus the semantic similarity cutoff.
+ */
+export interface SemanticSearchOptions extends SearchFilter {
+    /** Minimum similarity score in [0, 1]. Default 0.1. */
+    threshold?: number;
+}
+/**
+ * AI Trio context pack — a token-budgeted, ranked, namespace-filtered
+ * slice of memory intended to be folded into an LLM prompt by Guardian.
+ *
+ * See `docs/ai-trio-contracts.md` for the full contract.
+ */
+export interface ContextPackItem {
+    id: string;
+    content: string;
+    summary: string;
+    score: number;
+    scores?: {
+        keyword?: number;
+        semantic?: number;
+        hybrid?: number;
+    };
+    trust: string;
+    source: string;
+    /**
+     * Provenance tier of the item's channel (see `ProvenanceTier`).
+     * Present on packs built after the provenance-trust layer.
+     */
+    provenance?: string;
+    /**
+     * True when the item comes from a low-trust channel (`imported` /
+     * `tool-output` tier, or quarantined-then-released): confirm before
+     * acting on it.
+     */
+    untrustedSource?: boolean;
+    tags: string[];
+    updatedAt: string;
+}
+export interface ContextPack {
+    schema: "ai-trio.memos.context-pack.v1";
+    query: string;
+    namespace: string;
+    tokenBudget: number;
+    items: ContextPackItem[];
+}
+/**
+ * A memory node bundled with its relevance score after a search.
+ */
+export interface ScoredMemory {
+    node: MemoryNode;
+    /** Relevance score returned by the search algorithm. */
+    score: number;
+    /**
+     * Provenance tier of the result's channel (see `ProvenanceTier`).
+     * Stamped by `decorateTrustFlags` for agent-facing result sets.
+     */
+    provenance?: ProvenanceTier;
+    /**
+     * Citable `[mem:hex]` token tracing the memory to its source episode
+     * (see `src/citations.ts`). Stamped by `decorateTrustFlags`.
+     */
+    citation?: string;
+    /**
+     * True when the memory comes from a low-trust channel (`imported` /
+     * `tool-output` tier, or quarantined-then-released): the host agent
+     * should confirm it instead of silently injecting it as context.
+     * Stamped by `decorateTrustFlags`.
+     */
+    untrustedSource?: boolean;
+    /** Optional score breakdown for hybrid retrieval. `graph` marks a
+     * node injected by the graph-expansion leg, `ppr` the normalized
+     * personalized-PageRank score from the PPR-lite expansion blend,
+     * `session` one pulled in
+     * by session-sibling expansion, `rerank` the cross-encoder score
+     * (squashed to [0,1]) from the two-stage reranking pass, `entity` the
+     * query-entity overlap (in [0,1]) that earned the entity-fusion boost,
+     * and `entityLeg` the matched-entity count from the entity-inverted-index
+     * RRF leg (recall signal, distinct from the `entity` scoring boost),
+     * and `provenance` the per-tier trust multiplier from the
+     * provenance-trust layer.
+     *
+     * `semantic` vs `semanticRaw`: `semantic` is the leg's MIN-MAX
+     * NORMALIZED contribution used for fusion — its top candidate is
+     * always exactly `1`, so it is a fusion weight and never an absolute
+     * similarity. `semanticRaw` carries the raw embedding cosine on the
+     * embedder's own scale, which is the only form that can be compared
+     * against an absolute floor such as the abstention threshold in
+     * `shouldAbstain`. Consumers fall back to `semantic` when
+     * `semanticRaw` is absent (hand-built results, custom fusion paths).
+     */
+    scores?: {
+        keyword?: number;
+        /** Normalized semantic-leg contribution (fusion weight, 0..1). */
+        semantic?: number;
+        /** Raw embedding cosine (absolute similarity, embedder scale). */
+        semanticRaw?: number;
+        hybrid?: number;
+        graph?: number;
+        ppr?: number;
+        session?: number;
+        rerank?: number;
+        entity?: number;
+        /**
+         * Present when read-time contradiction resolution demoted this
+         * result: the demotion factor applied (see
+         * CONTRADICTION_DEMOTION_FACTOR in src/contradictions.ts).
+         */
+        contradiction_demoted?: number;
+        entityLeg?: number;
+        /**
+         * Raw CLIP cosine from the image-memory leg (`image_embeddings`,
+         * scanned by `querySimilarImages`). Present only when Track B is
+         * enabled and the leg actually retrieved this candidate — an absent
+         * value means the image leg did not surface it, exactly like
+         * `entityLeg`.
+         */
+        imageLeg?: number;
+        /**
+         * Present when provenance-trust weighting ran: the per-tier trust
+         * multiplier applied (`1 - strength * (1 - tierTrust)` — see
+         * `provenanceMultiplier` in src/provenance.ts).
+         */
+        provenance?: number;
+        /**
+         * Present when retrieval-time anomaly scoring ran: the demotion
+         * factor applied because the memory's write-time attack-shape
+         * similarity was high while the query was not attack-shaped (see
+         * `applyRetrievalAnomalyScoring` in src/memory.ts).
+         */
+        retrievalAnomaly?: number;
+    };
+    /**
+     * Relevance-gate outcome (see `RelevanceGateConfig` /
+     * `applyRelevanceGate`). Present on every result only when the gate is
+     * enabled (`retrieval.relevanceGate.enabled`, or `MEMOS_RELEVANCE_GATE=1`)
+     * — an absent field means the gate never ran, so the list is exactly
+     * what the pre-gate pipeline produced.
+     *
+     * `abstained` is `false` on every kept result: abstention empties the
+     * result list rather than marking survivors.
+     */
+    relevanceGate?: RelevanceGateResult;
+}
+/**
+ * Lifecycle status of a recorded contradiction pair.
+ *
+ * - `unresolved`: detected at write time by the rule-based detector;
+ *   both versions are kept (add-only). Read-time resolution demotes the
+ *   older member. Sleep-time LLM adjudication (future) may resolve it.
+ * - `resolved`: a contradiction outcome was confirmed through the
+ *   evidence state machine (e.g. an old memory superseded by a new
+ *   version) — the pair is recorded for provenance.
+ */
+export type ContradictionStatus = "unresolved" | "resolved";
+/**
+ * A recorded contradiction pair: two memory nodes about the same
+ * subject that disagree. Node ids are stored in canonical (sorted)
+ * order so the UNIQUE(node_a, node_b) constraint dedups pairs
+ * regardless of insertion order.
+ */
+export interface ContradictionRecord {
+    id: string;
+    nodeA: string;
+    nodeB: string;
+    detectedAt: number;
+    status: ContradictionStatus;
+}
+/** How to address the memory a revert applies to. */
+export type RevertScopeInput = {
+    kind: "last";
+} | {
+    kind: "id";
+    id: string;
+} | {
+    kind: "entity";
+    entity: string;
+} | {
+    kind: "text";
+    text: string;
+};
+/**
+ * Options for {@link MemOS.revert}.
+ */
+export interface RevertOptions {
+    /** Who issued the revert (free text, e.g. "user", "agent:coder"). Default "user". */
+    actor?: string;
+    /** Why the revert was issued — recorded on the audit event. */
+    reason?: string;
+    /** If true, resolve and report the target without writing anything. Default false. */
+    dryRun?: boolean;
+    /** Namespace to resolve "last"/named scopes in. Default "default". */
+    namespace?: string;
+}
+/**
+ * The resolved target of a revert command, plus the other candidates
+ * that matched (empty when the scope was unambiguous). When several
+ * memories match a named target, the most recently created valid memory
+ * wins and the rest are reported here for confirmation.
+ */
+export interface RevertTargetResolution {
+    /** The memory that would be (or was) reverted. */
+    target: MemoryNode;
+    /** The scope that produced this target. */
+    scope: RevertScopeInput;
+    /** Other memories that matched the scope (most recent first). */
+    alternatives: ScoredMemory[];
+}
+/**
+ * The outcome of {@link MemOS.revert}.
+ *
+ * Ledger mechanics: the target's validity interval is closed at `at`
+ * (add-only — the row stays in history), the predecessor's interval is
+ * reopened (`validTo = null`), and the revert itself is recorded as an
+ * audit event node (tags `audit`/`revert`, metadata.audit === "revert").
+ */
+export interface RevertResult {
+    /** The reverted-away memory — now historical (validTo = at). */
+    target: MemoryNode;
+    /** The reactivated predecessor — the belief recall returns now. */
+    predecessor: MemoryNode;
+    /** ID of the audit event node, or null on dry-run. */
+    auditId: string | null;
+    /** Unix ms when the revert executed (0 on dry-run). */
+    at: number;
+    /** True when nothing was written. */
+    dryRun: boolean;
+    /** Other candidates that matched the scope. */
+    alternatives: ScoredMemory[];
+}
+/** Outcome feedback for a procedural lesson. */
+export type LessonOutcome = "success" | "failure";
+/**
+ * A procedural lesson: behavioral guidance ("check rate limits before
+ * batch calls") rather than a fact. Captured via `memorizeProcedural`,
+ * reinforced/demoted by `recordLessonOutcome`, and surfaced via
+ * `recallProcedural` / context-pack injection. Scoring is pure local
+ * math — see `src/procedural.ts`.
+ */
+export interface ProceduralLesson {
+    id: string;
+    /** The lesson text — an instruction for future behavior. */
+    lesson: string;
+    /** When/where the lesson applies (free text). */
+    context: string;
+    tags: string[];
+    /** Stored score in [0.01, 0.99]; read-time decay is applied lazily. */
+    score: number;
+    successCount: number;
+    failureCount: number;
+    useCount: number;
+    namespace: string;
+    createdAt: number;
+    updatedAt: number;
+    lastUsedAt: number;
+}
+/** Input for creating a procedural lesson (id/timestamps assigned). */
+export interface NewProceduralLesson {
+    lesson: string;
+    context?: string;
+    tags?: string[];
+    namespace?: string;
+    /** Override the neutral 0.5 prior. Clamped to [0.01, 0.99]. */
+    initialScore?: number;
+}
+export type EmbeddingVector = number[];
+/**
+ * Runtime resolution metadata for an embedding provider instance.
+ *
+ * Benchmarks (and any caller who cares about reproducibility) use this to
+ * verify that the provider they REQUESTED is the provider that actually
+ * loaded — in particular to detect the FastEmbed local-hash fallback that
+ * activates when the transformers package is missing.
+ */
+export interface EmbeddingRuntimeInfo {
+    /** Provider kind the caller asked for, e.g. "fastembed". */
+    requestedProvider: string;
+    /** Provider actually serving embeddings, e.g. "fastembed" or
+     * "local-hash-fallback". Equal to `requestedProvider` when no fallback. */
+    resolvedProvider: string;
+    /** Model the caller asked for. */
+    requestedModel: string;
+    /** Model actually producing vectors. */
+    resolvedModel: string;
+    /** Model revision/commit when the provider exposes one, else null. */
+    modelRevision: string | null;
+    /** Dimensions the caller declared. */
+    requestedDimensions: number;
+    /** Dimensions observed on the most recent embed call, or null before
+     * the first call. Differs from `requestedDimensions` only when the
+     * provider's real output shape disagrees with configuration. */
+    observedDimensions: number | null;
+    /** True when the requested backend did NOT load and a fallback is
+     * serving embeddings instead. Only meaningful after the first embed
+     * call (or an explicit probe) has run. */
+    fallbackActive: boolean;
+    /** Human-readable reason for the fallback, or null when none occurred. */
+    fallbackReason: string | null;
+}
+export interface EmbeddingProvider {
+    /** Stable provider identifier, e.g. "local-hash" or "ollama". */
+    id: string;
+    /** Human-readable embedding model name. */
+    model: string;
+    /** Expected vector dimensionality. */
+    dimensions: number;
+    /**
+     * Runtime resolution metadata (requested vs. resolved provider/model,
+     * fallback status). Optional so custom providers need not implement it;
+     * when absent, callers should assume the provider IS what it claims and
+     * there is no fallback. The built-in FastEmbed provider implements it to
+     * expose the local-hash fallback state.
+     */
+    getRuntimeInfo?(): EmbeddingRuntimeInfo;
+    /** Generate a normalized embedding vector for a text input. */
+    embed(text: string): Promise<EmbeddingVector>;
+    /**
+     * Optional batch embedding. If the provider can batch, override this to
+     * amortize network round-trips. Default implementation calls `embed` for
+     * each text in order. The returned vectors must be in the same order as
+     * the input `texts` array.
+     */
+    batchEmbed?(texts: string[]): Promise<EmbeddingVector[]>;
+    /**
+     * Embed a QUERY — a short natural-language retrieval question.
+     *
+     * Many modern retrieval models (e.g. the Liquid E / e5 families, and
+     * Cohere embed-v3) are trained for an asymmetric query/document setting:
+     * they expect an instruction or "query" prefix on the query side and plain
+     * text on the document side. Routing queries through a dedicated method lets
+     * providers apply that signal, which materially improves semantic recall for
+     * paraphrase questions.
+     *
+     * Optional for backward compatibility: when a provider does not implement it,
+     * `embedQuery`/`embedDocuments` default to the plain `embed` path so
+     * existing custom providers keep working unchanged.
+     */
+    embedQuery?(text: string): Promise<EmbeddingVector>;
+    /**
+     * Embed a batch of DOCUMENTS (the persisted memory contents) for indexing.
+     *
+     * Optional; defaults to `batchEmbed`, falling back to per-text `embed`.
+     * Providers that distinguish query from document mode should use the document
+     * input type here (e.g. Cohere `search_document`).
+     */
+    embedDocuments?(texts: string[]): Promise<EmbeddingVector[]>;
+    /**
+     * Optional image encoder. Text and CLIP vectors live in different
+     * vector spaces (and different tables), so this is an OPTIONAL extra
+     * capability, never the provider's primary contract — a text provider
+     * that also encodes images can satisfy both interfaces, and the
+     * image-embedding path must never be handed to the text embedding
+     * queue. See {@link EmbedImageProvider} for the dedicated contract.
+     */
+    embedImage?(image: Buffer | string): Promise<EmbeddingVector>;
+}
+export type EmbeddingProviderKind = "local-hash" | "ollama" | "openai-compatible" | "voyage" | "cohere" | "fastembed";
+export interface EmbeddingConfig {
+    /** Enables embedding generation. Defaults to true when semantic search is enabled. */
+    enabled?: boolean;
+    /** Built-in provider kind, or a custom provider implementation. */
+    provider?: EmbeddingProviderKind | EmbeddingProvider;
+    /** Provider model name. */
+    model?: string;
+    /** Embedding vector dimensions. */
+    dimensions?: number;
+    /** Base URL for Ollama or OpenAI-compatible embedding endpoints. */
+    baseUrl?: string;
+    /** API key for OpenAI-compatible embedding endpoints. */
+    apiKey?: string;
+    /**
+     * Prefix prepended to QUERY text before embedding. Asymmetric retrieval
+     * models are trained with a query-side instruction and silently degrade
+     * without it — e.g. Liquid LFM2.5-Embedding and e5 models expect
+     * `"query: "`. Empty (default) sends queries as-is.
+     */
+    queryPrefix?: string;
+    /**
+     * Prefix prepended to DOCUMENT text (stored memory content) before
+     * embedding at index time. e.g. Liquid LFM2.5-Embedding and e5 models
+     * expect `"document: "`. Empty (default) sends documents as-is.
+     */
+    documentPrefix?: string;
+    /**
+     * Which node text to embed at store time: the raw `content`, or
+     * `summary + "\n" + content` (the historical default — for short facts
+     * the extractive summary roughly doubles the embedded tokens).
+     */
+    embedText?: "content" | "summary+content";
+}
+export interface EmbeddingRecordInfo {
+    model: string;
+    dimensions: number;
+    updatedAt: number;
+}
+/**
+ * Per-node embedding pipeline status. `pending` means the node has been
+ * stored but its embedding has not been computed yet. `ready` means the
+ * persisted vector is fresh for the current provider/model. `failed`
+ * means the most recent attempt gave up after retries.
+ */
+export type EmbeddingNodeStatus = "pending" | "queued" | "running" | "ready" | "failed";
+/** Lightweight status snapshot returned by `memos.embeddingStatus()`. */
+export interface EmbeddingNodeStatusInfo {
+    nodeId: string;
+    status: EmbeddingNodeStatus;
+    attempts: number;
+    lastError: string | null;
+    updatedAt: number;
+}
+/** Aggregate status returned by `memos.embeddingStatus()` (no args). */
+export interface EmbeddingQueueStatus {
+    pending: number;
+    running: number;
+    total: number;
+    nodes: EmbeddingNodeStatusInfo[];
+}
+/**
+ * Configuration for the background embedding queue. All fields are
+ * optional; sensible defaults are used when omitted.
+ */
+export interface EmbeddingQueueConfig {
+    /** Max concurrent in-flight embed calls. Default 2. */
+    concurrency?: number;
+    /**
+     * Max pending jobs drained into a single `batchEmbed()` call when the
+     * provider supports batching (array-input HTTP endpoints). Default 1 =
+     * one `embed()` call per job. Groups that fail fall back to per-job
+     * retries.
+     */
+    batchSize?: number;
+    /** Max buffered jobs before `enqueue` throws. Default 10000. */
+    maxQueueSize?: number;
+    /** Max retry attempts per job before marking it failed. Default 3. */
+    maxRetries?: number;
+    /** Base backoff in ms; retries use exponential backoff. Default 250. */
+    retryBackoffMs?: number;
+    /**
+     * Coalescing delay in ms before a fully-idle queue picks up
+     * newly-enqueued work. Default 5. Lets rapid sequential `store()` calls
+     * form full `batchSize` groups instead of one single-job group each.
+     * Set to 0 for immediate microtask pickup.
+     */
+    batchLingerMs?: number;
+    /**
+     * If true, `store()` waits for the embedding to complete before
+     * returning. Default false — background mode. Tests and the CLI
+     * `memos flush-embeddings` command benefit from this being false.
+     */
+    synchronous?: boolean;
+}
+/**
+ * Full in-memory graph snapshot.
+ */
+export interface GraphSnapshot {
+    nodes: MemoryNode[];
+    edges: MemoryEdge[];
+}
+/**
+ * Mutation recorded in the tamper-evident log.
+ *
+ * - `store` — new memory written via `MemOS.store()` (including event-update
+ *   replacements and revert audit entries).
+ * - `import` — record imported with its original identity (`importRecord`,
+ *   e.g. encrypted sync restore).
+ * - `update` — node mutated via `updateNode` (content, tags, metadata,
+ *   validity, provenance…), TTL changes, and `setValidity`.
+ * - `forget` — node deleted via `MemOS.forget()`.
+ */
+export type TamperOp = "store" | "import" | "update" | "forget";
+/**
+ * One entry of the tamper-evident mutation log.
+ *
+ * Entries form a hash chain: `entryHash = sha256("memos-tamper-entry-v2"|
+ * seq|ts|op|nodeId|nodeHash|prevHash)` where `prevHash` is the previous
+ * entry's `entryHash` (or a fixed genesis constant for seq 1) and `seq`
+ * is the entry's 1-based chain position, assigned atomically by the
+ * storage adapter. `nodeHash` is `sha256` over a canonical serialization
+ * of the node's full mutable state at mutation time (content, summary,
+ * type, tags, importance, namespace, metadata, provenance, validity,
+ * TTL, timestamps — everything except volatile read stats) — for
+ * `forget` it is the hash of the deleted node's final state, so
+ * deletions are provable too.
+ */
+export interface TamperLogEntry {
+    seq: number;
+    ts: number;
+    op: TamperOp;
+    nodeId: string;
+    nodeHash: string;
+    prevHash: string;
+    entryHash: string;
+}
+/**
+ * A tamper-log entry as supplied by the caller. The storage adapter
+ * assigns the chain position atomically: it determines `prevHash` from
+ * the current tip, allocates `seq`, and computes `entryHash` — all in
+ * one transaction — then returns the complete stored entry.
+ */
+export type NewTamperLogEntry = Pick<TamperLogEntry, "ts" | "op" | "nodeId" | "nodeHash">;
+/**
+ * Backend-agnostic storage contract.
+ *
+ * Any persistence backend (SQLite, Postgres, Redis, Qdrant …) must
+ * implement this interface. The core engine only depends on this
+ * contract, never on a concrete backend.
+ */
+export interface StorageAdapter {
+    /** Initialise tables / indices / connections. Called once at startup. */
+    init(): Promise<void>;
+    /** Persist a new memory node. Returns the created node. */
+    saveNode(node: MemoryNode): Promise<MemoryNode>;
+    /** Retrieve a node by ID. Returns `null` when not found.
+     *  Implementations should bump the access stats (access_count,
+     *  last_accessed) on read. For side-effect-free reads, use `peekNode`. */
+    getNode(id: string): Promise<MemoryNode | null>;
+    /**
+     * Side-effect-free variant of `getNode`. Does not increment
+     * `access_count` or update `last_accessed`. Use for internal lookups
+     * where the read is not a user-initiated retrieval — e.g. tag
+     * updates, TTL changes, eviction candidate selection.
+     */
+    peekNode?(id: string): Promise<MemoryNode | null>;
+    /**
+     * Delete the single least-important node, where "least important" is
+     * defined as lowest `importance` then oldest `last_accessed`.
+     * Returns the id of the deleted node, or null if the table is empty.
+     * Implementations may fall back to in-memory selection if SQL is
+     * not appropriate.
+     */
+    evictLeastImportant?(): Promise<string | null>;
+    /** Partially update a node. Returns the updated node. */
+    updateNode(id: string, input: UpdateMemoryInput): Promise<MemoryNode | null>;
+    /** Delete a node and all connected edges. */
+    deleteNode(id: string): Promise<boolean>;
+    /**
+     * Record one read access for a node: bumps `access_count` and
+     * `last_accessed` ONLY. Must not touch `updatedAt` or any content —
+     * a read is not a write, and mutating `updatedAt` on read would
+     * corrupt recency ordering, sync conflict resolution, embedding
+     * freshness, and the tamper-evident log's content cross-check.
+     *
+     * Optional: adapters that don't implement it skip read telemetry
+     * (fail-open). Never route read telemetry through `updateNode` —
+     * see `bumpAccessCounters` in `src/memory.ts`.
+     */
+    recordAccess?(id: string): void | Promise<void>;
+    /**
+     * Append one entry to the tamper-evident mutation log. The adapter
+     * MUST assign the chain position atomically: determine `prevHash`
+     * from the current tip, allocate `seq`, compute `entryHash`, and
+     * insert — all in a single transaction — then return the complete
+     * stored entry. Optional: adapters that don't implement the log
+     * disable mutation logging (fail-open) and `verifyTamperLog`
+     * reports the log as unsupported.
+     */
+    appendTamperEntry?(entry: NewTamperLogEntry): Promise<TamperLogEntry>;
+    /** Read the full tamper-evident log in sequence order. */
+    readTamperLog?(): Promise<TamperLogEntry[]>;
+    /** Persist a new edge. Returns the created edge. */
+    saveEdge(edge: MemoryEdge): Promise<MemoryEdge>;
+    /**
+     * Batch-insert multiple edges in a single transaction.
+     * Falls back to individual saveEdge calls when not implemented.
+     */
+    saveEdgesBatch?(edges: MemoryEdge[]): Promise<MemoryEdge[]>;
+    /** Retrieve an edge by ID. */
+    getEdge(id: string): Promise<MemoryEdge | null>;
+    /** Delete an edge by ID. */
+    deleteEdge(id: string): Promise<boolean>;
+    /**
+     * Scoped-space inventory: every namespace with its live memory count.
+     * Optional — adapters that cannot provide it fall back to a full scan.
+     */
+    listNamespaces?(): Promise<Array<{
+        namespace: string;
+        count: number;
+    }>>;
+    /**
+     * Close (invalidate) the currently-valid edges incident to a node by
+     * stamping `valid_to = validTo`. Rows are updated, never deleted, so
+     * as-of reads at earlier timestamps still return them.
+     * Returns the number of edges closed.
+     */
+    closeEdgesForNode?(nodeId: string, validTo: number): Promise<number>;
+    /** Query nodes with filters. */
+    queryNodes(filter: SearchFilter): Promise<ScoredMemory[]>;
+    /**
+     * Per-harness memory counts (`SELECT harness, COUNT(*) … GROUP BY
+     * harness`). Optional — `MemOS.getHarnessCounts()` falls back to a
+     * paged `queryNodes` scan when the adapter does not implement it.
+     */
+    getHarnessCounts?(): Promise<HarnessCount[]>;
+    /** Persist an embedding vector for a node. */
+    saveEmbedding?(nodeId: string, vector: EmbeddingVector, model: string): Promise<void>;
+    /** Return stored embedding metadata for startup backfill decisions. */
+    getEmbeddingInfo?(nodeId: string): Promise<EmbeddingRecordInfo | null>;
+    /**
+     * Return stored embedding metadata for every node in one round trip.
+     * Optional bulk counterpart to `getEmbeddingInfo` — lets startup
+     * backfill avoid one SELECT per node. Storages that don't implement it
+     * fall back to per-node `getEmbeddingInfo` calls.
+     */
+    getAllEmbeddingInfos?(): Promise<Array<{
+        nodeId: string;
+    } & EmbeddingRecordInfo>>;
+    /** Query nodes by vector similarity. */
+    querySimilarEmbeddings?(vector: EmbeddingVector, filter: SearchFilter, limit: number, threshold?: number, 
+    /**
+     * When provided, only rows stored by this exact model are compared.
+     * Cosine similarity is meaningless across models, and two different
+     * models can share a dimensionality — dimension equality alone does
+     * not prevent silently mixing incompatible vectors.
+     */
+    model?: string): Promise<ScoredMemory[]>;
+    /** Counts of stored embeddings grouped by model (reindex/audit support). */
+    getEmbeddingModelCounts?(): Promise<Array<{
+        model: string;
+        count: number;
+    }>>;
+    /**
+     * Bulk-fetch stored embedding vectors for the given node ids.
+     * Used by write-time contradiction detection to avoid one SELECT per
+     * neighbor. Returns only ids that have a stored vector.
+     */
+    getEmbeddingVectors?(nodeIds: string[]): Promise<Map<string, EmbeddingVector>>;
+    /** Delete all embedding rows stored by the given model. Returns the count. */
+    deleteEmbeddingsByModel?(model: string): Promise<number>;
+    /**
+     * Persist a CLIP image vector for a node, in the SEPARATE
+     * `image_embeddings` space. Never mixed with text `embeddings`:
+     * cosine similarity across the two spaces is meaningless.
+     */
+    saveImageEmbedding?(nodeId: string, vector: EmbeddingVector, model: string): Promise<void>;
+    /** Every stored image vector (node id + vector + model), for reindex/audit. */
+    getAllImageEmbeddings?(): Promise<Array<{
+        nodeId: string;
+        vector: EmbeddingVector;
+        model: string;
+    }>>;
+    /**
+     * Query image memories by CLIP vector similarity. Behaves exactly like
+     * `querySimilarEmbeddings`, except it scans `image_embeddings` and
+     * filters on model + dimensions — a 768-d text vector must never be
+     * scored against a 512-d CLIP query.
+     */
+    querySimilarImages?(vector: EmbeddingVector, filter: SearchFilter, limit: number, threshold?: number, 
+    /** Only rows stored by this exact CLIP model are compared. */
+    model?: string): Promise<ScoredMemory[]>;
+    /**
+     * Image-embedding model counts, for `memos diagnostics` / reindex
+     * support. Grouped by model like `getEmbeddingModelCounts`.
+     */
+    getImageEmbeddingModelCounts?(): Promise<Array<{
+        model: string;
+        count: number;
+    }>>;
+    /**
+     * Delete the image-embedding row for a node (used by the node-delete
+     * path alongside the blob unlink). Returns true when a row was removed.
+     */
+    deleteImageEmbedding?(nodeId: string): Promise<boolean>;
+    /** Query edges, optionally filtered by source/target. */
+    queryEdges(filter?: {
+        sourceId?: string;
+        targetId?: string;
+        relation?: EdgeRelation;
+        /**
+         * Bitemporal as-of read: when provided, only edges whose event-time
+         * validity interval covers this Unix-ms timestamp are returned
+         * (NULL bounds are open-ended). Default returns all edges.
+         */
+        validAt?: number;
+    }): Promise<MemoryEdge[]>;
+    /**
+     * Record a contradiction pair between two memory nodes. Node ids are
+     * canonicalized (sorted) by the implementation so the UNIQUE constraint
+     * dedups reversed pairs. Insert is idempotent (no-op when the pair is
+     * already recorded).
+     */
+    addContradiction?(nodeA: string, nodeB: string, status?: ContradictionStatus): Promise<ContradictionRecord>;
+    /**
+     * Return recorded contradiction pairs where node_a OR node_b is in
+     * `nodeIds` — the bounded read-time lookup for
+     * `resolveContradictionsAtRead`.
+     */
+    getContradictionPairsFor?(nodeIds: string[]): Promise<ContradictionRecord[]>;
+    /** Transition a contradiction record between `unresolved`/`resolved`. */
+    updateContradictionStatus?(id: string, status: ContradictionStatus): Promise<void>;
+    /**
+     * Procedural lessons (optional — only SQLiteStorage implements these
+     * today). `updateProceduralLesson` applies a partial patch (score,
+     * counts, timestamps) and returns the updated record, or null when
+     * the id is unknown.
+     */
+    saveProceduralLesson?(lesson: NewProceduralLesson): Promise<ProceduralLesson>;
+    getProceduralLesson?(id: string): Promise<ProceduralLesson | null>;
+    updateProceduralLesson?(id: string, patch: Partial<ProceduralLesson>): Promise<ProceduralLesson | null>;
+    listProceduralLessons?(namespace?: string): Promise<ProceduralLesson[]>;
+    /**
+     * Find memory nodes whose id (dashes ignored) starts with `prefix`
+     * (hex, case-insensitive). Backs citation resolution; capped by the
+     * implementation to a bounded candidate list.
+     */
+    findNodesByIdPrefix?(prefix: string): Promise<MemoryNode[]>;
+    /** Return the full graph (nodes + edges). */
+    getGraph(): Promise<GraphSnapshot>;
+    /**
+     * Return the graph as of a bitemporal timestamp (unix ms): nodes and
+     * edges whose validity interval covers `atTime`. Optional so
+     * third-party adapters are not forced to implement history; callers
+     * should fall back to filtering `getGraph()` with the same predicates.
+     */
+    getGraphAtTime?(atTime: number): Promise<GraphSnapshot>;
+    /**
+     * Return every persisted embedding (node id + vector + model). Used
+     * by memory consolidation. Implementations may return an empty
+     * array when embeddings are not stored.
+     */
+    getAllEmbeddings?(): Promise<Array<{
+        nodeId: string;
+        vector: EmbeddingVector;
+        model: string;
+    }>>;
+    /**
+     * Update only the `namespace` of a node. Used by `archive` to
+     * move a memory to the `archived` namespace.
+     */
+    setNodeNamespace?(id: string, namespace: string): Promise<void>;
+    /** Set TTL on a node. */
+    setTTL(id: string, seconds: number): Promise<void>;
+    /** Clear TTL on a node. */
+    clearTTL(id: string): Promise<void>;
+    /** Delete expired nodes and return the count of deleted nodes. */
+    sweepExpired(): Promise<number>;
+    /** Get all nodes with a specific tag. */
+    queryNodesByTag(tag: string): Promise<MemoryNode[]>;
+    /**
+     * ── item2: entity leg ── candidate generation for hybrid search: node
+     * ids whose indexed entities intersect `entities`, ranked by number of
+     * matched entities (desc), node id tiebreak. Backed by the
+     * `entity_index` inverted table in the SQLite storage. Optional —
+     * storages without an entity index omit this and the entity RRF leg
+     * degrades to no candidates.
+     */
+    searchByEntities?(entities: string[], limit: number): Promise<Array<{
+        nodeId: string;
+        matches: number;
+    }>>;
+    /** Delete all nodes and edges (batch operation). */
+    deleteAllNodes(): Promise<void>;
+    /** Close connections and release resources. */
+    close(): Promise<void>;
+}
+/**
+ * Experimental feature flags.
+ */
+/**
+ * Wire format a context pack will be serialized to. Used by the
+ * budget-accounting path to charge each item what it actually costs on
+ * the wire (TOON row scaffolding / JSON field names, citations)
+ * instead of the legacy flat `content + summary + 4` estimate.
+ *
+ * See `wireFormat` on the context-pack options in
+ * `src/context-pack.ts`.
+ */
+export type ContextPackWireFormat = "json" | "toon" | "toon-compact";
+/**
+ * Compression knobs for the context-pack budget path — the switch that
+ * finally uses `compressText` from `src/compression.ts`.
+ *
+ * Compression is attempted ONLY for an item that does not fit the
+ * pack's `tokenBudget`: the compressor runs over the item's
+ * already-debloated content (and summary) and the item is admitted when
+ * the compressed form fits. An item that still does not fit after
+ * compression is skipped exactly as it is today, so enabling
+ * compression can only ever ADD items to a pack, never remove them.
+ *
+ * Default `enabled: false`, deliberately: `compressText` is a lossy
+ * stopword filter ("the deploy pipeline" → "deploy pipeline"), so the
+ * default build keeps every content byte identical to the
+ * pre-compression pack. Opt in when you want the extra recall and
+ * accept terser evidence text.
+ */
+export interface ContextPackCompressionOptions {
+    /**
+     * Try `compressText` on items that would otherwise be dropped for
+     * not fitting the token budget. Default false — when false the
+     * compressor is never invoked and no content is altered.
+     */
+    enabled?: boolean;
+    /**
+     * Compression aggressiveness. `"light"` drops articles, copulas and
+     * common prepositions; `"aggressive"` additionally drops filler
+     * adverbs and most pronouns (roughly 40-60% of prose tokens — read
+     * the output before trusting it). Default `"light"`.
+     */
+    level?: CompressionLevel;
+}
+export interface ExperimentalConfig {
+    /**
+     * @deprecated No longer required — `semanticSearch()` works without it.
+     * Kept as a shorthand for enabling embeddings with the default provider
+     * (equivalent to `embeddings: { enabled: true }`).
+     */
+    semanticSearch?: boolean;
+    /**
+     * Context-pack budget compression. When `enabled`, items that do not
+     * fit `contextPack({ tokenBudget })` are first re-rendered through
+     * `compressText` (`src/compression.ts`) and admitted if the compressed
+     * form fits; only items that are still too big are skipped.
+     *
+     * Default off: compression is lossy, so the default pack contents stay
+     * byte-identical to the pre-compression build. Read the rationale in
+     * `ContextPackCompressionOptions`.
+     */
+    packCompression?: ContextPackCompressionOptions;
+    /** Enable graph visualization export. */
+    graphViz?: boolean;
+    /** Enable namespace isolation. */
+    namespaces?: boolean;
+    /** Enable context injection from graph neighbours. */
+    contextInjection?: boolean;
+    /**
+     * Extract semantic (subject, predicate, object) triples at write time
+     * and store them in node metadata. Enables triple-aware retrieval
+     * boosting. Experimental, default off.
+     */
+    tripleExtraction?: boolean;
+    /**
+     * Apply Ebbinghaus forgetting-curve reinforcement to retrieval scoring.
+     * Memories decay exponentially by time-since-access divided by access
+     * count; frequently-recalled memories stay strong. Experimental,
+     * default off.
+     */
+    ebbinghaus?: boolean;
+    /**
+     * Run the evidence state machine on every `store()`: similar existing
+     * memories are reinforced, revised, or superseded, and near-duplicates
+     * (similarity >= 0.92) are folded into the existing node instead of
+     * being written again. Default: true.
+     */
+    evidenceOnStore?: boolean;
+    /**
+     * After a node's embedding is persisted, auto-link it to its top
+     * embedding-similarity neighbours (cosine >= 0.6, max 8 edges) in
+     * addition to the bag-of-words links. Only active when an embedding
+     * provider is configured. Default: true.
+     */
+    embeddingAutoLink?: boolean;
+    /**
+     * Apply a gentle recency boost to hybrid search ranking. Off by
+     * default: enabling it makes scores time-dependent, which relaxes the
+     * score-reproducibility guarantee in `docs/ai-trio-contracts.md`.
+     * Default: false.
+     */
+    recencyBoost?: boolean;
+    /**
+     * Graph-expansion recall leg for hybrid search. After fusion, the top
+     * `maxSeeds` results are expanded along their graph edges and unseen
+     * neighbours are injected into the ranking at `seedScore * scoreFactor`
+     * (capped at `maxAdded` extra nodes). Useful for multi-evidence /
+     * multi-hop queries where related facts are connected by
+     * `relates_to`/`supports` edges but neither retrieval leg surfaces them.
+     * Off by default.
+     */
+    graphExpansion?: {
+        enabled?: boolean;
+        /** How many top fused results to expand along edges. Default 3. */
+        maxSeeds?: number;
+        /** Maximum neighbours injected per query. Default 5. */
+        maxAdded?: number;
+        /** Injected neighbour score = seed score × this factor. Default 0.85. */
+        scoreFactor?: number;
+    };
+    /**
+     * Two-stage reranking: after fusion, the top `candidates` results are
+     * re-scored by a cross-encoder and the final ranking is reordered by
+     * relevance score. The first stage (hybrid search) exists to recall;
+     * the reranker decides what the caller actually sees. Two providers:
+     *
+     * - `"endpoint"` (default when `endpoint` is set): re-scores via an HTTP
+     *   `/rerank` server (e.g. llama-server with bge-reranker-v2-m3).
+     * - `"local"`: in-process cross-encoder through `@huggingface/transformers`
+     *   (default model `Xenova/bge-reranker-base`, ~280 MB, downloaded on
+     *   first use). No server needed; needs one of the transformers packages
+     *   installed.
+     *
+     * On reranker failure the fused order is kept unchanged (graceful
+     * degradation). Off by default.
+     */
+    /**
+     * Cosine threshold for the opt-in `filter.semanticDedup` in hybrid
+     * search. Default 0.95 — near-verbatim duplicates only.
+     */
+    searchDedupThreshold?: number;
+    /**
+     * Round 4: RM3-lite pseudo-relevance feedback for hybrid search.
+     * For short queries (≤3 content terms) whose primary keyword leg is
+     * thin (<5 hits), harvest up to 3 expansion terms from the top-5
+     * semantic hits and re-probe FTS5 as a second keyword pass. Union
+     * semantics: expansion can only ADD candidates, never demote or
+     * remove primary-leg results (expansion-only hits are demoted below
+     * every primary hit, since expansion bm25 scores are not comparable
+     * to primary-query bm25 scores).
+     *
+     * Off by default: PRF is a recall booster with query-drift risk —
+     * enable it only after measuring a win on your eval (deterministic
+     * eval was neutral: 0.9792/0.9688 with and without). `MEMOS_PRF=1`
+     * forces it on for experiments without a config change.
+     * Default: false.
+     */
+    prfExpansion?: boolean;
+    rerank?: {
+        /**
+         * Rerank provider: `"endpoint"` (HTTP `/rerank` server) or `"local"`
+         * (in-process cross-encoder). Default: `"endpoint"` when `endpoint` is
+         * set, `"local"` when `localModel` is set. `MEMOS_RERANK_LOCAL=1`
+         * forces the local provider for experiments without a config change.
+         */
+        provider?: "endpoint" | "local";
+        /** Base URL of the rerank server, e.g. "http://127.0.0.1:8081".
+         *  Receives `POST {endpoint}/rerank` with
+         *  `{ model, query, documents: string[] }`. Required for the
+         *  `"endpoint"` provider; ignored for `"local"`. */
+        endpoint?: string;
+        /** Bearer token for the rerank endpoint, when required. */
+        apiKey?: string;
+        /** Model name sent to the endpoint (many local servers ignore it). */
+        model?: string;
+        /**
+         * Local cross-encoder model id for `provider: "local"`.
+         * Default `"Xenova/bge-reranker-base"`. Overridable for
+         * experiments with `MEMOS_RERANK_MODEL`.
+         */
+        localModel?: string;
+        /**
+         * Weight dtype for the local model (`from_pretrained` dtype, e.g.
+         * `"q8"`, `"fp32"`). Default `"q8"` — much faster on CPU with
+         * negligible ranking impact. Overridable with `MEMOS_RERANK_DTYPE`.
+         */
+        localDtype?: string;
+        /** How many fused candidates to submit for reranking. Default 50.
+         *  Overridable for experiments with `MEMOS_RERANK_CANDIDATES`. */
+        candidates?: number;
+        /**
+         * Truncate each reranked document to this many characters before
+         * sending. Cross-encoder relevance signal lives in the first few
+         * hundred tokens, and capping pair length keeps the request's token
+         * count predictable — long-tail documents otherwise force many extra
+         * GPU waves on the rerank server. Default 0 = send full documents.
+         */
+        maxDocChars?: number;
+        /** Request timeout in ms. Default 5000. */
+        timeoutMs?: number;
+    };
+    /**
+     * Session-neighbour expansion for hybrid search. After fusion, the top
+     * `maxSeeds` results are expanded along their same-conversation
+     * neighbours and unseen siblings are injected into the ranking at a
+     * decaying `seed.score * scoreFactor^k`. Multi-hop answers typically
+     * span many turns of one session, so recovering the neighbours of a
+     * single relevant turn raises all-evidence recall without another
+     * embedding pass. Default: true (injected siblings sit behind every
+     * organically-retrieved result, so head ordering never moves).
+     */
+    sessionExpansion?: boolean;
+}
+/**
+ * Relevance-gate knobs for hybrid search (see `applyRelevanceGate` and
+ * `shouldAbstain` in `src/retrieval.ts`).
+ *
+ * Two independent problems, one knob each:
+ *
+ *  - ABSTENTION. When nothing in the store is genuinely about the query,
+ *    the honest answer is "no memories" — not "the ten least-bad rows".
+ *    A memory layer that always returns k results forces the caller to
+ *    invent an answer.
+ *  - TAIL TRIMMING. Precision@10 measured 0.099 on LoCoMo: about nine of
+ *    every ten injected items were noise. Dropping candidates that trail
+ *    the top score by a large factor costs little recall and sharply
+ *    improves a context pack's signal-to-noise ratio.
+ *
+ * Lives in `types.ts` (dependency-free) and is forwarded by
+ * `MemOSConfig.retrieval.relevanceGate` into every hybrid search
+ * (`search`, `contextPack`, `multiStreamSearch`, `recall`'s scoring
+ * pipeline). Off unless `enabled` is true — see the field's default.
+ */
+export interface RelevanceGateConfig {
+    /**
+     * Master switch for the whole gate (tail trimming AND abstention).
+     *
+     * Defaults to `false`. This is a published SDK: an enabled gate
+     * changes how many memories `search()` returns for the same query
+     * (results whose fused score trails the top hit by more than
+     * `1 - ratio` are dropped), and silently shrinking a consumer's result
+     * count on upgrade is not a behaviour change we can make for them.
+     * Turning it on is deliberately one explicit field:
+     *
+     * ```ts
+     * new MemOS({ retrieval: { relevanceGate: { enabled: true } } })
+     * // or, for a one-off experiment with no config change:
+     * //   MEMOS_RELEVANCE_GATE=1
+     * ```
+     */
+    enabled?: boolean;
+    /**
+     * Keep only candidates whose fused score is at least
+     * `topScore * ratio`. `0` disables trimming while leaving abstention
+     * (if configured) active.
+     *
+     * Default 0.15 (`DEFAULT_RELEVANCE_RATIO` in `src/retrieval.ts`) —
+     * deliberately low: it exists to cut the long tail of "matched one
+     * stopword" rows, not to make fine-grained relevance decisions.
+     */
+    ratio?: number;
+    /**
+     * Abstain (return nothing) when no candidate reaches this cosine
+     * similarity on the semantic leg AND nothing matched the query
+     * literally. `undefined` disables abstention entirely.
+     *
+     * Deliberately unset by default even when the gate is enabled: the
+     * floor is embedder-dependent — a 256-d hash embedder and a 1024-d
+     * transformer do not share a cosine scale. Calibrate against your
+     * embedder before switching this on (0.3 is a reasonable starting
+     * point for paraphrase-quality embedders — see
+     * `DEFAULT_ABSTAIN_SIMILARITY`).
+     */
+    abstainSimilarity?: number;
+    /**
+     * Safety floor: never trim below this many results, whatever the ratio
+     * says. Useful for callers that need at least N items to render a view.
+     * `0` means no floor.
+     */
+    minResults?: number;
+}
+/**
+ * Outcome of one relevance-gate pass. Additive metadata — never breaks
+ * the `ScoredMemory[]` shape `search()` has always returned.
+ *
+ * Surface points:
+ *  - `ScoredMemory.relevanceGate` on every result of a gated search;
+ *  - the `{ results, gate }` member pair returned by
+ *    `MemOS.searchWithGate()`.
+ */
+export interface RelevanceGateResult {
+    /**
+     * True when the gate decided nothing in the store is relevant to the
+     * query. The result list is empty and the caller should answer from
+     * its own knowledge rather than from memory.
+     */
+    abstained: boolean;
+    /** True when at least one candidate was dropped by tail trimming. */
+    trimmed: boolean;
+    /** How many fused candidates the gate removed. */
+    dropped: number;
+}
+/**
+ * Tunable knobs for the hybrid-search Reciprocal Rank Fusion. Lives in
+ * `types.ts` (dependency-free) and is re-exported by `src/retrieval.ts`,
+ * where `fuseResults()` consumes it. `MemOSConfig.fusion` forwards these
+ * to every hybrid search; unset fields fall back to `retrieval.ts`
+ * defaults.
+ */
+export interface FusionOptions {
+    /** RRF constant K. Larger K flattens rank differences. Default 60. */
+    rrfK?: number;
+    /** Weight of the keyword (FTS5) leg. Default 0.8. */
+    keywordWeight?: number;
+    /** Weight of the semantic (embedding) leg. Default 0.2. */
+    semanticWeight?: number;
+    /**
+     * Lower bound of the trust multiplier (applied as
+     * `trustFloor + trustScore * (1 - trustFloor)`). Default 0.7.
+     * Set to 1.0 to disable trust weighting.
+     */
+    trustFloor?: number;
+    /**
+     * Strength of the confidence/trust combined multiplier from the
+     * evidence state machine. Default 0.35. Set to 0 to disable
+     * confidence-aware ranking.
+     */
+    confidenceWeightStrength?: number;
+    /**
+     * Recency half-life in ms for the tie-break among near-equal scores.
+     * Default 30 days. Set to 0 to disable recency tie-breaking.
+     */
+    recencyHalfLifeMs?: number;
+    /**
+     * Reference "now" for recency computations. Defaults to wall-clock;
+     * injectable for deterministic tests/benchmarks.
+     */
+    nowMs?: number;
+    /**
+     * Entities extracted from the query (populated automatically by
+     * `hybridSearch` via `extractQueryEntities`). When non-empty, memories
+     * whose tags / `metadata.entities` overlap the query entities receive a
+     * post-fusion boost — the third retrieval signal alongside keyword and
+     * semantic (see the 2026 fused multi-signal retrieval consensus).
+     */
+    queryEntities?: string[];
+    /**
+     * Strength of the entity-overlap boost: `score *= 1 + entityWeight *
+     * overlap`. Default 0.15. Set to 0 to disable entity-fused scoring.
+     *
+     * Distinct from `entityLegWeight`: the overlap boost only re-scores
+     * candidates the keyword/semantic legs already retrieved, while the
+     * entity leg adds recall (entity-matched memories the other legs
+     * missed enter the candidate pool).
+     */
+    entityWeight?: number;
+    /**
+     * ── item2: entity leg ── weight of the entity-inverted-index RRF leg
+     * (the third retrieval signal alongside keyword and semantic). Applied
+     * as `entityLegWeight / (rrfK + rank)` per candidate, so entity-matched
+     * memories surface even when FTS and embeddings missed them. Default
+     * 0.1 (deliberately below the semantic leg's 0.2 weight — see
+     * DEFAULT_ENTITY_LEG_WEIGHT). Set to 0 to disable the leg.
+     */
+    entityLegWeight?: number;
+    /**
+     * Strength of the provenance-tier trust multiplier from the
+     * provenance-trust layer. Applied as
+     * `score *= 1 - strength * (1 - tierTrust)` with per-tier trust from
+     * `PROVENANCE_TRUST` (user-verified 1.0 … imported 0.72). Default
+     * 0.5 — low-trust content is slightly down-ranked without overriding
+     * relevance. Set to 0 to disable trust-weighted recall. Calibrated
+     * neutral-or-better on the retrieval eval (scripts/eval-retrieval.ts).
+     */
+    provenanceWeightStrength?: number;
+    /**
+     * Single-step PPR-lite graph expansion after fusion (HippoRAG-style,
+     * see `src/graph-expansion.ts`). The top `graphExpansionSeeds` fused
+     * results seed a personalized PageRank (damping 0.5, `graphExpansionHops`
+     * hops) over graph edges plus shared-entity links; the final score
+     * blends as `(1 - graphExpansionAlpha) * fused + graphExpansionAlpha *
+     * pprNorm` with PPR scores normalized to [0,1]. Graph neighbours of
+     * seeds that neither retrieval leg surfaced can enter the results this
+     * way — the multi-hop recall win without iterative LLM retrieval.
+     * Default: false (opt-in; expansion is off unless enabled here or per
+     * query via `SearchFilter.graphExpansion: true`). When disabled the
+     * pipeline is byte-identical to pre-expansion behaviour (no extra
+     * storage reads, no score changes).
+     */
+    graphExpansion?: boolean;
+    /**
+     * Blend weight of the normalized PPR score in the post-fusion blend.
+     * Default 0.2.
+     */
+    graphExpansionAlpha?: number;
+    /** PPR neighbourhood depth explored from each seed. Default 2. */
+    graphExpansionHops?: number;
+    /** How many top fused results seed the PPR walk. Default 10. */
+    graphExpansionSeeds?: number;
+    /**
+     * Fusion algorithm for combining the retrieval legs.
+     *
+     * - `"rrf"` — weighted Reciprocal Rank Fusion (rank-based voting,
+     *   robust to score outliers; the pre-round-4 default).
+     * - `"convex"` — min-max normalize each leg's native scores to [0,1],
+     *   then take the weighted sum with renormalized leg weights. Lets
+     *   strong absolute scores (a near-exact embedding match, a dominant
+     *   bm25 hit) dominate instead of being flattened to rank votes.
+     *   Default `"convex"` (round 4; Sept 2026 TOIS analysis found convex
+     *   combination beats RRF in- and out-of-domain, and Weaviate made the
+     *   same switch). Set to `"rrf"` to restore the legacy behavior.
+     */
+    fusionMode?: "rrf" | "convex";
+    /**
+     * Raw query text, used only for the deterministic adaptive leg
+     * weighting (short-query keyword emphasis, entity-dense entity-leg
+     * emphasis, temporal-query recency). Populated automatically by
+     * `hybridSearch`; no effect when `adaptiveWeighting` is false.
+     */
+    query?: string;
+    /**
+     * Master switch for the deterministic query-type adaptive weighting
+     * (round 4). Default true. Set to false for fixed leg weights.
+     */
+    adaptiveWeighting?: boolean;
+    /**
+     * Strength of the temporal-query recency multiplier:
+     * `score *= 1 + temporalRecencyStrength * 0.5^(age/halfLife)`,
+     * applied only when the query carries temporal markers (today,
+     * yesterday, last week, …) and `adaptiveWeighting` is on. Default
+     * 0.05 (at most a 5% nudge toward fresh memories). Set to 0 to
+     * disable.
+     */
+    temporalRecencyStrength?: number;
+    /**
+     * Weight of the CLIP image leg (Track B of image memory). Applied
+     * exactly like the entity leg: `imageLegWeight / (rrfK + rank)` per
+     * candidate in RRF mode, as a renormalized convex term otherwise.
+     *
+     * Defaults to {@link DEFAULT_IMAGE_LEG_WEIGHT} (0.1) whenever the leg
+     * actually has results, so Track B contributes without any config.
+     * The leg is inert when `vision.clip.enabled` is unset or the store
+     * holds no image embeddings — a text-only install never pays for it
+     * and its results are byte-identical to before. Set to 0 explicitly
+     * to disable the leg even when images exist.
+     */
+    imageLegWeight?: number;
+}
+/**
+ * Configuration options for a MemOS instance.
+ */
+export interface MemOSConfig {
+    /**
+     * Optional write-time contextual enrichment hook (contextual retrieval,
+     * Anthropic-style). Called once per `store()` with the memory's signals;
+     * return a single line describing the situation the memory was captured
+     * in (e.g. "stated while debugging the deploy pipeline"). The line is
+     * stored in `metadata.context`, prepended to the embedded text, and
+     * surfaced in context packs — it makes embeddings carry situational
+     * meaning, which is the best-attested cheap retrieval upgrade in the
+     * literature. Wire this to a local LLM (0.6B-class is enough) or any
+     * heuristic. Errors are swallowed (fail-soft) and `opts.context`
+     * always takes precedence over the hook.
+     */
+    enrichMemory?: (input: {
+        content: string;
+        type: MemoryType;
+        tags: string[];
+        source: MemorySource;
+        namespace: string;
+    }) => Promise<string | null | undefined> | string | null | undefined;
+    /**
+     * Deployment-specific entity aliases for fused retrieval scoring,
+     * merged over the built-in table (`BUILTIN_ENTITY_ALIASES` in
+     * `src/entity-extraction.ts`). Keys and values are matched
+     * case-insensitively. Use this to canonicalize domain vocabulary —
+     * e.g. `{ "sso": "auth", "okta": "auth" }` — so memories surface no
+     * matter which phrasing a query uses.
+     */
+    entityAliases?: Record<string, string>;
+    /**
+     * Optional LLM distillation hook for `summarizeCluster` /
+     * `consolidate`. Receives the contents of one cluster and returns an
+     * abstractive summary (a runbook-style note — the highest-value
+     * granularity in the LongMemEval-V2 ablations). When omitted or when
+     * the hook fails/returns empty, the extractive summarizer is used.
+     * Wire this to a local 0.6B–4B model for fully-offline consolidation.
+     */
+    summarizeClusterLlm?: (input: {
+        contents: string[];
+        sourceIds: string[];
+    }) => Promise<string | null | undefined> | string | null | undefined;
+    /**
+     * Hybrid-search fusion tuning forwarded to `fuseResults()` on every
+     * hybrid search. Unset fields use `src/retrieval.ts` defaults
+     * (keyword 0.8 / semantic 0.2 / K 60 — tuned for the hash baseline;
+     * stronger embedding models generally want a higher semantic weight).
+     */
+    fusion?: FusionOptions;
+    /**
+     * Path to the SQLite database file.
+     * @default "~/.memos/memos.db"
+     */
+    dbPath?: string;
+    /**
+     * Enable WAL mode for SQLite.
+     * @default true
+     */
+    wal?: boolean;
+    /**
+     * Maximum number of memories to keep before LRU eviction.
+     * Set to `0` to disable eviction.
+     * @default 0
+     */
+    maxMemories?: number;
+    /**
+     * Auto-link threshold: minimum cosine-similarity score (bag-of-words)
+     * between two nodes to automatically create an edge.
+     * Set to `0` to disable auto-linking.
+     * @default 0.3
+     */
+    autoLinkThreshold?: number;
+    /**
+     * Custom storage adapter. When provided, `dbPath` is ignored.
+     */
+    storage?: StorageAdapter;
+    /**
+     * Options forwarded to the built-in SQLite storage adapter when
+     * `storage` is not supplied. `vectorCacheEntries` bounds the in-process
+     * parsed-vector cache (default 25,000 ≈ 100MB at 1024 dims); lower it
+     * for memory-constrained hosts.
+     */
+    storageOptions?: {
+        vectorCacheEntries?: number;
+        /**
+         * How the semantic leg (`querySimilarEmbeddings`) picks which stored
+         * vectors to score.
+         *
+         * - `"exact"` (default): every candidate vector is scored. Cosine
+         *   results and rankings are bit-identical to the pre-optimisation
+         *   implementation — the scan only got cheaper per candidate
+         *   (cached norms, fused dot product, streaming bounded top-K,
+         *   early exit once a perfect match is found).
+         * - `"prefilter"`: candidates are first ranked by a coarse strided
+         *   projection and only the top `max(32, limit * 4)` are exactly
+         *   rescored. Bounds the scan on large corpora, but is APPROXIMATE:
+         *   a true neighbour ranked below the cutoff is never returned.
+         *
+         * Only the built-in SQLite adapter reads this.
+         */
+        semanticScan?: "exact" | "prefilter";
+    };
+    /**
+     * Encryption key for at-rest encryption of the SQLite database.
+     * Requires the optional `better-sqlite3-multiple-ciphers` driver
+     * (`npm i better-sqlite3-multiple-ciphers`). Falls back to the
+     * `MEMOS_KEY` environment variable. Only NEW databases get encrypted —
+     * convert an existing plaintext DB with `memos encrypt`.
+     */
+    cipherKey?: string;
+    /**
+     * Interval in seconds for the TTL expiration sweep.
+     * Set to `0` to disable the sweep.
+     * @default 60
+     */
+    sweepInterval?: number;
+    /**
+     * Experimental feature flags.
+     */
+    experimental?: ExperimentalConfig;
+    /**
+     * Effective importance model tuning. Controls how recency decay and
+     * access reinforcement modulate the base `importance` for eviction,
+     * archival, decay-forgetting, and (since the ranking wiring) hybrid
+     * search ranking. See `ImportanceConfig` in `src/importance.ts`.
+     *
+     * OPT-IN: leaving this unset (or passing `{}`) keeps the historical
+     * behaviour byte-for-byte — raw `node.importance` is still what
+     * eviction, archival, and ranking use. Setting at least one field
+     * switches those paths to `computeEffectiveImportance()`, so an old,
+     * frequently-reinforced memory now outranks an equally-scored fresh
+     * one, and a long-untouched memory is evicted sooner.
+     */
+    importance?: ImportanceConfig;
+    /**
+     * Retrieval-quality knobs: the relevance gate (abstention + tail
+     * trimming). Off by default — see `RelevanceGateConfig.enabled` for
+     * why turning it on is an explicit opt-in.
+     */
+    retrieval?: {
+        relevanceGate?: RelevanceGateConfig;
+    };
+    /**
+     * Half-life (days) for the optional recency boost in hybrid search
+     * ranking. Only used when `experimental.recencyBoost` is enabled.
+     * @default 14
+     */
+    recencyHalfLifeDays?: number;
+    /**
+     * Embedding provider configuration for semantic and hybrid retrieval.
+     */
+    embeddings?: EmbeddingConfig;
+    /**
+     * Background embedding queue tuning. Only takes effect when an
+     * embedding provider is configured. See `EmbeddingQueueConfig`.
+     */
+    embeddingQueue?: EmbeddingQueueConfig;
+    /**
+     * Image memory (vision) configuration. Disabled by default: a bare
+     * `new MemOS()` changes nothing — no new vector rows, no new search
+     * results, no new pack bytes. See {@link VisionConfig}.
+     */
+    vision?: VisionConfig;
+}
+/**
+ * Coarse taxonomy for what an image *is*, used for filtering and prompt
+ * context — never as the type discriminator (see `metadata.image`).
+ */
+export type ImageKind = "photo" | "screenshot" | "chart" | "diagram" | "memo" | "meme" | "other";
+/**
+ * Reference form of an image carried by context packs and API results.
+ * The bytes are NEVER inlined — consumers resolve the `ref` through the
+ * blob store.
+ */
+export interface ImageAttachment {
+    /** Content-addressed key, `img_<sha256[0:12]>`. */
+    ref: string;
+    mime: string;
+    width: number;
+    height: number;
+    kind: ImageKind;
+    /** The caption text stored as the node's `content`. */
+    caption: string;
+    /** Full hex digest of the image bytes (dedupe + integrity). */
+    sha256: string;
+    /** Size of the stored blob in bytes. */
+    bytes: number;
+}
+/**
+ * The vision payload stored in `MemoryNode.metadata.image`. Presence of
+ * this key — not `type`, not a new `MemoryType` member — is what marks a
+ * node as an image memory (same discriminator pattern as
+ * `metadata.context`), so `MemoryType` exhaustiveness stays intact
+ * everywhere (sync allowlist, fidelity labels, adapters, MCP schema).
+ */
+export interface ImageMemoryMeta extends ImageAttachment {
+    /** Blob path, resolved relative to the database directory. */
+    path: string;
+    /** When the image was captured (not stored). Unix ms. */
+    capturedAt: number;
+    /** Optional conversation this image was shared in. */
+    conversationId?: string;
+    /** Who supplied the image. */
+    source: ImageSource;
+    /** Which caption production path produced the caption. */
+    captionSource: "user" | "llm" | "generated";
+}
+/** Where an image came from. */
+export type ImageSource = "user" | "agent" | "tool";
+/**
+ * CLIP leg status recorded in `metadata.clip.status`. Track A (caption →
+ * text embeddings) works regardless of this value.
+ */
+export type ClipStatus = "ready" | "pending" | "failed" | "skipped";
+/** CLIP bookkeeping recorded in `metadata.clip` when Track B is enabled. */
+export interface ClipMeta {
+    model: string;
+    dims: number;
+    status: ClipStatus;
+    /** Set when `status` is `"failed"`. */
+    error?: string;
+    /** Unix ms of the last status transition. */
+    updatedAt: number;
+}
+/**
+ * A provider that encodes images — and optionally the CLIP text side, for
+ * text→image queries.
+ *
+ * Deliberately separate from `EmbeddingProvider`: CLIP vectors live in a
+ * different vector space (and a different table) than text embeddings, so
+ * the image encoder must never be handed to the text embedding queue.
+ */
+export interface EmbedImageProvider {
+    /** Stable provider identifier, e.g. `"clip"`. */
+    readonly id: string;
+    /** Model the provider encodes with. */
+    readonly model: string;
+    /** Vector dimensionality (512 for `clip-vit-base-patch32`). */
+    readonly dimensions: number;
+    /** Encode image bytes (or a path/URL) to a normalized vector. */
+    embedImage(image: Buffer | string): Promise<EmbeddingVector>;
+    /**
+     * Encode a text query into the CLIP image space. Optional: providers
+     * that can only do image→image search leave it unimplemented, and the
+     * text→image leg silently degrades to the caption leg.
+     */
+    embedImageText?(query: string): Promise<EmbeddingVector>;
+}
+/** Image-memory configuration. Disabled by default — a bare
+ *  `new MemOS()` is byte-for-byte unchanged. */
+export interface VisionConfig {
+    /** Master switch. Default false. */
+    enabled?: boolean;
+    clip?: {
+        /** Track B opt-in. Default false (no ~350 MB model download). */
+        enabled?: boolean;
+        /** CLIP model id. Default `"Xenova/clip-vit-base-patch32"`. */
+        model?: string;
+        /** Expected dimensionality. Default 512. */
+        dimensions?: number;
+        /**
+         * Explicit image encoder. When omitted, `ClipEmbeddingProvider` is
+         * constructed lazily; when the transformers package is missing,
+         * Track B fails soft to Track A — it never throws and never
+         * substitutes a text vector.
+         */
+        embedImage?: EmbedImageProvider;
+    };
+    /** Blob store root. Default `<dbDir>/memos-images`. */
+    storeRoot?: string;
+    /** Max accepted image size in bytes. Default 5 MiB. */
+    maxImageBytes?: number;
+    /** Max edge length before re-encode is required. Default 4096. */
+    maxDimension?: number;
+}
+/**
+ * Every shape `addImageMemory` accepts, resolved by one normalizer.
+ *
+ * - `string`  → a filesystem path (or a `data:` URL, detected by prefix)
+ * - `Buffer` / `Uint8Array` → raw bytes
+ * - `{ data, mime }`        → base64 payload plus its declared MIME type
+ * - `{ url }`               → an http(s)/file/data URL to fetch
+ */
+export type ImageInput = string | Buffer | Uint8Array | {
+    data: string;
+    mime: string;
+} | {
+    url: string;
+};
+/** Options for {@link MemOS.addImageMemory}. Extends the store options. */
+export interface AddImageMemoryOptions extends Omit<CreateMemoryInput, "content"> {
+    /**
+     * The caption stored as the node's `content` — this is what text
+     * retrieval actually matches. When omitted, a generated placeholder
+     * records the kind and dimensions so the memory is still findable by
+     * tag and still resolvable.
+     */
+    caption?: string;
+    /** Coarse taxonomy override. Defaults to the MIME-derived kind. */
+    kind?: ImageKind;
+    /** When the image was captured (not stored). Defaults to now. */
+    capturedAt?: number;
+    /** Who supplied the image. Default `"user"`. */
+    imageSource?: ImageSource;
+    /** Optional conversation this image was shared in. */
+    conversationId?: string;
+}
+/** What {@link MemOS.addImageMemory} returns. */
+export interface AddImageMemoryResult {
+    /** The memory node (caption as content, `metadata.image` present). */
+    node: MemoryNode;
+    /** The image payload now carried by the node. */
+    image: ImageMemoryMeta;
+    /** Track B status: `ready` | `pending` | `skipped` | `failed`. */
+    clipStatus: ClipStatus;
+    /** True when identical bytes already existed and no new node was written. */
+    deduped: boolean;
+}
+/** Options for {@link MemOS.searchImages}. */
+export interface SearchImagesOptions {
+    limit?: number;
+    /** Minimum CLIP cosine for the image leg. Default 0.15. */
+    threshold?: number;
+    namespace?: string;
+    namespaces?: string[];
+    /** Restrict to one image kind (e.g. `"diagram"`). */
+    kind?: ImageKind;
+}
+/** Options for {@link MemOS.listImages}. */
+export interface ListImagesOptions {
+    limit?: number;
+    namespace?: string;
+}
+/** One image hit: the node, its fused score, and the attachment. */
+export interface ImageSearchResult {
+    node: MemoryNode;
+    score: number;
+    image: ImageMemoryMeta;
+}
+/**
+ * Export format options.
+ */
+export type ExportFormat = "json" | "markdown" | "obsidian";
+/**
+ * Options for exporting memories.
+ */
+export interface ExportOptions {
+    /** Export format. */
+    format?: ExportFormat;
+    /** Output directory path (for markdown/obsidian). */
+    output?: string;
+    /** Only export memories with this tag. */
+    tag?: string;
+}
+/**
+ * Result of an export operation.
+ */
+export interface ExportResult {
+    /** The format used. */
+    format: ExportFormat;
+    /** For JSON format, the serialized data. For file-based formats, the output directory. */
+    data: string;
+    /** Number of memories exported. */
+    count: number;
+}
+/**
+ * Options for importing memories.
+ */
+export interface ImportOptions {
+    /** Source format: json file path, or directory of markdown/obsidian files. */
+    source: string;
+    /** Import format: json, markdown, or obsidian. Auto-detected from path if omitted. */
+    format?: ImportFormat;
+}
+/**
+ * Import format options.
+ */
+export type ImportFormat = "json" | "markdown" | "obsidian";
+/**
+ * Result of an import operation.
+ */
+export interface ImportResult {
+    /** Number of memories imported. */
+    count: number;
+    /** Number of edges recreated (from wikilinks in obsidian format). */
+    edgesCreated: number;
+}
+/**
+ * Per-harness memory count, as returned by `getHarnessCounts()` /
+ * `memos harness list`. Memories written before harness attribution
+ * existed read as `"unknown"`.
+ */
+export interface HarnessCount {
+    /** Harness slug (or `"unknown"` for unattributed rows). */
+    harness: string;
+    /** Number of memories stamped with this harness. */
+    count: number;
+}
+/** Options for `MemOS.mergeHarnessDb` (`memos harness merge`). */
+export interface HarnessMergeOptions {
+    /**
+     * When true, report the merge plan without writing anything.
+     * Default false.
+     */
+    dryRun?: boolean;
+}
+/**
+ * One source node in a harness-merge plan/result. `remapped` is true
+ * when the target DB already held a node with the same id — the source
+ * node is imported under a fresh id and every incident edge endpoint is
+ * rewritten to it.
+ */
+export interface HarnessMergeNode {
+    /** Original id in the source DB. */
+    sourceId: string;
+    /** Id under which the node is (or would be) stored in the target. */
+    targetId: string;
+    /** True when the id had to be remapped (collision in the target). */
+    remapped: boolean;
+    /** Harness that originally wrote the memory (preserved verbatim). */
+    harness: string;
+}
+/**
+ * Outcome of `MemOS.mergeHarnessDb` (`memos harness merge --from`).
+ * `dryRun: true` fills the plan fields and writes nothing.
+ */
+export interface HarnessMergeResult {
+    /** Source database path. */
+    from: string;
+    /** When true, no writes were performed. */
+    dryRun: boolean;
+    /** Source nodes examined. */
+    sourceNodes: number;
+    /** Source edges examined. */
+    sourceEdges: number;
+    /** Nodes imported (or that would be imported under `dryRun`). */
+    nodesImported: number;
+    /** Nodes whose ids collided and were remapped. */
+    nodesRemapped: number;
+    /** Edges imported (or that would be imported under `dryRun`). */
+    edgesImported: number;
+    /** Edges skipped because their endpoints were missing. */
+    edgesSkipped: number;
+    /** Per-node import plan (id mapping + preserved harness). */
+    nodes: HarnessMergeNode[];
+    /** Milliseconds the merge took. */
+    durationMs: number;
+}
+/** Events emitted by the MemoryManager. */
+export type MemOSEvent = "node:created" | "node:updated" | "node:deleted" | "edge:created" | "edge:deleted" | "link:auto" | "eviction" | "ttl:expired" | "embedding:queued" | "embedding:started" | "embedding:complete" | "embedding:failed" | "embedding:retry" | "consolidation:complete" | "trust:changed" | "validity:changed" | "facts:extracted" | "memory:reinforced" | "memory:superseded" | "memory:reverted" | "contradiction:detected";
+/** Event listener signature. */
+export type MemOSEventListener = (data: unknown) => void;
+/** Options for {@link MemOS.dedupe}. */
+export interface DedupeOptions {
+    /** Cosine-similarity threshold above which two memories are merged. Default 0.92. */
+    threshold?: number;
+    /** Only consider memories in this namespace. Default "default". */
+    namespace?: string;
+    /** If true, do not delete or merge anything. Default false. */
+    dryRun?: boolean;
+    /** Cap on how many pairs to compare. Default 10_000. */
+    maxPairs?: number;
+}
+/** A single merge performed by `dedupe()`. */
+export interface DedupeMerge {
+    /** The id of the surviving node. */
+    kept: string;
+    /** The ids of the nodes merged into the survivor and removed. */
+    removed: string[];
+    /** The reason this merge was selected. */
+    reason: string;
+    /** Mean cosine similarity across the cluster that was merged. */
+    similarity: number;
+}
+/** Result returned by {@link MemOS.dedupe}. */
+export interface DedupeResult {
+    merges: DedupeMerge[];
+    /** Number of distinct clusters that were detected. */
+    clustersFound: number;
+    dryRun: boolean;
+    durationMs: number;
+}
+/** Options for {@link MemOS.archive}. */
+export interface ArchiveOptions {
+    /** Move memories older than this many days. Default 90. */
+    afterDays?: number;
+    /** Cap on importance for archival. Default 0.3. */
+    importanceBelow?: number;
+    /** Only consider memories in this namespace. Default "default". */
+    namespace?: string;
+    /** If true, do not actually move anything. Default false. */
+    dryRun?: boolean;
+}
+/** A single archive operation. */
+export interface ArchiveMove {
+    /** The id of the moved memory. */
+    id: string;
+    /** Reason it was archived (e.g. "stale_and_low_importance"). */
+    reason: string;
+}
+/** Result returned by {@link MemOS.archive}. */
+export interface ArchiveResult {
+    moves: ArchiveMove[];
+    dryRun: boolean;
+    durationMs: number;
+}
+/** Options for {@link MemOS.summarizeCluster}. */
+export interface SummarizeClusterOptions {
+    /** Namespace to cluster. Default "default". */
+    namespace?: string;
+    /** Minimum cluster size to summarize. Default 3. */
+    minClusterSize?: number;
+    /** Cosine-similarity threshold for cluster membership. Default 0.78. */
+    threshold?: number;
+    /** If true, do not actually create summary nodes. Default false. */
+    dryRun?: boolean;
+}
+/** A cluster that was summarized. */
+export interface ClusterSummary {
+    /** The id of the newly-created summary node. Null when `dryRun: true`. */
+    summaryId: string | null;
+    /** The ids of the source nodes that the summary was derived from. */
+    derivedFrom: string[];
+    /** The generated summary text. */
+    summary: string;
+}
+/** Result returned by {@link MemOS.summarizeCluster}. */
+export interface SummarizeClusterResult {
+    clusters: ClusterSummary[];
+    dryRun: boolean;
+    durationMs: number;
+}
+/** Options for {@link MemOS.consolidate}. */
+export interface ConsolidateOptions {
+    /** Cosine threshold for dedupe. Default 0.92. */
+    dedupeThreshold?: number;
+    /** Move memories older than this many days. Default 90. */
+    archiveAfterDays?: number;
+    /** Cap on importance for archival. Default 0.3. */
+    archiveImportanceBelow?: number;
+    /** Only consider memories in this namespace. Default "default". */
+    namespace?: string;
+    /** If true, do not actually mutate anything. Default false. */
+    dryRun?: boolean;
+    /** Generate cluster summaries in addition to dedupe + archive. Default true. */
+    summarize?: boolean;
+    /** Minimum cluster size for summarization. Default 3. */
+    minClusterSize?: number;
+    /** Cosine threshold for cluster membership. Default 0.78. */
+    clusterThreshold?: number;
+    /**
+     * Run decay-based forgetting (algorithmic forgetting with an exponential
+     * recency half-life). Superseded memories are marked historical
+     * (`validTo = now`) — never deleted — so they stay queryable via
+     * `searchTemporal`. Default true.
+     */
+    decay?: boolean;
+    /** Exponential half-life (days) for the recency term of the retention score. Default 60. */
+    decayHalfLifeDays?: number;
+    /** Retention scores below this supersede the memory. Default 0.2. */
+    minRetentionScore?: number;
+    /** Only memories created more than this many days ago are eligible. Default 60. */
+    olderThanDays?: number;
+}
+/**
+ * A single memory superseded by the decay-forgetting stage of
+ * `consolidate()`.
+ */
+export interface DecaySuperseded {
+    /** The superseded memory's id. */
+    id: string;
+    /** The retention score that fell below `minRetentionScore`. */
+    score: number;
+}
+/** Options for {@link MemOS.forgetByDecay}. */
+export interface DecayForgettingOptions {
+    /** Only consider memories in this namespace. Default "default". */
+    namespace?: string;
+    /** Exponential half-life (days) for the recency term. Default 60. */
+    halfLifeDays?: number;
+    /** Retention scores below this supersede the memory. Default 0.2. */
+    minScore?: number;
+    /** Only memories untouched for this many days are eligible. Default 60. */
+    olderThanDays?: number;
+    /** If true, do not actually supersede anything. Default false. */
+    dryRun?: boolean;
+}
+/** Result returned by {@link MemOS.forgetByDecay}. */
+export interface DecayForgetResult {
+    superseded: DecaySuperseded[];
+    dryRun: boolean;
+    durationMs: number;
+}
+/** Options for {@link MemOS.history}. */
+export interface HistoryOptions {
+    /** Minimum similarity for related versions. Default 0.8. */
+    threshold?: number;
+    /** Cap on related versions per direction. Default 10. */
+    limit?: number;
+}
+/**
+ * The full version timeline for one memory: the memory itself, the older
+ * versions it replaced, the newer versions that replaced it, and any
+ * consolidated notes derived from it. Supersession is inferred from
+ * content similarity plus temporal-validity windows — superseded versions
+ * are historical (`validTo` set), the live version is not.
+ */
+export interface MemoryHistory {
+    node: MemoryNode;
+    /** Older versions this memory replaced (oldest first). */
+    supersedes: ScoredMemory[];
+    /** Newer versions that replaced this memory (newest first). */
+    supersededBy: ScoredMemory[];
+    /** Notes (note pool) derived from this memory via `derived_from` edges. */
+    derivedNotes: MemoryNode[];
+    /** All graph edges touching this memory. */
+    edges: MemoryEdge[];
+}
+/** Result returned by {@link MemOS.consolidate}. */
+export interface ConsolidateResult {
+    merges: DedupeMerge[];
+    moves: ArchiveMove[];
+    clusters: ClusterSummary[];
+    /** Memories superseded by decay-based forgetting. */
+    decayed: DecaySuperseded[];
+    dryRun: boolean;
+    durationMs: number;
+}
+/**
+ * A single message in a conversation, used by `extractFacts`.
+ */
+export interface ConversationMessage {
+    /** Speaker role: "user", "assistant", or "system". */
+    role: "user" | "assistant" | "system";
+    /** Message text content. */
+    content: string;
+    /** Optional speaker name for multi-user conversations. */
+    speaker?: string;
+}
+/**
+ * A candidate fact extracted from a conversation.
+ */
+export interface ExtractedFact {
+    /** The extracted fact text. */
+    content: string;
+    /** Inferred memory type. */
+    type: MemoryType;
+    /** Confidence in [0, 1]. */
+    confidence: number;
+    /** Optional tags inferred from context. */
+    tags: string[];
+    /** Source of the fact — usually `user_input` or `agent_inferred`. */
+    source: MemorySource;
+}
+/**
+ * Options for {@link MemOS.extractFacts}.
+ */
+export interface ExtractFactsOptions {
+    /**
+     * If true, automatically store all extracted facts with confidence >=
+     * `minConfidence`. Default false — returns candidates without storing.
+     */
+    autoStore?: boolean;
+    /** Only auto-store facts with confidence >= this threshold. Default 0.6. */
+    minConfidence?: number;
+    /** Namespace to store facts in (when autoStore is true). */
+    namespace?: string;
+    /**
+     * When true, skip facts that are near-duplicates of existing memories.
+     * Default true.
+     */
+    dedupe?: boolean;
+    /** Cosine similarity threshold for dedup. Default 0.85. */
+    dedupeThreshold?: number;
+}
+/** Result returned by {@link MemOS.extractFacts}. */
+export interface ExtractFactsResult {
+    /** Extracted fact candidates. */
+    facts: ExtractedFact[];
+    /** IDs of stored nodes (when `autoStore` is true). */
+    storedIds: string[];
+    /** Number of facts skipped as near-duplicates. */
+    duplicates: number;
+}
+/**
+ * Detailed diagnostics snapshot returned by `memos.diagnostics()`.
+ */
+export interface DiagnosticsResult {
+    /** Total number of stored memories. */
+    totalNodes: number;
+    /** Total number of edges. */
+    totalEdges: number;
+    /** Number of memories with embeddings. */
+    nodesWithEmbeddings: number;
+    /** Number of memories with temporal validity set. */
+    nodesWithValidity: number;
+    /** Number of historical (superseded) memories. */
+    historicalNodes: number;
+    /** Number of memories with a TTL. */
+    nodesWithTTL: number;
+    /** Number of expired memories pending sweep. */
+    expiredNodes: number;
+    /** Average importance across all nodes. */
+    avgImportance: number;
+    /** Average trust score across all nodes. */
+    avgTrustScore: number;
+    /** Breakdown of nodes by provenance source. */
+    bySource: Record<string, number>;
+    /** Breakdown of nodes by memory type. */
+    byType: Record<string, number>;
+    /** Breakdown of nodes by namespace. */
+    byNamespace: Record<string, number>;
+    /** Database file size in bytes. */
+    dbSizeBytes: number;
+    /** Embedding queue status, if configured. */
+    embeddingQueue?: EmbeddingQueueStatus;
+    /** Whether the storage adapter supports optional methods. */
+    storageCapabilities: {
+        peekNode: boolean;
+        evictLeastImportant: boolean;
+        saveEmbedding: boolean;
+        getAllEmbeddings: boolean;
+        setNodeNamespace: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map