@melandlabs/memory-store 1.3.6 → 1.3.8

package/dist/config-BuWr-nvt.d.ts

@@ -1,988 +0,0 @@
-import * as _melandlabs_memory_consolidation from '@melandlabs/memory-consolidation';
-import { MemoryApplicabilityContext } from '@melandlabs/memory-consolidation';
-import * as _melandlabs_contracts_peer from '@melandlabs/contracts/peer';
-import { Peer } from '@melandlabs/contracts/peer';
-import { FactType } from '@melandlabs/contracts';
-import { DerivedFact } from '@melandlabs/contracts/derived-fact';
-import { EntityEdge } from '@melandlabs/contracts/entity-edge';
-import { RawMessage, RawMessageSearchChunk } from '@melandlabs/indexeddb';
-
-/**
- * Reranker adapter contract.
- *
- * A `Reranker` is an optional plug-in applied to the unified-search output
- * after per-source merge but before the final `slice(0, limit)`. It lets a
- * host swap in a cross-encoder, a learned ranker, or any other deterministic
- * ordering without changing the retrieval pipeline.
- *
- * Implementations MUST be deterministic for the same `(query, candidates)`
- * pair — non-deterministic orderings would defeat the existing
- * `rrfScore`/`similarity` tie-break tests.
- */
-interface RerankerCandidate {
-    id: string;
-    content: string;
-    metadata?: Record<string, unknown>;
-}
-interface RerankerInput {
-    query: string;
-    candidates: RerankerCandidate[];
-    topK?: number;
-}
-interface RerankerScore {
-    id: string;
-    score: number;
-}
-interface Reranker {
-    rerank(input: RerankerInput): Promise<RerankerScore[]>;
-}
-
-/**
- * Pure helpers used by the unified memory search pipeline.
- *
- * Kept side-effect free so they can be reused by tests, MCP tools,
- * and the HTTP daemon without pulling in any of the heavier
- * storage/search implementations.
- */
-
-type UnifiedMemorySearchSource = "memory" | "insights" | "knowledge";
-/**
- * A retrieval channel that contributed to a hit's final score.
- *
- *   - `semantic` — dense embedding lookup (`searchRawMessagesAnn` or
- *     the SQLite manager's semantic-search fallback).
- *   - `lexical`  — BM25 / FTS5 keyword match
- *     (`searchRawMessagesLexical` or the SQLite manager's lexical
- *     fallback).
- *   - `entity`   — entity-link match supplied by the host's
- *     `entitySearch` dep.
- */
-type HitChannel = "semantic" | "lexical" | "hybrid" | "entity";
-/**
- * Per-hit score breakdown. Always emitted by `search()` (default merge
- * strategy) so callers can threshold / re-rank without losing the
- * individual channel contributions. The RRF fusion additionally
- * populates `signals.rrf` and continues to mirror the fused score
- * onto `metadata.rrfScore` (legacy field).
- *
- * Each numeric field is the raw per-channel score for the *first*
- * (highest-ranked) appearance of the same `(type, id)` key in the
- * channel's list. Channels that did not contribute are `undefined`.
- */
-interface HitSignals {
-    /** Channels the hit actually appeared in. */
-    channels: HitChannel[];
-    /** Semantic sub-query similarity in [0..1] (undefined when absent). */
-    semantic?: number;
-    /** Lexical sub-query BM25 score (undefined when absent). */
-    lexical?: number;
-    /** Native backend dense+BM25 fused score (undefined when absent). */
-    hybrid?: number;
-    /** Entity sub-query match score (undefined when absent). */
-    entity?: number;
-    /** RRF-fused score (only when mergeStrategy === "rrf"). */
-    rrf?: number;
-}
-/**
- * Derive simple lexical keywords from a query string. Splits on any
- * non-letter/non-digit Unicode boundary, lowercases, drops tokens
- * shorter than 2 chars, and caps the list at 16. Used by the unified
- * search lexical sub-query and by the `derive` primitive's candidate
- * fetch fallback.
- */
-declare function deriveLexicalKeywords(query: string): string[];
-type UnifiedMemoryReasoningStrategy = "none" | "rewrite" | "iterative" | "union";
-interface UnifiedMemorySearchWarning {
-    source: UnifiedMemorySearchSource;
-    code: string;
-    message: string;
-}
-interface UnifiedMemoryReasoningInfo {
-    strategy: UnifiedMemoryReasoningStrategy;
-    /**
-     * True when the caller asked for a non-`"none"` strategy but the
-     * corresponding reasoning provider was not configured (or its LLM
-     * call failed), so the unified search silently fell back to the default
-     * one-shot semantic + lexical path. Callers can use this to surface a
-     * degraded-mode warning to their users.
-     */
-    degraded?: boolean;
-    /** Query variants produced by the rewriter (original + rewritten). */
-    rewrittenQueries?: string[];
-    /** Number of planner iterations executed (iterative mode only). */
-    iterations?: number;
-    /** Number of evidence items collected by the planner (iterative mode only). */
-    evidenceCount?: number;
-    /** Date range that was applied to the memory source, if any. */
-    dateRange?: {
-        from?: string;
-        to?: string;
-    };
-}
-interface UnifiedMemorySearchInput {
-    userId: string;
-    query: string;
-    sources?: UnifiedMemorySearchSource[];
-    limit?: number;
-    threshold?: number;
-    authToken?: string;
-    includeArchivedInsights?: boolean;
-    botIds?: string[];
-    documentIds?: string[];
-    /**
-     * Optional ISO-8601 timestamp. When set, graph-aware retrieval and other
-     * snapshot consumers drop nodes / edges whose `applicability.validFrom` /
-     * `validUntil` window is closed at that instant. Backward-compatible:
-     * omitted `asOf` keeps the legacy behaviour exactly.
-     *
-     * This is a single-point snapshot, not a date range. For interval filtering
-     * over memory timestamps use `dateFrom` / `dateTo`.
-     */
-    asOf?: string;
-    /**
-     * Optional inclusive start date (ISO-8601). When set, the memory source
-     * filters out candidates whose timestamp is before this boundary. The
-     * iterative planner also receives this bound and may emit narrower ranges.
-     *
-     * This only affects the `memory` source; `insights` and `knowledge` are
-     * not filtered by this range. Candidates without a recognised timestamp are
-     * retained.
-     */
-    dateFrom?: string;
-    /**
-     * Optional inclusive end date (ISO-8601). When set, the memory source
-     * filters out candidates whose timestamp is after this boundary. Date-only
-     * strings are treated as the end of that day.
-     *
-     * This only affects the `memory` source; `insights` and `knowledge` are
-     * not filtered by this range. Candidates without a recognised timestamp are
-     * retained.
-     */
-    dateTo?: string;
-    /**
-     * How to merge per-source result lists. Defaults to `"rrf"` reciprocal-rank
-     * fusion. `"similarity"` preserves the legacy global similarity sort.
-     */
-    mergeStrategy?: UnifiedMemoryMergeStrategy;
-    /**
-     * Optional additive scope-narrowing filter expressed as structured
-     * peers. Coexists with `userId`/`botIds`. When supplied, the host's
-     * `UnifiedSearchDeps.peerScopeCheck` is consulted; peers that fall
-     * outside `userId` are dropped with a `peer_filter_outside_user_scope`
-     * warning rather than broadening the scope.
-     */
-    peerFilter?: ReadonlyArray<Peer>;
-    /**
-     * Optional reasoning strategy. `"rewrite"` rewrites the query before
-     * embedding; `"iterative"` runs an LLM planner that searches, notes
-     * evidence, and searches again. Defaults to `"none"`.
-     */
-    reasoningStrategy?: UnifiedMemoryReasoningStrategy;
-    /**
-     * Optional `FactType` read-side filter. When supplied, the memory
-     * source narrows candidates to rows whose `factType` is in this set.
-     * Only affects the `memory` source; `insights` and `knowledge` are
-     * not filtered by this. Empty array is treated as "no filter" so
-     * callers can pass `searchInput.factTypes ?? []` without surprises.
-     */
-    factTypes?: FactType[];
-    /** Include pre-fusion channel candidates in the response for diagnostics. */
-    includeRetrievalDiagnostics?: boolean;
-    /**
-     * Include messages that have been soft-deprecated
-     * (`raw_messages.deprecated_at IS NOT NULL`). Default `false` keeps
-     * `current-truth` retrievals clean: a row that was marked superseded
-     * via `deprecateMessages` (or the `opencontext deprecate` CLI) is
-     * excluded from results. Set to `true` for audits and historical
-     * exploration.
-     */
-    includeDeprecated?: boolean;
-}
-type UnifiedMemoryMergeStrategy = "similarity" | "rrf";
-/**
- * A single ranked list from one retrieval channel. Used by the RRF merge to
- * combine multiple signals (semantic + lexical + insights + knowledge) without
- * flattening them into a single similarity score first.
- */
-interface UnifiedMemoryRankedList {
-    /** Label for the source list (e.g. a tier or channel). Free-form; the
-     * RRF fusion only reads `hits`, so `name` is purely diagnostic. */
-    name: string;
-    hits: UnifiedMemorySearchResult[];
-}
-interface UnifiedMemorySearchResult {
-    type: "memory" | "insight" | "knowledge";
-    id: string;
-    content: string;
-    similarity: number;
-    metadata: Record<string, unknown>;
-    /**
-     * Optional per-channel score breakdown. Always populated by the
-     * pipeline when at least one channel contributed a non-empty list;
-     * callers should treat absence as "no channel info available".
-     */
-    signals?: HitSignals;
-}
-interface UnifiedMemorySearchOutput {
-    query: string;
-    sources: UnifiedMemorySearchSource[];
-    results: UnifiedMemorySearchResult[];
-    count: number;
-    warnings: UnifiedMemorySearchWarning[];
-    retrievalDiagnostics?: UnifiedMemoryRetrievalDiagnostics;
-    /**
-     * Diagnostic information about reasoning and date filtering. Present
-     * when (a) a non-`"none"` reasoning strategy was requested, or (b) a
-     * `dateFrom` / `dateTo` filter was applied to the memory source.
-     */
-    reasoning?: UnifiedMemoryReasoningInfo;
-}
-interface UnifiedMemoryRetrievalDiagnostics {
-    mergeStrategy: UnifiedMemoryMergeStrategy;
-    candidateLimit: number;
-    backend?: string;
-    semanticDegradedReason?: string;
-    candidateCounts?: {
-        semantic: number;
-        lexical: number;
-        hybrid: number;
-        entity: number;
-        fused: number;
-        final: number;
-    };
-    channels: {
-        semantic: UnifiedMemorySearchResult[];
-        lexical: UnifiedMemorySearchResult[];
-        hybrid?: UnifiedMemorySearchResult[];
-        entity?: UnifiedMemorySearchResult[];
-    };
-    /** Results after channel/source fusion and before an optional host reranker. */
-    fusedBeforeRerank: UnifiedMemorySearchResult[];
-    reranker?: {
-        enabled: boolean;
-        provider?: string;
-        model?: string;
-        inputCount: number;
-        outputCount: number;
-        latencyMs: number;
-        orderChanged: boolean;
-    };
-    /** Final results after optional reranking and Top-K truncation. */
-    final: UnifiedMemorySearchResult[];
-}
-/**
- * Cross-source retrieval surface for the unified search. Mirrors
- * `UnifiedMemorySearchSource` but is exposed under a more discoverable
- * name.
- */
-type SearchSource = UnifiedMemorySearchSource;
-/**
- * Per-tier evidence bucket consulted by `reflect`-style synthesis.
- * Includes the `summary` tier that the read-only sources do not surface.
- */
-type SearchTier = "summary" | "raw" | "insight" | "knowledge";
-interface SearchInput {
-    userId: string;
-    query: string;
-    /** Cross-source retrieval surface (defaults to all three sources). */
-    sources?: ReadonlyArray<SearchSource>;
-    /**
-     * Per-tier subset — when omitted, defaults to all four tiers.
-     * Forwarded to the gather step so the read pipeline can scope the
-     * evidence. Most callers pass nothing; `synthesize` callers can
-     * narrow to `["raw"]` or `["summary", "raw"]` for cheaper synthesis.
-     */
-    tiers?: ReadonlyArray<SearchTier>;
-    /**
-     * Opt-in LLM synthesis. When `true`, runs `reasoning.complete` after
-     * gathering evidence and returns `answer` in the output. When
-     * omitted / `false`, no LLM call is made (matches today's
-     * `searchUnifiedMemory`). The `responseSchema` form lets the LLM
-     * return JSON; the SDK extracts `{ answer: string }` from the
-     * payload and surfaces the rest via warnings.
-     */
-    synthesize?: boolean | {
-        responseSchema?: Record<string, unknown>;
-    };
-    limit?: number;
-    threshold?: number;
-    botIds?: string[];
-    documentIds?: string[];
-    dateFrom?: string;
-    dateTo?: string;
-    asOf?: string;
-    peerFilter?: ReadonlyArray<Peer>;
-    authToken?: string;
-    factTypes?: FactType[];
-    mergeStrategy?: UnifiedMemoryMergeStrategy;
-    reasoningStrategy?: UnifiedMemoryReasoningStrategy;
-    /**
-     * Backward-compat pass-through for callers that previously passed
-     * `responseSchema` at the top level. When set, it overrides
-     * `synthesize.responseSchema`.
-     */
-    responseSchema?: Record<string, unknown>;
-    /**
-     * Backward-compat pass-through for callers that previously passed
-     * `includeArchivedInsights` to the read-only search.
-     */
-    includeArchivedInsights?: boolean;
-    /** Include pre-fusion retrieval candidates; intended for evaluation/debugging. */
-    includeRetrievalDiagnostics?: boolean;
-    /**
-     * Include messages that have been soft-deprecated
-     * (`raw_messages.deprecated_at IS NOT NULL`). Default `false` keeps
-     * `current-truth` retrievals clean: a row that was marked superseded
-     * via `deprecateMessages` (or the `opencontext deprecate` CLI) is
-     * excluded from results. Set to `true` for audits and historical
-     * exploration.
-     */
-    includeDeprecated?: boolean;
-}
-interface SearchEvidence {
-    id: string;
-    source: SearchSource | SearchTier;
-    snippet: string;
-    score: number;
-    timestamp?: number;
-    /**
-     * Forwarded from the underlying hit's `metadata`. Surfaces per-fact
-     * provenance (`metadata.source`, `metadata.factType`, etc.) to the
-     * synthesis prompt and the CLI's `--context-only` / `--json` output.
-     */
-    metadata?: Record<string, unknown>;
-}
-interface SearchOutput {
-    query: string;
-    sources: ReadonlyArray<SearchSource>;
-    results: UnifiedMemorySearchResult[];
-    /** Same hits as `results`, with the source labelled for synthesis callers. */
-    evidence: SearchEvidence[];
-    count: number;
-    warnings: UnifiedMemorySearchWarning[];
-    retrievalDiagnostics?: UnifiedMemoryRetrievalDiagnostics;
-    reasoning?: UnifiedMemoryReasoningInfo;
-    /** Only present when `synthesize` was truthy. */
-    answer?: string;
-}
-declare function normalizeUnifiedMemorySearchSources(sources: unknown): UnifiedMemorySearchSource[];
-declare function clampUnifiedMemorySearchLimit(limit: unknown): number;
-declare function clampUnifiedMemorySearchThreshold(threshold: unknown): number;
-declare function mergeUnifiedMemorySearchResults(results: UnifiedMemorySearchResult[], limit: number, options?: {
-    strategy?: UnifiedMemoryMergeStrategy;
-    rankedLists?: UnifiedMemoryRankedList[];
-}): UnifiedMemorySearchResult[];
-declare function normalizeUnifiedMemoryMergeStrategy(value: unknown): UnifiedMemoryMergeStrategy;
-declare function normalizeUnifiedMemoryReasoningStrategy(value: unknown, defaultStrategy?: UnifiedMemoryReasoningStrategy): UnifiedMemoryReasoningStrategy;
-/**
- * Reciprocal Rank Fusion across multiple ranked lists. Each list contributes
- * `1 / (k + rank + 1)` to a hit's accumulated score. Hits are de-duplicated by
- * `(type, id)` so the same message surfaced by both lexical and semantic
- * channels naturally outranks single-channel matches. Tie-break is
- * deterministic: descending RRF score, then `(type, id)` lexical.
- */
-declare function mergeUnifiedMemorySearchResultsRrf(lists: UnifiedMemoryRankedList[], limit: number, k?: number): UnifiedMemorySearchResult[];
-declare function toKnowledgeResult(result: {
-    chunkId: string;
-    documentId: string;
-    documentName: string;
-    content: string;
-    similarity: number;
-    chunkIndex: number;
-}): UnifiedMemorySearchResult;
-declare function toMemoryResult(result: {
-    id: string;
-    content: string;
-    similarity: number;
-    metadata: Record<string, unknown>;
-}): UnifiedMemorySearchResult;
-/**
- * Build the `signals` breakdown for a single hit from the per-channel
- * ranked lists it appeared in. Only the highest-ranked (i.e. first)
- * appearance of `(type, id)` per channel contributes — duplicate hits
- * later in the same list are ignored so the breakdown stays
- * deterministic.
- *
- * Used by `mergeAcrossSources` to attach `signals` to every emitted
- * `UnifiedMemorySearchResult`. Pure; no I/O.
- */
-declare function materializeSignals(lists: ReadonlyArray<{
-    name: string;
-    hits: UnifiedMemorySearchResult[];
-}>, hit: UnifiedMemorySearchResult): HitSignals | undefined;
-/**
- * Map a `UnifiedMemoryRankedList.name` to a `HitChannel`. Unknown names
- * (e.g. "insights", "knowledge", "summary") are not channels — they
- * surface their similarity through the merge's `similarity` field and
- * are simply skipped here so callers can still see which channel set
- * the hit came from.
- */
-declare function listNameToChannel(name: string): HitChannel | undefined;
-declare function isRawMemorySemanticResult(result: unknown): result is {
-    id: string;
-    content: string;
-    similarity: number;
-    metadata: Record<string, unknown>;
-};
-
-/**
- * Iterative, LLM-driven memory retrieval.
- *
- * Instead of issuing one fixed query, a small planner model examines the
- * original question and the evidence collected so far, then decides:
- *   - search again with different keywords / time bounds
- *   - save some of the last results as evidence
- *   - finish gathering
- *
- * This trades latency and token cost for better evidence location on
- * multi-hop, temporal, or underspecified questions.
- *
- * The module is provider-agnostic: callers inject a `complete` callback.
- */
-interface IterativeRecallCandidate {
-    id: string;
-    content: string;
-    similarity: number;
-    metadata: Record<string, unknown>;
-}
-interface IterativeRecallSearchRequest {
-    keywords: string[];
-    dateFrom?: string;
-    dateTo?: string;
-}
-interface IterativeRecallSearchResult {
-    candidates: IterativeRecallCandidate[];
-}
-interface IterativeRecallExecutor {
-    search(request: IterativeRecallSearchRequest): Promise<IterativeRecallSearchResult>;
-}
-interface IterativeRecallStats {
-    iterations: number;
-    searches: number;
-    notes: number;
-}
-interface IterativeRecallResult {
-    /** Evidence selected by the planner, in the order it was collected. */
-    evidence: IterativeRecallCandidate[];
-    /** Diagnostic statistics. */
-    stats: IterativeRecallStats;
-}
-interface IterativeRecallPlanner {
-    plan(input: {
-        query: string;
-        executor: IterativeRecallExecutor;
-        options?: IterativeRecallPlannerOptions;
-        /**
-         * Optional absolute date range for the search. The planner passes these
-         * bounds to the executor and may also emit narrower ranges in later actions.
-         */
-        dateFrom?: string;
-        dateTo?: string;
-    }): Promise<IterativeRecallResult>;
-    /**
-     * Optional. When implemented, returns true iff the most recent `plan()`
-     * could not run the planner as designed and fell back to a degraded
-     * result — for example the LLM call threw, every iteration produced an
-     * unparseable action, or the result relied on the fallback path
-     * (recent-hits or baseline search) because the planner never committed
-     * any evidence via a `note` action.
-     */
-    lastDegraded?: () => boolean;
-}
-interface IterativeRecallPlannerOptions {
-    /** Maximum planner actions. @default 4 */
-    maxIterations?: number;
-    /** Results exposed to the planner per internal search. @default 5 */
-    searchTopK?: number;
-    /** When true, skip planning and return no evidence. @default false */
-    disabled?: boolean;
-    /**
-     * When true (default), if the planner finishes without noting any
-     * evidence the planner falls back to either the most recent hits or a
-     * baseline keyword search against the original query, so the call is
-     * never a total loss. Set to false to surface empty results honestly
-     * when the planner never committed anything.
-     * @default true
-     */
-    fallbackToBaseline?: boolean;
-}
-interface IterativeRecallPlannerDeps {
-    /** LLM completion callback. */
-    complete: (prompt: string) => Promise<string>;
-    /** Default options. */
-    options?: IterativeRecallPlannerOptions;
-}
-declare function createIterativeRecallPlanner(deps: IterativeRecallPlannerDeps): IterativeRecallPlanner;
-/**
- * A no-op planner that never runs iterative retrieval.
- */
-declare function createIdentityIterativePlanner(): IterativeRecallPlanner;
-
-/**
- * Query rewriting for memory retrieval.
- *
- * The memory corpus is usually a first-person chat log ("I told you ...",
- * "I prefer ..."). A query asked in the assistant's register ("What does the
- * user prefer?") often misses the best evidence. A rewriter rephrases the
- * question into the register the memory was written in, improving dense
- * retrieval without changing the underlying index.
- *
- * The module is provider-agnostic: callers inject a `complete` callback that
- * talks to whatever LLM they already use.
- */
-interface QueryRewriterInput {
-    query: string;
-    userId: string;
-    authToken?: string;
-}
-interface QueryRewriter {
-    /**
-     * Return one or more query variants. The first element is always the
-     * original query; subsequent elements are rewritten variants.
-     */
-    rewrite(input: QueryRewriterInput): Promise<string[]>;
-    /**
-     * Optional hook that reports whether the most recent `rewrite` call
-     * silently degraded to the original query (for example because the LLM
-     * call failed or produced no usable variants).
-     */
-    lastDegraded?(): boolean;
-}
-interface QueryRewriterOptions {
-    /**
-     * LLM completion callback. Receives the full prompt and returns the raw
-     * model output. The rewriter parses the output and falls back to the
-     * original query on any failure.
-     */
-    complete: (prompt: string) => Promise<string>;
-    /**
-     * Maximum number of rewritten variants to return in addition to the
-     * original query. Use `0` to return only the original. Higher values ask
-     * the LLM for more alternatives and multiply embedding/search cost
-     * proportionally, so callers should bound it (typical: 1–3).
-     * @default 1
-     */
-    maxVariants?: number;
-    /**
-     * When true, the rewriter returns only the original query and skips the
-     * LLM call. Useful as a kill-switch.
-     * @default false
-     */
-    disabled?: boolean;
-}
-declare function createUserVoiceRewriter(options: QueryRewriterOptions): QueryRewriter;
-/**
- * A no-op rewriter that always returns the original query.
- */
-declare function createIdentityRewriter(): QueryRewriter;
-
-interface MemoryStoreDb {
-    /** Resolve the active Drizzle DB handle. Must be server-side. */
-    getDb(): unknown;
-    /** Whether the DB has finished initializing (optional, for startup gating). */
-    isDbInitialized?(): boolean;
-    /** Initialize the DB (optional, called by `createMemoryStore` if present). */
-    initDb?(): unknown;
-    /**
-     * Drizzle table references for the postgres backend. Required when
-     * running outside Tauri mode without a registered factory. The host
-     * application owns the actual schema.
-     */
-    tables?: {
-        rawMessages?: unknown;
-        memorySummaries?: unknown;
-    };
-}
-/**
- * Placeholder for the historical host-injected environment. The fields
- * it used to expose (`isTauriMode`, `getTauriDbPath`, `getTauriDataDir`)
- * were Tauri-specific and have been removed. Backend selection is now
- * driven entirely by the `OPENCONTEXT_MEMORY_STORE_BACKEND` env var.
- *
- * The interface is kept (empty) so existing `env?: MemoryStoreEnv`
- * parameters on the public surface still type-check, but new code
- * should not need to construct a value of this type.
- */
-interface MemoryStoreEnv {
-}
-type VectorBackend = "sqlite-vec" | "chroma" | "lancedb" | "milvus";
-interface MemoryStoreVectorConfig {
-    /** Active backend selector. Defaults to env-based detection. */
-    backend?: VectorBackend;
-    /** SQLite-vec options (used when backend === "sqlite-vec"). */
-    sqliteVec?: {
-        dbPath?: string;
-        insightsCollection?: string;
-    };
-    /** Chroma options (used when backend === "chroma"). */
-    chroma?: {
-        url?: string;
-        rawMessagesCollection?: string;
-        insightsCollection?: string;
-    };
-    /** LanceDB options (used when backend === "lancedb"). */
-    lancedb?: {
-        uri: string;
-        table?: string;
-    };
-    /** Milvus options (used when backend === "milvus"). */
-    milvus?: {
-        address: string;
-        token?: string;
-        database?: string;
-        collection?: string;
-        dimension?: number;
-    };
-}
-type EmbedQueryFn = (input: {
-    userId: string;
-    query: string;
-    authToken?: string;
-}) => Promise<number[]>;
-type EmbedDocumentsFn = (input: {
-    userId: string;
-    texts: string[];
-    authToken?: string;
-}) => Promise<number[][]>;
-interface UnifiedSearchKnowledgeResult {
-    chunkId: string;
-    documentId: string;
-    documentName: string;
-    content: string;
-    similarity: number;
-    chunkIndex: number;
-}
-interface UnifiedSearchInsightsResult {
-    id: string;
-    content: string;
-    similarity: number;
-    metadata: Record<string, unknown>;
-}
-interface UnifiedSearchReasoningDeps {
-    /**
-     * LLM single-turn synthesis callback. Wired into
-     * `search({ synthesize: true })` so a host that wants synthesis
-     * responses only has to drop in one callable. When omitted, the
-     * synthesis path returns the gathered evidence with a
-     * `synthesize_llm_not_configured` warning instead of throwing.
-     */
-    complete?: (prompt: string) => Promise<string>;
-    /** Default merge strategy used by `searchUnifiedMemory` when the caller does not specify one. @default "rrf" */
-    defaultMergeStrategy?: UnifiedMemoryMergeStrategy;
-    /** Optional query rewriter. When present, "rewrite" strategy is available. */
-    queryRewriter?: QueryRewriter;
-    /** Optional iterative recall planner. When present, "iterative" strategy is available. */
-    iterativePlanner?: IterativeRecallPlanner;
-    /** Default reasoning strategy when callers do not specify one. @default "none" */
-    defaultStrategy?: UnifiedMemoryReasoningStrategy;
-}
-interface MemorySummaryHit {
-    summaryId: string;
-    summaryText: string;
-    summaryTier?: "L1" | "L2" | "L3";
-    keywords?: string[];
-    startTimestamp?: number;
-    endTimestamp?: number;
-}
-/**
- * Trusted applicability fields forwarded together to retrieval providers.
- * They are absent for legacy unscoped searches and always present together
- * for scoped searches. Providers must enforce the canonical applicability
- * contract at `applicabilityAt`; these values must not be derived from public
- * request payloads.
- */
-interface SearchProviderApplicabilityInput {
-    applicabilityContexts?: readonly MemoryApplicabilityContext[];
-    /** Epoch milliseconds resolved once at the `search()` boundary. */
-    applicabilityAt?: number;
-}
-interface UnifiedSearchDeps {
-    /** Embed a query string using the active user's provider. */
-    embedQuery?: EmbedQueryFn;
-    /** Batch document embedding used by child indexing when the provider supports it. */
-    embedDocuments?: EmbedDocumentsFn;
-    /** Safe, non-secret identity used by health checks and child-index metadata. */
-    embeddingInfo?: {
-        provider?: string;
-        model?: string;
-        dimensions?: number;
-        maxTokens?: number;
-    };
-    /** Runtime-safe retrieval readiness used by health and diagnostics. */
-    getRawMessageRetrievalStatus?: () => Promise<{
-        backend: string;
-        embeddingProvider?: string;
-        embeddingModel?: string;
-        embeddingDimensions?: number;
-        childCount: number;
-        embeddedChildCount: number;
-        indexedDimensions: number[];
-        semanticReady: boolean;
-        lexicalReady: boolean;
-        semanticDegradedReason?: string;
-        rerankerProvider?: string;
-        rerankerModel?: string;
-        rerankerReady?: boolean;
-    }>;
-    /** Optional external child-vector index used by the shared write path. */
-    rawMessageChildIndex?: {
-        replaceMessages(messages: RawMessage[], chunks: RawMessageSearchChunk[]): Promise<void>;
-    };
-    /**
-     * Dense raw-message search supplied by the selected child-vector backend.
-     * External Postgres hosts may also provide their legacy parent-level
-     * implementation here; Postgres schema changes are outside this package.
-     */
-    searchRawMessagesAnn?: (input: SearchProviderApplicabilityInput & {
-        userId: string;
-        queryEmbedding: number[];
-        limit: number;
-        threshold: number;
-        botId?: string;
-        /**
-         * Forward `includeDeprecated` from `UnifiedMemorySearchInput` so
-         * supersession-aware callers can opt into deprecated rows for
-         * audits. Default `false` preserves the current-truth behaviour.
-         */
-        includeDeprecated?: boolean;
-        /**
-         * Forward `asOf` from `UnifiedMemorySearchInput` so time-travel
-         * callers can ask "what was true at this instant?". Implementations
-         * that don't yet honour the field should ignore it — the rest of
-         * the unified pipeline stays correct.
-         */
-        asOf?: string;
-        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
-        peers?: ReadonlyArray<Peer>;
-        /** Optional `FactType` filter resolved from `UnifiedMemorySearchInput.factTypes`. */
-        factTypes?: FactType[];
-    }) => Promise<Array<{
-        id: string;
-        content: string;
-        similarity: number;
-        metadata: Record<string, unknown>;
-    }>>;
-    /** Native dense+BM25 path for backends such as LanceDB and Milvus. */
-    searchRawMessagesHybrid?: (input: SearchProviderApplicabilityInput & {
-        userId: string;
-        query: string;
-        queryEmbedding: number[];
-        limit: number;
-        botId?: string;
-    }) => Promise<Array<{
-        id: string;
-        content: string;
-        similarity: number;
-        metadata: Record<string, unknown>;
-    }>>;
-    /** RAG over uploaded knowledge documents. Returns a list of chunk hits. */
-    searchKnowledge?: (input: SearchProviderApplicabilityInput & {
-        userId: string;
-        query: string;
-        options: {
-            limit: number;
-            threshold: number;
-            documentIds?: string[];
-        };
-        authToken?: string;
-        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
-        peers?: ReadonlyArray<Peer>;
-    }) => Promise<UnifiedSearchKnowledgeResult[]>;
-    /** Semantic search over extracted insights. */
-    searchInsights?: (input: SearchProviderApplicabilityInput & {
-        userId: string;
-        query: string;
-        limit: number;
-        threshold: number;
-        botIds?: string[];
-        includeArchived?: boolean;
-        authToken?: string;
-        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
-        peers?: ReadonlyArray<Peer>;
-    }) => Promise<UnifiedSearchInsightsResult[]>;
-    /**
-     * Optional BM25 (lexical) sub-query for the memory source. Mirrors the
-     * `searchRawMessagesAnn` shape but operates on FTS5 keywords instead of
-     * dense embeddings. When absent, the unified pipeline skips the lexical
-     * path and emits a `memory_lexical_search_not_configured` warning.
-     */
-    searchRawMessagesLexical?: (input: SearchProviderApplicabilityInput & {
-        userId: string;
-        keywords: string[];
-        limit: number;
-        botId?: string;
-        /**
-         * Forward `includeDeprecated` from `UnifiedMemorySearchInput` so
-         * supersession-aware callers can opt into deprecated rows for
-         * audits. Default `false` preserves the current-truth behaviour.
-         */
-        includeDeprecated?: boolean;
-        /**
-         * Forward `asOf` from `UnifiedMemorySearchInput` so time-travel
-         * callers can ask "what was true at this instant?". Implementations
-         * that don't yet honour the field should ignore it — the rest of
-         * the unified pipeline stays correct.
-         */
-        asOf?: string;
-        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
-        peers?: ReadonlyArray<Peer>;
-        /** Optional `FactType` filter resolved from `UnifiedMemorySearchInput.factTypes`. */
-        factTypes?: FactType[];
-    }) => Promise<Array<{
-        id: string;
-        content: string;
-        similarity: number;
-        metadata: Record<string, unknown>;
-    }>>;
-    /**
-     * Optional summary-tier search. When wired in, `reflect()` consults the
-     * summary tier alongside raw messages and emits a
-     * `reflect_summaries_unavailable` warning if the call fails.
-     */
-    searchSummaries?: (input: SearchProviderApplicabilityInput & {
-        userId: string;
-        query: string;
-        keywords: string[];
-        limit: number;
-        threshold: number;
-        dateFrom?: string;
-        dateTo?: string;
-        authToken?: string;
-        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
-        peers?: ReadonlyArray<Peer>;
-    }) => Promise<MemorySummaryHit[]>;
-    /**
-     * Optional entity sub-query provider. Hosts wire this in to opt
-     * into the `entity` channel of unified search: matches are
-     * projected back as `UnifiedMemorySearchResult`s and fused with
-     * semantic + lexical via RRF. Without it, the entity channel is
-     * skipped silently (with a `memory_entity_search_not_configured`
-     * warning when RRF was requested).
-     *
-     * The provider is intentionally narrow: it returns `(messageId,
-     * label, score)` tuples. The host is responsible for keeping its
-     * own entity store (graph nodes, separate SQLite table, etc.) —
-     * the SDK never persists entity edges itself.
-     */
-    entitySearch?: (input: SearchProviderApplicabilityInput & {
-        userId: string;
-        keywords: string[];
-        limit: number;
-        botId?: string;
-        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
-        peers?: ReadonlyArray<Peer>;
-    }) => Promise<Array<{
-        messageId: string;
-        label: string;
-        score: number;
-    }>>;
-    /**
-     * Optional entity extractor wired into the `distill` primitive. The
-     * extractor receives the raw message text and returns a batch of
-     * `EntityEdge`s the host may persist via the `persist` callback
-     * supplied on the `distill` input.
-     *
-     * When omitted, `distill` short-circuits with a
-     * `distill_extractor_not_configured` warning — matching the
-     * `memory_iterative_planner_not_configured` precedent.
-     */
-    entityExtractor?: (input: {
-        userId: string;
-        messageId: string;
-        content: string;
-    }) => Promise<EntityEdge[]>;
-    /**
-     * Optional deriver wired into the `derive` primitive. The deriver
-     * receives a window of candidate fact texts and returns a batch of
-     * `DerivedFact`s the host may persist via the `persist` callback
-     * supplied on the `derive` input.
-     *
-     * When omitted, `derive` short-circuits with a
-     * `derive_deriver_not_configured` warning — same precedent.
-     */
-    deriver?: (input: {
-        userId: string;
-        userScope: {
-            userId: string;
-            botIds?: string[];
-            dateFrom?: string;
-            dateTo?: string;
-        };
-        recentFactTexts: string[];
-        window?: {
-            from: number;
-            to: number;
-        };
-    }) => Promise<DerivedFact[]>;
-    /**
-     * Optional host-side check that validates whether a `peerFilter` peer is
-     * actually reachable from this `userId`. Used by
-     * `resolveScopePeer` to drop out-of-scope peers with a warning
-     * rather than broadening the search. May be omitted for hosts that
-     * have no peer-permission model.
-     */
-    peerScopeCheck?: (input: {
-        userId: string;
-        peers: ReadonlyArray<_melandlabs_contracts_peer.Peer>;
-    }) => Promise<boolean> | boolean;
-    /** Optional reasoning providers. */
-    reasoning?: UnifiedSearchReasoningDeps;
-    /**
-     * Optional reranker applied after per-source merge and before the
-     * final limit. Defaults to an identity pass-through so the merge order
-     * is preserved.
-     */
-    reranker?: Reranker;
-    /** Safe, non-secret reranker identity surfaced by health and diagnostics. */
-    rerankerInfo?: {
-        provider: string;
-        model?: string;
-        maxTokens?: number;
-        ready: boolean;
-    };
-    /**
-     * Optional logger. When set (e.g. via `MemoryStoreConfig.logger`),
-     * `reflect` / `consolidate` log through it instead of `console`.
-     * Falls back to `console` when omitted.
-     */
-    logger?: Pick<Console, "log" | "warn" | "error">;
-}
-interface MemoryStoreConfig {
-    /**
-     * Database handle factory. Required for the Postgres backend
-     * (`OPENCONTEXT_MEMORY_STORE_BACKEND=postgres`).
-     */
-    db?: MemoryStoreDb;
-    /**
-     * Custom SQLite database file path for the default SQLite backend.
-     *
-     * If provided, this takes precedence over the `MEMORY_STORE_DB_PATH`
-     * environment variable and the default `~/.opencontext/memory/store.db`.
-     *
-     * For backward compatibility with early tutorials, `db.path` is also
-     * honoured when `db` is supplied as `{ type, path }`.
-     */
-    dbPath?: string;
-    /** Environment helpers. Defaults to a process.env-only stub if omitted. */
-    env?: MemoryStoreEnv;
-    /** Vector backend config. Defaults to env-based detection. */
-    vector?: MemoryStoreVectorConfig;
-    /** Optional cross-source search providers. */
-    unified?: UnifiedSearchDeps;
-    /**
-     * Optional write-back graph store. When set, `createMemoryStore` wires
-     * it into `store.graphStore` and forwards it to `consolidate`. Hosts
-     * that prefer post-construction wiring can use `attachMemoryGraphStore`.
-     */
-    graphStore?: _melandlabs_memory_consolidation.MemoryGraphStoreWithOperationHistory;
-    /**
-     * Optional storage adapter carrying `deprecateRecords`. Forwarded into
-     * `consolidate` for callers that want deprecation writes without
-     * attaching a full graph store.
-     */
-    storage?: _melandlabs_memory_consolidation.MemoryStorageAdapterLike;
-    /** Optional logger. Defaults to console. */
-    logger?: Pick<Console, "log" | "warn" | "error">;
-}
-
-export { createUserVoiceRewriter as $, toMemoryResult as A, type IterativeRecallExecutor as B, type IterativeRecallPlanner as C, type IterativeRecallPlannerOptions as D, type EmbedQueryFn as E, type IterativeRecallResult as F, type IterativeRecallSearchRequest as G, type HitChannel as H, type IterativeRecallCandidate as I, type IterativeRecallSearchResult as J, type IterativeRecallStats as K, type MemoryStoreDb as L, type MemoryStoreConfig as M, type QueryRewriterInput as N, type QueryRewriterOptions as O, type SearchProviderApplicabilityInput as P, type QueryRewriter as Q, type UnifiedMemoryReasoningInfo as R, type SearchTier as S, type UnifiedSearchInsightsResult as T, type UnifiedSearchDeps as U, type UnifiedSearchKnowledgeResult as V, type UnifiedSearchReasoningDeps as W, type VectorBackend as X, createIdentityIterativePlanner as Y, createIdentityRewriter as Z, createIterativeRecallPlanner as _, type MemoryStoreEnv as a, type UnifiedMemorySearchWarning as b, type SearchEvidence as c, type SearchInput as d, type SearchOutput as e, type UnifiedMemorySearchInput as f, type UnifiedMemorySearchOutput as g, type UnifiedMemorySearchResult as h, type HitSignals as i, type SearchSource as j, type UnifiedMemoryMergeStrategy as k, type UnifiedMemoryRankedList as l, type UnifiedMemoryReasoningStrategy as m, type UnifiedMemorySearchSource as n, clampUnifiedMemorySearchLimit as o, clampUnifiedMemorySearchThreshold as p, deriveLexicalKeywords as q, isRawMemorySemanticResult as r, listNameToChannel as s, materializeSignals as t, mergeUnifiedMemorySearchResults as u, mergeUnifiedMemorySearchResultsRrf as v, normalizeUnifiedMemoryMergeStrategy as w, normalizeUnifiedMemoryReasoningStrategy as x, normalizeUnifiedMemorySearchSources as y, toKnowledgeResult as z };