@lorekit/cli 1.45.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.45.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
@@ -115,7 +117,11 @@ export const SCOPE_READ_LIMIT = 25;
 // 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 } = {}) {
+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
@@ -197,11 +203,12 @@ export async function fetchLessons(store, cwd, { now = Date.now(), scope: scopeO
   // 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 = sessionRankOpts(scope, now);
+  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
@@ -217,7 +224,7 @@ export async function fetchLessons(store, cwd, { now = Date.now(), scope: scopeO
   // 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 ───────────────
   //
@@ -587,9 +594,12 @@ export function branchQueryTerms(scope) {
 // 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) {
+export function sessionRankOpts(scope, now, { branchHint = true } = {}) {
   return {
-    terms: branchQueryTerms(scope),
+    // `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,
   };

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,