@lorekit/cli 1.44.0 → 1.46.0

package/README.md

@@ -717,6 +717,26 @@ Both files share this schema — all fields optional:
                            // memories are RANKED before the budget is spent, so what
                            // survives is the most-recurring and most-recent, not the newest
 
+  "hooks.sessionStart.loopCap": 2,
+                           // how many memories one self-improvement loop (a
+                           // "loop::<bucket>" tag) may contribute to that block
+                           // (default 2, bounded 0–40; 0 excludes loop buckets
+                           // entirely so only general memories are read). Clamped,
+                           // not rejected; repo wins over user with the same
+                           // declared-value-owns-the-layer rule as maxChars
+
+  "hooks.sessionStart.branchHint": "on",
+                           // whether the block is nudged toward the current git
+                           // branch's topic — on "feat/embedding-pipeline",
+                           // embedding memories are lifted (the leading type/author
+                           // segment is ignored). Default "on"; it only ever lifts
+                           // an on-topic memory, never buries one. "off" restores
+                           // the plain most-recurring / most-recent read. Repo wins
+                           // over user, but — following hooks.userPrompt, not the
+                           // maxChars layer-lock — a declared-but-unparseable repo
+                           // value FALLS THROUGH to a valid user value rather than
+                           // owning the layer
+
   "hooks.adapter": "claude",
                            // explicit adapter when auto-detection is ambiguous
                            // values: "claude" | "cursor" | "codex"

package/package.json

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

package/src/control.mjs

@@ -10,6 +10,8 @@
 //   hooks.stop      — Stop-hook gating ("friction" default | "always" | "off")
 //   hooks.sessionStart          — injected-block shape ("hybrid" default | "index" | "map")
 //   hooks.sessionStart.maxChars — character budget for that block (default 1500)
+//   hooks.sessionStart.loopCap  — max lessons per self-improvement loop bucket (default 2; 0 excludes them)
+//   hooks.sessionStart.branchHint — nudge the read toward the git branch topic ("on" default | "off")
 //   hooks.userPrompt — the per-turn relevance pull ("on" default | "off")
 //   hooks.adapter   — explicit adapter override ("claude" | "cursor" | "codex")
 //
@@ -140,6 +142,31 @@ export function normalizeSessionStartMaxChars(v) {
   return i;
 }
 
+// The default per-loop-bucket cap for the SessionStart read, and the bounds a
+// configured one is held to. 2 keeps each self-improvement loop's top couple of
+// lessons without letting one bucket flood a general session; 0 is a meaningful
+// setting — exclude loop buckets entirely and read only general codebase lessons.
+// The ceiling is a generous backstop against a typo'd cap, not a shared constant:
+// `core/lessons.mjs` bounds the whole read at its own hard lesson ceiling
+// downstream, so any loopCap at or above that never binds regardless of the exact
+// number here — they are deliberately independent, not kept in lockstep.
+export const DEFAULT_SESSION_START_LOOP_CAP = 2;
+export const MIN_SESSION_START_LOOP_CAP = 0;
+export const MAX_SESSION_START_LOOP_CAP = 40;
+
+// Clamp a configured loop cap into range, or null when it is not a usable number
+// (absent, a bare string, NaN). Total: the caller substitutes the default for
+// null. Out-of-range CLAMPS rather than rejecting, like the maxChars budget — and
+// `0` is honoured, not floored away, because "exclude loop buckets" is a real ask.
+export function normalizeSessionStartLoopCap(v) {
+  const n = firstNumber(v);
+  if (n === null) return null;
+  const i = Math.round(n);
+  if (i < MIN_SESSION_START_LOOP_CAP) return MIN_SESSION_START_LOOP_CAP;
+  if (i > MAX_SESSION_START_LOOP_CAP) return MAX_SESSION_START_LOOP_CAP;
+  return i;
+}
+
 // A config value that is meant to be a number, or null when it is absent or is
 // something else entirely. Numeric strings are accepted because JSON configs get
 // hand-edited; the RANGE check happens later, at the point of use.
@@ -328,6 +355,26 @@ export function resolveControl({
   const hooksSessionStartMaxChars =
     normalizeSessionStartMaxChars(sessionStartMaxCharsRaw) ?? DEFAULT_SESSION_START_MAX_CHARS;
 
+  // `hooks.sessionStart.loopCap` — how many lessons one `loop::<bucket>` may
+  // contribute. Same layer-before-parse rule as maxChars (declaresScalar): a repo
+  // that declared a cap owns it even when the value is garbage, so two people on
+  // the same commit get the same read. `0` is a valid, deliberate value, so the
+  // default is only substituted when NOTHING usable was declared.
+  const sessionStartLoopCapRaw = declaresScalar(repoConfig['hooks.sessionStart.loopCap'])
+    ? repoConfig['hooks.sessionStart.loopCap']
+    : userConfig['hooks.sessionStart.loopCap'];
+  const normalizedLoopCap = normalizeSessionStartLoopCap(sessionStartLoopCapRaw);
+  const hooksSessionStartLoopCap =
+    normalizedLoopCap === null ? DEFAULT_SESSION_START_LOOP_CAP : normalizedLoopCap;
+
+  // `hooks.sessionStart.branchHint` — whether the read is nudged toward the git
+  // branch topic. On/off (the `hooks.userPrompt` vocabulary), default `on`, repo
+  // layer wins. Off restores the pre-branch-query read: recency + salience only.
+  const hooksSessionStartBranchHint =
+    normalizeUserPromptMode(repoConfig['hooks.sessionStart.branchHint']) ||
+    normalizeUserPromptMode(userConfig['hooks.sessionStart.branchHint']) ||
+    'on';
+
   // `hooks.adapter` — repo layer wins over user layer (explicit project override).
   const hooksAdapter =
     (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
@@ -368,6 +415,8 @@ export function resolveControl({
     hooksUserPrompt,
     hooksSessionStart,
     hooksSessionStartMaxChars,
+    hooksSessionStartLoopCap,
+    hooksSessionStartBranchHint,
     hooksAdapter,
     hooksInstructions,
   };

package/src/core/lessons.mjs

@@ -75,7 +75,9 @@ const HARD_LESSON_CEILING = 40;
 // back by their own host through a tag filter. Two per bucket keeps the signal
 // (a loop's top couple of lessons still surface) without the flood; general,
 // non-loop lessons are never capped. Bounded, not shaped: on a store with no
-// loop lessons it never binds.
+// loop lessons it never binds. This is the DEFAULT — a repo/user can override it
+// with `hooks.sessionStart.loopCap` (0 excludes loop buckets entirely), which
+// `fetchLessons` receives as its `loopCap` option.
 const SESSION_START_LOOP_CAP = 2;
 
 // How many lessons ride along with the scope map in `map` mode. Small on
@@ -111,8 +113,16 @@ const MAX_SCAN_CHARS = 4096;
 // is the follow-up that replaces this.
 export const SCOPE_READ_LIMIT = 25;
 
-export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
-  const scope = deriveScope(cwd);
+// `scope` may be injected instead of derived from `cwd` — a seam for callers
+// that already hold a resolved scope and for tests that need a deterministic
+// branch (deriveScope shells out to git, so the ambient branch — often a
+// detached `HEAD` in CI — cannot exercise the branch-seeded read otherwise).
+export async function fetchLessons(
+  store,
+  cwd,
+  { now = Date.now(), scope: scopeOverride = null, loopCap = SESSION_START_LOOP_CAP, branchHint = true } = {},
+) {
+  const scope = scopeOverride || deriveScope(cwd);
   // Issued BEFORE the per-scope read loop and awaited after it. Nothing in the
   // inventory depends on the loop, so awaiting it afterwards would cost a
   // remote store one extra SERIAL round-trip on the session-start path; started
@@ -177,25 +187,28 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // narrow scope should instead be guaranteed floor space, that is a weighting
   // change in `rankLessons`, not something to re-derive here.
   //
-  // `terms: []` is the SessionStart case: nothing has been asked yet, so the
-  // relevance factor contributes nothing and the order is recency + salience.
-  // `scopeOrder` is passed explicitly rather than left to the scorer's
-  // 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.
+  // The rank options (see `sessionRankOpts`): a relevance query distilled from
+  // the branch NAME, at the DEFAULT weight, so a session on `feat/embedding-…`
+  // nudges embedding lessons up. Relevance only ever LIFTS an on-topic lesson —
+  // a non-matching lesson scores relevance 0, so a branch that matches nothing
+  // does not reorder the read — which is why it need not (and must not, per the
+  // Σweights normalisation) be damped by a smaller weight. A trunk branch or
+  // detached HEAD yields no terms, and the read is recency + salience exactly as
+  // before. `scopeOrder` is passed explicitly rather than left to the scorer's
+  // first-appearance default — the hierarchy is `readOrder`'s to state, not an
+  // artefact of how this function happens to build its array.
   // 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
+  // the two can never drift on terms, weights OR the `now` clock:
+  // `diversifyRankedLessons` recomputes each entry's score to seed the MMR
+  // objective, and scored with different options those would not line up with the
+  // sorted order. `k` is diversification-only; `scopeOrder` is ranking-only and
   // simply ignored by the diversifier's destructuring.
-  const rankOpts = { terms: [], now, scopeOrder: scope.readOrder };
+  const rankOpts = sessionRankOpts(scope, now, { branchHint });
   const ranked = rankLessons(winners, rankOpts);
 
   // AUDIENCE CAP before diversification: no single self-improvement loop may
-  // take more than `SESSION_START_LOOP_CAP` of the injected slots, so a general
+  // take more than `loopCap` (the `hooks.sessionStart.loopCap` option, default
+  // `SESSION_START_LOOP_CAP`) of the injected slots, so a general
   // session is not flooded with one bot's private `loop::<bucket>` bookkeeping.
   // General (non-loop) lessons pass through uncapped — they are what the cap
   // frees room for. Applied to the ranked list so the survivors are each
@@ -211,7 +224,7 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // which the bounded read never fetched. Reaching those is the recency-window
   // limit (the `order=rank` CANDIDATE_LIMIT problem, one scope down), not this
   // cap's to solve; the cap still does its job of unflooding across scopes.
-  const capped = capPerBucket(ranked, { cap: SESSION_START_LOOP_CAP, bucketOf: loopBucketOf });
+  const capped = capPerBucket(ranked, { cap: loopCap, bucketOf: loopBucketOf });
 
   // ── the scope map: EXACT counts when the store can enumerate ───────────────
   //
@@ -274,11 +287,12 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // 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.
+  // the set stops being a wall of duplicates. Spreading `rankOpts` here (rather
+  // than restating terms/weights) is what keeps the diversifier's recomputed
+  // scores in agreement with the `rankLessons` sort above — same terms, same
+  // branch-relevance weight, same `now`. 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
@@ -541,6 +555,56 @@ export function distilTerms(text) {
   return terms;
 }
 
+// Single-segment branch names that carry no topic: the trunk names a session is
+// most often on. A `<segment>/…` branch always has a leading type/author segment
+// (`feat`, `fix`, `claude`, `dependabot`, a username) that is never the topic —
+// see `branchQueryTerms` — so those words don't need listing here; this set is
+// only consulted for a branch with NO `/`.
+const TRUNK_BRANCHES = new Set(['main', 'master', 'develop', 'trunk', 'head']);
+
+// Distil a relevance query from the branch NAME only — owner/repo never enters,
+// because `deriveScope` keeps the raw branch in `scope.branch`. The leading
+// `/`-segment of a branch is a type or author by convention (`feat/…`,
+// `dependabot/…`, `alice/…`) and never the topic, so it is dropped WHOLESALE when
+// a `/` is present; the DESCRIPTION is then tokenised by the shared `distilTerms`
+// (so `MIN_TERM_LEN`, dedupe and the FTS-safe shape apply). A word like `release`
+// survives when it is in the description (`feat/release-notes`), because only the
+// FIRST segment is removed. Empty for a bare trunk name, a detached `HEAD`, or no
+// git — the read then behaves exactly as before. Pure and total.
+export function branchQueryTerms(scope) {
+  const branch = scope && typeof scope.branch === 'string' ? scope.branch : '';
+  if (!branch || branch === 'HEAD') return [];
+  const slash = branch.indexOf('/');
+  if (slash === -1) {
+    // No prefix segment: a bare trunk name carries no topic; anything else is
+    // its own description.
+    return TRUNK_BRANCHES.has(branch.toLowerCase()) ? [] : distilTerms(branch);
+  }
+  return distilTerms(branch.slice(slash + 1));
+}
+
+// The rank options for a session-start read of `scope` at `now` — THE wiring
+// seam, so the branch-seeding is unit-testable without a git checkout. The branch
+// query rides at the DEFAULT relevance weight, exactly like the prompt/failure
+// paths: it only ever LIFTS an on-topic lesson (a non-matching lesson scores
+// relevance 0, so a branch that matches nothing is byte-for-byte the old read),
+// and it is deliberately NOT damped by a smaller weight — reducing one factor's
+// weight shrinks the normaliser (Σweights) and rescales every score, which then
+// distorts the unscaled Jaccard term in `selectDiverse`'s MMR even for lessons
+// the branch never matched. `fetchLessons` feeds the ONE object this returns to
+// both `rankLessons` and (spread) the diversifier, so their scores agree on
+// terms and the clock.
+export function sessionRankOpts(scope, now, { branchHint = true } = {}) {
+  return {
+    // `branchHint: false` (config `hooks.sessionStart.branchHint: off`) restores
+    // the pre-branch-query read — no terms, so relevance contributes nothing and
+    // the order is recency + salience.
+    terms: branchHint ? branchQueryTerms(scope) : [],
+    now,
+    scopeOrder: scope && scope.readOrder ? scope.readOrder : null,
+  };
+}
+
 // De-duplicate store-search hits by `scope::key` and cap them, PRESERVING the
 // store's order — which is NOT relevance ordering: the remote store filters by
 // FTS but orders by `updated_at desc` (recency), and the local one yields scope

package/src/hook.mjs

@@ -115,7 +115,10 @@ async function run(args) {
       }
       return 0;
     }
-    const { scope: readScope, lessons, scopeCounts, applicable } = await fetchLessons(store, root);
+    const { scope: readScope, lessons, scopeCounts, applicable } = await fetchLessons(store, root, {
+      loopCap: control.hooksSessionStartLoopCap,
+      branchHint: control.hooksSessionStartBranchHint !== 'off',
+    });
     emit(formatLessons(lessons, readScope, {
       instruction: sessionInstruction,
       mode: control.hooksSessionStart,