@anuma/sdk 6.21.0 → 6.22.0

package/dist/memory/context.d.mts

@@ -0,0 +1,936 @@
+import { Model, Database, Collection } from '@nozbe/watermelondb';
+
+/**
+ * Options for signing messages.
+ */
+interface SignMessageOptions {
+    /** Whether to show wallet UI during signing. Default: true */
+    showWalletUIs?: boolean;
+}
+/**
+ * Type for the signMessage function that client must provide.
+ * This is typically from Privy's useSignMessage hook.
+ */
+type SignMessageFn = (message: string, options?: SignMessageOptions) => Promise<string>;
+/**
+ * Type for embedded wallet signer function that enables silent signing.
+ * For Privy embedded wallets, this can sign programmatically without user interaction
+ * when configured correctly in the Privy dashboard.
+ */
+type EmbeddedWalletSignerFn = (message: string, options?: SignMessageOptions) => Promise<string>;
+
+declare class VaultMemory extends Model {
+    static table: string;
+    content: string;
+    scope: string;
+    folderId: string | null;
+    userId: string | null;
+    embedding: string | null;
+    /** Model that produced `embedding`. Null on legacy rows (grandfathered). */
+    embeddingModel: string | null;
+    sourceChunkIds: string | null;
+    proofCount: number | null;
+    source: string | null;
+    /** W6 temporal lane — Unix ms timestamp of when the event occurred. */
+    eventTimeStart: number | null;
+    /** W6 temporal lane — Unix ms timestamp of event end (range/ongoing). */
+    eventTimeEnd: number | null;
+    /** W6 temporal lane — `point | range | ongoing | null`. */
+    eventTimeKind: string | null;
+    /** When true, the user has manually set this memory's topics; auto-extraction
+     *  leaves its entity links alone. Null on legacy rows (treated as false). */
+    topicsUserManaged: boolean | null;
+    /** The durable, synced record of this memory's topics — JSON `StoredTopic[]`.
+     *  `entity` / `memory_entity` are a device-local index over it. Null = pre-v42
+     *  (backfilled from the row's current links by the sweep). */
+    topics: string | null;
+    /** Unix ms of the last `topics` write. Separate from `updated_at`, which every
+     *  topic writer pins on purpose (recall recency) — see the schema note. */
+    topicsUpdatedAt: number | null;
+    /** The photo(s) a SERVER-EXTRACTED memory came from — JSON
+     *  `[{feed_item_id, object_key}]`, exactly the shape
+     *  GET /api/memories/published returns. Null on anything not from a photo. */
+    media: string | null;
+    /** Unix ms of the last LLM topic-extraction pass. Null = never extracted
+     *  standalone (linked legacy rows are grandfathered as extracted).
+     *  DEPRECATED (v42) — subsumed by `topics_updated_at`; see the schema note. */
+    topicsExtractedAt: number | null;
+    /** A2 supersession: newer memory id that replaced this one, or null if live. */
+    supersededBy: string | null;
+    supersededAt: number | null;
+    /** Extraction-logic version this memory was last stamped under. Null (pre-v38)
+     *  reads as 0, so a TOPICS_EXTRACTION_VERSION bump re-extracts stale rows.
+     *  DEPRECATED (v42) — subsumed by `topics_updated_at`; see the schema note. */
+    topicsExtractedVersion: number | null;
+    /** C3 re-observation watermark: Unix ms of the last retain() merge, or null. */
+    lastObservedAt: number | null;
+    /** Typed memory (PR1) — the extractor's FactType. Null on legacy/manual rows. */
+    factType: string | null;
+    /** Decay archive state (PR2) — Unix ms when archived, null when active. */
+    archivedAt: number | null;
+    /** Tier-0 security (PR3) — "quarantined" | "trusted" | null. */
+    trustTier: string | null;
+    /** People Nearby visibility: 'private' | 'public'. Null on legacy rows, and
+     *  any unrecognised value, read as 'private' — never published without opt-in. */
+    visibility: string | null;
+    /** Owner opted this memory into their own digital twin (twin-scoped only). */
+    twinOptIn: boolean | null;
+    /** Unix ms when visibility last became non-private; null while private. */
+    publishedAt: number | null;
+    /** Reserved coarse-geohash slot for landmark/Trail memories. */
+    geohash: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    isDeleted: boolean;
+}
+
+/**
+ * A canonical entity (person, place, thing) extracted from the user's
+ * conversations. Many-to-many with vault memories via {@link MemoryEntity}.
+ *
+ * Created on the write path by the auto-extraction worker (W2) when a
+ * candidate fact arrives with non-empty `entities[]`. Used at retrieval
+ * time as a 3rd RRF lane (W5 graph traversal): query entity overlap
+ * with stored memories surfaces topically-related facts that pure
+ * semantic search misses.
+ */
+declare class Entity extends Model {
+    static table: string;
+    /** Lowercased, trimmed name used for dedup and lookup. */
+    canonicalName: string;
+    /** Optional category — "person" | "place" | "thing" | "concept" | etc. */
+    kind: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Join row: a memory references an entity (and vice versa). Multiple
+ * rows per memory (one per entity) and per entity (one per memory).
+ */
+declare class MemoryEntity extends Model {
+    static table: string;
+    memoryId: string;
+    entityId: string;
+    /**
+     * User-scope for the W5 graph lane. Optional because client-side
+     * (single-user) deployments may leave it null; server-side multi-user
+     * deployments must set it so retrieval can filter cross-user IDs.
+     */
+    userId: string | null;
+    createdAt: Date;
+}
+
+/**
+ * Who put a topic on a memory. Written to `memory_vault.topics` but not yet
+ * READ anywhere — it exists so a later improvement can refresh the `auto`
+ * entries of a curated memory while leaving `user` entries alone (today
+ * `topics_user_managed` is all-or-nothing per memory) without needing a second
+ * migration or backfill. Don't build that behavior off it yet.
+ *
+ * When you do: a value written by the v42 backfill is NOT ground truth. Pre-v42
+ * rows carry no per-topic provenance, so `backfillMemoryTopicsOp` derives it
+ * from the per-memory `topics_user_managed` flag and stamps a curated legacy
+ * row's every topic `user` — see the note at that derivation.
+ * @public
+ */
+type TopicSource = "user" | "auto";
+/**
+ * One entry in `memory_vault.topics` — the durable, synced record of a memory's
+ * topics. `name` carries the CALLER's display casing, unlike
+ * {@link StoredEntity.canonicalName}, which {@link normalizeEntityName}
+ * lowercases and which has no display column: preserving casing here is the
+ * point of storing names on the memory row.
+ * @public
+ */
+interface StoredTopic {
+    name: string;
+    kind?: string;
+    source: TopicSource;
+}
+
+interface EntityOperationsContext {
+    database: Database;
+    entityCollection: Collection<Entity>;
+    memoryEntityCollection: Collection<MemoryEntity>;
+    /**
+     * Optional user-scope. When provided, `linkMemoryEntitiesOp` stamps
+     * `user_id` on new memory_entity rows and `getMemoriesByEntityNamesOp`
+     * filters lookups by it. Leave undefined for single-user clients.
+     */
+    userId?: string;
+    /**
+     * When `true`, `getMemoriesByEntityNamesOp` admits rows with
+     * `user_id = null` alongside the strict `userId` match. Set this on
+     * LokiJS (web) adapters where the v31 `unsafeExecuteSql` backfill
+     * is a no-op — pre-v31 rows otherwise become invisible to the W5
+     * lane until `backfillMemoryEntityUserIdsOp` runs. Default `false`
+     * (server / SQLite, where the migration backfill is authoritative).
+     */
+    allowUnscopedRows?: boolean;
+}
+
+/**
+ * Shared portal LLM call for the memory pipeline.
+ *
+ * The three LLM-driven steps (`extractFacts`, `consolidateMemory`,
+ * `decomposeQuery`) share the same shape: POST to `/api/v1/chat/completions`
+ * with a system+user prompt and `response_format: json_object`, parse
+ * `choices[0].message.content` as JSON, validate, return null on any failure.
+ * This helper owns the fetch+timeout+parse+log boilerplate so each caller
+ * stays focused on its prompt and validator.
+ *
+ * PROMPT CACHING. The portal inserts explicit prompt-cache breakpoints only for
+ * `anthropic/` models. Its request schema does carry OpenAI's
+ * `prompt_cache_key`, but that is a routing hint for OpenAI's own implicit
+ * cache rather than a switch that enables caching, and we deliberately don't
+ * send it: the memory pipeline runs open-weights models by default (gpt-oss for
+ * extraction/topics, ling for consolidation), and this module already has one
+ * hard lesson about OpenAI-standard fields a non-OpenAI provider hard-400s on
+ * (`response_format`, below). Revisit only with a verified per-provider gate.
+ *
+ * So on the models this pipeline actually uses, the only cache that can hit is
+ * the provider's own implicit prefix cache — which makes prefix stability the
+ * one lever a caller controls. Messages are assembled system-first (below), so
+ * every caller must pass a CONSTANT `systemPrompt` and keep all per-call
+ * material in `userMessage`: a single interpolated timestamp, id, or count in a
+ * system prompt shifts every byte after it and misses the cache on every
+ * request thereafter. The memory callers are regression-gated on that property
+ * in `promptPrefixStability.test.ts`.
+ *
+ * Whether those implicit caches hit is observable: each successful response
+ * logs the portal's reported token counts at debug level, including
+ * `portal.cached_tokens` (the prompt tokens the provider served from cache —
+ * the portal omits the field when there was no hit). See {@link logPortalUsage}.
+ *
+ * There is no batch/async-bulk route on the portal, so a backfill or reindex
+ * has no discounted-throughput path either; its only levers are the same stable
+ * prefix and caller-side batching (e.g. topicExtract's 10-memories-per-call).
+ */
+
+/**
+ * Auth for portal LLM calls (extraction, consolidation, decomposition,
+ * reflection). Mirrors `memoryEngine`'s `EmbeddingOptions` dual-auth:
+ *
+ * - `apiKey`: For direct API keys (uses x-api-key header)
+ * - `getToken`: For Privy identity tokens (uses Authorization: Bearer header)
+ *
+ * At least one of `apiKey` or `getToken` must be provided (enforced at
+ * runtime); `apiKey` takes precedence when both are set.
+ *
+ * @public
+ */
+interface PortalLlmAuth {
+    /** Direct API key — sent as `x-api-key` (server-side / CLI usage). Wins when both are provided. */
+    apiKey?: string;
+    /** Function to get an auth token (e.g., Privy's getIdentityToken). Token is sent as `Authorization: Bearer`. */
+    getToken?: () => Promise<string | null>;
+}
+
+/**
+ * Linear recency decay multiplier — applied post-fusion to nudge fresh
+ * memories above stale ones with otherwise comparable scores.
+ *
+ * Formula:
+ *   multiplier(ageDays) = max(floor, 1 - perYearDecay * (ageDays / 365))
+ *
+ * Memories without an `updatedAt` get a neutral 0.5 (Hindsight pattern —
+ * neither boost nor penalty when freshness is unknown).
+ */
+interface RecencyOptions {
+    /** Override "now" — useful for deterministic tests and back-dated benchmarks. */
+    now?: Date;
+    /** Linear decay slope per year. Default 0.2 (1y → 0.8x, 4.5y → floor). */
+    perYearDecay?: number;
+    /** Lower bound on the multiplier so very old memories don't vanish. Default 0.1. */
+    floor?: number;
+    /** Multiplier returned when `updatedAt` is missing. Default 0.5 (neutral). */
+    noDateMultiplier?: number;
+}
+
+/**
+ * How a fact's evidence has been evolving.
+ *
+ * - `new` — first seen inside the recent window, few proofs yet.
+ * - `strengthening` — established fact re-observed recently (rising density).
+ * - `stable` — known for a while, still observed inside the stale window.
+ * - `weakening` — quiet for ≥30 and <90 days after having been observed.
+ * - `stale` — no observation in ≥90 days.
+ */
+type ObservationTrend = "new" | "strengthening" | "stable" | "weakening" | "stale";
+
+/**
+ * Unified memory layer types — the Recall / Retain API.
+ *
+ * This module defines the public surface for the new unified memory layer
+ * that sits above `memoryVault` (curated facts) and `memoryEngine` (raw
+ * conversation chunks). Callers should prefer these types over the legacy
+ * `VaultSearchResult` / `ChunkSearchResult` shapes; the underlying stores
+ * may converge later, the API will not.
+ */
+
+type MemoryKind = "fact" | "chunk";
+/**
+ * Budget controls retrieval depth/cost. Higher budgets enable more
+ * candidate sources and the cross-encoder reranker.
+ *
+ * - `low`: cosine + BM25 + recency. No reranker. Mobile default.
+ * - `mid`: + cross-encoder rerank.
+ * - `high`: + multi-hop graph traversal. LLM-free — query decomposition
+ *   (when wanted) lives in the tool/agent layer ({@link createRecallTool}),
+ *   not inside `recall()` itself (719/B4).
+ */
+type Budget = "low" | "mid" | "high";
+interface ScoreBreakdown {
+    /** Raw cosine similarity. Set only when callers compute it explicitly
+     * (e.g. cosine-only `useFusion: false` search); the fusion path sets
+     * {@link fused} instead so the label stays honest. */
+    cosine?: number;
+    /** Composite score from the fused ranker (cosine + BM25 + RRF + recency
+     * + proof boost). What `RankedMemory.score` carries when the fusion
+     * pipeline ran. */
+    fused?: number;
+    bm25?: number;
+    recency?: number;
+    rerank?: number;
+    /** Final RRF rank (1-indexed) before any boost. */
+    rrfRank?: number;
+}
+/**
+ * A ranked memory returned by `recall()`. Shape is uniform across kinds —
+ * `kind` discriminates, kind-specific metadata is optional.
+ */
+interface RankedMemory {
+    id: string;
+    kind: MemoryKind;
+    content: string;
+    score: number;
+    scoreBreakdown?: ScoreBreakdown;
+    sourceChunkIds?: string[];
+    proofCount?: number;
+    source?: string;
+    folderId?: string | null;
+    /**
+     * C3 re-observation watermark (Unix ms). Null/undefined when the fact
+     * has never been merge-reinforced since the column landed.
+     */
+    lastObservedAt?: number | null;
+    /**
+     * C2 observation-trend label derived from createdAt / lastObservedAt /
+     * proofCount over 30/90-day windows. Fact-only; omitted for chunks.
+     */
+    observationTrend?: ObservationTrend;
+    /**
+     * Anchored event-time for the fact (the date the underlying event
+     * occurred, not the write time). When present, the recall executor
+     * surfaces it to the LLM as `(event: YYYY-MM-DD)` so the answer model
+     * can do date arithmetic for temporal-reasoning questions. Null /
+     * undefined means the fact has no anchored date.
+     */
+    eventTimeStart?: number | null;
+    eventTimeEnd?: number | null;
+    eventTimeKind?: "point" | "range" | "ongoing" | null;
+    /**
+     * Typed memory (PR1) — the extractor's FactType classification for this
+     * fact, threaded through the same channel as the event-time anchors so
+     * recall results (and UI) can show the type without a second DB read.
+     * Null/undefined on legacy/untyped/manual facts. Kept as a loose string
+     * (not narrowed to FactType) since it originates from a stored column.
+     */
+    factType?: string | null;
+    conversationId?: string;
+    messageId?: string;
+    role?: "user" | "assistant";
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface RecallOptions {
+    /** Which kinds to search. Default: ['fact']. */
+    types?: MemoryKind[];
+    /** Max items returned. Default: 8. */
+    limit?: number;
+    /** Token budget for the result; greedy-truncates after ranking. Not yet enforced; reserved for W1. */
+    maxTokens?: number;
+    /** Search depth. Default: 'low'. */
+    budget?: Budget;
+    /** Include source chunks for fact memories that have provenance. Default: false. */
+    includeChunks?: boolean;
+    /** Vault scope filter. Vault-only. */
+    scopes?: string[];
+    /** Vault folder filter. Vault-only. */
+    folderId?: string | null;
+    /**
+     * Typed memory (PR1) — restrict fact recall to these FactTypes. Optional
+     * and no-op when unset (all types are eligible). Vault-only.
+     */
+    factTypes?: FactType[];
+    /** Restrict fact candidates BEFORE ranking. Empty means no facts. When set,
+     * unrestricted chunk search is disabled; it must not escape a topic scope.
+     * Asking for `"chunk"` alongside this yields no excerpts and reports
+     * `"chunks-scope-restricted"` on {@link RecallDiagnostics.degraded}. */
+    memoryIds?: string[];
+    /**
+     * PR5 — optional per-FactType score multiplier applied in the fusion boost
+     * stage (e.g. boost `identity`/`constraint`, down-weight `ongoing_context`).
+     * A type absent from the map (and untyped rows) uses 1.0, so an empty/omitted
+     * map is a no-op (uniform weighting). Vault-only.
+     */
+    factTypeWeights?: Partial<Record<FactType, number>>;
+    /** Restrict chunk search to one conversation. Chunk-only. */
+    conversationId?: string;
+    /** Exclude one conversation from chunk search. Chunk-only. */
+    excludeConversationId?: string;
+    /** Drop results below this score. Default: 0.1 for facts, 0.5 for chunks (mirrors today's defaults). */
+    minScore?: number;
+    /**
+     * Pre-decomposed facet queries for the composite ranker. When ≥2 are
+     * supplied, the vault lane runs `rankComposite` over them (no LLM call
+     * inside `recall()` — 719/B4). Callers that still want LLM rewrite
+     * (e.g. {@link createRecallTool} at `budget: 'high'`) call
+     * `decomposeQuery` themselves and pass the result here. A single entry
+     * (or omitting this) keeps the single-query path.
+     */
+    subQueries?: string[];
+    /**
+     * Auth + endpoint for optional LLM helpers that reuse portal auth —
+     * currently {@link RecallOptions.graphRefine} neighbor selection.
+     * Query decomposition is **not** driven by this field inside `recall()`
+     * (719/B4); {@link createRecallTool} reads the same shape from
+     * `RecallToolOptions.decomposeOptions` for tool-layer rewrite.
+     *
+     * Callers that still pass `{ budget: 'high', decomposeOptions }` without
+     * {@link RecallOptions.subQueries} keep compiling but no longer rewrite —
+     * `recall()` emits `decompose-moved` on {@link RecallDiagnostics.degraded}
+     * so upgrades without a changelog read still leave a telemetry breadcrumb.
+     *
+     * Auth is the dual pattern — one of `apiKey` / `getToken` is required;
+     * see {@link PortalLlmAuth}.
+     */
+    decomposeOptions?: PortalLlmAuth & {
+        baseUrl?: string;
+        model?: string;
+    };
+    /**
+     * Reference "now" for resolving relative temporal phrases in the
+     * query ("last week", "yesterday", "N days ago"). Default: `Date.now()`.
+     * Override for back-dated evaluation harnesses (bench corpora dated
+     * 2021–2023) and for deterministic tests — otherwise the W6 lane
+     * resolves windows in 2026 and never overlaps stored event_time.
+     */
+    now?: number;
+    /**
+     * Best-effort observability hook. Called once per `recall()` with per-lane
+     * timings, lane counts, and soft-degradation signals — the raw material for
+     * tuning latency/quality and for wiring recall telemetry to PostHog. Invoked
+     * synchronously just before `recall()` returns; a throwing callback is
+     * swallowed (diagnostics must never break retrieval). Off unless provided.
+     */
+    onDiagnostics?: (diagnostics: RecallDiagnostics) => void;
+    /** Number of candidates fed to the cross-encoder rerank stage. Default: 5;
+     *  was 30 until 2026-08-13 — see anuma-ai/sdk#845. */
+    rerankTopN?: number;
+    /** Multiplicative cross-encoder blend weight. Default: 0.1. */
+    ceWeight?: number;
+    /** Recency boost slope in the fused ranker. Default: 1.0. */
+    recencyAlpha?: number;
+    /** Recency decay curve overrides (per-year decay slope, floor, no-date multiplier). */
+    recency?: RecencyOptions;
+    /** Apply MMR diversification after ranking (rerank pipeline only). Default: false. */
+    mmr?: boolean;
+    /** Supersession score-gap transfer factor. Default: 0.8. */
+    supersessionBoost?: number;
+    /** Hard cap on the supersession candidate window. Default: 50. */
+    supersessionWindow?: number;
+    /** Proof-count log-boost scale. Default: 0.1. */
+    proofCountAlpha?: number;
+    /** Divisor mapping BM25 scores to the admission floor. Default: 50. */
+    bm25AdmissionDivisor?: number;
+    /** RRF smoothing constant for lane fusion (facts × chunks and side lanes). Default: 60. */
+    rrfK?: number;
+    /**
+     * Decrypt vault memory content only for the top-N ranked candidates
+     * instead of the whole vault. Forwarded verbatim to the vault search
+     * pipeline's `MemoryVaultSearchOptions`. Default: off (legacy
+     * whole-vault decrypt path).
+     */
+    decryptLast?: boolean;
+    /** Total graph hops incl. the seed lookup (hop 1). Default: 1 (seed only). */
+    maxHops?: number;
+    /** Max neighbor entities expanded per hop. Default: 8. */
+    entityFanout?: number;
+    /** Hard cap on accumulated memory IDs across all hops. Default: 64. */
+    nodeBudget?: number;
+    /**
+     * PR5 — enable LLM graph path-refinement: at each traversal hop a model picks
+     * which neighbor entities to expand instead of pure co-occurrence ranking.
+     * Opt-in (default false); only active on the `high` budget (needs the
+     * `traverse` flag) AND when `decomposeOptions` is set (reuses that auth).
+     * Falls back to deterministic co-occurrence order on any error. Adds ≤1 LLM
+     * call per expansion hop.
+     */
+    graphRefine?: boolean;
+}
+interface RecallResult {
+    memories: RankedMemory[];
+    /** Diagnostic: budget actually used (may downgrade if reranker fails). */
+    usedBudget: Budget;
+    /** Diagnostic: was the reranker invoked? */
+    reranked: boolean;
+    /** Diagnostic: total candidates considered before truncation. */
+    candidateCount: number;
+    /** Diagnostic: total memories in the vault when fact lane was queried. */
+    vaultSize?: number;
+}
+/** Soft-degradation signals surfaced via {@link RecallDiagnostics.degraded}. */
+type RecallDegradation = 
+/** Rerank was requested (budget mid/high) but the cross-encoder didn't run
+ *  this call — unavailable (e.g. React Native) or a transient failure. */
+"rerank-unavailable"
+/**
+ * @deprecated 719/B4 moved query decomposition out of `recall()`. Budget
+ * `high` no longer requires `decomposeOptions` and this signal is never
+ * emitted. Prefer `"decompose-moved"` for the upgrade breadcrumb. Kept in
+ * the union so existing telemetry consumers stay typed.
+ */
+ | "decompose-unavailable"
+/**
+ * `budget: 'high'` with `decomposeOptions` set but no usable
+ * {@link RecallOptions.subQueries}. Pre-B4 this call shape triggered LLM
+ * rewrite inside `recall()`; post-B4 it stays on the single-query high
+ * path (rerank + graph) and callers must pass facets (or use
+ * {@link createRecallTool}). Surfaced so silent quality regressions show
+ * up in diagnostics instead of looking healthier than before.
+ */
+ | "decompose-moved"
+/** There was no usable cosine lane, so results were ranked on BM25 (lexical)
+ *  alone: either the query embedding failed (or came back empty), or no
+ *  candidate had a vector to score against it because the row (re)embed failed.
+ *  Also set when the chunk lane — cosine-only, with no lexical equivalent — was
+ *  skipped for the same reason. The embeddings provider is a single upstream
+ *  with no fallback, so this is a whole-provider outage rather than a per-item
+ *  miss — expect a quality drop, not a total loss.
+ *
+ *  NOT set for a partial failure that leaves cosine running (a sub-query embed
+ *  failing back to the single-query path, or a row batch failing while other
+ *  rows keep usable vectors) — those are logged, not reported, so this stays a
+ *  reliable outage signal rather than a general embedding-error counter. */
+ | "embeddings-unavailable"
+/** The W5 graph (entity) side lane threw and was dropped. Auxiliary, so recall
+ *  still returned — but its RRF signal is missing from the ranking, and until
+ *  this existed the drop was a log line and nothing else. */
+ | "graph-lane-failed"
+/** The W6 temporal side lane threw and was dropped. Same posture as the graph
+ *  lane: recall still returned, ranked without the temporal signal. */
+ | "temporal-lane-failed"
+/** {@link RecallOptions.memoryIds} was set and `types` asked for `"chunk"`.
+ *  Conversation excerpts have no equivalent membership filter, so running the
+ *  chunk lane would escape the topic/folder scope — it is dropped instead.
+ *  Without this signal a scoped caller asking for excerpts got an empty
+ *  result indistinguishable from "the vault had no match". */
+ | "chunks-scope-restricted";
+/**
+ * Why a recall returned nothing. `""` when it returned something, so the field
+ * is always present and groupable rather than being absent on the healthy path.
+ *
+ * The four are different problems: an empty query is a caller bug, no-lanes is a
+ * context wiring bug (the requested kinds have no store), vault-empty is a new
+ * user, and no-candidates is the only one that is about retrieval quality. They
+ * were previously indistinguishable from outside — every one reported
+ * `candidateCount: 0`.
+ */
+type RecallEmptyReason = "" | "empty-query" | "no-lanes" | "vault-empty" | "no-candidates";
+/**
+ * Per-call recall observability payload (see {@link RecallOptions.onDiagnostics}).
+ * All timings are wall-clock milliseconds. Lane counts are post-dedupe,
+ * pre-fusion. Intended to be forwarded to a metrics sink (e.g. PostHog).
+ */
+interface RecallDiagnostics {
+    /** Budget actually executed (may have downgraded from the requested one). */
+    usedBudget: Budget;
+    /** Whether the cross-encoder actually reranked the fact lane this call. */
+    reranked: boolean;
+    /** Total candidates considered before truncation. */
+    candidateCount: number;
+    /** Total vault size when the fact lane ran (absent if it didn't). */
+    vaultSize?: number;
+    /**
+     * Which vault read path the fact lane actually executed: `true` for the
+     * projected key scan that decrypts only the admission window, `false` for the
+     * legacy whole-vault load. Absent when the fact lane didn't run.
+     *
+     * Reported because "the option was passed" and "the branch ran" are different
+     * facts, and #845 needed the second one: the projected path was enabled in
+     * production and the p50 did not move, with no way to tell a flag that never
+     * reached the bundle from a projection that isn't cheaper at that vault size.
+     */
+    decryptLast?: boolean;
+    /**
+     * Rows the fact lane paid to decrypt. Absent when it didn't run.
+     *
+     * Read against {@link RecallDiagnostics.vaultSize} — that ratio is the whole
+     * point. `decryptLast` true with `vaultRowsDecrypted` ≈ `vaultSize` means the
+     * admission window is admitting the entire vault and the projection is buying
+     * nothing. Far below `vaultSize` with latency unchanged means the decrypt was
+     * never the cost.
+     */
+    vaultRowsDecrypted?: number;
+    /**
+     * Rows the fact lane had to re-embed through the portal because their stored
+     * vector was unusable — stale `embedding_model`, wrong dimension, or
+     * unparseable. Absent when the fact lane didn't run.
+     *
+     * Expected to be 0 on a healthy vault: rows are embedded at write time and the
+     * re-embed writes the current model back, so a persistently non-zero value
+     * means the writeback is not sticking and every turn is paying for it. On the
+     * LEGACY read path this batch is uncapped, so it can be the whole vault.
+     */
+    vaultRowsEmbedded?: number;
+    /** Facts the fact lane returned (post-dedupe, pre-fusion). */
+    factCount: number;
+    /** Chunks the chunk lane returned (post-dedupe, pre-fusion). */
+    chunkCount: number;
+    /**
+     * Memories actually RETURNED — `memories.length` after fusion, cross-lane
+     * dedup and the `limit` slice.
+     *
+     * `candidateCount` is what was considered; this is what the caller got, and
+     * the two are routinely far apart (the fact lane pulls `limit * 2` when fusing).
+     * Every consumer that wanted "how many memories did this turn actually get"
+     * was reading `candidateCount` and overcounting.
+     */
+    admittedCount: number;
+    /** Highest score among the returned memories; -1 when none were returned. */
+    topScore: number;
+    /** Lowest score among the returned memories; -1 when none were returned. */
+    lowestAdmittedScore: number;
+    /**
+     * The similarity floor the lane that produced these scores actually applied:
+     * the fact lane's when it RETURNED results, otherwise the chunk lane's, and
+     * **-1 when neither ran** (empty query, unwired context). Gated on results
+     * rather than on the lane running, because a fact lane that ran and came
+     * back empty filtered none of the scores in the payload — reporting its
+     * 0.1 default against chunks that cleared 0.5 corrupted the telemetry.
+     * When NOTHING was admitted, the floor a lane did apply is still reported:
+     * "searched at this floor, found nothing" is the useful reading.
+     *
+     * Per-lane rather than one constant because the two defaults differ (0.1 fact
+     * / 0.5 chunk), so a single seeded value reported a floor that a chunk-only
+     * recall never applied. Reported next to the scores because the scores alone
+     * cannot say what they cleared.
+     */
+    minScoreApplied: number;
+    /**
+     * Whether the `limit` cut an ELIGIBLE result — recorded at the cut, not
+     * derived from `candidateCount > limit`. In the fused path `candidateCount`
+     * counts before provenance suppression, so a recall whose suppressed chunks
+     * brought it under the limit would otherwise report a truncation that never
+     * happened.
+     */
+    truncated: boolean;
+    /** Memory ids the W5 graph (entity) side lane contributed to the fusion. */
+    graphLaneCount: number;
+    /** Memory ids the W6 temporal side lane contributed to the fusion. */
+    temporalLaneCount: number;
+    /** Why nothing came back — see {@link RecallEmptyReason}. `""` when something did. */
+    emptyReason: RecallEmptyReason;
+    /** Wall-clock phase timings (ms). */
+    timings: {
+        /** Whole `recall()` call. */
+        total: number;
+        /** Parallel query-embed + graph/temporal side-lane build. */
+        prep: number;
+        /** Vault fact-lane search (`searchVaultMemoriesWithSize`). */
+        factLane: number;
+        /**
+         * The cross-encoder's share of {@link factLane} — wall-clock spent inside
+         * `rerankPairs`. Billed even when the CE threw partway through, because a
+         * rerank that burned three seconds and then failed still cost them.
+         *
+         * A SUBSET of `factLane`, not a sibling: read `factLane - rerank` for
+         * everything else the lane did (query embed, vault read, fused ranking).
+         * 0 when the CE did not run; `reranked` is what distinguishes that from a
+         * rerank that cost nothing.
+         *
+         * Exists because #845 spent three rounds arguing about which stage inside
+         * the fact lane dominated — whole-vault read, then admission window, then
+         * the CE — with one aggregate number for all of them. Every hypothesis was
+         * an inference; this makes the question a query.
+         */
+        rerank: number;
+        /**
+         * The query embed's share of {@link factLane} — one portal round trip.
+         *
+         * Also a SUBSET of `factLane`. Together with `rerank` this makes the lane
+         * decomposable: `factLane - queryEmbed - rerank` is the local work (vault
+         * read, decrypt, BM25/cosine fusion), and each of the three implies a
+         * completely different fix.
+         *
+         * 0 when the lane returned before embedding, which includes every empty
+         * vault — `prepareVaultCandidates` short-circuits first. That is why the
+         * fast `vault_size = 0` population never established a baseline for this
+         * cost, and why the ~850ms floor on the smallest NON-empty vaults had no
+         * attributable owner.
+         */
+        queryEmbed: number;
+        /** Chunk-lane search (`searchChunksOp`). */
+        chunkLane: number;
+        /** Cross-lane RRF fusion + provenance dedup after both lanes. */
+        fuse: number;
+    };
+    /** Soft-degradation signals that fired this call (empty when clean). */
+    degraded: RecallDegradation[];
+}
+
+/**
+ * Auto-extraction worker — W2.
+ *
+ * After each assistant turn, this pipeline reads the recent conversation,
+ * asks an LLM to identify durable user facts, and writes them to the
+ * vault via retain(). The user never needs to ask Anuma to remember
+ * something — durable facts are captured automatically.
+ *
+ * Two-stage pipeline (extract → retain). The retain step uses
+ * write-time auto-merge (W4) so the same fact re-observed in a later
+ * conversation increments proof_count instead of duplicating.
+ *
+ * Spec: see `tasks/hackathon/auto-extraction-prompt.md`.
+ */
+
+declare const FACT_TYPES: readonly ["identity", "preference", "relationship", "plan", "ongoing_context", "constraint", "other"];
+type FactType = (typeof FACT_TYPES)[number];
+
+/**
+ * LEGACY. This column no longer decides anything.
+ *
+ * `scope === 'shared'` is now the single publication axis: it means the memory
+ * is on the People Nearby profile, its text goes to the nearby server, and it
+ * may inform what strangers see. `scope: 'private'` means it is not. There is
+ * no second control, and scope no longer gates model access either — every
+ * model tier reads every memory. Do NOT reason about publication from this
+ * type; read `scope`.
+ *
+ * The column survives in the schema and is still stamped on writes so that
+ * stored rows stay readable by builds that predate the change. Nothing on a
+ * current build reads it to make a decision.
+ *
+ * Values, kept for tolerance of already-stored data:
+ * - `private`: local-only (a null column reads as private)
+ * - `public`: the row was published
+ *
+ * TWO TIERS ONLY (decided 2026-07-27). An earlier design had a middle
+ * `matchable` tier that published a memory's embedding while keeping its text
+ * on-device; it was dropped. Any unrecognised stored value — including a
+ * `matchable` row written by a pre-release build — reads as `private`, which is
+ * the fail-safe direction: it un-publishes rather than exposes.
+ */
+type VaultMemoryVisibility = "private" | "public";
+interface StoredVaultMemory {
+    /** WatermelonDB internal ID */
+    uniqueId: string;
+    /** Plain text memory content */
+    content: string;
+    /** Scope for partitioning memories (e.g., "private", "shared") */
+    scope: string;
+    /** Folder ID for organization, null if unfiled */
+    folderId: string | null;
+    /** User ID for multi-user server-side scoping, null on client */
+    userId: string | null;
+    /** JSON-stringified embedding vector, null if not yet computed */
+    embedding: string | null;
+    /** Model that produced `embedding`. Null on legacy rows (grandfathered as
+     * compatible with the current model). */
+    embeddingModel: string | null;
+    /** JSON-stringified array of source message IDs this fact was extracted from. */
+    sourceChunkIds: string[] | null;
+    /** Times this fact has been re-observed (for ranking + UX badges). */
+    proofCount: number | null;
+    /** How the memory was created: manual | auto-extracted | capsule | photo. */
+    source: string | null;
+    /** The photo(s) a SERVER-EXTRACTED memory was read out of. Null on every
+     * memory that did not come from a photo. See {@link PhotoMediaRef}.
+     *
+     * OPTIONAL rather than required: every read path sets it (the row mappers
+     * always call parseMedia), but making it required would be a compile-break
+     * for any caller that CONSTRUCTS a StoredVaultMemory — fixtures, mocks, and
+     * anything downstream — for a field that is null on all but photo rows. */
+    media?: PhotoMediaRef[] | null;
+    /** W6 temporal lane — Unix ms when the event occurred (point/start of range). */
+    eventTimeStart: number | null;
+    /** W6 temporal lane — Unix ms when the event ended (range only). */
+    eventTimeEnd: number | null;
+    /** W6 temporal lane — `point | range | ongoing | null`. */
+    eventTimeKind: string | null;
+    /** When true, the user has manually set this memory's topics (entity links);
+     * auto-extraction leaves them alone. False on legacy/auto rows. */
+    topicsUserManaged: boolean;
+    /** The memory's topics as the DURABLE, synced record — `entity` /
+     * `memory_entity` are a device-local index over it. Null = pre-v42, no record
+     * yet; `[]` = a record of "no topics". */
+    topics: StoredTopic[] | null;
+    /** Unix ms of the last `topics` write, or null if never written. Separate from
+     * `updatedAt`, which topic writes deliberately pin (recall recency). */
+    topicsUpdatedAt: number | null;
+    /** Unix ms of the last LLM topic-extraction pass over this memory's content.
+     * Null = never extracted standalone; rows that already carry entity links
+     * are grandfathered as extracted (see getMemoriesNeedingTopicExtractionOp).
+     * DEPRECATED (v42) — subsumed by `topicsUpdatedAt`; see the schema note. */
+    topicsExtractedAt: number | null;
+    /** Write-time supersession (A2): id of the newer memory that replaced this
+     * one (incompatible-value update, e.g. "Lives in Portland" → "Lives in SF").
+     * Null = live. Superseded rows are excluded from recall/dedup by default but
+     * kept for history + the read-time fallback. */
+    supersededBy: string | null;
+    /** Unix ms when this memory was superseded. Null when live. */
+    supersededAt: number | null;
+    /** Extraction-logic version this memory was last stamped under. Null (pre-v38)
+     * reads as 0, so a TOPICS_EXTRACTION_VERSION bump re-extracts stale rows.
+     * DEPRECATED (v42) — subsumed by `topicsUpdatedAt`; see the schema note. */
+    topicsExtractedVersion: number | null;
+    /** C3 re-observation watermark: Unix ms of the last retain() merge into this
+     * fact. Distinct from `updatedAt` (which merges preserve). Null = never
+     * re-observed since the column was added; synthesis falls back to
+     * `updatedAt` in that case. */
+    lastObservedAt: number | null;
+    /** Typed memory (PR1) — the extractor's FactType for this fact, or null on
+     * legacy/manual/untyped rows. Plaintext string (not narrowed to FactType
+     * here since the DB can hold any stored value). */
+    factType: string | null;
+    /** Decay archive state (PR2) — Unix ms when archived, or null when active. */
+    archivedAt: number | null;
+    /** Tier-0 security (PR3) — "quarantined" | "trusted" | null. */
+    trustTier: string | null;
+    /** People Nearby cross-user visibility. Null column reads as "private". */
+    visibility: VaultMemoryVisibility;
+    /** Owner opted this memory into their own digital twin even when otherwise
+     * private (twin-scoped only — never indexed for matching, never displayed). */
+    twinOptIn: boolean;
+    /** Unix ms when visibility last became non-private; null while private. */
+    publishedAt: number | null;
+    /** Reserved coarse-geohash slot for landmark/Trail memories. */
+    geohash: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    isDeleted: boolean;
+}
+/**
+ * A photo a server-extracted memory came from, as
+ * GET /api/memories/published returns it in `media[]`.
+ *
+ * Both identifiers travel because both are needed: `feedItemId` is the server's
+ * handle for the photo, and `objectKey` is what a client turns into a CDN URL
+ * without another round-trip per memory.
+ */
+interface PhotoMediaRef {
+    feedItemId: number;
+    objectKey: string | null;
+}
+
+interface VaultMemoryOperationsContext {
+    database: Database;
+    vaultMemoryCollection: Collection<VaultMemory>;
+    walletAddress?: string;
+    signMessage?: SignMessageFn;
+    embeddedWalletSigner?: EmbeddedWalletSignerFn;
+    /** When set, operations scope to this user (server-side multi-user). */
+    userId?: string;
+    /** Optional extraction source eligibility check, executed inside the writer.
+     * Must only read the database (must not start another writer). */
+    canWrite?: () => Promise<boolean>;
+    /**
+     * Asserts this context runs against a physically single-tenant database — one
+     * where every row belongs to the same owner (the per-wallet client DBs, which
+     * hold exactly one wallet's rows written with `user_id = null`). This is the
+     * ONLY thing that makes the decay sweep's unscoped scan/archive/delete safe
+     * without a `userId`: see {@link assertVaultScopeForSweep}. A shared /
+     * multi-tenant DB must NOT set this — it must scope by `userId` instead.
+     * `walletAddress` presence alone is NOT a substitute (the sweep query filters
+     * by `user_id` only, so a bare `walletAddress` on a shared DB would sweep
+     * every tenant).
+     */
+    singleTenant?: boolean;
+    /**
+     * When set, vault delete ops cascade to memory_entity rows pointing at
+     * the deleted memories. Without this the W5 graph lane keeps returning
+     * IDs of soft-deleted memories and the join table grows unbounded.
+     */
+    entityCtx?: EntityOperationsContext;
+}
+declare function getAllVaultMemoriesOp(ctx: VaultMemoryOperationsContext, options?: {
+    scopes?: string[];
+    since?: Date;
+    limit?: number;
+    folderId?: string | null;
+    /**
+     * Include soft-deleted memories in the result (each carries
+     * `isDeleted: true`). Default `false` — deleted rows are excluded, as
+     * they are from every other read path. Used by the Memory Graph to
+     * render "forgotten" nodes; ordinary consumers should leave this off.
+     */
+    includeDeleted?: boolean;
+    /** Include archived (decayed) memories. Default `false` (PR1 choke point). */
+    includeArchived?: boolean;
+    /** Include quarantined memories. Default `false` (PR1 choke point). */
+    includeQuarantined?: boolean;
+    /** Typed memory (PR1) — restrict to these fact types. Omit for no filter. */
+    factTypes?: string[];
+    memoryIds?: string[];
+    /**
+     * Include A2-superseded memories (each carries `supersededBy`). Default
+     * `false` — superseded rows are excluded, as they are from recall/dedup.
+     * Used by a "memory history" view to render retired facts.
+     */
+    includeSuperseded?: boolean;
+    /**
+     * Filter by People Nearby visibility. Legacy rows with a NULL column
+     * count as "private". Used by the publish reconciler to fetch the
+     * published set to diff against the server index.
+     */
+    visibility?: VaultMemoryVisibility[];
+}): Promise<StoredVaultMemory[]>;
+
+type MemoryContextLane = "profile" | "fact" | "episode" | "session";
+interface MemoryContextItem {
+    id: string;
+    content: string;
+    score: number;
+    lane: MemoryContextLane;
+    sourceIds: string[];
+    /** Ranked fact evidence, retained when profile deduplication wins placement. */
+    recalled?: boolean;
+}
+interface MemoryContextOptions {
+    query: string;
+    recall: (query: string, options: RecallOptions) => Promise<RecallResult>;
+    loadFacts?: ((options: Parameters<typeof getAllVaultMemoriesOp>[1]) => Promise<StoredVaultMemory[]>) | null;
+    loadSessionRefs?: (() => Promise<Array<{
+        memoryId: string;
+        score: number;
+    }>>) | null;
+    recallOptions?: RecallOptions;
+    /** Topic membership is applied before ranking and to every context lane. */
+    memoryIds?: string[];
+    /** Character budget for contents (formatting overhead is excluded). Default 12000. */
+    maxChars?: number;
+    includeEpisodes?: boolean;
+    onDegraded?: (lane: MemoryContextLane, error: unknown) => void;
+}
+interface MemoryContextResult {
+    items: MemoryContextItem[];
+    ranked: boolean;
+    rankedCount: number;
+    degraded: MemoryContextLane[];
+    truncated: boolean;
+}
+/** Only skip confidently trivial utterances. Word counts reject useful short
+ * queries and languages whose writing does not separate words with spaces.
+ *
+ * The stoplist is an exact-match allowance for greetings and acknowledgments,
+ * not a language model: anything not listed still recalls, so a missing
+ * language costs a wasted lookup, never a missed memory. Kept to the handful of
+ * forms that cannot carry a fact in the languages the app ships in. */
+declare function shouldRecallMemory(query: string): boolean;
+/** Assemble bounded stable/dynamic profile, relevant facts, source excerpts and
+ * prior-turn facts. Lane failures are isolated: an outage cannot replace a
+ * legitimate empty search with unrelated vault contents. */
+declare function assembleMemoryContext(options: MemoryContextOptions): Promise<MemoryContextResult>;
+
+export { type MemoryContextItem, type MemoryContextLane, type MemoryContextOptions, type MemoryContextResult, assembleMemoryContext, shouldRecallMemory };