@melandlabs/memory-store 1.3.7 → 1.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,597 @@
1
+ import { FactType } from '@melandlabs/contracts';
2
+ import { Peer } from '@melandlabs/contracts/peer';
3
+
4
+ /**
5
+ * Iterative, LLM-driven memory retrieval.
6
+ *
7
+ * Instead of issuing one fixed query, a small planner model examines the
8
+ * original question and the evidence collected so far, then decides:
9
+ * - search again with different keywords / time bounds
10
+ * - save some of the last results as evidence
11
+ * - finish gathering
12
+ *
13
+ * This trades latency and token cost for better evidence location on
14
+ * multi-hop, temporal, or underspecified questions.
15
+ *
16
+ * The module is provider-agnostic: callers inject a `complete` callback.
17
+ */
18
+ interface IterativeRecallCandidate {
19
+ id: string;
20
+ content: string;
21
+ similarity: number;
22
+ metadata: Record<string, unknown>;
23
+ }
24
+ interface IterativeRecallSearchRequest {
25
+ keywords: string[];
26
+ dateFrom?: string;
27
+ dateTo?: string;
28
+ }
29
+ interface IterativeRecallSearchResult {
30
+ candidates: IterativeRecallCandidate[];
31
+ }
32
+ interface IterativeRecallExecutor {
33
+ search(request: IterativeRecallSearchRequest): Promise<IterativeRecallSearchResult>;
34
+ }
35
+ interface IterativeRecallStats {
36
+ iterations: number;
37
+ searches: number;
38
+ notes: number;
39
+ }
40
+ interface IterativeRecallResult {
41
+ /** Evidence selected by the planner, in the order it was collected. */
42
+ evidence: IterativeRecallCandidate[];
43
+ /** Diagnostic statistics. */
44
+ stats: IterativeRecallStats;
45
+ /** Opt-in action diagnostics. Never used to select or rank evidence. */
46
+ diagnostics?: IterativeRecallDiagnostics;
47
+ }
48
+ interface IterativeRecallDiagnostics {
49
+ steps: Array<{
50
+ iteration: number;
51
+ action: PlannerAction["type"] | "invalid" | "completion_error";
52
+ responseExcerpt?: string;
53
+ multipleActions?: boolean;
54
+ errorName?: string;
55
+ httpStatus?: number;
56
+ }>;
57
+ fallback?: "recent-hits" | "baseline";
58
+ searches: number;
59
+ notes: number;
60
+ }
61
+ interface IterativeRecallPlanner {
62
+ plan(input: {
63
+ query: string;
64
+ executor: IterativeRecallExecutor;
65
+ options?: IterativeRecallPlannerOptions;
66
+ /**
67
+ * Optional absolute date range for the search. The planner passes these
68
+ * bounds to the executor and may also emit narrower ranges in later actions.
69
+ */
70
+ dateFrom?: string;
71
+ dateTo?: string;
72
+ }): Promise<IterativeRecallResult>;
73
+ /**
74
+ * Optional. When implemented, returns true iff the most recent `plan()`
75
+ * could not run the planner as designed and fell back to a degraded
76
+ * result — for example the LLM call threw, every iteration produced an
77
+ * unparseable action, or the result relied on the fallback path
78
+ * (recent-hits or baseline search) because the planner never committed
79
+ * any evidence via a `note` action.
80
+ */
81
+ lastDegraded?: () => boolean;
82
+ }
83
+ interface IterativeRecallPlannerOptions {
84
+ /** Maximum planner actions. @default 4 */
85
+ maxIterations?: number;
86
+ /** Results exposed to the planner per internal search. @default 5 */
87
+ searchTopK?: number;
88
+ /** When true, skip planning and return no evidence. @default false */
89
+ disabled?: boolean;
90
+ /**
91
+ * When true (default), if the planner finishes without noting any
92
+ * evidence the planner falls back to either the most recent hits or a
93
+ * baseline keyword search against the original query, so the call is
94
+ * never a total loss. Set to false to surface empty results honestly
95
+ * when the planner never committed anything.
96
+ * @default true
97
+ */
98
+ fallbackToBaseline?: boolean;
99
+ /** Include bounded response excerpts and degradation causes. @default false */
100
+ collectDiagnostics?: boolean;
101
+ }
102
+ interface IterativeRecallCompletionOptions {
103
+ /** Preserve real chat roles instead of asking the model to continue a transcript. */
104
+ messages: ReadonlyArray<{
105
+ role: "system" | "user" | "assistant";
106
+ content: string;
107
+ }>;
108
+ }
109
+ interface IterativeRecallPlannerDeps {
110
+ /** LLM completion callback. Chat transports should send options.messages
111
+ * verbatim; the string prompt is also supplied for plain completion hosts. */
112
+ complete: (prompt: string, options?: IterativeRecallCompletionOptions) => Promise<string>;
113
+ /** Default options. */
114
+ options?: IterativeRecallPlannerOptions;
115
+ }
116
+ type PlannerAction = {
117
+ type: "search";
118
+ keywords: string[];
119
+ dateFrom?: string;
120
+ dateTo?: string;
121
+ } | {
122
+ type: "note";
123
+ indices: number[];
124
+ } | {
125
+ type: "finish";
126
+ };
127
+ declare function createIterativeRecallPlanner(deps: IterativeRecallPlannerDeps): IterativeRecallPlanner;
128
+ /**
129
+ * A no-op planner that never runs iterative retrieval.
130
+ */
131
+ declare function createIdentityIterativePlanner(): IterativeRecallPlanner;
132
+
133
+ type UnifiedMemorySearchSource = "memory" | "insights" | "knowledge";
134
+ /**
135
+ * A retrieval channel that contributed to a hit's final score.
136
+ *
137
+ * - `semantic` — dense embedding lookup (`searchRawMessagesAnn` or
138
+ * the SQLite manager's semantic-search fallback).
139
+ * - `lexical` — BM25 / FTS5 keyword match
140
+ * (`searchRawMessagesLexical` or the SQLite manager's lexical
141
+ * fallback).
142
+ * - `planner` — evidence selected by iterative recall.
143
+ * - `entity` — entity-link match supplied by the host's
144
+ * `entitySearch` dep.
145
+ */
146
+ type HitChannel = "semantic" | "lexical" | "planner" | "hybrid" | "entity";
147
+ type UnifiedMemoryRrfWeights = Partial<Record<HitChannel, number>>;
148
+ /**
149
+ * Per-hit score breakdown. Always emitted by `search()` (default merge
150
+ * strategy) so callers can threshold / re-rank without losing the
151
+ * individual channel contributions. The RRF fusion additionally
152
+ * populates `signals.rrf` and continues to mirror the fused score
153
+ * onto `metadata.rrfScore` (legacy field).
154
+ *
155
+ * Each numeric field is the raw per-channel score for the *first*
156
+ * (highest-ranked) appearance of the same `(type, id)` key in the
157
+ * channel's list. Channels that did not contribute are `undefined`.
158
+ */
159
+ interface HitSignals {
160
+ /** Channels the hit actually appeared in. */
161
+ channels: HitChannel[];
162
+ /** Semantic sub-query similarity in [0..1] (undefined when absent). */
163
+ semantic?: number;
164
+ /** Lexical sub-query BM25 score (undefined when absent). */
165
+ lexical?: number;
166
+ /** Iterative planner evidence score (undefined when absent). */
167
+ planner?: number;
168
+ /** Native backend dense+BM25 fused score (undefined when absent). */
169
+ hybrid?: number;
170
+ /** Entity sub-query match score (undefined when absent). */
171
+ entity?: number;
172
+ /** RRF-fused score (only when mergeStrategy === "rrf"). */
173
+ rrf?: number;
174
+ }
175
+ /**
176
+ * Derive simple lexical keywords from a query string. Splits on any
177
+ * non-letter/non-digit Unicode boundary, lowercases, drops tokens
178
+ * shorter than 2 chars, deduplicates in first-occurrence order, and caps
179
+ * the unique list at 16. Used by the unified
180
+ * search lexical sub-query and by the `derive` primitive's candidate
181
+ * fetch fallback.
182
+ */
183
+ declare function deriveLexicalKeywords(query: string): string[];
184
+ type UnifiedMemoryReasoningStrategy = "none" | "rewrite" | "iterative" | "union";
185
+ interface UnifiedMemorySearchWarning {
186
+ source: UnifiedMemorySearchSource;
187
+ code: string;
188
+ message: string;
189
+ }
190
+ interface UnifiedMemoryReasoningInfo {
191
+ strategy: UnifiedMemoryReasoningStrategy;
192
+ /**
193
+ * True when the caller asked for a non-`"none"` strategy but the
194
+ * corresponding reasoning provider was not configured (or its LLM
195
+ * call failed), so the unified search silently fell back to the default
196
+ * one-shot semantic + lexical path. Callers can use this to surface a
197
+ * degraded-mode warning to their users.
198
+ */
199
+ degraded?: boolean;
200
+ /** Query variants produced by the rewriter (original + rewritten). */
201
+ rewrittenQueries?: string[];
202
+ /** Bounded query variants actually used by the opt-in lexical rewrite path. */
203
+ lexicalRewrittenQueries?: string[];
204
+ /** Present only when RRF fusion of multiple semantic query variants ran. */
205
+ semanticVariantMerge?: "rrf";
206
+ /** Number of planner iterations executed (iterative mode only). */
207
+ iterations?: number;
208
+ /** Number of evidence items collected by the planner (iterative mode only). */
209
+ evidenceCount?: number;
210
+ /** Opt-in planner action ledger, only when retrieval diagnostics were requested. */
211
+ plannerDiagnostics?: IterativeRecallDiagnostics;
212
+ /** Date range that was applied to the memory source, if any. */
213
+ dateRange?: {
214
+ from?: string;
215
+ to?: string;
216
+ };
217
+ }
218
+ interface UnifiedMemorySearchInput {
219
+ userId: string;
220
+ query: string;
221
+ sources?: UnifiedMemorySearchSource[];
222
+ limit?: number;
223
+ /** Optional diagnostic candidate budget; defaults to max(limit, limit * 4). */
224
+ candidateLimit?: number;
225
+ threshold?: number;
226
+ authToken?: string;
227
+ includeArchivedInsights?: boolean;
228
+ botIds?: string[];
229
+ documentIds?: string[];
230
+ /**
231
+ * Optional ISO-8601 timestamp. When set, graph-aware retrieval and other
232
+ * snapshot consumers drop nodes / edges whose `applicability.validFrom` /
233
+ * `validUntil` window is closed at that instant. Backward-compatible:
234
+ * omitted `asOf` keeps the legacy behaviour exactly.
235
+ *
236
+ * This is a single-point snapshot, not a date range. For interval filtering
237
+ * over memory timestamps use `dateFrom` / `dateTo`.
238
+ */
239
+ asOf?: string;
240
+ /**
241
+ * Optional inclusive start date (ISO-8601). When set, the memory source
242
+ * filters out candidates whose timestamp is before this boundary. The
243
+ * iterative planner also receives this bound and may emit narrower ranges.
244
+ *
245
+ * This only affects the `memory` source; `insights` and `knowledge` are
246
+ * not filtered by this range. Candidates without a recognised timestamp are
247
+ * retained.
248
+ */
249
+ dateFrom?: string;
250
+ /**
251
+ * Optional inclusive end date (ISO-8601). When set, the memory source
252
+ * filters out candidates whose timestamp is after this boundary. Date-only
253
+ * strings are treated as the end of that day.
254
+ *
255
+ * This only affects the `memory` source; `insights` and `knowledge` are
256
+ * not filtered by this range. Candidates without a recognised timestamp are
257
+ * retained.
258
+ */
259
+ dateTo?: string;
260
+ /**
261
+ * How to merge per-source result lists. Defaults to `"rrf"` reciprocal-rank
262
+ * fusion. `"similarity"` preserves the legacy global similarity sort.
263
+ */
264
+ mergeStrategy?: UnifiedMemoryMergeStrategy;
265
+ /** Optional per-channel RRF weights. Omitted channels retain weight 1. */
266
+ rrfWeights?: UnifiedMemoryRrfWeights;
267
+ /** Optional reciprocal-rank damping constant. Defaults to 60. */
268
+ rrfK?: number;
269
+ /** Opt-in post-fusion session-neighbor expansion used by retrieval experiments. */
270
+ sessionNeighborExpansion?: SessionNeighborExpansionOptions;
271
+ /**
272
+ * Optional additive scope-narrowing filter expressed as structured
273
+ * peers. Coexists with `userId`/`botIds`. When supplied, the host's
274
+ * `UnifiedSearchDeps.peerScopeCheck` is consulted; peers that fall
275
+ * outside `userId` are dropped with a `peer_filter_outside_user_scope`
276
+ * warning rather than broadening the scope.
277
+ */
278
+ peerFilter?: ReadonlyArray<Peer>;
279
+ /**
280
+ * Optional reasoning strategy. `"rewrite"` rewrites the query before
281
+ * embedding; `"iterative"` runs an LLM planner that searches, notes
282
+ * evidence, and searches again. Defaults to `"none"`.
283
+ */
284
+ reasoningStrategy?: UnifiedMemoryReasoningStrategy;
285
+ /**
286
+ * Optional `FactType` read-side filter. When supplied, the memory
287
+ * source narrows candidates to rows whose `factType` is in this set.
288
+ * Only affects the `memory` source; `insights` and `knowledge` are
289
+ * not filtered by this. Empty array is treated as "no filter" so
290
+ * callers can pass `searchInput.factTypes ?? []` without surprises.
291
+ */
292
+ factTypes?: FactType[];
293
+ /** Include pre-fusion channel candidates in the response for diagnostics. */
294
+ includeRetrievalDiagnostics?: boolean;
295
+ /**
296
+ * Include messages that have been soft-deprecated
297
+ * (`raw_messages.deprecated_at IS NOT NULL`). Default `false` keeps
298
+ * `current-truth` retrievals clean: a row that was marked superseded
299
+ * via `deprecateMessages` (or the `opencontext deprecate` CLI) is
300
+ * excluded from results. Set to `true` for audits and historical
301
+ * exploration.
302
+ */
303
+ includeDeprecated?: boolean;
304
+ }
305
+ type UnifiedMemoryMergeStrategy = "similarity" | "rrf";
306
+ /**
307
+ * A single ranked list from one retrieval channel. Used by the RRF merge to
308
+ * combine multiple signals (semantic + lexical + insights + knowledge) without
309
+ * flattening them into a single similarity score first.
310
+ */
311
+ interface UnifiedMemoryRankedList {
312
+ /** Label for the source list (e.g. a tier or channel). Free-form; the
313
+ * RRF fusion only reads `hits`, so `name` is purely diagnostic. */
314
+ name: string;
315
+ hits: UnifiedMemorySearchResult[];
316
+ }
317
+ type SessionNeighborExpansionMode = "union" | "protected";
318
+ interface SessionNeighborExpansionOptions {
319
+ /** Number of fused seed messages used to find neighbors. */
320
+ seedLimit?: number;
321
+ /** Number of messageSequence steps to inspect on each side. */
322
+ window?: number;
323
+ /** `union` lets reranking choose all candidates; `protected` reserves slots for direct hits. */
324
+ mode?: SessionNeighborExpansionMode;
325
+ /** Maximum neighbor results in `protected` mode. */
326
+ maxNeighborSlots?: number;
327
+ }
328
+ interface UnifiedMemorySearchResult {
329
+ type: "memory" | "insight" | "knowledge";
330
+ id: string;
331
+ content: string;
332
+ similarity: number;
333
+ metadata: Record<string, unknown>;
334
+ /**
335
+ * Optional per-channel score breakdown. Always populated by the
336
+ * pipeline when at least one channel contributed a non-empty list;
337
+ * callers should treat absence as "no channel info available".
338
+ */
339
+ signals?: HitSignals;
340
+ }
341
+ interface UnifiedMemorySearchOutput {
342
+ query: string;
343
+ sources: UnifiedMemorySearchSource[];
344
+ results: UnifiedMemorySearchResult[];
345
+ count: number;
346
+ warnings: UnifiedMemorySearchWarning[];
347
+ retrievalDiagnostics?: UnifiedMemoryRetrievalDiagnostics;
348
+ /**
349
+ * Diagnostic information about reasoning and date filtering. Present
350
+ * when (a) a non-`"none"` reasoning strategy was requested, or (b) a
351
+ * `dateFrom` / `dateTo` filter was applied to the memory source.
352
+ */
353
+ reasoning?: UnifiedMemoryReasoningInfo;
354
+ }
355
+ interface UnifiedMemoryRetrievalDiagnostics {
356
+ mergeStrategy: UnifiedMemoryMergeStrategy;
357
+ candidateLimit: number;
358
+ rrf?: {
359
+ k: number;
360
+ weights: UnifiedMemoryRrfWeights;
361
+ };
362
+ backend?: string;
363
+ semanticDegradedReason?: string;
364
+ /** Wall-clock timings for the retrieval stages, in milliseconds. */
365
+ timings?: {
366
+ totalMs: number;
367
+ memorySourceMs: number;
368
+ semanticMs: number;
369
+ lexicalMs: number;
370
+ hybridMs: number;
371
+ plannerMs: number;
372
+ fusionMs: number;
373
+ rerankerMs: number;
374
+ neighborMs?: number;
375
+ };
376
+ candidateCounts?: {
377
+ semantic: number;
378
+ lexical: number;
379
+ planner?: number;
380
+ hybrid: number;
381
+ entity: number;
382
+ fused: number;
383
+ expanded?: number;
384
+ final: number;
385
+ };
386
+ channels: {
387
+ semantic: UnifiedMemorySearchResult[];
388
+ lexical: UnifiedMemorySearchResult[];
389
+ planner?: UnifiedMemorySearchResult[];
390
+ hybrid?: UnifiedMemorySearchResult[];
391
+ entity?: UnifiedMemorySearchResult[];
392
+ };
393
+ /** Results after channel/source fusion and before an optional host reranker. */
394
+ fusedBeforeRerank: UnifiedMemorySearchResult[];
395
+ /** Candidates after optional session-neighbor expansion and before reranking. */
396
+ expandedBeforeRerank?: UnifiedMemorySearchResult[];
397
+ sessionNeighborExpansion?: {
398
+ enabled: boolean;
399
+ mode?: SessionNeighborExpansionMode;
400
+ seedCount: number;
401
+ neighborCount: number;
402
+ sessions: number;
403
+ latencyMs: number;
404
+ };
405
+ reranker?: {
406
+ enabled: boolean;
407
+ provider?: string;
408
+ model?: string;
409
+ inputCount: number;
410
+ outputCount: number;
411
+ latencyMs: number;
412
+ orderChanged: boolean;
413
+ };
414
+ /** Final results after optional reranking and Top-K truncation. */
415
+ final: UnifiedMemorySearchResult[];
416
+ }
417
+ /**
418
+ * Cross-source retrieval surface for the unified search. Mirrors
419
+ * `UnifiedMemorySearchSource` but is exposed under a more discoverable
420
+ * name.
421
+ */
422
+ type SearchSource = UnifiedMemorySearchSource;
423
+ /**
424
+ * Per-tier evidence bucket consulted by `reflect`-style synthesis.
425
+ * Includes the `summary` tier that the read-only sources do not surface.
426
+ */
427
+ type SearchTier = "summary" | "raw" | "insight" | "knowledge";
428
+ interface SearchInput {
429
+ userId: string;
430
+ query: string;
431
+ /** Cross-source retrieval surface (defaults to all three sources). */
432
+ sources?: ReadonlyArray<SearchSource>;
433
+ /**
434
+ * Per-tier subset — when omitted, defaults to all four tiers.
435
+ * Forwarded to the gather step so the read pipeline can scope the
436
+ * evidence. Most callers pass nothing; `synthesize` callers can
437
+ * narrow to `["raw"]` or `["summary", "raw"]` for cheaper synthesis.
438
+ */
439
+ tiers?: ReadonlyArray<SearchTier>;
440
+ /**
441
+ * Opt-in LLM synthesis. When `true`, runs `reasoning.complete` after
442
+ * gathering evidence and returns `answer` in the output. When
443
+ * omitted / `false`, no LLM call is made (matches today's
444
+ * `searchUnifiedMemory`). The `responseSchema` form lets the LLM
445
+ * return JSON; the SDK extracts `{ answer: string }` from the
446
+ * payload and surfaces the rest via warnings.
447
+ */
448
+ synthesize?: boolean | {
449
+ responseSchema?: Record<string, unknown>;
450
+ };
451
+ limit?: number;
452
+ /** Optional diagnostic candidate budget; defaults to max(limit, limit * 4). */
453
+ candidateLimit?: number;
454
+ threshold?: number;
455
+ botIds?: string[];
456
+ documentIds?: string[];
457
+ dateFrom?: string;
458
+ dateTo?: string;
459
+ asOf?: string;
460
+ peerFilter?: ReadonlyArray<Peer>;
461
+ authToken?: string;
462
+ factTypes?: FactType[];
463
+ mergeStrategy?: UnifiedMemoryMergeStrategy;
464
+ rrfWeights?: UnifiedMemoryRrfWeights;
465
+ rrfK?: number;
466
+ sessionNeighborExpansion?: SessionNeighborExpansionOptions;
467
+ reasoningStrategy?: UnifiedMemoryReasoningStrategy;
468
+ /**
469
+ * Backward-compat pass-through for callers that previously passed
470
+ * `responseSchema` at the top level. When set, it overrides
471
+ * `synthesize.responseSchema`.
472
+ */
473
+ responseSchema?: Record<string, unknown>;
474
+ /**
475
+ * Backward-compat pass-through for callers that previously passed
476
+ * `includeArchivedInsights` to the read-only search.
477
+ */
478
+ includeArchivedInsights?: boolean;
479
+ /** Include pre-fusion retrieval candidates; intended for evaluation/debugging. */
480
+ includeRetrievalDiagnostics?: boolean;
481
+ /**
482
+ * Include messages that have been soft-deprecated
483
+ * (`raw_messages.deprecated_at IS NOT NULL`). Default `false` keeps
484
+ * `current-truth` retrievals clean: a row that was marked superseded
485
+ * via `deprecateMessages` (or the `opencontext deprecate` CLI) is
486
+ * excluded from results. Set to `true` for audits and historical
487
+ * exploration.
488
+ */
489
+ includeDeprecated?: boolean;
490
+ }
491
+ interface SearchEvidence {
492
+ id: string;
493
+ source: SearchSource | SearchTier;
494
+ snippet: string;
495
+ score: number;
496
+ timestamp?: number;
497
+ /**
498
+ * Forwarded from the underlying hit's `metadata`. Surfaces per-fact
499
+ * provenance (`metadata.source`, `metadata.factType`, etc.) to the
500
+ * synthesis prompt and the CLI's `--context-only` / `--json` output.
501
+ */
502
+ metadata?: Record<string, unknown>;
503
+ }
504
+ interface SearchOutput {
505
+ query: string;
506
+ sources: ReadonlyArray<SearchSource>;
507
+ results: UnifiedMemorySearchResult[];
508
+ /** Same hits as `results`, with the source labelled for synthesis callers. */
509
+ evidence: SearchEvidence[];
510
+ count: number;
511
+ warnings: UnifiedMemorySearchWarning[];
512
+ retrievalDiagnostics?: UnifiedMemoryRetrievalDiagnostics;
513
+ reasoning?: UnifiedMemoryReasoningInfo;
514
+ /** Only present when `synthesize` was truthy. */
515
+ answer?: string;
516
+ }
517
+ declare function normalizeUnifiedMemorySearchSources(sources: unknown): UnifiedMemorySearchSource[];
518
+ declare function clampUnifiedMemorySearchLimit(limit: unknown): number;
519
+ declare function clampUnifiedMemorySearchThreshold(threshold: unknown): number;
520
+ declare function mergeUnifiedMemorySearchResults(results: UnifiedMemorySearchResult[], limit: number, options?: {
521
+ strategy?: UnifiedMemoryMergeStrategy;
522
+ rankedLists?: UnifiedMemoryRankedList[];
523
+ rrfK?: number;
524
+ rrfWeights?: UnifiedMemoryRrfWeights;
525
+ }): UnifiedMemorySearchResult[];
526
+ declare function normalizeUnifiedMemoryMergeStrategy(value: unknown): UnifiedMemoryMergeStrategy;
527
+ declare function normalizeUnifiedMemoryReasoningStrategy(value: unknown, defaultStrategy?: UnifiedMemoryReasoningStrategy): UnifiedMemoryReasoningStrategy;
528
+ /**
529
+ * Reciprocal Rank Fusion across multiple ranked lists. Each list contributes
530
+ * `1 / (k + rank + 1)` to a hit's accumulated score. Hits are de-duplicated by
531
+ * `(type, id)` so the same message surfaced by both lexical and semantic
532
+ * channels naturally outranks single-channel matches. Tie-break is
533
+ * deterministic: descending RRF score, then `(type, id)` lexical.
534
+ */
535
+ declare function mergeUnifiedMemorySearchResultsRrf(lists: UnifiedMemoryRankedList[], limit: number, k?: number, weights?: UnifiedMemoryRrfWeights): UnifiedMemorySearchResult[];
536
+ declare function toKnowledgeResult(result: {
537
+ chunkId: string;
538
+ documentId: string;
539
+ documentName: string;
540
+ content: string;
541
+ similarity: number;
542
+ chunkIndex: number;
543
+ }): UnifiedMemorySearchResult;
544
+ declare function toMemoryResult(result: {
545
+ id: string;
546
+ content: string;
547
+ similarity: number;
548
+ metadata: Record<string, unknown>;
549
+ }): UnifiedMemorySearchResult;
550
+ /**
551
+ * Build the `signals` breakdown for a single hit from the per-channel
552
+ * ranked lists it appeared in. Only the highest-ranked (i.e. first)
553
+ * appearance of `(type, id)` per channel contributes — duplicate hits
554
+ * later in the same list are ignored so the breakdown stays
555
+ * deterministic.
556
+ *
557
+ * Used by `mergeAcrossSources` to attach `signals` to every emitted
558
+ * `UnifiedMemorySearchResult`. Pure; no I/O.
559
+ */
560
+ declare function materializeSignals(lists: ReadonlyArray<{
561
+ name: string;
562
+ hits: UnifiedMemorySearchResult[];
563
+ }>, hit: UnifiedMemorySearchResult): HitSignals | undefined;
564
+ /**
565
+ * Map a `UnifiedMemoryRankedList.name` to a `HitChannel`. Unknown names
566
+ * (e.g. "insights", "knowledge", "summary") are not channels — they
567
+ * surface their similarity through the merge's `similarity` field and
568
+ * are simply skipped here so callers can still see which channel set
569
+ * the hit came from.
570
+ */
571
+ declare function listNameToChannel(name: string): HitChannel | undefined;
572
+ declare function isRawMemorySemanticResult(result: unknown): result is {
573
+ id: string;
574
+ content: string;
575
+ similarity: number;
576
+ metadata: Record<string, unknown>;
577
+ };
578
+
579
+ interface EvidenceSelector {
580
+ select(input: {
581
+ query: string;
582
+ hits: UnifiedMemorySearchResult[];
583
+ }): Promise<{
584
+ hits: UnifiedMemorySearchResult[];
585
+ warnings: UnifiedMemorySearchWarning[];
586
+ }>;
587
+ }
588
+ interface EvidenceSelectorOptions {
589
+ complete: (prompt: string) => Promise<string>;
590
+ /** Serialized source character budget; oversized hits remain intact. */
591
+ maxSourceCharacters?: number;
592
+ }
593
+ /** Extractive selection AFTER ranking. No writes, invented text, new sources,
594
+ * changed ranking, or reranker-input changes. Disabled unless explicitly wired. */
595
+ declare function createExtractiveEvidenceSelector(options: EvidenceSelectorOptions): EvidenceSelector;
596
+
597
+ export { toMemoryResult as A, type EvidenceSelectorOptions as B, type IterativeRecallCandidate as C, type IterativeRecallCompletionOptions as D, type EvidenceSelector as E, type IterativeRecallExecutor as F, type IterativeRecallPlannerOptions as G, type HitChannel as H, type IterativeRecallPlanner as I, type IterativeRecallResult as J, type IterativeRecallSearchRequest as K, type IterativeRecallSearchResult as L, type IterativeRecallStats as M, type UnifiedMemoryReasoningInfo as N, createExtractiveEvidenceSelector as O, createIdentityIterativePlanner as P, createIterativeRecallPlanner as Q, type SearchTier as S, type UnifiedMemorySearchWarning as U, type SearchEvidence as a, type SearchInput as b, type SearchOutput as c, type UnifiedMemorySearchInput as d, type UnifiedMemorySearchOutput as e, type UnifiedMemorySearchResult as f, type HitSignals as g, type SearchSource as h, type SessionNeighborExpansionOptions as i, type UnifiedMemoryMergeStrategy as j, type UnifiedMemoryRankedList as k, type UnifiedMemoryReasoningStrategy as l, type UnifiedMemoryRrfWeights 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 CHANGED
@@ -1,6 +1,7 @@
1
- import { M as MemoryStoreConfig } from './config-BuWr-nvt.js';
1
+ import { M as MemoryStoreConfig } from './config-9RzSCdXG.js';
2
2
  import '@melandlabs/memory-consolidation';
3
3
  import '@melandlabs/contracts/peer';
4
+ import './evidence-selector-uOHsxwch.js';
4
5
  import '@melandlabs/contracts';
5
6
  import '@melandlabs/contracts/derived-fact';
6
7
  import '@melandlabs/contracts/entity-edge';