@ngockhoale/ukit 3.4.85 → 3.5.2

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.
Files changed (34) hide show
  1. package/CHANGELOG.md +33 -1064
  2. package/bin/ukit +9 -0
  3. package/manifests/documentation.yaml +12 -0
  4. package/manifests/platform.full.yaml +23 -0
  5. package/package.json +1 -1
  6. package/src/cli/commands/install.js +12 -0
  7. package/src/cli/commands/memory.js +30 -3
  8. package/src/core/memory/episodeArchive.js +147 -0
  9. package/src/core/memory/episodes.js +199 -37
  10. package/src/core/memory/memoryHit.js +59 -40
  11. package/src/core/memory/mutateMemory.js +23 -3
  12. package/src/core/memory/recallEngine.js +423 -0
  13. package/src/core/memory/retrieval.js +55 -92
  14. package/src/core/observability/emit/lifecycle.js +30 -0
  15. package/src/core/runtimeConfig.js +7 -0
  16. package/src/index/buildIndex.js +22 -0
  17. package/src/index/impactContext.js +11 -1
  18. package/template_project/.claude/hooks/edit-hint.mjs +119 -0
  19. package/template_project/.claude/hooks/skill-router.sh +82 -51
  20. package/template_project/.claude/settings.json +2 -2
  21. package/template_project/.claude/ukit/index/edit-graph.mjs +274 -0
  22. package/template_project/.claude/ukit/index/lib/index-core.mjs +36 -1
  23. package/template_project/.claude/ukit/index/post-edit-verify.mjs +8 -5
  24. package/template_project/.claude/ukit/index/resolve-context.mjs +17 -0
  25. package/template_project/.claude/ukit/index/route-task.mjs +29 -48
  26. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +45 -0
  27. package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +62 -5
  28. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +237 -0
  29. package/template_project/.claude/ukit/runtime/memory-recall.mjs +423 -0
  30. package/template_project/.claude/ukit/runtime/reinject-context.mjs +29 -45
  31. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  32. package/template_project/AGENTS.md +1 -1
  33. package/template_project/CLAUDE.md +1 -1
  34. package/template_project/instructions/core.md +1 -1
@@ -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,8 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
531
531
  maxArchivedSessions: 50,
532
532
  maxPatternCandidates: 50,
533
533
  redactSecrets: true,
534
+ sources: ['docs/MEMORY.md'],
535
+ editHints: { enabled: true, mirrors: [], ignoreMirrors: [] },
534
536
  },
535
537
  validation: {
536
538
  enabled: true,
@@ -1188,6 +1190,11 @@ export function validateRuntimeConfig(config) {
1188
1190
  pushPositiveNumberError(errors, config.memory.maxArchivedSessions, 'memory.maxArchivedSessions');
1189
1191
  pushPositiveNumberError(errors, config.memory.maxPatternCandidates, 'memory.maxPatternCandidates');
1190
1192
  pushBooleanError(errors, config.memory.redactSecrets, 'memory.redactSecrets');
1193
+ if (config.memory.sources !== undefined
1194
+ && (!Array.isArray(config.memory.sources)
1195
+ || config.memory.sources.some((entry) => typeof entry !== 'string'))) {
1196
+ errors.push('memory.sources must be an array of relative .md paths.');
1197
+ }
1191
1198
  }
1192
1199
 
1193
1200
  if (!isPlainObject(config.validation)) {
@@ -11,6 +11,8 @@ import { withAsyncLock } from '../../template_project/.claude/ukit/runtime/async
11
11
 
12
12
  import { getArtifactPath, getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, isLikelyTestFilePath, normalizeRelative } from './paths.js';
13
13
  import { importsNeedAliasContext, loadImportAliasContextState, resolveImportSpecifier } from './importResolution.js';
14
+ import { ensureEditGraph } from '../../template_project/.claude/ukit/index/edit-graph.mjs';
15
+ import { MIRROR_PAIRS } from './impactCatalog.js';
14
16
  import { clearIndexArtifactCache } from './queryIndex.js';
15
17
  import { clearRelatedTestArtifactCache } from './relatedTests.js';
16
18
 
@@ -582,6 +584,7 @@ async function buildCodeIndexInner({ rootDir = process.cwd(), changedFiles = nul
582
584
  [INDEX_ARTIFACTS.relations]: relations.length,
583
585
  },
584
586
  });
587
+ await refreshEditGraph(absoluteRoot, sourceFingerprint.digest, fileRecords, codeFiles, imports, importAliasContext, signal);
585
588
  const preservedRuntimeCaches = canReuseFilesArtifact
586
589
  && canReuseAllParsedArtifacts
587
590
  && canReuseTestsMap
@@ -1241,6 +1244,7 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
1241
1244
  clearIndexArtifactCache(absoluteRoot);
1242
1245
  clearRelatedTestArtifactCache(absoluteRoot);
1243
1246
  }
1247
+ await refreshEditGraph(absoluteRoot, refreshedFingerprint.digest, mergedFileRecords, codeFiles, imports, importAliasContext, signal);
1244
1248
 
1245
1249
  return {
1246
1250
  indexDir,
@@ -2573,6 +2577,24 @@ function areSourceFingerprintsEqual(previousFingerprint, nextFingerprint) {
2573
2577
  && previousFingerprint?.digest === nextFingerprint?.digest;
2574
2578
  }
2575
2579
 
2580
+ // Edit graph (mirror/test/import edges): rebuilt only when missing or its digest
2581
+ // differs from the index fingerprint. Never fails the index build.
2582
+ async function refreshEditGraph(rootDir, indexDigest, fileRecords, codeFiles, imports, aliasContext, signal) {
2583
+ await ensureEditGraph({
2584
+ rootDir,
2585
+ indexDigest,
2586
+ signal,
2587
+ inputs: () => {
2588
+ const resolved = buildResolvedImportMap(rootDir, imports, new Set(codeFiles.map((f) => f.filePath)), aliasContext);
2589
+ return {
2590
+ files: fileRecords,
2591
+ imports: resolved,
2592
+ declaredMirrors: MIRROR_PAIRS,
2593
+ };
2594
+ },
2595
+ });
2596
+ }
2597
+
2576
2598
  async function writeArtifact(rootDir, artifactName, payload) {
2577
2599
  const artifactPath = getArtifactPath(rootDir, artifactName);
2578
2600
  const temporaryPath = `${artifactPath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
 
4
4
  import { getArtifactPath, INDEX_ARTIFACTS, isLikelyTestFilePath } from './paths.js';
5
+ import { loadEditGraph, neighboursOf } from '../../template_project/.claude/ukit/index/edit-graph.mjs';
5
6
  import { classifyImpactRisk, findMirrorCounterparts } from './impactCatalog.js';
6
7
  import { inferRelatedTestsFromArtifacts, loadRelatedTestArtifacts } from './relatedTests.js';
7
8
  import { importsNeedAliasContext, loadImportAliasContext, resolveImportSpecifier } from './importResolution.js';
@@ -108,7 +109,16 @@ export async function resolveImpactContext({
108
109
  const callItems = safeItems(callsArtifact);
109
110
  const importItems = safeItems(importsArtifact);
110
111
  const risk = classifyImpactRisk(normalizedChangedFiles);
111
- const mirrorCounterparts = findMirrorCounterparts(normalizedChangedFiles).slice(0, budget.maxMirrors);
112
+ const editGraph = await loadEditGraph(absoluteRoot);
113
+ const mirrorCounterparts = [...findMirrorCounterparts(normalizedChangedFiles)];
114
+ for (const changed of normalizedChangedFiles) {
115
+ for (const mirror of neighboursOf(editGraph, changed).mirrors) {
116
+ if (!mirrorCounterparts.some((m) => m.filePath === mirror.path && m.source === changed)) {
117
+ mirrorCounterparts.push({ filePath: mirror.path, reason: `edit-graph ${mirror.kind} mirror`, source: changed });
118
+ }
119
+ }
120
+ }
121
+ mirrorCounterparts.splice(budget.maxMirrors);
112
122
 
113
123
  const changedFileSet = new Set(normalizedChangedFiles);
114
124
  const changedSymbolSet = new Set(normalizedChangedSymbols);
@@ -0,0 +1,119 @@
1
+ // edit-hint.mjs — PostToolUse Edit|Write chain step (advisory, always code 0).
2
+ // After a successful edit of file X, hands the MODEL the edit-graph hint once per
3
+ // file per task (mirror to fix, tests to run, cited memory). Claude Code: JSON
4
+ // hookSpecificOutput.additionalContext; omp: the bridge appends stdout verbatim,
5
+ // so plain text. Async fs only; self-deadline 400 ms; any failure emits nothing.
6
+ import fsp from 'node:fs/promises';
7
+ import path from 'node:path';
8
+
9
+ const DEADLINE_MS = 400; // once per file per task; the step slot is 8 s
10
+ const MEMORY_MS = 250; // memory sub-budget: a miss still emits mirrors/tests
11
+ const MAX_SEEN = 200;
12
+ const MAX_BYTES = 16 * 1024;
13
+ const NONE = { code: 0, stdout: '', stderr: '' };
14
+ const safe = (v, d) => String(v || d).replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || d;
15
+ const readJson = async (file) => {
16
+ try { return JSON.parse(await fsp.readFile(file, 'utf8')); } catch { return null; }
17
+ };
18
+
19
+ // Retention: over 64 entries, drop this step's own `<safe>.<safe>.json` files older than 7 days (max 32 deletions, 128 stats per run). Fire-and-forget.
20
+ async function prune(dir, keep) {
21
+ try {
22
+ const names = await fsp.readdir(dir);
23
+ if (names.length <= 64) return;
24
+ let left = 32;
25
+ let stats = 128;
26
+ for (const n of names) {
27
+ if (left <= 0 || stats <= 0) break;
28
+ if (n === keep || !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.json$/.test(n)) continue;
29
+ stats -= 1;
30
+ try {
31
+ const f = path.join(dir, n);
32
+ if (Date.now() - (await fsp.stat(f)).mtimeMs <= 7 * 864e5) continue;
33
+ await fsp.unlink(f);
34
+ left -= 1;
35
+ } catch { /* ignore */ }
36
+ }
37
+ } catch { /* retention is best-effort */ }
38
+ }
39
+
40
+ async function hint(ctx, signal, commit) {
41
+ const { payload: p = {}, projectRoot, env = {} } = ctx;
42
+ if (env.UKIT_EDIT_HINTS === '0' || process.env.UKIT_EDIT_HINTS === '0') return NONE;
43
+ if (!['Edit', 'Write'].includes(p.tool_name) || !projectRoot) return NONE;
44
+ const res = p.tool_response;
45
+ if (res && (res.is_error === true || res.isError === true || res.success === false)) return NONE;
46
+ const raw = p.tool_input?.file_path;
47
+ if (typeof raw !== 'string' || !raw) return NONE;
48
+ const rel = path.relative(projectRoot, path.resolve(p.cwd || projectRoot, raw)).split(path.sep).join('/');
49
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return NONE;
50
+
51
+ const config = await readJson(path.join(projectRoot, '.ukit/storage/config.json'));
52
+ if (config?.memory?.editHints?.enabled === false) return NONE;
53
+ const route = await readJson(path.join(projectRoot, '.claude/ukit/skill-router-state.json'));
54
+ const session = safe(p.session_id, 'nosession');
55
+ const task = typeof route?.taskInstanceId === 'string' && route.taskInstanceId ? route.taskInstanceId : session;
56
+ const stateFile = path.join(projectRoot, '.ukit/storage/cache/edit-hints', `${session}.${safe(p.agent_id, 'main')}.json`);
57
+ const prev = await readJson(stateFile);
58
+ const st = prev && prev.task === task && Array.isArray(prev.seen)
59
+ ? { task, seen: prev.seen.filter((x) => typeof x === 'string'), shownMem: Array.isArray(prev.shownMem) ? prev.shownMem.filter((x) => typeof x === 'string') : [] }
60
+ : { task, seen: [], shownMem: [] };
61
+ if (st.seen.includes(rel)) return NONE;
62
+
63
+ const lanes = await import('../ukit/runtime/memory-lanes.mjs');
64
+ const out = await lanes.editHintFor({
65
+ projectRoot, target: rel, config: config ?? {}, signal, memoryBudgetMs: MEMORY_MS,
66
+ exclude: { paths: st.seen, memoryIds: st.shownMem },
67
+ });
68
+ if (signal.aborted) return NONE;
69
+ // Memory missed its budget and there is no graph text: not "nothing to say", retry next edit.
70
+ if (out?.memoryMissed && !out.text) return NONE;
71
+
72
+ // Commit point: once state is being marked, finish and emit (a few ms of fs) so a
73
+ // deadline firing mid-write can never mark the file seen without delivering the hint.
74
+ commit.on = true;
75
+ st.seen.push(rel);
76
+ st.shownMem.push(...(out?.memoryIds || []));
77
+ st.seen = st.seen.slice(-MAX_SEEN);
78
+ st.shownMem = st.shownMem.slice(-MAX_SEEN);
79
+ let body = JSON.stringify(st);
80
+ while (body.length > MAX_BYTES && st.seen.length > 1) {
81
+ st.seen.shift();
82
+ st.shownMem.shift();
83
+ body = JSON.stringify(st);
84
+ }
85
+ try {
86
+ await fsp.mkdir(path.dirname(stateFile), { recursive: true });
87
+ const tmp = `${stateFile}.${process.pid}.tmp`;
88
+ await fsp.writeFile(tmp, body);
89
+ await fsp.rename(tmp, stateFile);
90
+ } catch { /* state is best-effort */ }
91
+ void prune(path.dirname(stateFile), path.basename(stateFile));
92
+
93
+ const text = typeof out?.text === 'string' ? out.text.trim() : '';
94
+ if (!text) return NONE;
95
+ const omp = p.ukit_harness === 'omp' || env.UKIT_HARNESS === 'omp';
96
+ const stdout = omp
97
+ ? `${text}\n`
98
+ : `${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } })}\n`;
99
+ return { code: 0, stdout, stderr: '' };
100
+ }
101
+
102
+ export async function runHook(ctx = {}) {
103
+ const ac = new AbortController();
104
+ const commit = { on: false };
105
+ const ms = Math.min(DEADLINE_MS, Number.isFinite(ctx.deadlineMs) ? ctx.deadlineMs : DEADLINE_MS);
106
+ const timer = setTimeout(() => ac.abort(), Math.max(1, ms));
107
+ const outer = ctx.signal;
108
+ if (outer) outer.aborted ? ac.abort() : outer.addEventListener('abort', () => ac.abort(), { once: true });
109
+ try {
110
+ return await Promise.race([
111
+ hint(ctx, ac.signal, commit),
112
+ new Promise((resolve) => ac.signal.addEventListener('abort', () => { if (!commit.on) resolve(NONE); }, { once: true })),
113
+ ]);
114
+ } catch {
115
+ return NONE;
116
+ } finally {
117
+ clearTimeout(timer);
118
+ }
119
+ }
@@ -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),