@lorekit/cli 1.42.0 → 1.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.42.0",
+  "version": "1.43.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/core/lessons.mjs

@@ -12,7 +12,7 @@ import { deriveScope } from '../scope.mjs';
 // the injected set is chosen by ONE scorer, and a future `memory.relevant` verb
 // must be able to reuse it rather than grow a second ranking with its own idea
 // of what "most useful" means.
-import { resolvePrecedence, rankLessons } from '../lessons-pure.mjs';
+import { resolvePrecedence, rankLessons, diversifyRankedLessons } from '../lessons-pure.mjs';
 // The store's own scope inventory, normalised — the SAME helper `memory.scopes`
 // uses, so the map and the MCP tool cannot disagree about what a scope holds or
 // about what a failed enumeration looks like.
@@ -167,7 +167,16 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // first-appearance default — they agree today, but the hierarchy is
   // `readOrder`'s to state, not an artefact of how this function happens to
   // build its array.
-  const ranked = rankLessons(winners, { terms: [], now, scopeOrder: scope.readOrder });
+  // ONE options object feeds both the ranking and the diversification below, so
+  // the two can never drift: `diversifyRankedLessons` recomputes each entry's
+  // score to seed the MMR objective, and if its `terms`/`now`/`weights` differed
+  // from what `rankLessons` sorted on, those scores would not line up with the
+  // order — the near-identical `now` clock especially. Sharing the object makes
+  // that agreement structural rather than a thing two call sites have to keep in
+  // step by hand. `k` is diversification-only; `scopeOrder` is ranking-only and
+  // simply ignored by the diversifier's destructuring.
+  const rankOpts = { terms: [], now, scopeOrder: scope.readOrder };
+  const ranked = rankLessons(winners, rankOpts);
 
   // ── the scope map: EXACT counts when the store can enumerate ───────────────
   //
@@ -219,12 +228,29 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
     ? scopeInventoryFromStore(inventory.scopes, scope.readOrder, derivedCounts)
     : derivedCounts;
 
+  // DIVERSIFY before the ceiling, so the budget is not spent on near-identical
+  // lessons. Ranking answers "which lessons score highest"; on an active repo
+  // the highest cluster is often one task's iteration log — a dozen
+  // `review-outcomes::pr395-it{3,4,5}` rows that score alike AND read alike, so
+  // a plain top-N hands the reader the same lesson several times and evicts the
+  // variety underneath. `diversifyRankedLessons` applies the SAME MMR
+  // (`selectDiverse`, λ=0.7 lexical Jaccard) the hosted `order=rank` path
+  // already uses, which was defined and exported here but never wired into the
+  // session-start read. It seeds with the top-ranked lesson (score is still
+  // 0.7 of the objective) and only spends the remaining 0.3 pushing down a
+  // lesson that repeats one already shown — so the best lesson stays first and
+  // the set stops being a wall of duplicates. `terms: []` matches the
+  // `rankLessons` call above (relevance contributes nothing at session start),
+  // which the scores MUST agree with. The scope map and `applicable` still read
+  // from `ranked` — the map is a pointer to what EXISTS per scope, a question
+  // diversification does not change.
+  //
   // `applicable` is the honest denominator for the header — how many the reader
   // has, as opposed to how many fitted. It is counted BEFORE the ceiling, so
   // "8 of 50" stays true no matter how the render is bounded.
   return {
     scope,
-    lessons: ranked.slice(0, HARD_LESSON_CEILING),
+    lessons: diversifyRankedLessons(ranked, { ...rankOpts, k: HARD_LESSON_CEILING }),
     scopeCounts,
     applicable: ranked.length,
   };

package/src/lessons-pure.mjs

@@ -706,3 +706,42 @@ export function rankLessons(entries = [], {
   return scored.map((s) => s.entry);
 }
 
+/**
+ * Rank-then-diversify in one call — the `.mjs` twin's convenience for what the
+ * TS twin gets for free by carrying `{ entry, score }` pairs into `selectDiverse`.
+ *
+ * `selectDiverse` needs a parallel `scores` array, and those scores MUST be the
+ * same set-relative values the list was sorted on: the salience factor is
+ * normalised against the max `seen_count` in the candidate SET, so a score
+ * recomputed over a different population would not line up with the order. This
+ * helper recomputes the scores over exactly the list it diversifies, beside the
+ * unexported `seenCountFrom`/`scoreWithTerms`, so callers can apply MMR without
+ * reconstructing that alignment (and without `seenCountFrom` leaking out).
+ *
+ * `entries` is expected to be `rankLessons` output (best-first) so the seed of
+ * the greedy MMR is the top-ranked lesson; the pass-through
+ * `terms`/`weights`/`halfLifeDays`/`now` MUST match the `rankLessons` call that
+ * produced it, or the recomputed scores diverge from the sort. `k` caps the
+ * returned count (default: all). Empty/degenerate input returns `[]`.
+ */
+export function diversifyRankedLessons(entries = [], {
+  terms = [],
+  now = Date.now(),
+  weights = DEFAULT_RANK_WEIGHTS,
+  halfLifeDays = RECENCY_HALF_LIFE_DAYS,
+  k = Infinity,
+  lambda,
+} = {}) {
+  const list = Array.isArray(entries) ? entries.filter((e) => e && typeof e === 'object') : [];
+  if (list.length === 0) return [];
+  const termSet = distinctTerms(terms);
+  let maxSeenCount = 0;
+  for (const e of list) maxSeenCount = Math.max(maxSeenCount, seenCountFrom(e));
+  const scores = list.map((e) => scoreWithTerms(e, termSet, { now, weights, maxSeenCount, halfLifeDays }));
+  // `numberOr` is the module's coercion convention: a non-finite `k` (the
+  // `Infinity` default, `null`, or a stringy `'40'`) resolves to a real cap —
+  // the default falls through to the whole list, `'40'` becomes 40 — rather than
+  // silently returning everything on a shape a caller plausibly passes.
+  const limit = numberOr(k, list.length);
+  return selectDiverse(list, limit, { scores, lambda });
+}