@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.
- package/CHANGELOG.md +15 -857
- package/bin/ukit +9 -0
- package/manifests/documentation.yaml +12 -0
- package/package.json +1 -1
- package/src/cli/commands/install.js +12 -0
- package/src/cli/commands/memory.js +30 -3
- package/src/core/memory/episodeArchive.js +147 -0
- package/src/core/memory/episodes.js +199 -37
- package/src/core/memory/memoryHit.js +59 -40
- package/src/core/memory/mutateMemory.js +23 -3
- package/src/core/memory/recallEngine.js +423 -0
- package/src/core/memory/retrieval.js +55 -92
- package/src/core/observability/emit/lifecycle.js +30 -0
- package/src/core/runtimeConfig.js +6 -0
- package/template_project/.claude/hooks/skill-router.sh +82 -51
- package/template_project/.claude/ukit/index/route-task.mjs +29 -48
- package/template_project/.claude/ukit/runtime/execution-ledger.mjs +45 -0
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +423 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +29 -45
|
@@ -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 {
|
|
14
|
-
import { buildMemoryHit,
|
|
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
|
-
//
|
|
291
|
-
|
|
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
|
-
|
|
365
|
-
//
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
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
|
|
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) =>
|
|
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
|
-
:
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
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) =>
|
|
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) =>
|
|
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
|
|
2299
|
-
const
|
|
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
|
-
|
|
2307
|
-
|
|
2308
|
-
|
|
2309
|
-
|
|
2310
|
-
|
|
2311
|
-
|
|
2312
|
-
|
|
2313
|
-
|
|
2314
|
-
.
|
|
2315
|
-
|
|
2316
|
-
|
|
2317
|
-
|
|
2318
|
-
|
|
2319
|
-
|
|
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(
|
|
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
|
|
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
|
-
|
|
7290
|
-
|
|
7291
|
-
|
|
7292
|
-
|
|
7293
|
-
.
|
|
7294
|
-
|
|
7295
|
-
|
|
7296
|
-
|
|
7297
|
-
|
|
7298
|
-
|
|
7299
|
-
|
|
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) =>
|
|
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),
|