@melandlabs/memory-store 1.1.8 → 1.2.0

package/dist/{config-CnbqSek5.d.ts → config-DfvVZ--0.d.ts}

@@ -2,6 +2,8 @@ import * as _melandlabs_memory_consolidation from '@melandlabs/memory-consolidat
 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';
 
 /**
  * Reranker adapter contract.
@@ -42,6 +44,49 @@ interface Reranker {
  */
 
 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" | "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;
+    /** 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";
 interface UnifiedMemorySearchWarning {
     source: UnifiedMemorySearchSource;
@@ -158,6 +203,12 @@ interface UnifiedMemorySearchResult {
     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;
@@ -280,6 +331,28 @@ declare function toMemoryResult(result: {
     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;
@@ -616,6 +689,69 @@ interface UnifiedSearchDeps {
         /** 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: {
+        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
@@ -680,4 +816,4 @@ interface MemoryStoreConfig {
     logger?: Pick<Console, "log" | "warn" | "error">;
 }
 
-export { type IterativeRecallResult as A, type IterativeRecallSearchRequest as B, type IterativeRecallSearchResult as C, type IterativeRecallStats as D, type EmbedQueryFn as E, type MemoryStoreDb as F, type QueryRewriterInput as G, type QueryRewriterOptions as H, type IterativeRecallCandidate as I, type UnifiedMemoryReasoningInfo as J, type UnifiedSearchInsightsResult as K, type UnifiedSearchKnowledgeResult as L, type MemoryStoreConfig as M, type UnifiedSearchReasoningDeps as N, createIdentityIterativePlanner as O, createIdentityRewriter as P, type QueryRewriter as Q, createIterativeRecallPlanner as R, type SearchTier as S, createUserVoiceRewriter as T, type UnifiedSearchDeps as U, type VectorBackend as V, 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 SearchSource as i, type UnifiedMemoryMergeStrategy as j, type UnifiedMemoryRankedList as k, type UnifiedMemoryReasoningStrategy as l, type UnifiedMemorySearchSource as m, clampUnifiedMemorySearchLimit as n, clampUnifiedMemorySearchThreshold as o, isRawMemorySemanticResult as p, mergeUnifiedMemorySearchResults as q, mergeUnifiedMemorySearchResultsRrf as r, normalizeUnifiedMemoryMergeStrategy as s, normalizeUnifiedMemoryReasoningStrategy as t, normalizeUnifiedMemorySearchSources as u, toKnowledgeResult as v, toMemoryResult as w, type IterativeRecallExecutor as x, type IterativeRecallPlanner as y, type IterativeRecallPlannerOptions as z };
+export { 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 UnifiedMemoryReasoningInfo as P, type QueryRewriter as Q, type UnifiedSearchInsightsResult as R, type SearchTier as S, type UnifiedSearchKnowledgeResult as T, type UnifiedSearchDeps as U, type UnifiedSearchReasoningDeps as V, type VectorBackend as W, createIdentityIterativePlanner as X, createIdentityRewriter as Y, createIterativeRecallPlanner as Z, createUserVoiceRewriter 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 };

package/dist/http.d.ts

@@ -1,7 +1,9 @@
-import { M as MemoryStoreConfig } from './config-CnbqSek5.js';
+import { M as MemoryStoreConfig } from './config-DfvVZ--0.js';
 import '@melandlabs/memory-consolidation';
 import '@melandlabs/contracts/peer';
 import '@melandlabs/contracts';
+import '@melandlabs/contracts/derived-fact';
+import '@melandlabs/contracts/entity-edge';
 
 /**
  * @melandlabs/memory-store/http — HTTP server entry.
@@ -16,7 +18,14 @@ import '@melandlabs/contracts';
  * Endpoints (all POST, JSON in/out):
  *   GET  /health              → { ok: true }
  *   POST /v1/search           → SearchOutput (set `synthesize: true` for
- *                                LLM synthesis)
+ *                                LLM synthesis). Each hit carries a
+ *                                `signals` field with per-channel scores.
+ *   POST /v1/distill          → DistillOutput (entity extraction from
+ *                                a single raw message; requires
+ *                                `unified.entityExtractor`)
+ *   POST /v1/derive           → DeriveOutput (fact derivation over a
+ *                                window of candidate texts; requires
+ *                                `unified.deriver`)
  *   POST /v1/raw-messages     → upsert raw messages (returns count)
  *   GET  /v1/raw-messages/:id → single raw message
  *   POST /v1/consolidate:apply → ApplyConsolidateOutput (agentic write-back)