@lorekit/cli 1.49.0 → 1.51.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.49.0",
+  "version": "1.51.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.mjs

@@ -158,6 +158,30 @@ export function normalizeRunEnvironment(raw) {
   return /^[A-Za-z0-9_.\-:]+$/.test(t) ? t : null;
 }
 
+/**
+ * The retry delay a failed response advertised, in whole seconds, or null.
+ *
+ * Prefers the JSON body's `retryAfterSeconds` over the `Retry-After` header:
+ * both are set by the same `tooManyRequests()` helper, and the body value is
+ * the number the rate-limit RPC actually returned, while the header is its
+ * stringified copy that an intermediary may rewrite.
+ *
+ * TOTAL over any input. `headers` is read through optional calls because a
+ * test double (and a hand-rolled Response-alike) may not implement the Headers
+ * interface, and a missing retry hint must never be able to throw on an error
+ * path — the caller is already handling a failure.
+ */
+export function retryAfterFrom(data, headers) {
+  const raw = data?.retryAfterSeconds ?? (typeof headers?.get === 'function' ? headers.get('retry-after') : null);
+  if (raw == null || raw === '') return null;
+  const n = Number(raw);
+  // A `Retry-After` may also be an HTTP-date; a non-numeric value is reported
+  // as "no hint" so the caller falls back to its own backoff rather than
+  // waiting on NaN.
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.ceil(n);
+}
+
 export async function restFetch(baseUrl, token, path, { method = 'GET', body, timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -203,6 +227,12 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
       return {
         ok: false,
         httpStatus: res.status,
+        // How long the server asked the caller to wait, in seconds, or null when
+        // it did not say. Only a 429 carries one today (`tooManyRequests` sets
+        // BOTH a `retryAfterSeconds` body field and the `Retry-After` header),
+        // but this is read on every failure so a future 503 needs no change
+        // here. Additive: existing callers ignore the extra key.
+        retryAfter: retryAfterFrom(data, res.headers),
         error: data?.error ? { message: data.error, code: data.code } : { code: res.status, message: text.slice(0, 200) || res.statusText },
       };
     }

package/src/store/format.mjs

@@ -29,7 +29,7 @@ export const FIELDS = [
   // columns: a file written before this existed simply decodes it as absent.
   'expires_at',
   // Recurrence — how many times this lesson has been written, mirroring the
-  // hosted `memories.seen_count` column (migration 00058) so an offline store
+  // hosted `memories.seen_count` column (migration 00059) so an offline store
   // carries the same salience signal a remote one does. Appended like the
   // columns above: a file written before this existed decodes it as absent,
   // which the read projection reports as 0 rather than inventing a count.

package/src/store/local.mjs

@@ -134,7 +134,7 @@ class LocalStore {
       archived_at: null,
       expires_at,
       // Recurrence, counted the way the hosted `memory_write` RPC counts it
-      // (migration 00058): a write against a key this store already holds IS
+      // (migration 00059): a write against a key this store already holds IS
       // the next sighting. `seenCountOf` floors an absent/hand-edited value to
       // 0, so a file written before this column existed resumes at 1 on its
       // next write rather than throwing or restarting the tally at 2.

package/src/store/remote.mjs

@@ -21,6 +21,7 @@
 import { restFetch, mcpToRestBase } from '../mcp.mjs';
 import { getActiveTraceparent } from '../telemetry.mjs';
 import { withReadFields } from './entry-fields.mjs';
+import { normalizeCreatedAt } from './created-at.mjs';
 
 // Drop undefined/null args so JSON payloads stay tidy.
 function stripUndefined(obj) {
@@ -29,6 +30,55 @@ function stripUndefined(obj) {
   return out;
 }
 
+/**
+ * A read that could not be answered — a transport failure or a non-2xx status,
+ * as opposed to "the lesson is not there".
+ *
+ * Exported so a caller can tell it from a programming error and degrade
+ * per-entry (report this one, keep going) instead of aborting a whole run.
+ * `result` carries the raw store envelope for the message the caller shows.
+ */
+export class StoreReadError extends Error {
+  constructor(message, result) {
+    super(message);
+    this.name = 'StoreReadError';
+    this.result = result;
+  }
+}
+
+// An absolute `expires_at` expressed as the hosted write's relative `ttl_days`.
+//
+// Three outcomes, and the third exists because "no expiry" and "I cannot tell"
+// must not collapse into one answer:
+//
+//   `undefined`  no expiry — the caller states that positively with
+//                `clear_ttl: true`, so a permanent lesson stops being expiring.
+//   `'expired'`  already elapsed; the caller must refuse (see `putEntry`).
+//   `'unknown'`  an unparseable value. The caller then sends NEITHER TTL field,
+//                leaving the RPC on its `'keep'` branch, because the safe
+//                reading of a corrupt frontmatter field is "do not touch the
+//                expiry" — the same fail-safe posture as `isExpired`. Treating
+//                it as no expiry would let one bad character wipe a live remote
+//                TTL.
+//
+//   else         the remaining WHOLE days, clamped to the schema's 1–365.
+function remoteTtlDays(expiresAt, now = new Date()) {
+  const exact = remoteTtlDaysExact(expiresAt, now);
+  if (typeof exact !== 'number') return exact;
+  return Math.min(365, Math.max(1, exact));
+}
+
+// The same conversion WITHOUT the 1–365 clamp, so a caller can see that the
+// clamp bound and report the loss. Same three non-numeric outcomes.
+function remoteTtlDaysExact(expiresAt, now = new Date()) {
+  if (!expiresAt) return undefined;
+  const ms = Date.parse(expiresAt);
+  if (Number.isNaN(ms)) return 'unknown';
+  const remaining = ms - now.getTime();
+  if (remaining <= 0) return 'expired';
+  return Math.ceil(remaining / 86_400_000);
+}
+
 export function createRemoteStore({ endpoint, token } = {}) {
   return new RemoteStore(endpoint, token);
 }
@@ -151,7 +201,24 @@ class RemoteStore {
     // scope+key is unique, so one row is all there can be — don't pull the default page of 50.
     p.set('limit', '1');
     const res = await this._rest(`/memories?${p}`);
-    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
+    // `unusable` is passed through: `_rest` short-circuits an unconfigured
+    // store with that flag and NOTHING else, so a caller that drops it is left
+    // with a failure carrying no error and no networkError — a blank failure it
+    // can only report generically. Additive; every existing caller branches on
+    // `ok` and ignores the extra key.
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: res.error ?? null,
+        // Carried for the same reason `write` carries them: a read can be
+        // rate-limited too, and a caller that retries needs to tell a 429 it
+        // should wait out from one it must not.
+        httpStatus: res.httpStatus ?? null,
+        retryAfter: res.retryAfter ?? null,
+        networkError: res.networkError ?? null,
+        unusable: res.unusable ?? false,
+      };
+    }
     const entries = res.data?.entries ?? [];
     // Same projection as list/search — a single read must not answer with a
     // different shape than the listing the caller found the key in.
@@ -181,7 +248,223 @@ class RemoteStore {
     if (origin_commit !== undefined) body.origin_commit = origin_commit;
     if (origin_pr !== undefined) body.origin_pr = origin_pr;
     const res = await this._rest('/memories', { method: 'POST', body });
-    return { ok: res.ok, error: res.error, networkError: res.networkError };
+    // `httpStatus` and `retryAfter` are passed through so a caller can tell the
+    // two 429s apart and honour the server's own backoff. They are DIFFERENT
+    // failures wearing one status code: `code: 'rate_limited'` is transient and
+    // must be retried, `code: 'memory_cap'` is terminal (translateDbError maps
+    // the LK001 cap trigger to 429 as well) and must not be. Additive — the
+    // existing `{ ok, error, networkError }` keys are unchanged.
+    // Every field is coalesced, not just the retry hint: a caller comparing
+    // `httpStatus` must not get `null` from a refusal and `undefined` from the
+    // network-error or `unusable` branch, which is the exact split the shape
+    // exists to remove.
+    return {
+      ok: res.ok,
+      error: res.error ?? null,
+      httpStatus: res.httpStatus ?? null,
+      retryAfter: res.retryAfter ?? null,
+      networkError: res.networkError ?? null,
+      // `_rest` short-circuits an unconfigured store with `{ ok:false,
+      // unusable:true }` and no error at all, so without this the caller sees
+      // a failure with every field null and no reason. Passed through the way
+      // `listScopes` already does.
+      unusable: res.unusable ?? false,
+    };
+  }
+
+  // ── Migrate-destination parity with LocalStore ────────────────────────────
+  //
+  // `migrate` classifies each source entry ADD / UPDATE / NOOP with a read and
+  // then upserts it, against whatever store it was handed. LocalStore answers
+  // that with `getEntry` + `putEntry`; these are the remote halves, so the
+  // migrate loop stays ONE code path instead of branching per destination.
+  //
+  // The local pair is lossless (`putEntry` writes every field verbatim,
+  // archived rows included). The remote pair CANNOT be, because the hosted
+  // write is an RPC with a fixed parameter list, not a file write:
+  //
+  //   preserved  scope, key, source_agent, trigger, and `created` —
+  //              sent as `created_at`, which memory_write honours on INSERT
+  //              only, so a migrated lesson keeps its original creation date
+  //              and its ranking recency with it. `value` survives too but is
+  //              TRIMMED: `MemoryWriteSchema` applies `.transform(s =>
+  //              s.trim())`, so surrounding whitespace does not make the trip.
+  //   re-stamped `updated` — the server sets it to the write instant. There is
+  //              no parameter for it, and inventing one would let a client
+  //              backdate an edit it did not make.
+  //   derived    `seen_count` — the RPC owns the tally (migration 00059: a
+  //              write against an existing key IS the next sighting). A lesson
+  //              the hosted store has never seen lands at 1; one it already
+  //              holds lands at ITS count plus one, not the local one. Either
+  //              way the local history does not transfer.
+  //   converted  `expires_at` → `ttl_days`, the remaining whole days, clamped
+  //              to the schema's 1–365 (a longer-lived TTL is clamped, not
+  //              dropped — the alternative is silently making it permanent).
+  //              A clamp IS lossy, so it is reported: the result carries
+  //              `ttlClamped: true` and the caller can list the entry as
+  //              shortened rather than leaving the user to discover it.
+  //              A PERMANENT entry sends `clear_ttl: true` rather than simply
+  //              omitting `ttl_days`: omission is the RPC's `'keep'` branch
+  //              (migration 00031), which leaves an existing remote
+  //              `expires_at` in place, so a permanent local lesson would
+  //              land on an expiring remote row and still die.
+  //   authoritative
+  //              `tags`. The conflict clause is `tags = excluded.tags`, so the
+  //              source entry's list REPLACES the hosted one — an untagged
+  //              local entry sends `[]` and clears whatever labels the hosted
+  //              row carried. That is what a verbatim upsert means here (the
+  //              local file is the thing being migrated), but it is the one
+  //              field where "verbatim" can remove hosted data, so it is
+  //              called out rather than filed under preserved.
+  //   sticky     `origin_*`. The RPC's conflict clause coalesces provenance
+  //              (`coalesce(excluded.origin_repo, memories.origin_repo)`, and
+  //              likewise for branch/commit/pr) so a write that does not know
+  //              a field cannot erase what an earlier one recorded. A migrated
+  //              entry with NO provenance therefore leaves whatever the hosted
+  //              row already had; it cannot clear it, by design, and there is
+  //              no parameter that would. `source_agent` and `trigger` are NOT
+  //              coalesced (`= excluded.*`), so an absent one still CLEARS the
+  //              hosted value — not because a null is sent (`stripUndefined`
+  //              drops nulls before the request) but because the REST handler
+  //              substitutes `?? null` for the missing field and the RPC
+  //              writes that. Omitted and null are the same instruction here,
+  //              which is the opposite of what they mean for `origin_*`. `kind` and `host` are coalesced the same
+  //              way, and this store never sends them at all — the server
+  //              infers both from the `loop::` tag (`resolveKindHost`), which
+  //              the tags carry, so a migrated lesson classifies itself.
+  //
+  // Two states have no remote representation at all and are REFUSED rather
+  // than silently rewritten, because writing them would resurrect a lesson the
+  // user retired: an archived entry (every conflict predicate on `memories` is
+  // partial on `archived_at is null`, so the hosted write does not revive the
+  // archived row — it INSERTS a second, live one beside it, leaving the store
+  // with both) and
+  // an already-expired one (any `ttl_days` re-dates it into the future). Both
+  // come back as `{ ok:false, unsupported }` so the caller can report them as
+  // skipped. `migrate` does NOT filter them today — adding that filter is the
+  // job of the PR that makes a remote destination reachable — so until then
+  // this refusal is the only thing standing between an archived lesson and
+  // resurrection, which is why it lives in the store and not in the caller.
+
+  // Raw lookup by scope+key, mirroring `LocalStore.getEntry` — the entry or
+  // null. The ROW is each store's own: this answers a REST `MemoryEntry`
+  // (`created_at`/`updated_at`) and the local one answers parsed frontmatter
+  // (`created`/`updated`), both through `withReadFields`. That is deliberate —
+  // the pair exists so a caller can ASK either store whether a key is there,
+  // not so it can compare two rows field-by-field without knowing which store
+  // produced them. A caller that compares has to speak the destination's
+  // spelling; that is what the remote comparison in the migrate loop does. LocalStore's is synchronous and this one cannot be, so callers must
+  // `await` it; awaiting the local store's plain return value is a no-op.
+  //
+  // One semantic difference the caller has to know about: LocalStore.getEntry
+  // sees archived rows and this cannot — `GET /memories` filters them out — so
+  // a remote destination classifies an archived counterpart as ADD, and the
+  // write then lands as a NEW live row beside the archived one (the conflict
+  // predicates are partial on `archived_at is null`). That is what the hosted
+  // `memory_write` does for any write against an archived key, not a
+  // migrate-specific quirk — and it is why `putEntry` refuses an archived
+  // source entry outright rather than relying on this classification.
+  //
+  // A FAILED read THROWS rather than answering null. Null is the answer to "no
+  // such lesson", and a caller that classifies ADD / UPDATE / NOOP acts on it:
+  // returning null for a transient 500 or a dropped connection would quietly
+  // reclassify an existing hosted lesson as new and overwrite it. The local
+  // store never throws here (a file read that fails is genuinely a miss), so
+  // this widens the contract only where the failure mode exists.
+  async getEntry({ scope, key } = {}) {
+    const res = await this.read({ scope, key });
+    if (!res.ok) {
+      // An unconfigured store carries no error at all, so name that case
+      // rather than reporting the generic failure text for it.
+      const reason = res.unusable
+        ? 'the remote store is not configured (missing endpoint or token)'
+        : (res.networkError || res.error?.message || 'read failed');
+      throw new StoreReadError(`remote read failed for ${scope}::${key}: ${reason}`, res);
+    }
+    return res.entry ?? null;
+  }
+
+  // Upsert one entry, as close to verbatim as the hosted write allows. See the
+  // fidelity table above for exactly which fields survive.
+  //
+  // EVERY branch answers with the SAME key set — `write`'s
+  // `{ ok, error, httpStatus, retryAfter, networkError, unusable }` plus
+  // Unlike `LocalStore.putEntry`, no `entry` comes back: the hosted write
+  // returns an id and derives the rest server-side, so echoing the request as
+  // if it were the stored row would be a fabrication. A caller that needs the
+  // stored row reads it back.
+  //
+  // `unsupported` (the refusal reason, else null), `ttlClamped` (the entry
+  // landed with a shortened life) and `createdAtDropped` (its `created` was
+  // unusable, so the server stamped the write instant instead). The last two
+  // report what HAPPENED, so both are false when the write did not succeed. A refusal fills the transport fields
+  // with null rather than omitting them, so a caller reading any one key never
+  // gets a value from one branch and `undefined` from another.
+  async putEntry(entry = {}, { now = new Date() } = {}) {
+    const refuse = (unsupported, message) => ({
+      ok: false,
+      unsupported,
+      // Carries a `code` like every real failure, so a caller can branch on
+      // one field instead of matching prose.
+      error: { message, code: 'unsupported' },
+      httpStatus: null,
+      retryAfter: null,
+      networkError: null,
+      // Every key any putEntry branch answers with, so a caller reading one
+      // never gets a value from one branch and `undefined` from another.
+      unusable: false,
+      ttlClamped: false,
+      createdAtDropped: false,
+    });
+    if (entry?.archived_at) {
+      return refuse('archived', 'archived entries cannot be written remotely — the hosted write would insert a second, live row beside the archived one');
+    }
+    const ttl = remoteTtlDays(entry?.expires_at, now);
+    if (ttl === 'expired') {
+      return refuse('expired', 'expired entries cannot be written remotely — any TTL would re-date them into the future');
+    }
+    // The same validation the server applies (`_shared/created-at.ts`, mirrored
+    // here), run BEFORE the request rather than discovered as a 400. A local
+    // file can hold a hand-edited or clock-skewed `created`, and losing the
+    // whole lesson over its creation date is the wrong trade: drop the
+    // override, let the server stamp now, and report the loss so the caller
+    // can say which entries were re-dated.
+    let createdAt;
+    let createdAtDropped = false;
+    try {
+      createdAt = normalizeCreatedAt(entry?.created ?? null, now) ?? undefined;
+    } catch {
+      createdAt = undefined;
+      createdAtDropped = Boolean(entry?.created);
+    }
+    const result = await this.write(stripUndefined({
+      scope: entry.scope,
+      key: entry.key,
+      value: entry.value == null ? '' : String(entry.value),
+      tags: Array.isArray(entry.tags) ? entry.tags : [],
+      source_agent: entry.source_agent,
+      trigger: entry.trigger,
+      created_at: createdAt,
+      // `'unknown'` sends neither field, leaving the RPC on its `'keep'`
+      // branch. A real TTL sends only `ttl_days`; no TTL says so explicitly
+      // with `clear_ttl` rather than by omission — see the fidelity note above.
+      ttl_days: typeof ttl === 'number' ? ttl : undefined,
+      clear_ttl: ttl === undefined ? true : undefined,
+      origin_repo: entry.origin_repo,
+      origin_branch: entry.origin_branch,
+      origin_commit: entry.origin_commit,
+      origin_pr: entry.origin_pr,
+    }));
+    // Always present, like every other key in this envelope — a caller must
+    // not have to know which branch produced the result to read it.
+    // Both flags describe what HAPPENED, so they are false on a write that did
+    // not happen — a failed request shortened nothing and re-dated nothing.
+    return {
+      ...result,
+      unsupported: null,
+      ttlClamped: Boolean(result.ok) && ttl === 365 && remoteTtlDaysExact(entry?.expires_at, now) > 365,
+      createdAtDropped: Boolean(result.ok) && createdAtDropped,
+    };
   }
 
   // Natural-key DELETE. Without `force` the server soft-archives (stamps