@melandlabs/memory-store 0.2.7 → 0.3.1

package/dist/config-2Q092MUz.d.ts

@@ -0,0 +1,470 @@
+/**
+ * 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";
+type UnifiedMemoryReasoningStrategy = "none" | "rewrite" | "iterative";
+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 `"similarity"` —
+     * the legacy global sort by similarity, then type/id tie-break. The
+     * alternate value `"rrf"` invokes reciprocal-rank fusion across the
+     * lists fed via the (internal) `rankedLists` option.
+     */
+    mergeStrategy?: UnifiedMemoryMergeStrategy;
+    /**
+     * 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;
+}
+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 {
+    name: "memory-bm25" | "memory-semantic" | "insights" | "knowledge";
+    hits: UnifiedMemorySearchResult[];
+}
+interface UnifiedMemorySearchResult {
+    type: "memory" | "insight" | "knowledge";
+    id: string;
+    content: string;
+    similarity: number;
+    metadata: Record<string, unknown>;
+}
+interface UnifiedMemorySearchOutput {
+    query: string;
+    sources: UnifiedMemorySearchSource[];
+    results: UnifiedMemorySearchResult[];
+    count: number;
+    warnings: UnifiedMemorySearchWarning[];
+    /**
+     * 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;
+}
+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;
+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";
+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;
+    };
+}
+type EmbedQueryFn = (input: {
+    userId: string;
+    query: 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 {
+    /** 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 UnifiedSearchDeps {
+    /** Embed a query string using the active user's provider. */
+    embedQuery?: EmbedQueryFn;
+    /**
+     * Postgres-side ANN search over `raw_messages`. Used when chroma is
+     * not enabled but the host has a postgres-backed manager. If both
+     * chroma and this are absent, the memory source will return empty
+     * (with a warning) in standalone mode.
+     */
+    searchRawMessagesAnn?: (input: {
+        userId: string;
+        queryEmbedding: number[];
+        limit: number;
+        threshold: 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: {
+        userId: string;
+        query: string;
+        options: {
+            limit: number;
+            threshold: number;
+            documentIds?: string[];
+        };
+        authToken?: string;
+    }) => Promise<UnifiedSearchKnowledgeResult[]>;
+    /** Semantic search over extracted insights. */
+    searchInsights?: (input: {
+        userId: string;
+        query: string;
+        limit: number;
+        threshold: number;
+        botIds?: string[];
+        includeArchived?: boolean;
+        authToken?: string;
+    }) => 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: {
+        userId: string;
+        keywords: string[];
+        limit: number;
+        botId?: string;
+    }) => Promise<Array<{
+        id: string;
+        content: string;
+        similarity: number;
+        metadata: Record<string, unknown>;
+    }>>;
+    /** Optional reasoning providers. */
+    reasoning?: UnifiedSearchReasoningDeps;
+}
+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 logger. Defaults to console. */
+    logger?: Pick<Console, "log" | "warn" | "error">;
+}
+
+export { isRawMemorySemanticResult as A, mergeUnifiedMemorySearchResults as B, normalizeUnifiedMemoryReasoningStrategy as C, normalizeUnifiedMemorySearchSources as D, type EmbedQueryFn as E, toKnowledgeResult as F, toMemoryResult as G, type UnifiedSearchDeps as H, type IterativeRecallCandidate as I, type UnifiedMemoryMergeStrategy as J, type UnifiedMemoryRankedList as K, mergeUnifiedMemorySearchResultsRrf as L, type MemoryStoreConfig as M, normalizeUnifiedMemoryMergeStrategy as N, type QueryRewriter as Q, type UnifiedMemoryReasoningInfo as U, type VectorBackend as V, type IterativeRecallExecutor as a, type IterativeRecallPlanner as b, type IterativeRecallPlannerOptions as c, type IterativeRecallResult as d, type IterativeRecallSearchRequest as e, type IterativeRecallSearchResult as f, type IterativeRecallStats as g, type MemoryStoreDb as h, type MemoryStoreEnv as i, type QueryRewriterInput as j, type QueryRewriterOptions as k, type UnifiedMemoryReasoningStrategy as l, type UnifiedMemorySearchInput as m, type UnifiedMemorySearchOutput as n, type UnifiedMemorySearchResult as o, type UnifiedMemorySearchSource as p, type UnifiedMemorySearchWarning as q, type UnifiedSearchInsightsResult as r, type UnifiedSearchKnowledgeResult as s, type UnifiedSearchReasoningDeps as t, clampUnifiedMemorySearchLimit as u, clampUnifiedMemorySearchThreshold as v, createIdentityIterativePlanner as w, createIdentityRewriter as x, createIterativeRecallPlanner as y, createUserVoiceRewriter as z };

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-import { M as MemoryStoreConfig } from './config-Ll6ktm4D.js';
+import { M as MemoryStoreConfig } from './config-2Q092MUz.js';
 
 /**
  * @melandlabs/memory-store/http — HTTP server entry.