@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.
- package/README.md +5 -0
- package/dist/config-9RzSCdXG.d.ts +550 -0
- package/dist/contracts.d.ts +3 -1
- package/dist/evidence-selector-uOHsxwch.d.ts +597 -0
- package/dist/http.d.ts +2 -1
- package/dist/http.js +676 -153
- package/dist/index.d.ts +6 -4
- package/dist/index.js +768 -148
- package/dist/mcp.d.ts +2 -1
- package/dist/mcp.js +689 -153
- package/dist/search/derive.d.ts +2 -1
- package/dist/search/derive.js +5 -1
- package/dist/search/distill.d.ts +2 -1
- package/dist/search/evidence-selector.d.ts +3 -0
- package/dist/search/evidence-selector.js +153 -0
- package/dist/search/unified-search.d.ts +3 -2
- package/dist/search/unified-search.js +589 -136
- package/dist/server/cli-http.js +1150 -271
- package/dist/server/cli-mcp.js +1163 -271
- package/dist/server/cli-shared.d.ts +18 -2
- package/dist/server/cli-shared.js +493 -119
- package/dist/storage/postgres-raw-message-factory.d.ts +2 -1
- package/dist/storage/raw-message-store.d.ts +10 -2
- package/dist/storage/sqlite-raw-message-store.d.ts +2 -1
- package/dist/storage/sqlite-vector-index.d.ts +2 -1
- package/dist/{unified-search-CtFFRj2O.d.ts → unified-search-BBC3jkPJ.d.ts} +2 -1
- package/package.json +15 -14
- package/dist/config-BuWr-nvt.d.ts +0 -988
|
@@ -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-
|
|
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';
|