@lorekit/cli 1.48.0 → 1.50.0

package/README.md

@@ -706,9 +706,9 @@ Both files share this schema — all fields optional:
                            // next layer is tried, so a mistyped repo value falls through to
                            // the user layer before defaulting to hybrid
 
-  "hooks.sessionStart.maxChars": 1500,
-                           // character budget for that block (default 1500, ~375 tokens)
-                           // bounded to 200–20000; an out-of-range value is CLAMPED, not
+  "hooks.sessionStart.maxChars": 3000,
+                           // character budget for that block (default 3000, ~750 tokens,
+                           // ~25 index lines); bounded 200–20000, out-of-range CLAMPED not
                            // rejected — a small number means "keep it short", and honouring
                            // the floor is closer to that intent than restoring the default
                            // repo wins over user, and a declared-but-unparseable repo value
@@ -717,11 +717,34 @@ 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,
+  "hooks.sessionStart.maxLessons": 100,
+                           // how many memory LINES that block may hold, where
+                           // maxChars bounds its characters — whichever binds
+                           // first decides the block, so raising this alone does
+                           // nothing unless maxChars comes up with it
+                           // (default 100, bounded 3–200). Clamped, not
+                           // rejected; repo wins over user with the same
+                           // declared-value-owns-the-layer rule as maxChars.
+                           // In practice this is a READ-DEPTH dial, not a size
+                           // one: maxChars runs out around line 25, so what
+                           // this really sets is the per-scope candidate fetch
+                           // (100/scope by default) the ranker chooses from —
+                           // 400 candidates across a four-scope hierarchy
+                           // instead of the newest handful. It never exceeds
+                           // 100/scope, the largest page GET /memories will
+                           // return, so a ceiling above 100 fills its remaining
+                           // lines from the other scopes instead. Below 25 the
+                           // read does not shrink; you just see fewer lines.
+
+  "hooks.sessionStart.loopCap": 1,
                            // 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,
+                           // (default 1, bounded 0–40; 0 excludes loop buckets
+                           // entirely so only general memories are read). One per
+                           // bucket keeps a loop's best lesson without letting its
+                           // bookkeeping take a second slot from your codebase's
+                           // memories, which are read by a different audience.
+                           // Clamped,
                            // not rejected; repo wins over user with the same
                            // declared-value-owns-the-layer rule as maxChars
 

package/package.json

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

package/src/control.mjs

@@ -9,8 +9,9 @@
 //   hooks.disabled  — array of hook event names to suppress (e.g. ["Stop"])
 //   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.maxChars — character budget for that block (default 3000)
+//   hooks.sessionStart.loopCap  — max lessons per self-improvement loop bucket (default 1; 0 excludes them)
+//   hooks.sessionStart.maxLessons — max LINES that block may hold (default 100, range 3–200)
 //   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")
@@ -103,16 +104,19 @@ export function normalizeSessionStartMode(v) {
 }
 
 // The default SessionStart character budget, and the bounds a configured one is
-// held to. ~1500 chars is roughly 375 tokens on the 4-chars-per-token heuristic
-// — enough for a dozen index lines plus the frame, and small enough that it
-// stays a footnote in a context window rather than a section of it.
+// held to. ~3000 chars is roughly 750 tokens on the 4-chars-per-token heuristic
+// — around 25 index lines plus the frame. That is the number that decides how
+// much of the agent's window this costs, so it is the one tuned for value per
+// token rather than for smallness: a dozen lines (the old 1500) routinely showed
+// a store's newest churn and nothing that had been re-learned, which reads as
+// noise and trains the reader to skim the block.
 //
 // The floor is what one header plus one lesson line needs; below it the block
 // would be a header and nothing else, which is worse than not firing. The
 // ceiling is a backstop against a typo'd `"maxChars": 1500000` turning every
 // session start into a wall of text — the hard lesson ceiling in
 // `core/lessons.mjs` bounds it a second time, from the other direction.
-export const DEFAULT_SESSION_START_MAX_CHARS = 1500;
+export const DEFAULT_SESSION_START_MAX_CHARS = 3000;
 export const MIN_SESSION_START_MAX_CHARS = 200;
 export const MAX_SESSION_START_MAX_CHARS = 20000;
 
@@ -132,7 +136,7 @@ export const HOOK_INSTRUCTION_EVENTS = [
 // not a usable number at all (absent, a bare string, NaN). Total: the caller
 // substitutes the default for null. Out-of-range CLAMPS rather than rejecting —
 // a user who wrote `"maxChars": 50` wants a small block, and honouring the floor
-// is closer to that intent than silently restoring the 1500 default.
+// is closer to that intent than silently restoring the default.
 export function normalizeSessionStartMaxChars(v) {
   const n = firstNumber(v);
   if (n === null) return null;
@@ -143,14 +147,31 @@ export function normalizeSessionStartMaxChars(v) {
 }
 
 // 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.
+// configured one is held to.
+//
+// WHAT A BUCKET IS AND WHY IT NEEDS CAPPING. A prolific self-improvement loop —
+// the pr-reviewer's `loop::review-outcomes` / `loop::reviewer-comment-relevance`,
+// or `loop::implement-suggestion-lessons` — writes constantly and recently, so it
+// wins recency AND (being built to recur) salience, and a whole scope's read can
+// collapse to one bot's private bookkeeping (observed: 13 of 15 slots before any
+// cap existed). Ranking and MMR cannot fix that — the flood is real, varied and
+// genuinely high-scoring — but it is not what a GENERAL coding session needs.
+// General, non-loop lessons are never capped; they are what the cap frees room
+// for. Bounded, not shaped: on a store with no loop lessons it never binds.
+//
+// ONE lesson per bucket: a self-improvement loop's
+// single best lesson still surfaces, but its private bookkeeping cannot take a
+// second slot from the codebase lore a general session actually needs. It was 2,
+// which on a store with several active loops still spent a visible share of the
+// block on bot ledgers — the measured case was 4 of 7 rendered lines. Loops read
+// their own lessons back through a tag filter, so a slot spent here is a slot
+// spent on the wrong audience. `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 DEFAULT_SESSION_START_LOOP_CAP = 1;
 export const MIN_SESSION_START_LOOP_CAP = 0;
 export const MAX_SESSION_START_LOOP_CAP = 40;
 
@@ -167,6 +188,54 @@ export function normalizeSessionStartLoopCap(v) {
   return i;
 }
 
+// The default SessionStart LINE ceiling, and the bounds a configured one is held
+// to.
+//
+// TWO BOUNDS, TWO QUESTIONS. `maxChars` bounds what the block COSTS; this bounds
+// what it LOOKS LIKE. A budget alone cannot stop a store of 500 one-word keys
+// from rendering 400 lines inside it, and a 400-line index is unreadable however
+// few characters it costs. Whichever binds first wins.
+//
+// AND IN PRACTICE THAT IS ALWAYS `maxChars`, WHICH IS THE POINT OF THIS NUMBER.
+// At the default budget a block runs out of characters around line 25, so a
+// ceiling of 100 does not render 100 lines — it is not a size setting at all. It
+// is the DEPTH OF THE READ: `scopeReadLimit` derives the per-scope fetch from it,
+// so 100 means the ranker chooses its ~25 rendered lines from up to 100 rows per
+// scope (400 across a four-scope hierarchy) instead of from 25 (100 across four).
+//
+// That is where relevance actually comes from. The old default of 40 read the
+// newest 25 rows per scope, so on a store of any size the candidate pool was the
+// most RECENT few percent — a lesson re-learned five times last quarter could not
+// be ranked because it was never fetched. Widening the pool costs one bigger read
+// per session start and changes what the same ~25 lines are chosen from, which is
+// a far better trade than rendering more lines from a shallow pool.
+//
+// The floor is three: below that the block stops being an index and becomes a
+// sample, and the `map` shape already shows three. The ceiling is 200 because
+// that is roughly where `MAX_SESSION_START_MAX_CHARS` runs out at ~120 chars a
+// line — past it the ceiling could never bind, so a higher number would be inert
+// rather than generous. `core/lessons.mjs` clamps to the same 200 a second time,
+// from the other direction, so a caller passing the option directly is bounded
+// too, and `MAX_STORE_LIST_LIMIT` caps the derived READ at what the route accepts.
+export const DEFAULT_SESSION_START_MAX_LESSONS = 100;
+export const MIN_SESSION_START_MAX_LESSONS = 3;
+export const MAX_SESSION_START_MAX_LESSONS = 200;
+
+// Clamp a configured line ceiling 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, exactly like the maxChars
+// budget and the loop cap — a user who wrote `"maxLessons": 1` wants a short
+// block, and honouring the floor is closer to that intent than silently
+// restoring the default.
+export function normalizeSessionStartMaxLessons(v) {
+  const n = firstNumber(v);
+  if (n === null) return null;
+  const i = Math.round(n);
+  if (i < MIN_SESSION_START_MAX_LESSONS) return MIN_SESSION_START_MAX_LESSONS;
+  if (i > MAX_SESSION_START_MAX_LESSONS) return MAX_SESSION_START_MAX_LESSONS;
+  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.
@@ -367,6 +436,16 @@ export function resolveControl({
   const hooksSessionStartLoopCap =
     normalizedLoopCap === null ? DEFAULT_SESSION_START_LOOP_CAP : normalizedLoopCap;
 
+  // `hooks.sessionStart.maxLessons` — how many LINES that block may hold. Same
+  // layer-before-parse rule as maxChars/loopCap (declaresScalar), for the same
+  // reason: a repo that declared a ceiling owns it even when the value is
+  // garbage, so two people on the same commit read the same block.
+  const sessionStartMaxLessonsRaw = declaresScalar(repoConfig['hooks.sessionStart.maxLessons'])
+    ? repoConfig['hooks.sessionStart.maxLessons']
+    : userConfig['hooks.sessionStart.maxLessons'];
+  const hooksSessionStartMaxLessons =
+    normalizeSessionStartMaxLessons(sessionStartMaxLessonsRaw) ?? DEFAULT_SESSION_START_MAX_LESSONS;
+
   // `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.
@@ -416,6 +495,7 @@ export function resolveControl({
     hooksSessionStart,
     hooksSessionStartMaxChars,
     hooksSessionStartLoopCap,
+    hooksSessionStartMaxLessons,
     hooksSessionStartBranchHint,
     hooksAdapter,
     hooksInstructions,

package/src/core/lessons.mjs

@@ -35,7 +35,13 @@ import { resolveDefaultTtlDays, matchesScopePrefix } from '../store/ttl.mjs';
 // unconfigured workspace gets. `formatLessons` is called directly by tests and
 // by the no-store path in `hook.mjs`, so it needs its own fallback rather than
 // relying on every caller to pass one.
-import { DEFAULT_SESSION_START_MAX_CHARS, SESSION_START_MODES } from '../control.mjs';
+import {
+  DEFAULT_SESSION_START_LOOP_CAP,
+  DEFAULT_SESSION_START_MAX_CHARS,
+  DEFAULT_SESSION_START_MAX_LESSONS,
+  MAX_SESSION_START_MAX_LESSONS,
+  SESSION_START_MODES,
+} from '../control.mjs';
 import { FRICTION_FAILURE, FRICTION_STUCK_LOOP } from './friction.mjs';
 
 // THE INJECTED SET IS BOUNDED BY A CHARACTER BUDGET, NOT BY A COUNT.
@@ -56,29 +62,44 @@ import { FRICTION_FAILURE, FRICTION_STUCK_LOOP } from './friction.mjs';
 // the ~4-chars-per-token heuristic is accurate enough for a budget whose job is
 // to bound an order of magnitude.
 //
-// `HARD_LESSON_CEILING` is the second bound, from the other direction. A budget
-// alone cannot stop a store of 500 one-word keys from rendering 400 lines inside
-// it, and a 400-line index is unreadable however few characters it costs. It is
-// deliberately well above any budget a sane `maxChars` can fill, so in normal
-// operation it never binds — it exists so the worst case is bounded, not to
-// shape the common one.
-const HARD_LESSON_CEILING = 40;
-
-// How many lessons any ONE self-improvement loop (`loop::<bucket>` tag) may
-// contribute to a session-start injection. A prolific loop — the pr-reviewer's
-// `loop::review-outcomes` / `loop::reviewer-comment-relevance`, or
-// `loop::implement-suggestion-lessons` — writes constantly and recently, so it
-// wins recency AND (being built to recur) salience, and a whole scope's read
-// can collapse to one bot's private bookkeeping (observed: 13 of 15 slots).
-// Ranking and MMR cannot fix that — the flood is real, varied, and high-scoring
-// — but it is not what a GENERAL coding session needs; those lessons are read
-// 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. 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;
+// The LINE ceiling is the second bound, from the other direction. A budget alone
+// cannot stop a store of 500 one-word keys from rendering 400 lines inside it,
+// and a 400-line index is unreadable however few characters it costs. At its
+// default (`DEFAULT_SESSION_START_MAX_LESSONS`, 100) it sits well above any block
+// a default `maxChars` can fill, so in normal operation it never binds as a
+// RENDER bound — its working job is to set the depth of the fetch (see
+// `scopeReadLimit`), and bounding the worst-case line count is the backstop.
+//
+// It is CONFIGURABLE (`hooks.sessionStart.maxLessons`), which is why the two
+// numbers are separate: the config is a preference, and `HARD_LESSON_CEILING` is
+// the absolute clamp no caller can exceed — the same 200 the config normaliser
+// clamps to, applied a second time here because `fetchLessons`/`formatLessons`
+// take `maxLessons` as a plain option and a direct caller never passes through
+// that normaliser.
+const HARD_LESSON_CEILING = MAX_SESSION_START_MAX_LESSONS;
+
+// The line ceiling a caller actually gets: their `maxLessons` ROUNDED (not
+// truncated — `Math.round`, so 40.6 becomes 41) and clamped into
+// [1, HARD_LESSON_CEILING], or the default when the value is unusable. `1` and
+// not the config floor of 3 — this is the last-resort clamp on an already
+// normalised number, and a caller that deliberately asks for one line should get
+// one, not three. Pure.
+//
+// UNUSABLE INCLUDES ZERO AND NEGATIVES, not just NaN, and that is the whole
+// reason this reads as it does rather than as a bare `Math.max(1, …)`.
+// `Number(null)` is `0` and `Number('')` is `0`, so a caller passing an explicit
+// `maxLessons: null` — which the option default does NOT catch, since only
+// `undefined` triggers a destructuring default — would clamp UP to a ONE-LINE
+// block: a near-total, silent loss of the injection dressed up as a valid
+// ceiling. A zero or negative ceiling is not a request for a short block, it is
+// a value that has no reading, so it falls back to the default exactly like
+// `normalizeSessionStartMaxLessons` returning `null` does. An explicit `1` is a
+// reading, and still gets one line.
+function resolveLessonCeiling(maxLessons) {
+  const n = Number(maxLessons);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_SESSION_START_MAX_LESSONS;
+  return Math.min(HARD_LESSON_CEILING, Math.max(1, Math.round(n)));
+}
 
 // How many lessons ride along with the scope map in `map` mode. Small on
 // purpose: the point of that shape is the inventory, and a "map" that is mostly
@@ -104,15 +125,74 @@ const MAX_SCAN_CHARS = 4096;
 // precedence via the shared pure `resolvePrecedence` (the SAME first-seen /
 // more-specific-wins merge `tree` renders) — so the hook and `tree` provably
 // can't drift. Any per-scope failure is skipped (memory is best-effort).
-// Per-scope read cap. Unchanged from the count-capped era: it bounds the FETCH,
-// which is a different question from how much gets injected, and raising it
-// would make every session start pay for rows the budget was never going to
-// show. Its one visible consequence is that a scope holding more than this
-// many lessons reports a lower-bound count in the scope map — rendered `25+`
-// rather than a number that looks exact. `memory.scopes` answers it exactly and
-// is the follow-up that replaces this.
+// The FLOOR on the per-scope read — not the default, which is the higher
+// `scopeReadLimit(DEFAULT_SESSION_START_MAX_LESSONS)`. It exists so a LOWERED
+// ceiling cannot starve the ranker: asking for five lines is a statement about
+// the render, not permission to rank them out of five candidates.
+//
+// The visible consequence of whatever limit applies is that a scope holding more
+// than that many lessons reports a lower-bound count in the scope map — rendered
+// with a trailing `+` (`100+` at the default) rather than a number that looks
+// exact. `memory.scopes` answers it exactly and is the follow-up that replaces
+// this.
 export const SCOPE_READ_LIMIT = 25;
 
+// The largest `limit` the hosted route will ACCEPT on one `GET /memories` call.
+//
+// Mirrored from `ListMemoriesQuerySchema` in `@lorekit/schemas` — the schema
+// that validates `GET /memories`, which is the door `RemoteStore.list` actually
+// knocks on. NOT `MemoryListSchema`: that is the MCP *tool* schema, a different
+// entrance to the same data that happens to agree on 100 today. Self-contained
+// here for the
+// same reason `limits.ts` is mirrored into the edge function: this package takes
+// no dependencies, and the number is a CONTRACT with the other side rather than
+// a preference of ours. Keep the two in step — if the route's cap moves, this
+// moves with it.
+//
+// It is a HARD bound on the read, not a soft one, because the failure it
+// prevents is silent and total. Zod REJECTS an over-cap `limit` with a 400, so
+// `RemoteStore.list` returns `{ ok: false }`, and `fetchLessons` — best-effort by
+// design — skips that scope. Every scope fails the same way, so a remote user
+// who set `maxLessons` above 100 would get an EMPTY block with no error
+// anywhere: the exact shape of bug that survives for months because the hook
+// swallows everything by contract. The local store has no such cap, but the
+// bound is applied uniformly rather than per-store — one code path, and a
+// ceiling above 100 still fills from the several scopes in `readOrder`
+// (4 × 100 = 400 candidates for a 200-line ceiling).
+export const MAX_STORE_LIST_LIMIT = 100;
+
+// The per-scope read cap for a given line ceiling: the ceiling, held between the
+// `SCOPE_READ_LIMIT` floor and the `MAX_STORE_LIST_LIMIT` transport cap.
+//
+// THE FETCH IS WHAT THIS DIAL IS ACTUALLY FOR. `maxChars` runs out around line 25
+// at the default budget, so the ceiling almost never decides how many lines are
+// RENDERED — it decides how many rows are FETCHED, and therefore how good the
+// ~25 that render are. At the default of 100 the ranker chooses from up to 100
+// rows per scope (400 across a four-scope hierarchy) rather than the newest 25.
+// On a store of any size that is the difference between ranking a slice of this
+// week's churn and ranking a real corpus.
+//
+// It was previously gated to grow ONLY above the default, so an unconfigured
+// workspace kept a 25-row read. That gate died with the default it keyed on: once
+// the default IS the depth we want, `ceiling > DEFAULT` can never fire inside the
+// config's own 3–200 range, and the fetch would have been pinned at 25 forever
+// while the ceiling asked for 100 — a dial that silently could not be fed.
+//
+// LOWERING the ceiling still does NOT shrink the fetch below `SCOPE_READ_LIMIT`:
+// fewer candidates would mean the ranking picks its handful from a worse pool,
+// which is a quality regression dressed up as a saving. Monotone in `maxLessons`,
+// so the cost never falls as the ask grows.
+//
+// AND IT NEVER EXCEEDS WHAT THE TRANSPORT ACCEPTS (`MAX_STORE_LIST_LIMIT`). A
+// ceiling of 200 is a legal config value, but a 200-row `limit` is not a legal
+// request — so the read stops at 100 and the remaining lines fill from the other
+// scopes in `readOrder`. Without this the dial's own top half silently emptied
+// the block on a remote store. Pure.
+export function scopeReadLimit(maxLessons) {
+  const ceiling = resolveLessonCeiling(maxLessons);
+  return Math.min(Math.max(ceiling, SCOPE_READ_LIMIT), MAX_STORE_LIST_LIMIT);
+}
+
 // `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
@@ -120,9 +200,21 @@ export const SCOPE_READ_LIMIT = 25;
 export async function fetchLessons(
   store,
   cwd,
-  { now = Date.now(), scope: scopeOverride = null, loopCap = SESSION_START_LOOP_CAP, branchHint = true } = {},
+  {
+    now = Date.now(),
+    scope: scopeOverride = null,
+    loopCap = DEFAULT_SESSION_START_LOOP_CAP,
+    branchHint = true,
+    maxLessons = DEFAULT_SESSION_START_MAX_LESSONS,
+  } = {},
 ) {
   const scope = scopeOverride || deriveScope(cwd);
+  // ONE ceiling, derived once, spent on both the fetch and the diversifier — the
+  // two must agree or a raised ceiling asks for lines the read never fetched.
+  // `formatLessons` derives the same number from the same config key, so the
+  // render bound matches too.
+  const ceiling = resolveLessonCeiling(maxLessons);
+  const readLimit = scopeReadLimit(ceiling);
   // 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
@@ -141,10 +233,10 @@ export async function fetchLessons(
   // not a total, and the map must say so rather than quietly under-report.
   const truncatedScopes = new Set();
   for (const s of scope.readOrder) {
-    const res = await store.list({ scope: s, limit: SCOPE_READ_LIMIT });
+    const res = await store.list({ scope: s, limit: readLimit });
     if (!res || !res.ok) continue; // best-effort: a failed scope contributes nothing
     const raw = Array.isArray(res.entries) ? res.entries : [];
-    if (raw.length >= SCOPE_READ_LIMIT) truncatedScopes.add(s);
+    if (raw.length >= readLimit) truncatedScopes.add(s);
     const entries = raw
       .filter((e) => e && e.key)
       .map((e) => ({ ...e, scope: s }));
@@ -208,7 +300,7 @@ export async function fetchLessons(
 
   // AUDIENCE CAP before diversification: no single self-improvement loop may
   // take more than `loopCap` (the `hooks.sessionStart.loopCap` option, default
-  // `SESSION_START_LOOP_CAP`) of the injected slots, so a general
+  // `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 +309,7 @@ export async function fetchLessons(
   // shown, not the honest count of what exists per scope.
   //
   // WHERE THE FREED SLOTS FILL FROM, stated so the cap is not oversold. Each
-  // scope is read only to its newest `SCOPE_READ_LIMIT`, so on a scope whose
+  // scope is read only to its newest `readLimit` rows, so on a scope whose
   // recent writes are ALL one loop's, the general lessons that fill the freed
   // slots come from the OTHER scopes in `readOrder` (a repo's loop churn makes
   // room for `global` principles) — not from that same scope's older generals,
@@ -231,7 +323,7 @@ export async function fetchLessons(
   // The map's job is to tell a reader how much lore is sitting in each scope
   // that this injection did not show them, so its numbers should be the store's
   // real totals. Deriving them from the bounded read above cannot do that: the
-  // read stops at `SCOPE_READ_LIMIT`, so a scope holding 400 lessons reported
+  // read stops at `readLimit`, so a scope holding 400 lessons reported
   // `25+` — technically honest, useless as a quantity, and the `+` was doing a
   // lot of work.
   //
@@ -299,7 +391,7 @@ export async function fetchLessons(
   // "8 of 50" stays true no matter how the render is bounded.
   return {
     scope,
-    lessons: diversifyRankedLessons(capped, { ...rankOpts, k: HARD_LESSON_CEILING }),
+    lessons: diversifyRankedLessons(capped, { ...rankOpts, k: ceiling }),
     scopeCounts,
     applicable: ranked.length,
   };
@@ -408,10 +500,17 @@ function lessonHook(value, max = HOOK_LEN) {
 // to know what the reader saw (the shown-set bookkeeping) has to be told rather
 // than re-deriving it — a second copy of the fit maths would drift the moment
 // either bound changes.
+// `maxLessons` — the LINE ceiling (`hooks.sessionStart.maxLessons`), the second
+// bound alongside `maxChars`: whichever binds first decides the block. It is
+// passed rather than re-read from config for the same reason `maxChars` is, and
+// it must be the SAME number `fetchLessons` was given — a render bound above the
+// fetch bound asks for lines that were never fetched, and one below it silently
+// discards lessons the read paid for.
 export function formatLessons(lessons, scope, {
   instruction = null,
   mode = 'hybrid',
   maxChars = DEFAULT_SESSION_START_MAX_CHARS,
+  maxLessons = DEFAULT_SESSION_START_MAX_LESSONS,
   scopeCounts = null,
   applicable = null,
   onShown = null,
@@ -447,7 +546,11 @@ export function formatLessons(lessons, scope, {
   const map = renderScopeMap(scopeCounts);
   const reserve = shape === 'index' || !map ? 0 : map.length + 1;
 
-  const ceiling = shape === 'map' ? Math.min(MAP_TOP_K, HARD_LESSON_CEILING) : HARD_LESSON_CEILING;
+  // `map` shows a handful of lessons whatever the ceiling says — the point of
+  // that shape is the inventory. `Math.min` rather than a flat `MAP_TOP_K` so a
+  // ceiling BELOW three still binds: a reader who asked for one line gets one.
+  const lineCeiling = resolveLessonCeiling(maxLessons);
+  const ceiling = shape === 'map' ? Math.min(MAP_TOP_K, lineCeiling) : lineCeiling;
   const { shown } = fitLines(all, budget - reserve, ceiling);
   report(shown.map((s) => s.lesson));
 
@@ -503,8 +606,8 @@ function fitLines(lessons, budget, ceiling) {
 
 // The scope map: one line naming every scope that holds lessons and how many,
 // so a truncated block still tells the reader WHERE the rest live and which verb
-// reaches them. `25+` marks a scope whose read hit `SCOPE_READ_LIMIT`, so a
-// lower bound never reads as an exact total. Null when there is nothing to
+// reaches them. A trailing `+` (`25+`) marks a scope whose read hit the per-scope
+// limit, so a lower bound never reads as an exact total. Null when there is nothing to
 // describe. Pure.
 export function renderScopeMap(scopeCounts) {
   const rows = (Array.isArray(scopeCounts) ? scopeCounts : [])

package/src/hook.mjs

@@ -118,11 +118,16 @@ async function run(args) {
     const { scope: readScope, lessons, scopeCounts, applicable } = await fetchLessons(store, root, {
       loopCap: control.hooksSessionStartLoopCap,
       branchHint: control.hooksSessionStartBranchHint !== 'off',
+      maxLessons: control.hooksSessionStartMaxLessons,
     });
     emit(formatLessons(lessons, readScope, {
       instruction: sessionInstruction,
       mode: control.hooksSessionStart,
       maxChars: control.hooksSessionStartMaxChars,
+      // The SAME ceiling the fetch was given: the render bound and the fetch
+      // bound are one config key, and letting them diverge would either ask for
+      // lines that were never fetched or discard ones the read paid for.
+      maxLessons: control.hooksSessionStartMaxLessons,
       scopeCounts,
       applicable,
       // Record what this injection RENDERED, so the per-prompt hook treats it as

package/src/mcp-server.mjs

@@ -419,7 +419,7 @@ const MEMORY_DISPATCH = {
 // networkError, unusable }`. A tool that passed either through verbatim would
 // hand the model two different contracts for one tool name depending on a
 // config value it cannot see. What is left here is what only the MCP surface
-// owns: the ascending sort and the exit-clean degradation below.
+// owns: the count-desc-then-scope-asc sort and the exit-clean degradation below.
 //
 // DEGRADATION IS EXIT-CLEAN, mirroring the `scopes` command, which reports an
 // unreachable remote as a short note at exit 0 rather than failing the run. An
@@ -441,31 +441,31 @@ export async function listScopes(store) {
   return ok ? { ok: true, scopes: sortScopes(scopes) } : { ok: true, scopes: [], note: reason };
 }
 
-// Sorted by scope ascending, which is the contract `docs/mcp-tools.md`, the
-// tool catalog and `llms.txt` all state for `memory.scopes`. The HOSTED surface
-// gets that ordering from `lorekit_memory_scopes` (`order by m.scope asc`,
-// migration 00039/00049), but `LocalStore`/`TwoTierStore.listScopes()` both
-// return their `Map` insertion order — a walk order, not an ordering — so the
-// stdio server owns it here rather than the two surfaces answering differently.
-// Sorting BOTH shapes (not just the local one) makes the guarantee a property
-// of this function instead of an assumption about the store it was handed.
-// Codepoint comparison, deliberately not `localeCompare`: the ordering must not
-// depend on the HOST's locale.
+// Sorted by count DESC then scope asc, which is the contract `docs/mcp-tools.md`,
+// the tool catalog and `llms.txt` all state for `memory.scopes`. The HOSTED
+// surface gets that ordering from `lorekit_memory_scopes` (`order by count(*)
+// desc, m.scope asc`, migration 00065), but `LocalStore`/`TwoTierStore.
+// listScopes()` both return their `Map` insertion order — a walk order, not an
+// ordering — so the stdio server owns it here rather than the two surfaces
+// answering differently. Sorting BOTH shapes (not just the local one) makes the
+// guarantee a property of this function instead of an assumption about the store
+// it was handed.
 //
-// That is ascending-by-scope, not byte-identical parity with the hosted path,
-// and the difference is worth being precise about. `order by m.scope asc` sorts
-// under the DATABASE's collation (`en_US.UTF-8` on a default Supabase project),
-// which does not order like codepoint around punctuation — and a scope string
-// is mostly punctuation (`::`, `/`, `-`), so `repo::a-b` and `repo::ab` can come
-// out in the opposite relative order on the two surfaces. Case cannot differ
-// (every scope segment is lowercased, see docs/scope-format.md). Closing the
-// remaining gap means `collate "C"` on the RPC's `order by`, which changes the
-// order `GET /memories/scopes` has always returned — a public contract change
-// that belongs in its own migration, not here. Until then: both surfaces are
-// sorted ascending, neither is unordered, and nothing should depend on the two
-// agreeing on the exact position of a punctuated neighbour.
+// The primary key is `count` (a number), which orders identically on both
+// surfaces. Only the scope-asc TIEBREAK between equal-count scopes carries the
+// old caveat: it is a codepoint comparison here (deliberately not
+// `localeCompare`, so the ordering never depends on the HOST's locale), while
+// `order by m.scope asc` sorts under the DATABASE's collation (`en_US.UTF-8` on a
+// default Supabase project), which does not order like codepoint around
+// punctuation — and a scope string is mostly punctuation (`::`, `/`, `-`), so
+// two equal-count scopes like `repo::a-b` and `repo::ab` can come out in the
+// opposite relative order on the two surfaces. Case cannot differ (every scope
+// segment is lowercased, see docs/scope-format.md). Nothing should depend on the
+// two agreeing on the exact position of a punctuated equal-count neighbour.
 function sortScopes(rows) {
-  return rows.sort((a, b) => (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : 0));
+  return rows.sort(
+    (a, b) => b.count - a.count || (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : 0),
+  );
 }
 
 // Provenance for a tool call: the caller's explicit values win, the working

package/src/store/remote.mjs

@@ -257,7 +257,7 @@ class RemoteStore {
   // The `scopes` array is the SAME `[{ scope, count }]` inventory shape
   // `LocalStore.listScopes()` returns, so `scopes.mjs` feeds both through the
   // same pure `filterScopeInventory`/`summarizeScopeInventory` helpers. Ordering
-  // is not relied upon (the server sorts by scope asc; the view re-sorts by
+  // is not relied upon (the server sorts by count desc; the view re-sorts by
   // scope type). Failures use this store's standard `{ ok:false, error,
   // networkError }` envelope so the caller can degrade gracefully.
   //