@melandlabs/memory-store 1.3.7 → 1.4.0

package/README.md

@@ -73,6 +73,11 @@ Both bins accept the same `--embedding-provider` / `--*-backend` flag surface
 with `--reasoning`, which reads `OPENCONTEXT_LLM_API_KEY` /
 `OPENCONTEXT_LLM_BASE_URL` / `OPENCONTEXT_LLM_MODEL` from the environment:
 
+For reproducible OpenRouter runs, set `OPENCONTEXT_LLM_PROVIDER` to one
+provider name. The CLI disables provider fallback and rejects a response
+reported from a different provider; leaving it unset preserves automatic
+routing.
+
 ```bash
 # HTTP daemon with local embeddings + sqlite-vec memory + LLM reasoning
 opencontext-memory-http \

package/dist/config-Cnk2b7fH.d.ts

@@ -0,0 +1,571 @@
+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 { h as SearchEvidenceProvenance, j as SearchSourceState, o as UnifiedMemoryRrfWeights, k as SessionNeighborExpansionOptions, E as EvidenceSelector, l as UnifiedMemoryMergeStrategy, J as IterativeRecallPlanner, n as UnifiedMemoryReasoningStrategy } from './evidence-selector-C_ZUQsio.js';
+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;
+    evidenceScores?: Array<{
+        sourceChunkId?: string;
+        startPosition?: number;
+        endPosition?: number;
+        contentSha256: string;
+        score: number;
+        inputTokens: number;
+        queryTruncated: boolean;
+    }>;
+}
+interface Reranker {
+    rerank(input: RerankerInput): Promise<RerankerScore[]>;
+}
+
+interface SearchExecutionBudget {
+    signal?: AbortSignal;
+    /** Maximum wait per external retrieval operation. Defaults to five seconds. */
+    sourceTimeoutMs?: number;
+    /** Maximum wait for the complete search, including optional ranking. */
+    searchTimeoutMs?: number;
+}
+
+/**
+ * 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 {
+    /** Optional evidence-oriented retrieval expressions; legacy user voice remains default. */
+    style?: "user-voice" | "evidence";
+    /**
+     * 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;
+}
+/** Text candidates shared by host-owned insight and file retrieval. */
+interface UnifiedSearchTextResult {
+    id: string;
+    content: string;
+    similarity: number;
+    metadata: Record<string, unknown>;
+    provenance?: Partial<SearchEvidenceProvenance>;
+}
+type UnifiedSearchInsightsResult = UnifiedSearchTextResult;
+interface UnifiedSearchReasoningDeps {
+    /** Optional extractive context selection after ranking. Disabled unless supplied. */
+    evidenceSelector?: EvidenceSelector;
+    /**
+     * 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;
+    /** Also search rewritten expressions with BM25 under RRF. At most four distinct queries, including the original. @default false */
+    rewriteLexical?: boolean;
+    /** Optional rank fusion across semantic query variants under RRF. @default "max-score" */
+    rewriteSemanticMerge?: "max-score" | "rrf";
+    /** 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 extends SearchExecutionBudget {
+    /** Host-owned file search; the host must enforce trusted scope before querying. */
+    searchWorkspace?: (input: SearchProviderApplicabilityInput & {
+        userId: string;
+        query: string;
+        limit: number;
+    }) => Promise<{
+        hits: UnifiedSearchTextResult[];
+        status: SearchSourceState["status"];
+        message?: string;
+    }>;
+    /** Default rank-fusion weights; omitted channels use weight 1. */
+    defaultRrfWeights?: UnifiedMemoryRrfWeights;
+    /** Default reciprocal-rank damping constant. */
+    defaultRrfK?: number;
+    /** Default opt-in session-neighbor expansion configuration. */
+    defaultSessionNeighborExpansion?: SessionNeighborExpansionOptions;
+    /** 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;
+    /** Model-tokenizer chunking for new writes; omitted hosts retain legacy splitting. */
+    getDocumentChunking?: () => Promise<{
+        maxTokens: number;
+        overlapTokens: number;
+        countTokens: (text: string) => number;
+    }>;
+    /** 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 bounded lookup for messages adjacent to fused seed messages. */
+    searchRawMessageNeighbors?: (input: {
+        userId: string;
+        sessionId: string;
+        messageSequences: number[];
+        window: number;
+        includeDeprecated?: boolean;
+    }) => Promise<Array<{
+        id: string;
+        content: string;
+        metadata: Record<string, unknown>;
+        similarity: number;
+    }>>;
+    /**
+     * 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 { type EmbedQueryFn as E, type MemoryStoreConfig as M, type QueryRewriter as Q, type SearchProviderApplicabilityInput as S, type UnifiedSearchDeps as U, type VectorBackend as V, type MemoryStoreEnv as a, type MemoryStoreDb as b, type QueryRewriterInput as c, type QueryRewriterOptions as d, type UnifiedSearchInsightsResult as e, type UnifiedSearchKnowledgeResult as f, type UnifiedSearchReasoningDeps as g, type UnifiedSearchTextResult as h, createIdentityRewriter as i, createUserVoiceRewriter as j };

package/dist/contracts.d.ts

@@ -30,7 +30,9 @@ interface RawMessage {
     userId: string;
     channel?: string;
     person?: string;
-    timestamp: number;
+    timestamp?: number;
+    /** Storage-assigned, per-user insertion order; not an event timestamp. */
+    messageSequence?: number;
     content: string;
     attachments?: Array<{
         name: string;