@ngockhoale/ukit 3.4.85 → 3.5.1

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.
@@ -10,8 +10,9 @@ import { loadV2Records } from './storeV2Loader.js';
10
10
  import { POLICY_VERSION, eligible, resolveEffectiveScope } from './policy.js';
11
11
  import { loadRuntimeConfig } from '../runtimeConfig.js';
12
12
  import { resolveMemoryStage, appendRolloutReceipt, latencyBandForMs } from './memoryFlags.js';
13
- import { createIndex, normalize, scoreRecordTokens, tokenize } from './recordIndex.js';
14
- import { buildMemoryHit, rankHits } from './memoryHit.js';
13
+ import { normalize, tokenize } from './recordIndex.js';
14
+ import { buildMemoryHit, rankHitsDetailed } from './memoryHit.js';
15
+ import { loadMarkdownDocs, normalizeMemorySources, renderMarkdownDoc } from './recallEngine.js';
15
16
  import { resolveRecordFreshness } from './memoryFreshness.js';
16
17
  import { getHeadSha } from '../codeintel/freshness.js';
17
18
  import { emitRetrievalQuery, emitMemoryRetrieved } from './memoryEmit.js';
@@ -233,21 +234,6 @@ export const LEGACY_SCOPE_MATCH = {
233
234
  session: (record) => record.type === 'episode' || record.scope === 'session',
234
235
  };
235
236
 
236
- // TASK-003 (FR-005): both v2 search paths delegate ranking to rankHits.
237
- // rankHits includes bonus-only (lexical=0) records; the index path can only
238
- // surface token-matching candidates, so the scan path pre-filters to the
239
- // same candidate pool (scoreRecordTokens > 0) — identical hits either way.
240
- // Returns {hits, candidateCount} — the count feeds retrieval.query telemetry
241
- // (DF2-FR08) without recomputing the pool.
242
- function searchRecords(records, query, scope, limit, eligibleCtx, policy, now) {
243
- const queryTokens = tokenize(query);
244
- const candidates = records.filter((record) => scoreRecordTokens(record, queryTokens, now) > 0);
245
- return {
246
- hits: rankHits(candidates, { queryTokens, eligibleCtx, policy, scope, limit, now }),
247
- candidateCount: candidates.length,
248
- };
249
- }
250
-
251
237
  // Freshness is resolved post-limit only (≤ limit × MAX_EVIDENCE stats per
252
238
  // call). Watermarks are caller-supplied; when omitted and a hit carries
253
239
  // non-file evidence, `command` is filled lazily via getHeadSha (one bounded
@@ -269,6 +255,7 @@ async function attachFreshness(hits, records, { projectRoot, watermarks, now } =
269
255
  }
270
256
  await Promise.all(hits.map(async (hit) => {
271
257
  const record = recordById.get(hit.id);
258
+ if (!record) return; // markdown-source hits carry no record evidence
272
259
  hit.freshness = await resolveRecordFreshness(record, {
273
260
  projectRoot,
274
261
  watermarks: resolvedWatermarks,
@@ -287,37 +274,10 @@ const REQUESTED_SCOPE_TO_POLICY = { project: 'repo' };
287
274
  // mismatch, absence, or error falls back to the lexical scan — the index
288
275
  // narrows candidates, rankHits re-gates + scores (identical output either
289
276
  // path: the index candidate pool is exactly the score>0 set the scan uses).
290
- // Module-scoped index cache (in-process only, never persisted).
291
- const recordIndexes = new Map();
292
-
293
- export function resetRecordIndexForTests() {
294
- recordIndexes.clear();
295
- }
296
-
297
- function searchRecordsIndexed(records, query, scope, limit, eligibleCtx, policy, indexKey, generation, now) {
298
- const queryTokens = tokenize(query);
299
- if (queryTokens.length === 0) {
300
- return searchRecords(records, query, scope, limit, eligibleCtx, policy, now);
301
- }
302
- try {
303
- let index = recordIndexes.get(indexKey);
304
- if (!index) {
305
- index = createIndex();
306
- recordIndexes.set(indexKey, index);
307
- }
308
- if (index.stats().generation !== generation) {
309
- index.build(records, { generation });
310
- }
311
- const candidates = index.query(queryTokens, { limit: records.length })
312
- .map((hit) => hit.record);
313
- return {
314
- hits: rankHits(candidates, { queryTokens, eligibleCtx, policy, scope, limit, now }),
315
- candidateCount: candidates.length,
316
- };
317
- } catch {
318
- return searchRecords(records, query, scope, limit, eligibleCtx, policy, now);
319
- }
320
- }
277
+ // 3.5.1: the persistent-less inverted index path was removed with the move to
278
+ // one BM25 engine (IDF needs the whole eligible set anyway). Kept as a no-op
279
+ // so existing test imports keep working.
280
+ export function resetRecordIndexForTests() {}
321
281
 
322
282
  export async function search(query, scope = 'all', limit = 10, { projectRoot, projectId, projectAliases, index = true, watermarks, homeDir, now } = {}) {
323
283
  const startedAt = Date.now();
@@ -360,44 +320,27 @@ export async function search(query, scope = 'all', limit = 10, { projectRoot, pr
360
320
  includeUser: effective.includeUser,
361
321
  };
362
322
 
323
+ // Markdown source (docs/MEMORY.md bullets by default): read-only documents,
324
+ // never copied into records.json. Missing file => no documents, no error.
325
+ const markdownDocs = scope === 'all' || scope === 'project' || scope === 'repo'
326
+ ? await loadMarkdownDocs(projectRoot, normalizeMemorySources(config)).catch(() => [])
327
+ : [];
328
+
363
329
  if (!v2AllowsLegacyFallback(state)) {
364
- const indexKey = `${projectRoot ?? ''}::${effective.projectId ?? ''}::${POLICY_VERSION}`;
365
- // Index plane (FR-003): 'off' forces the linear scan; 'shadow' runs the
366
- // indexed path for measurement, discards it, and serves the scan result
367
- // (zero output change) plus a bounded receipt.
368
- if (index !== false && indexStage === 'shadow') {
369
- const shadowStarted = Date.now();
370
- try {
371
- searchRecordsIndexed(records, query, scope, limit, eligibleCtx, policy, indexKey, generation, now);
372
- await appendRolloutReceipt(projectRoot, {
373
- plane: 'index', stage: 'shadow', outcome: 'ok', code: 'search',
374
- latencyBand: latencyBandForMs(Date.now() - shadowStarted),
375
- });
376
- } catch {
377
- await appendRolloutReceipt(projectRoot, {
378
- plane: 'index', stage: 'shadow', outcome: 'error', code: 'search',
379
- latencyBand: latencyBandForMs(Date.now() - shadowStarted),
380
- });
381
- }
382
- }
383
- const useIndex = index !== false && indexStage !== 'off' && indexStage !== 'shadow';
384
- const { hits, candidateCount } = useIndex
385
- ? searchRecordsIndexed(
386
- records, query, scope, limit, eligibleCtx, policy,
387
- indexKey,
388
- generation,
389
- now,
390
- )
391
- : searchRecords(records, query, scope, limit, eligibleCtx, policy, now);
392
- const results = await attachFreshness(hits, records, { projectRoot, watermarks, now });
393
- emitQuery({ lane: 'v2', indexed: useIndex, candidateCount, results });
330
+ // One engine (recallEngine.js BM25): eligibility first, then IDF over the
331
+ // eligible set + markdown bullets, floor, explicit empty result.
332
+ const ranked = rankHitsDetailed(records, {
333
+ query, eligibleCtx, policy, scope, limit, now, extraDocs: markdownDocs,
334
+ });
335
+ const results = await attachFreshness(ranked.hits, records, { projectRoot, watermarks, now });
336
+ emitQuery({ lane: 'v2', indexed: false, candidateCount: ranked.candidateCount, results });
394
337
  return results;
395
338
  }
396
339
 
397
340
  const items = await listMemoryItems(projectRoot, { homeDir });
398
341
  const queryTokens = tokenize(query);
399
342
  const inScope = items.filter((item) => withinScope(item, scope, projectId, projectAliases));
400
- const results = inScope
343
+ const legacyResults = inScope
401
344
  .map((item) => ({
402
345
  item,
403
346
  score: scoreItem(item, queryTokens),
@@ -410,6 +353,10 @@ export async function search(query, scope = 'all', limit = 10, { projectRoot, pr
410
353
  ))
411
354
  .slice(0, limit)
412
355
  .map((entry) => buildSearchResult(entry.item, entry.score));
356
+ const markdownRanked = markdownDocs.length > 0
357
+ ? rankHitsDetailed([], { query, limit, now, extraDocs: markdownDocs }).hits
358
+ : [];
359
+ const results = [...markdownRanked, ...legacyResults].slice(0, limit);
413
360
  emitQuery({ lane: 'legacy', indexed: false, candidateCount: inScope.length, results });
414
361
  return results;
415
362
  }
@@ -533,6 +480,7 @@ function buildInjectionSnippet(item) {
533
480
 
534
481
 
535
482
  function buildRecordSnippet(record) {
483
+ if (record.type === 'markdown') return renderMarkdownDoc(record);
536
484
  const text = String(record.text ?? '').trim();
537
485
  return `${record.type}=${text.length > 160 ? `${text.slice(0, 157)}...` : text}`;
538
486
  }
@@ -676,21 +624,32 @@ export async function getContextInjection(
676
624
  });
677
625
  const rankedItems = await search(currentTask, 'all', Math.max(limit * 3, 8), { projectRoot, projectId, projectAliases, homeDir });
678
626
  const eligibleCtx = { projectId: projectId ?? null, projectAliases, includeUser: recallPlan.includeUserMemory };
627
+ // Markdown-source hits (read-only bullets) are cited data with provenance
628
+ // `path:line`; they are never records and carry no evidence/freshness.
629
+ const markdownRecord = (entry) => ({
630
+ id: entry.id, type: 'markdown', text: entry.snippet, provenance: entry.provenance, evidence: [],
631
+ });
632
+ const markdownSelected = rankedItems.filter((entry) => entry.type === 'markdown').map(markdownRecord);
679
633
  const selectedItems = v2Active
680
634
  ? dedupeItemsById(rankedItems
681
- .map((entry) => records.find((record) => record.id === entry.id))
635
+ .map((entry) => (entry.type === 'markdown'
636
+ ? markdownRecord(entry)
637
+ : records.find((record) => record.id === entry.id)))
682
638
  .filter(Boolean)
683
- .filter((record) => eligible(record, eligibleCtx, policy).ok))
639
+ .filter((record) => record.type === 'markdown' || eligible(record, eligibleCtx, policy).ok))
684
640
  .slice(0, Math.max(1, recallPlan.limit))
685
- : selectContextItems({
686
- items,
687
- rankedItems,
688
- projectId,
689
- projectAliases,
690
- limit: recallPlan.limit,
691
- includeUserMemory: recallPlan.includeUserMemory,
692
- allowProjectFallback: !String(currentTask ?? '').trim(),
693
- });
641
+ : [
642
+ ...markdownSelected,
643
+ ...selectContextItems({
644
+ items,
645
+ rankedItems: rankedItems.filter((entry) => entry.type !== 'markdown'),
646
+ projectId,
647
+ projectAliases,
648
+ limit: recallPlan.limit,
649
+ includeUserMemory: recallPlan.includeUserMemory,
650
+ allowProjectFallback: !String(currentTask ?? '').trim(),
651
+ }),
652
+ ].slice(0, Math.max(1, recallPlan.limit));
694
653
 
695
654
  if (selectedItems.length === 0) {
696
655
  return '';
@@ -741,10 +700,14 @@ export async function getContextInjection(
741
700
  const staleTag = (record) => (freshnessById.get(record.id)?.state === 'stale' ? ' [stale]' : '');
742
701
  const rawBodyLines = v2Active
743
702
  ? selectedItems.map((record) => `- [${record.type}] ${buildRecordSnippet(record)}${staleTag(record)}`)
744
- : selectedItems.map((item) => `- [${item.type}] ${buildDetailedInjectionSnippet(item)}`);
703
+ : selectedItems.map((item) => (item.type === 'markdown'
704
+ ? `- [markdown] ${renderMarkdownDoc(item)}`
705
+ : `- [${item.type}] ${buildDetailedInjectionSnippet(item)}`));
745
706
  const bodyLines = v2Active
746
707
  ? selectedItems.map((record) => `- ${buildRecordSnippet(record)}${staleTag(record)}`)
747
- : selectedItems.map((item) => `- ${buildInjectionSnippet(item)}`);
708
+ : selectedItems.map((item) => (item.type === 'markdown'
709
+ ? `- ${renderMarkdownDoc(item)}`
710
+ : `- ${buildInjectionSnippet(item)}`));
748
711
  const rawLines = ['## Previous Context', ...rawBodyLines];
749
712
  const rawText = rawLines.join('\n');
750
713
  const conciseText = ['## Previous Context', ...bodyLines].join('\n');
@@ -61,6 +61,7 @@
61
61
  */
62
62
 
63
63
  import crypto from 'node:crypto';
64
+ import fs from 'node:fs';
64
65
  import path from 'node:path';
65
66
  import { createRecorder } from './recorder.js';
66
67
  import { registerCrashCapture } from './crash.js';
@@ -406,6 +407,35 @@ export function recorderHealth({ projectRoot } = {}) {
406
407
  };
407
408
  }
408
409
 
410
+ /**
411
+ * flushAllRecorders({ deadlineMs }) — bounded drain of every memoized
412
+ * recorder. For short-lived CLI processes that never call startLifecycle:
413
+ * emit() only queues, so the entry point must flush before exit. Never
414
+ * throws; a failed/late flush keeps the recorder's own error policy
415
+ * (counters + last_error), and the deadline bounds the exit delay.
416
+ */
417
+ export async function flushAllRecorders({ deadlineMs = DEFAULT_EXIT_DEADLINE_MS } = {}) {
418
+ const runs = [];
419
+ for (const [key, rec] of recorders) {
420
+ try {
421
+ if (rec.health().queue_depth > 0) {
422
+ // appendRecord's root check realpaths the segment root's PARENT, which
423
+ // a fresh project lacks (io_enoent would drop the whole queue).
424
+ runs.push(
425
+ fs.promises
426
+ .mkdir(observabilityRoot(key), { recursive: true })
427
+ .catch(() => {})
428
+ .then(() => rec.flush({ deadlineMs }))
429
+ .catch(() => {}),
430
+ );
431
+ }
432
+ } catch {
433
+ // never-throw
434
+ }
435
+ }
436
+ if (runs.length > 0) await Promise.all(runs);
437
+ }
438
+
409
439
  /** Test/reset seam: detach every handle and drop all memoized recorders. */
410
440
  export function resetForTests() {
411
441
  detachLifecycle();
@@ -531,6 +531,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
531
531
  maxArchivedSessions: 50,
532
532
  maxPatternCandidates: 50,
533
533
  redactSecrets: true,
534
+ sources: ['docs/MEMORY.md'],
534
535
  },
535
536
  validation: {
536
537
  enabled: true,
@@ -1188,6 +1189,11 @@ export function validateRuntimeConfig(config) {
1188
1189
  pushPositiveNumberError(errors, config.memory.maxArchivedSessions, 'memory.maxArchivedSessions');
1189
1190
  pushPositiveNumberError(errors, config.memory.maxPatternCandidates, 'memory.maxPatternCandidates');
1190
1191
  pushBooleanError(errors, config.memory.redactSecrets, 'memory.redactSecrets');
1192
+ if (config.memory.sources !== undefined
1193
+ && (!Array.isArray(config.memory.sources)
1194
+ || config.memory.sources.some((entry) => typeof entry !== 'string'))) {
1195
+ errors.push('memory.sources must be an array of relative .md paths.');
1196
+ }
1191
1197
  }
1192
1198
 
1193
1199
  if (!isPlainObject(config.validation)) {
@@ -1116,6 +1116,7 @@ function applyTaskSemantics(contract, semantic) {
1116
1116
 
1117
1117
  return {
1118
1118
  configPath: path.join(storageRoot, 'config.json'),
1119
+ memoryRoot,
1119
1120
  userMemoryPath: path.join(memoryRoot, 'user.json'),
1120
1121
  projectsDir: path.join(memoryRoot, 'projects'),
1121
1122
  sessionsDir: path.join(memoryRoot, 'sessions'),
@@ -2187,12 +2188,6 @@ function applyTaskSemantics(contract, semantic) {
2187
2188
  .trim();
2188
2189
  }
2189
2190
 
2190
- function tokenizeMemoryText(text) {
2191
- return normalizeMemoryText(text)
2192
- .split(/\s+/)
2193
- .filter((token) => token && !STOPWORDS.has(token) && token.length > 1);
2194
- }
2195
-
2196
2191
  function getMemoryTimestamp(item) {
2197
2192
  return item.content?.updatedAt
2198
2193
  ?? item.content?.endedAt
@@ -2229,33 +2224,6 @@ function applyTaskSemantics(contract, semantic) {
2229
2224
  ];
2230
2225
  }
2231
2226
 
2232
- function scoreMemoryItem(item, queryTokens) {
2233
- if (queryTokens.length === 0) {
2234
- return 0;
2235
- }
2236
-
2237
- let score = 0;
2238
- for (const segment of buildMemorySegments(item)) {
2239
- const segmentTokens = new Set(tokenizeMemoryText(segment.text));
2240
- for (const token of queryTokens) {
2241
- if (segmentTokens.has(token)) {
2242
- score += segment.weight;
2243
- }
2244
- }
2245
- }
2246
-
2247
- if (score === 0) {
2248
- return 0;
2249
- }
2250
-
2251
- // TASK-027 CTX-01/CTX-04: the ranking must be a pure function of the logical memory
2252
- // content. A recency bonus scaled by Date.now() made the score — and therefore the
2253
- // injected previous-context block, its persisted order, and the PreCompact reinjection —
2254
- // shift on every wall-clock tick. Eligibility is unchanged (still score > 0); only the
2255
- // volatile ordering signal is dropped.
2256
- return score;
2257
- }
2258
-
2259
2227
  function buildPreviousContextSnippet(item) {
2260
2228
  const content = item.content ?? {};
2261
2229
  if (item.type === 'project') {
@@ -2293,37 +2261,100 @@ function applyTaskSemantics(contract, semantic) {
2293
2261
  return null;
2294
2262
  }
2295
2263
 
2264
+ // 3.5.1: one recall engine. This lane no longer ranks privately; it feeds
2265
+ // the v1 items, the v2 records (eligibility-gated) and the markdown source
2266
+ // bullets to the shared BM25 mirror (runtime/memory-recall.mjs) and cuts
2267
+ // only after scoring. Any import/IO failure degrades to "no context".
2268
+ let engine;
2269
+ let policyMirror;
2270
+ let flags;
2271
+ const runtimeDir = path.join(projectRoot, '.claude', 'ukit', 'runtime');
2272
+ try {
2273
+ engine = await import(pathToFileURL(path.join(runtimeDir, 'memory-recall.mjs')).href);
2274
+ policyMirror = await import(pathToFileURL(path.join(runtimeDir, 'memory-policy.mjs')).href);
2275
+ flags = await import(pathToFileURL(path.join(runtimeDir, 'memory-flags.mjs')).href);
2276
+ } catch {
2277
+ return null;
2278
+ }
2279
+
2296
2280
  const projectId = await detectProjectId(projectRoot);
2297
2281
  const items = await listMemoryItems(projectRoot);
2298
- const queryTokens = tokenizeMemoryText(taskQuery);
2299
- const rankedItems = items
2282
+ const identity = await policyMirror.resolveProjectIdentityMirror(projectRoot).catch(() => null);
2283
+ const memoryConfig = {
2284
+ ...config,
2285
+ memoryV2: {
2286
+ eligibility: { stage: 'default' },
2287
+ writer: { stage: 'default' },
2288
+ index: { stage: 'default' },
2289
+ decision: { stage: 'off' },
2290
+ canaryProjects: [],
2291
+ killSwitch: false,
2292
+ ...(config?.memoryV2 && typeof config.memoryV2 === 'object' ? config.memoryV2 : {}),
2293
+ },
2294
+ };
2295
+ const eligibleItems = items
2300
2296
  .filter((item) => item.type !== 'user')
2301
2297
  .filter((item) => (
2302
2298
  item.type === 'project'
2303
2299
  ? (item.content?.id === projectId)
2304
2300
  : (item.type === 'session' ? item.content?.projectId === projectId : true)
2305
- ))
2306
- .map((item) => ({
2307
- item,
2308
- score: scoreMemoryItem(item, queryTokens),
2309
- }))
2310
- .filter((entry) => entry.score > 0)
2311
- // CTX-01: ties break on the stable logical id (never on a volatile timestamp), so the
2312
- // same memory set always yields the same injected order regardless of when the
2313
- // entries were last written/ended.
2314
- .sort((left, right) => (
2315
- right.score - left.score
2316
- || left.item.id.localeCompare(right.item.id)
2317
- ))
2318
- .slice(0, 2)
2319
- .map((entry) => entry.item);
2301
+ ));
2302
+ const docs = eligibleItems.map((item) => ({
2303
+ id: item.id,
2304
+ type: item.type,
2305
+ text: buildMemorySegments(item).map((segment) => String(segment.text ?? '')).join(' '),
2306
+ created_at: getMemoryTimestamp(item),
2307
+ }));
2308
+ const recordById = new Map();
2309
+ if (flags.resolveMemoryStage(memoryConfig, 'eligibility', { projectId: identity?.projectId ?? null }) !== 'off') {
2310
+ const doc = await readJson(path.join(buildRuntimePaths(projectRoot).memoryRoot, 'v2', 'records.json'), null);
2311
+ const now = Date.now();
2312
+ const eligibleCtx = {
2313
+ projectId: identity?.projectId ?? null,
2314
+ projectAliases: Array.isArray(identity?.aliases) ? identity.aliases : [],
2315
+ includeUser: false,
2316
+ now,
2317
+ };
2318
+ for (const record of Array.isArray(doc?.records) ? doc.records : []) {
2319
+ if (!record || typeof record !== 'object' || record.status !== 'active') continue;
2320
+ if (record.valid_until != null && record.valid_until <= now) continue;
2321
+ if (!policyMirror.eligible(record, eligibleCtx).ok) continue;
2322
+ recordById.set(`record:${record.id}`, record);
2323
+ docs.push({
2324
+ id: `record:${record.id}`,
2325
+ type: record.type,
2326
+ provenance: record.provenance,
2327
+ text: String(record.text ?? ''),
2328
+ created_at: record.created_at ?? 0,
2329
+ });
2330
+ }
2331
+ }
2332
+ const recalled = await engine.recallForHook({
2333
+ projectRoot, query: taskQuery, docs, config: memoryConfig, limit: 2,
2334
+ });
2335
+ const itemById = new Map(eligibleItems.map((item) => [item.id, item]));
2336
+ const rankedItems = recalled.ranked.map((entry) => {
2337
+ if (entry.doc.type === 'markdown') return { id: entry.doc.id, type: 'markdown', doc: entry.doc };
2338
+ const record = recordById.get(entry.doc.id);
2339
+ if (record) return { id: entry.doc.id, type: 'record', record };
2340
+ return itemById.get(entry.doc.id);
2341
+ }).filter(Boolean);
2320
2342
 
2321
2343
  if (rankedItems.length === 0) {
2322
2344
  return null;
2323
2345
  }
2324
2346
 
2347
+ const renderItem = (item) => {
2348
+ if (item.type === 'markdown') return engine.renderMarkdownDoc(item.doc, 120);
2349
+ if (item.type === 'record') {
2350
+ const text = String(item.record.text ?? '').trim();
2351
+ return `[${item.record.type ?? 'record'}] ${text.length > 120 ? `${text.slice(0, 117)}...` : text}`;
2352
+ }
2353
+ return buildPreviousContextSnippet(item);
2354
+ };
2355
+
2325
2356
  return {
2326
- line: rankedItems.map((item) => buildPreviousContextSnippet(item)).join(' | '),
2357
+ line: rankedItems.map(renderItem).join(' | '),
2327
2358
  selectedIds: rankedItems.map((item) => item.id),
2328
2359
  fingerprint: buildCompactMachineKey('route-memory-v1', {
2329
2360
  taskQuery: normalizeMemoryText(taskQuery),
@@ -38,6 +38,7 @@ import {
38
38
  } from '../runtime/memory-policy.mjs';
39
39
  import { resolveRecordFreshness } from '../runtime/memory-freshness.mjs';
40
40
  import { resolveMemoryStage } from '../runtime/memory-flags.mjs';
41
+ import { recallForHook, renderMarkdownDoc } from '../runtime/memory-recall.mjs';
41
42
  import {
42
43
  ROUTE_VERSION,
43
44
  ROUTE_CONTRACT_VERSION,
@@ -6967,12 +6968,6 @@ function normalize(text) {
6967
6968
  .trim();
6968
6969
  }
6969
6970
 
6970
- function tokenize(text) {
6971
- return normalize(text)
6972
- .split(/\s+/)
6973
- .filter((token) => token && !STOPWORDS.has(token) && token.length > 1);
6974
- }
6975
-
6976
6971
  function getMemoryTimestamp(item) {
6977
6972
  return item.content?.updatedAt
6978
6973
  ?? item.content?.endedAt
@@ -7016,29 +7011,6 @@ function buildMemorySegments(item) {
7016
7011
  ];
7017
7012
  }
7018
7013
 
7019
- function scoreMemoryItem(item, queryTokens) {
7020
- if (queryTokens.length === 0) {
7021
- return 0;
7022
- }
7023
-
7024
- let score = 0;
7025
- for (const segment of buildMemorySegments(item)) {
7026
- const segmentTokens = new Set(tokenize(segment.text));
7027
- for (const token of queryTokens) {
7028
- if (segmentTokens.has(token)) {
7029
- score += segment.weight;
7030
- }
7031
- }
7032
- }
7033
-
7034
- if (score === 0) {
7035
- return 0;
7036
- }
7037
-
7038
- const recencyBonus = getMemoryTimestamp(item) > 0 ? Math.min(1, getMemoryTimestamp(item) / Date.now()) : 0;
7039
- return score + recencyBonus;
7040
- }
7041
-
7042
7014
  async function readDirectoryJsonItems(dirPath) {
7043
7015
  let entries = [];
7044
7016
  try {
@@ -7140,8 +7112,6 @@ async function listMemoryItems(rootDir, { config, projectId } = {}) {
7140
7112
  ];
7141
7113
  }
7142
7114
 
7143
- const MEMORY_V2_RECORD_POOL_LIMIT = 20;
7144
-
7145
7115
  // v2 lane (SI-101): approved records live in a single records.json document.
7146
7116
  // Missing/malformed store → [] (same never-throw discipline as
7147
7117
  // readDirectoryJsonItems). Candidates: status 'active' AND (valid_until == null
@@ -7166,8 +7136,6 @@ export async function listMemoryV2RecordItems(runtimeRootOrProjectRoot, { config
7166
7136
  .filter((record) => record && typeof record === 'object')
7167
7137
  .filter((record) => record.status === 'active')
7168
7138
  .filter((record) => record.valid_until == null || record.valid_until > now)
7169
- .sort((left, right) => (right.created_at ?? 0) - (left.created_at ?? 0))
7170
- .slice(0, MEMORY_V2_RECORD_POOL_LIMIT)
7171
7139
  .map((record) => ({
7172
7140
  id: `record:${record.id}`,
7173
7141
  type: 'record',
@@ -7263,7 +7231,6 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
7263
7231
  },
7264
7232
  };
7265
7233
  const items = await listMemoryItems(rootDir, { config: memoryConfig, projectId: binding.projectId });
7266
- const queryTokens = tokenize(taskQuery);
7267
7234
  // v2/legacy dedup: collect the legacy-lane ids first, then drop any record
7268
7235
  // whose logical twin (meta.legacyId → session:<id>, project_id →
7269
7236
  // project:<id>) is present — the legacy item carries the richer summary.
@@ -7271,7 +7238,7 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
7271
7238
  items.filter((item) => item.type !== 'record').map((item) => item.id),
7272
7239
  );
7273
7240
  const eligibleCtx = { projectId: binding.projectId, projectAliases: binding.aliases, includeUser: false };
7274
- const rankedItems = items
7241
+ const eligibleItems = items
7275
7242
  .filter((item) => item.type !== 'user')
7276
7243
  .filter((item) => {
7277
7244
  if (item.type === 'record') {
@@ -7285,18 +7252,30 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
7285
7252
  return matchesProjectBinding(item, binding);
7286
7253
  }
7287
7254
  return true;
7288
- })
7289
- .map((item) => ({
7290
- item,
7291
- score: scoreMemoryItem(item, queryTokens),
7292
- }))
7293
- .filter((entry) => entry.score > 0)
7294
- .sort((left, right) => (
7295
- right.score - left.score
7296
- || getMemoryTimestamp(right.item) - getMemoryTimestamp(left.item)
7297
- ))
7298
- .slice(0, 2)
7299
- .map((entry) => entry.item);
7255
+ });
7256
+ // Score-before-cut (3.5.1): every eligible item plus the markdown source
7257
+ // bullets goes through the shared BM25 engine; only then is the top 2 cut.
7258
+ const itemById = new Map();
7259
+ const docs = eligibleItems.map((item) => {
7260
+ itemById.set(item.id, item);
7261
+ return {
7262
+ id: item.id,
7263
+ type: item.type === 'record' ? item.record.type : item.type,
7264
+ provenance: item.type === 'record' ? item.record.provenance : undefined,
7265
+ // Records go in as their raw text, exactly as the CLI lane passes them: a
7266
+ // type prefix would defeat the engine's start-anchored episode shape checks.
7267
+ text: item.type === 'record'
7268
+ ? String(item.record.text ?? '')
7269
+ : buildMemorySegments(item).map((segment) => String(segment.text ?? '')).join(' '),
7270
+ created_at: getMemoryTimestamp(item),
7271
+ };
7272
+ });
7273
+ const recalled = await recallForHook({
7274
+ projectRoot: rootDir, query: taskQuery, docs, config: memoryConfig, limit: 2,
7275
+ });
7276
+ const rankedItems = recalled.ranked.map((entry) => (entry.doc.type === 'markdown'
7277
+ ? { id: entry.doc.id, type: 'markdown', doc: entry.doc }
7278
+ : itemById.get(entry.doc.id))).filter(Boolean);
7300
7279
 
7301
7280
  if (rankedItems.length === 0) {
7302
7281
  return null;
@@ -7313,7 +7292,9 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
7313
7292
  }));
7314
7293
 
7315
7294
  return {
7316
- line: rankedItems.map((item) => buildPreviousContextSnippet(item, freshnessById.get(item.id))).join(' | '),
7295
+ line: rankedItems.map((item) => (item.type === 'markdown'
7296
+ ? renderMarkdownDoc(item.doc, 120)
7297
+ : buildPreviousContextSnippet(item, freshnessById.get(item.id)))).join(' | '),
7317
7298
  selectedIds: rankedItems.map((item) => item.id),
7318
7299
  fingerprint: buildCompactMachineKey('route-memory-v2', {
7319
7300
  taskQuery: normalize(taskQuery),