@lorekit/cli 1.41.0 → 1.43.0

package/README.md

@@ -51,7 +51,9 @@ without needing a marketplace:
 2. **MCP server** (`lorekit`) — the connection to your lessons, merged into the
    MCP config (preserving any other servers).
 3. **Hooks** — the *deterministic* layer: lessons injected on every
-   `SessionStart`, and on a tool failure (`PostToolUseFailure`) any lessons that
+   `SessionStart`, the few that match what you just typed on every substantive
+   prompt (`UserPromptSubmit`, `hooks.userPrompt`), and on a tool failure
+   (`PostToolUseFailure`) any lessons that
    look **relevant to that failure** ("you've hit this before") plus a nudge to
    record the fix, and a retrospective nudge on `Stop` — by default only when the
    session actually hit friction (`hooks.stop`). These fire the shared
@@ -133,8 +135,8 @@ and the write is still the model calling `memory.write`.
 
 | Mode | Wires | What you get |
 |------|-------|--------------|
-| `all` | `SessionStart`, `PostToolUseFailure`, `Stop` | Lessons injected at session start, plus a nudge on a tool failure and a friction-gated one at end of turn |
-| `read-only` | `SessionStart` | Lessons injected; nothing ever nudges |
+| `all` | `SessionStart`, `UserPromptSubmit`, `PostToolUseFailure`, `Stop` | Lessons injected at session start, the ones matching each substantive prompt injected as you go, plus a nudge on a tool failure and a friction-gated one at end of turn |
+| `read-only` | `SessionStart` | Lessons injected ONCE at session start; nothing nudges and nothing runs per turn |
 | `none` | — | Skills + MCP only; memory stays model-invoked |
 
 ```bash
@@ -489,9 +491,9 @@ links now back the hooks' write-confirmation and retrospective nudges.)
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
 It is not run by hand — the plugins wire it into their hook config. It reads
 the host framework's JSON on stdin and prints that host's injection format on
-stdout (lessons at session start; relevant lessons plus a write-nudge on a tool
-failure; a retrospective nudge at end of turn), always exiting 0 so it can never
-block the host agent.
+stdout (lessons at session start; the ones matching each substantive prompt as
+you go; relevant lessons plus a write-nudge on a tool failure; a retrospective
+nudge at end of turn), always exiting 0 so it can never block the host agent.
 
 ```bash
 lorekit hook --adapter <claude|cursor|codex> --event <SessionStart|Stop|…>
@@ -659,7 +661,25 @@ Both files share this schema — all fields optional:
   // ── Hook behaviour ─────────────────────────────────────────────────────────
   "hooks.disabled": ["Stop"],
                            // suppress specific hook events; union across layers
-                           // values: "SessionStart" | "PostToolUseFailure" | "Stop"
+                           // values: "SessionStart" | "UserPromptSubmit" | "PostToolUseFailure" | "Stop"
+
+  "hooks.userPrompt": "on",
+                           // the per-turn relevance pull (UserPromptSubmit):
+                           //   "on"  (default) — on each substantive prompt, query the
+                           //     store for memories matching what you typed and inject
+                           //     at most 3 you have NOT already been shown this session
+                           //   "off"           — keep the rest of hook mode "all", drop
+                           //     just this event's output
+                           // a switch, not a mode: the knobs a mode would expose (how
+                           // many, how strict) are the two things that must not be
+                           // turned up on a hook that fires every single turn.
+                           // two install paths reach it: hook mode "all" ("read-only"
+                           // and "none" never wire the event), and the Claude
+                           // marketplace plugin, whose hooks.json wires it
+                           // unconditionally — no mode involved, so hooks.userPrompt is
+                           // the mode-independent opt-out there. (hooks.disabled:
+                           // ["UserPromptSubmit"] also switches it off, one gate
+                           // earlier, so it is not the only opt-out.) repo wins over user
 
   "hooks.stop": "friction",
                            // gate the end-of-turn retrospective nudge:
@@ -704,13 +724,14 @@ Both files share this schema — all fields optional:
 
   "hooks.instructions": {
     "SessionStart":        "Focus on migration safety. Treat any lesson tagged 'migration' as high-priority.",
+    "UserPromptSubmit":    "Prefer a memory that names the file you are editing.",
     "PostToolUseFailure":  "When recording a failure, always include the exact command and exit code.",
     "Stop":                null
   },
                            // per-event custom text appended to the hook output.
                            // both layers merged: repo instructions first, then user.
                            // null (or absent key) means no extra instruction for that event.
-                           // values: string | null  (keys: "SessionStart" | "PostToolUseFailure" | "Stop")
+                           // values: string | null  (keys: "SessionStart" | "UserPromptSubmit" | "PostToolUseFailure" | "Stop")
 
   // ── Telemetry ──────────────────────────────────────────────────────────────
   "telemetry.disabled": true,

package/package.json

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

package/src/adapters/claude.mjs

@@ -8,6 +8,12 @@ export const claude = {
     switch (event) {
       case 'SessionStart':
         return 'read';
+      // The per-turn relevance pull. Distinct from 'read': that one fires once
+      // and injects a ranked slice of everything applicable; this one fires on
+      // every prompt and injects only what the prompt itself points at, minus
+      // whatever has already been shown.
+      case 'UserPromptSubmit':
+        return 'relevant-read';
       case 'PostToolUse':
         return 'confirm';
       case 'PostToolUseFailure':
@@ -41,6 +47,10 @@ export const claude = {
       toolName: input.tool_name || 'tool',
       toolInput: input.tool_input || null,
       toolResponse: input.tool_response || null,
+      // The user's message, present on UserPromptSubmit. Claude Code sends it
+      // as `prompt`; it is the only field that event carries beyond the
+      // session envelope.
+      prompt: typeof input.prompt === 'string' ? input.prompt : null,
       event: input.hook_event_name || null,
       // Path to the session JSONL (present on Stop/SubagentStop) — read by the
       // friction-gated retrospective to decide whether the session is worth a nudge.

package/src/config.mjs

@@ -87,10 +87,33 @@ export function settingsPath(root, scope = 'project') {
   return path.join(base, '.claude', 'settings.json');
 }
 
-// The lifecycle events the memory loop wires: read lessons on start, nudge on a
+// The lifecycle events the memory loop wires: read lessons on start, pull the
+// ones matching each substantive prompt as the turn is submitted, nudge on a
 // tool failure, nudge a retrospective at end of turn. Mirrors the plugin's
-// hooks.json so `install` delivers the same deterministic layer.
-export const CLAUDE_HOOK_EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
+// hooks.json so `install` delivers the same deterministic layer — a parity test
+// in `test/frameworks.test.mjs` holds the two lists to that claim.
+export const CLAUDE_HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'PostToolUseFailure', 'Stop'];
+
+// The event set `all` meant BEFORE `UserPromptSubmit` was wired.
+//
+// It exists for one job: `hookModeFromEvents` must still answer 'all' for an
+// install done before that event existed. Without this, every pre-existing
+// installation would read as 'custom' the next time `install` inspected it —
+// and 'custom' is the answer that means "a human hand-wired this, do not touch
+// it", so the upgrade prompt would default to leaving them behind on the old
+// three events forever. Recognising the legacy set is what lets `install`
+// UPGRADE such a wiring instead of preserving it verbatim.
+//
+// It does NOT make a bare `install` re-run an upgrade. A fully-installed scope
+// short-circuits in `install.mjs` before the hook step, so reaching this
+// recognition still needs `--hooks <mode>` or `--force`; the short-circuit
+// summary names that command when an upgrade is available.
+//
+// Add to this list, never edit it: each entry is a historical fact about a
+// version that shipped, not a configuration.
+const LEGACY_ALL_EVENT_SETS = [
+  ['SessionStart', 'PostToolUseFailure', 'Stop'],
+];
 
 // Matches a hook command that fires the lorekit engine, whether wired as a
 // global `lorekit hook …` or `npx -y @lorekit/cli hook …`. Shared by the
@@ -181,13 +204,38 @@ export function hookEventsForMode(mode) {
 // wired only `Stop`) — the caller must not silently rewrite such a setup.
 export function hookModeFromEvents(events) {
   const set = new Set(events || []);
+  const matches = (want) => want.length === set.size && want.every((e) => set.has(e));
   for (const mode of HOOK_MODES) {
-    const want = hookEventsForMode(mode);
-    if (want.length === set.size && want.every((e) => set.has(e))) return mode;
+    if (matches(hookEventsForMode(mode))) return mode;
+  }
+  // An install from before a lifecycle event was added is still 'all' — see
+  // LEGACY_ALL_EVENT_SETS for why reading it as 'custom' would strand it.
+  for (const legacy of LEGACY_ALL_EVENT_SETS) {
+    if (matches(legacy)) return 'all';
   }
   return 'custom';
 }
 
+// Which events an existing wiring is MISSING relative to the mode it reads as.
+//
+// An install predating a lifecycle event still reads as its mode (see
+// LEGACY_ALL_EVENT_SETS), so `hookModeFromEvents` alone cannot tell a current
+// `all` from a stale one — and a stale one keeps reporting the mode it no
+// longer delivers. This is the difference, and it is the single derivation
+// BOTH surfaces that report it use: `install`'s already-installed summary and
+// `doctor`'s hooks line. A second copy is how the two would come to disagree
+// about what "up to date" means.
+//
+// `custom` yields [] deliberately: it means a human hand-wired this, and
+// `hookEventsForMode` answers the full set for any unrecognised mode, so
+// anything else would advertise an "upgrade" away from a wiring the user chose.
+export function missingHookEvents(events) {
+  const mode = hookModeFromEvents(events);
+  if (mode === 'custom') return [];
+  const wired = new Set(events || []);
+  return hookEventsForMode(mode).filter((e) => !wired.has(e));
+}
+
 // Extract the flat list of hook command strings for one event out of the nested
 // group shape Claude Code uses: { [event]: [ { hooks: [ { type, command } ] } ] }.
 export function hookCommandsForEvent(hooksObj, event) {

package/src/control.mjs

@@ -10,6 +10,7 @@
 //   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.userPrompt — the per-turn relevance pull ("on" default | "off")
 //   hooks.adapter   — explicit adapter override ("claude" | "cursor" | "codex")
 //
 // Two layers of config, two kinds of statement:
@@ -57,6 +58,26 @@ export function normalizeStopMode(v) {
   return null;
 }
 
+// `hooks.userPrompt` — the per-turn relevance pull, on or off.
+//
+// A BOOLEAN, not a mode, and that is a deliberate limit on the surface. The
+// interesting knobs a mode would expose (how many lessons, how strict the
+// match) are the two things this hook must never let a user turn up: it fires
+// on EVERY prompt, so a generous setting is not a preference, it is a way to
+// make the assistant unusable. The gates are fixed in code and reviewed here.
+//
+// Same forgiving vocabulary as `hooks.stop`, so a config that says `false`,
+// `none` or `disabled` means what it looks like.
+export const USER_PROMPT_MODES = ['on', 'off'];
+export function normalizeUserPromptMode(v) {
+  if (typeof v === 'boolean') return v ? 'on' : 'off';
+  if (typeof v !== 'string') return null;
+  const s = v.trim().toLowerCase();
+  if (['off', 'none', 'false', 'disabled', 'never', 'no'].includes(s)) return 'off';
+  if (['on', 'true', 'enabled', 'always', 'yes'].includes(s)) return 'on';
+  return null;
+}
+
 // SessionStart shape: what the injected block LOOKS like once the budget is
 // spent. All three spend the same character budget; they differ in what they do
 // with the lessons that did not fit.
@@ -93,6 +114,18 @@ export const DEFAULT_SESSION_START_MAX_CHARS = 1500;
 export const MIN_SESSION_START_MAX_CHARS = 200;
 export const MAX_SESSION_START_MAX_CHARS = 20000;
 
+// The events `hooks.instructions` can carry text for — every lifecycle event
+// that emits something a project instruction could ride along with. Exported so
+// `doctor` reports the same set the resolver reads: they were separate literals
+// and drifted, which is how `UserPromptSubmit` ended up documented, accepted in
+// config, and silently dropped by both.
+export const HOOK_INSTRUCTION_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PostToolUseFailure',
+  'Stop',
+];
+
 // Clamp a configured budget into the supported range, or null when the value is
 // 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 —
@@ -256,6 +289,21 @@ export function resolveControl({
     normalizeStopMode(userConfig['hooks.stop']) ||
     'friction';
 
+  // `hooks.userPrompt` — repo layer wins over user layer, default `on`.
+  //
+  // Default-on is safe because for an `install` the WIRING is the real switch:
+  // the event is installed by hook mode `all` alone, so a user who chose
+  // `read-only` or `none` never reaches this resolution at all, and someone who
+  // chose `all` opted into per-turn relevance — making them opt in twice would
+  // leave it dark for everyone who never read the config reference. A
+  // marketplace-plugin install has no mode and wires the event unconditionally,
+  // so there this key is the whole opt-out; that is why it stays a real config
+  // key rather than being folded into the hook mode.
+  const hooksUserPrompt =
+    normalizeUserPromptMode(repoConfig['hooks.userPrompt']) ||
+    normalizeUserPromptMode(userConfig['hooks.userPrompt']) ||
+    'on';
+
   // `hooks.sessionStart` — repo layer wins over user layer, default `hybrid`.
   // Chooses the SHAPE of the injected block (see SESSION_START_MODES). An
   // unrecognised value falls through to the next layer and finally to the
@@ -291,7 +339,6 @@ export function resolveControl({
   // Both layers contribute: repo instructions come first, user instructions follow
   // (same direction as `tags.default` — repo supplements, user personalises).
   // null for a given event means "no custom instruction for that event".
-  const HOOK_EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
   const hooksInstructions = {};
   {
     const repoInstr =
@@ -300,7 +347,7 @@ export function resolveControl({
     const userInstr =
       (userConfig['hooks.instructions'] && typeof userConfig['hooks.instructions'] === 'object')
         ? userConfig['hooks.instructions'] : {};
-    for (const ev of HOOK_EVENTS) {
+    for (const ev of HOOK_INSTRUCTION_EVENTS) {
       const parts = [repoInstr[ev], userInstr[ev]]
         .filter((v) => typeof v === 'string' && v.trim().length > 0);
       hooksInstructions[ev] = parts.length > 0 ? parts.join('\n') : null;
@@ -318,6 +365,7 @@ export function resolveControl({
     scopeDefaults,
     hooksDisabled,
     hooksStop,
+    hooksUserPrompt,
     hooksSessionStart,
     hooksSessionStartMaxChars,
     hooksAdapter,

package/src/core/lessons.mjs

@@ -12,7 +12,7 @@ import { deriveScope } from '../scope.mjs';
 // the injected set is chosen by ONE scorer, and a future `memory.relevant` verb
 // must be able to reuse it rather than grow a second ranking with its own idea
 // of what "most useful" means.
-import { resolvePrecedence, rankLessons } from '../lessons-pure.mjs';
+import { resolvePrecedence, rankLessons, diversifyRankedLessons } from '../lessons-pure.mjs';
 // The store's own scope inventory, normalised — the SAME helper `memory.scopes`
 // uses, so the map and the MCP tool cannot disagree about what a scope holds or
 // about what a failed enumeration looks like.
@@ -167,7 +167,16 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   // first-appearance default — they agree today, but the hierarchy is
   // `readOrder`'s to state, not an artefact of how this function happens to
   // build its array.
-  const ranked = rankLessons(winners, { terms: [], now, scopeOrder: scope.readOrder });
+  // ONE options object feeds both the ranking and the diversification below, so
+  // the two can never drift: `diversifyRankedLessons` recomputes each entry's
+  // score to seed the MMR objective, and if its `terms`/`now`/`weights` differed
+  // from what `rankLessons` sorted on, those scores would not line up with the
+  // order — the near-identical `now` clock especially. Sharing the object makes
+  // that agreement structural rather than a thing two call sites have to keep in
+  // step by hand. `k` is diversification-only; `scopeOrder` is ranking-only and
+  // simply ignored by the diversifier's destructuring.
+  const rankOpts = { terms: [], now, scopeOrder: scope.readOrder };
+  const ranked = rankLessons(winners, rankOpts);
 
   // ── the scope map: EXACT counts when the store can enumerate ───────────────
   //
@@ -219,12 +228,29 @@ export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
     ? scopeInventoryFromStore(inventory.scopes, scope.readOrder, derivedCounts)
     : derivedCounts;
 
+  // DIVERSIFY before the ceiling, so the budget is not spent on near-identical
+  // lessons. Ranking answers "which lessons score highest"; on an active repo
+  // the highest cluster is often one task's iteration log — a dozen
+  // `review-outcomes::pr395-it{3,4,5}` rows that score alike AND read alike, so
+  // a plain top-N hands the reader the same lesson several times and evicts the
+  // variety underneath. `diversifyRankedLessons` applies the SAME MMR
+  // (`selectDiverse`, λ=0.7 lexical Jaccard) the hosted `order=rank` path
+  // already uses, which was defined and exported here but never wired into the
+  // session-start read. It seeds with the top-ranked lesson (score is still
+  // 0.7 of the objective) and only spends the remaining 0.3 pushing down a
+  // lesson that repeats one already shown — so the best lesson stays first and
+  // the set stops being a wall of duplicates. `terms: []` matches the
+  // `rankLessons` call above (relevance contributes nothing at session start),
+  // which the scores MUST agree with. The scope map and `applicable` still read
+  // from `ranked` — the map is a pointer to what EXISTS per scope, a question
+  // diversification does not change.
+  //
   // `applicable` is the honest denominator for the header — how many the reader
   // has, as opposed to how many fitted. It is counted BEFORE the ceiling, so
   // "8 of 50" stays true no matter how the render is bounded.
   return {
     scope,
-    lessons: ranked.slice(0, HARD_LESSON_CEILING),
+    lessons: diversifyRankedLessons(ranked, { ...rankOpts, k: HARD_LESSON_CEILING }),
     scopeCounts,
     applicable: ranked.length,
   };
@@ -327,15 +353,29 @@ function lessonHook(value, max = HOOK_LEN) {
 // `hooks.instructions.SessionStart` in the control config. Lets teams inject
 // project-specific guidance (e.g. "focus on migration safety") without touching
 // the hook internals. Visible even when there are no lessons.
+// `onShown` — an optional callback receiving the lessons this call actually
+// RENDERED, which is a subset of `lessons` whenever the budget or the ceiling
+// binds. The selection happens in here and nowhere else, so a caller that needs
+// 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.
 export function formatLessons(lessons, scope, {
   instruction = null,
   mode = 'hybrid',
   maxChars = DEFAULT_SESSION_START_MAX_CHARS,
   scopeCounts = null,
   applicable = null,
+  onShown = null,
 } = {}) {
+  // Never let bookkeeping break the render: this function's contract is to
+  // return a block, and a throwing callback must not cost the reader theirs.
+  const report = (rendered) => {
+    if (typeof onShown !== 'function') return;
+    try { onShown(rendered); } catch { /* best-effort */ }
+  };
   const all = Array.isArray(lessons) ? lessons : [];
   if (all.length === 0) {
+    report([]);
     // No lessons — only emit if there is a custom instruction to show.
     if (!instruction) return null;
     return (
@@ -360,6 +400,7 @@ export function formatLessons(lessons, scope, {
 
   const ceiling = shape === 'map' ? Math.min(MAP_TOP_K, HARD_LESSON_CEILING) : HARD_LESSON_CEILING;
   const { shown } = fitLines(all, budget - reserve, ceiling);
+  report(shown.map((s) => s.lesson));
 
   // `map` always shows the inventory; `hybrid` shows it only when something was
   // actually left out — otherwise the reader is looking at the complete set and
@@ -434,10 +475,29 @@ export function renderScopeMap(scopeCounts) {
 // stays meaningful, and the count is capped (`MAX_TERMS`) so a huge error blob
 // can't blow up the downstream scan.
 export function failureQuery(toolName, toolResponse) {
-  const text = `${toolName ? String(toolName) : ''} ${errorText(toolResponse)}`.slice(0, MAX_SCAN_CHARS);
+  return distilTerms(`${toolName ? String(toolName) : ''} ${errorText(toolResponse)}`);
+}
+
+// The tokenizer both query builders share. Lowercased `[a-z0-9]+` runs of at
+// least `MIN_TERM_LEN` characters, stopword-filtered, de-duplicated, capped at
+// `MAX_TERMS`, over at most `MAX_SCAN_CHARS` of input. The floor is INCLUSIVE:
+// the filter is `raw.length < MIN_TERM_LEN`, so a term exactly `MIN_TERM_LEN`
+// characters long is kept.
+//
+// The bound is applied to the TEXT before splitting, not to the token array
+// after: a multi-megabyte stderr blob (or a pasted file) would otherwise
+// materialise a giant token array on the way to being capped — a CPU and memory
+// spike for a result that was always going to be twelve words.
+//
+// Producing `[a-z0-9]+` runs is also what keeps the terms safe to hand to the
+// remote store, whose `search` joins them into ONE `websearch` FTS query: no
+// FTS metacharacter can survive this filter, so no caller has to escape one.
+// Pure and total.
+export function distilTerms(text) {
+  const scanned = String(text ?? '').slice(0, MAX_SCAN_CHARS).toLowerCase();
   const seen = new Set();
   const terms = [];
-  for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+  for (const raw of scanned.split(/[^a-z0-9]+/)) {
     if (raw.length < MIN_TERM_LEN || STOPWORDS.has(raw) || seen.has(raw)) continue;
     seen.add(raw);
     terms.push(raw);
@@ -484,12 +544,19 @@ export function dedupeRelevant(entries, cap = MAX_RELEVANT) {
 // capped by the pure `dedupeRelevant`, keeping the store's own ordering (see its
 // docblock). Best-effort: an unusable/throwing store returns [] so the
 // caller falls back to the write-nudge alone.
-export async function relevantLessonsFromStore(store, scope, terms, { cap = MAX_RELEVANT } = {}) {
+export async function relevantLessonsFromStore(store, scope, terms, { cap = MAX_RELEVANT, timeoutMs, walkLimit } = {}) {
   if (!store || typeof store.search !== 'function') return [];
   if (!scope || !Array.isArray(scope.readOrder) || scope.readOrder.length === 0) return [];
   if (!Array.isArray(terms) || terms.length === 0) return [];
   try {
-    const res = await store.search({ q: terms, scopes: scope.readOrder });
+    // `timeoutMs` bounds the REMOTE route (a network fetch); `walkLimit` bounds
+    // the OFFLINE one (a synchronous file walk `timeoutMs` cannot interrupt).
+    // They are deliberately separate names: `RemoteStore.search` reads `limit`
+    // (→ `body.limit`), so a shared name would truncate the remote hit set
+    // BEFORE `rankLessons` runs — exactly what a hot-path caller must avoid.
+    // `walkLimit` is honoured only by the local stores; the remote ignores it
+    // and stays bounded by `timeoutMs` alone, as it was before this budget.
+    const res = await store.search({ q: terms, scopes: scope.readOrder, timeoutMs, walkLimit });
     if (!res || !res.ok || !Array.isArray(res.entries)) return [];
     return dedupeRelevant(res.entries, cap);
   } catch {
@@ -673,3 +740,165 @@ const STOPWORDS = new Set([
   'response',
   'status',
 ]);
+
+// ── the per-prompt relevance pull (UserPromptSubmit) ─────────────────────────
+//
+// SessionStart injects once, at the top of a session, before the user has said
+// what they are doing. That set is necessarily a guess: it is ranked on recency
+// and recurrence because there is nothing else to rank on yet. The moment the
+// user types "the migration keeps deadlocking", there IS something to rank on —
+// and until this hook, nothing used it. The only mid-session trigger was a tool
+// FAILURE, which means the loop could only ever tell you about a mistake after
+// you had already made it.
+//
+// The whole design problem is that this fires on EVERY turn, so the cost of
+// being wrong is paid over and over. Three gates keep it quiet, and each one
+// exists because the failure mode without it is worse than showing nothing:
+//
+//   LENGTH    — "yes", "continue", "go on" carry no terms worth querying, and a
+//               store lookup per keystroke-sized prompt is pure overhead.
+//   RELEVANCE — no match means silence. An "in case it helps" lesson attached
+//               to an unrelated prompt trains the reader to skim past the
+//               block, which costs the SessionStart injection its credibility
+//               too.
+//   DELTA     — a lesson already shown this session is not news. Re-injecting
+//               it is the specific way a per-turn hook becomes wallpaper.
+
+// Shortest prompt worth a store lookup. Tuned to skip the acknowledgements that
+// dominate a real session ("yes", "ok", "continue", "do it", "next") while
+// keeping anything that states an intent. Deliberately generous: the relevance
+// gate is the real filter, and this one only exists to avoid paying for a query
+// whose terms would be discarded anyway.
+const MIN_PROMPT_CHARS = 24;
+
+// Cap on lessons injected per prompt. Smaller than the SessionStart budget by an
+// order of magnitude, because this competes with the user's own turn: three
+// index lines is a glance, and anything more is an interruption.
+const MAX_PROMPT_LESSONS = 3;
+
+// Fetch budget for the per-prompt pull, deliberately far below `restFetch`'s
+// 10s default. This is the ONE lookup that sits on the user's critical path —
+// it runs before their turn is handed to the assistant — so a slow or wedged
+// store must cost them a fraction of a second, not ten. Timing out is not a
+// failure mode here: the abort surfaces as no hits, and no hits is already this
+// hook's most common and entirely valid answer. Same reasoning as
+// `telemetry.mjs`'s 1500 ms export budget; a touch more generous because a
+// missed lesson is worth slightly more than a missed metric.
+export const PROMPT_FETCH_TIMEOUT_MS = 2000;
+
+// The offline-store counterpart to the fetch budget above. `timeoutMs` bounds
+// the remote route, but the local store walks every scope's files synchronously
+// on every prompt — an unbounded walk a wall-clock budget cannot interrupt. The
+// per-prompt pull forwards this as `walkLimit` (NOT `limit`, which the remote
+// store maps to `body.limit` and would truncate its hit set pre-ranking), so it
+// bounds only the offline walk: the block ranks then keeps MAX_PROMPT_LESSONS,
+// so a few hundred nearest-scope hits is far more than the ranker needs to
+// surface the best three. Only the hot-path caller passes it; the failure hook
+// stays unbounded, as it was.
+export const PROMPT_LOCAL_SEARCH_LIMIT = 200;
+
+/**
+ * Is this prompt worth a relevance lookup?
+ *
+ * Length is measured AFTER trimming, on the raw prompt. A long prompt made
+ * entirely of stopwords still passes here and is caught by the term gate below
+ * — two cheap checks in series rather than one clever one.
+ */
+export function isSubstantivePrompt(prompt, min = MIN_PROMPT_CHARS) {
+  return String(prompt ?? '').trim().length >= min;
+}
+
+/**
+ * Distil search terms from a user prompt.
+ *
+ * The same tokenizer the failure lookup uses, for the same reason: whatever
+ * reaches the store must be `[a-z0-9]+` runs, and the two callers must agree on
+ * what counts as a term or "why did the failure hook find this and my prompt
+ * not?" becomes unanswerable.
+ *
+ * Returns `[]` for a prompt that is too short or carries nothing but stopwords,
+ * which the caller reads as "stay silent".
+ */
+export function promptQuery(prompt) {
+  if (!isSubstantivePrompt(prompt)) return [];
+  return distilTerms(prompt);
+}
+
+/**
+ * Render the per-turn block, or null when there is nothing to say.
+ *
+ * INDEX ONLY, and shorter than the failure block's lines. This arrives while
+ * the user is mid-thought, so it has to be scannable in a glance and cost as
+ * little context as possible; the body is always one `memory.read` away. The
+ * framing is "you have notes on this", never an instruction — the same
+ * considerations-not-rules posture as every other injection.
+ */
+export function formatPromptLessons(lessons, { instruction = null } = {}) {
+  if (!lessons || lessons.length === 0) return null;
+  const noun = lessons.length === 1 ? 'memory' : 'memories';
+  const header =
+    `LoreKit: ${lessons.length} ${noun} related to this — `
+    + `considerations, not rules; read in full with memory.read:`;
+  const body = lessons.map((l) => `- (${l.scope}) ${l.key} — ${lessonHook(l.value)}`).join('\n');
+  // `hooks.instructions.UserPromptSubmit`, appended the same way the other
+  // events append theirs. It rides an EXISTING block and never creates one:
+  // this hook fires on every turn, so an instruction that could emit on its own
+  // would be a line on every prompt — the noise the relevance gate exists to
+  // prevent.
+  const extra = typeof instruction === 'string' && instruction.trim()
+    ? `\n\nProject instruction: ${instruction}` : '';
+  return `${header}\n${body}${extra}`;
+}
+
+/**
+ * The per-prompt pull: query the store for this prompt's terms, rank, drop
+ * anything already shown, cap.
+ *
+ * QUERYING rather than filtering the injected set is the same call the failure
+ * hook makes, and for the same reason: a post-filter can only ever resurface a
+ * lesson that was already on screen, so a paraphrased match or one that lost
+ * the SessionStart ranking would be permanently unreachable — which is exactly
+ * the lore this hook exists to surface.
+ *
+ * RANKING runs after the store returns, because the store's own ordering is not
+ * relevance: the remote route answers `updated_at desc` and the local two-tier
+ * store answers project-tier-first. `rankLessons` with the prompt's terms
+ * applies the same scorer the SessionStart block uses, so a recurring lesson
+ * beats a fresher one-off here too.
+ *
+ * `alreadyShown` is a Set of `scope::key`. Filtering AFTER ranking rather than
+ * before is deliberate: it keeps the cap meaningful. Filtering first would let
+ * three weak lessons take the slots a strong-but-already-shown one vacated,
+ * which is worse than showing two.
+ *
+ * Best-effort and total — any failure yields `[]`, and the hook stays silent.
+ * That includes the fetch budget: the lookup runs under
+ * `PROMPT_FETCH_TIMEOUT_MS` rather than `restFetch`'s 10s default, and an abort
+ * arrives here as no hits, the same as a store that simply had nothing.
+ */
+export async function promptLessonsFromStore(store, scope, terms, {
+  alreadyShown = new Set(),
+  cap = MAX_PROMPT_LESSONS,
+  now = Date.now(),
+  timeoutMs = PROMPT_FETCH_TIMEOUT_MS,
+} = {}) {
+  if (!Array.isArray(terms) || terms.length === 0) return [];
+  const hits = await relevantLessonsFromStore(store, scope, terms, {
+    cap: Number.MAX_SAFE_INTEGER,
+    timeoutMs,
+    walkLimit: PROMPT_LOCAL_SEARCH_LIMIT,
+  });
+  if (hits.length === 0) return [];
+  const ranked = rankLessons(hits, {
+    terms,
+    now,
+    scopeOrder: Array.isArray(scope?.readOrder) ? scope.readOrder : null,
+  });
+  const fresh = ranked.filter((e) => !alreadyShown.has(lessonId(e)));
+  return dedupeRelevant(fresh, cap);
+}
+
+/** The identity a shown-set is keyed on. One spelling, used by both sides. */
+export function lessonId(entry) {
+  return `${entry?.scope ?? ''}::${entry?.key ?? ''}`;
+}

package/src/core/state.mjs

@@ -41,3 +41,115 @@ export function sessionMarkerExists(sessionId, tag) {
     return false;
   }
 }
+
+// ── the per-session shown-set ────────────────────────────────────────────────
+//
+// The one-shot markers above answer "has this hook fired yet". The per-prompt
+// relevance hook needs a finer question: "has the reader already been shown
+// THIS lesson this session". Without it the hook re-injects its own best match
+// on every turn of a conversation that stays on one topic — which is the exact
+// shape that turns an injection into wallpaper the reader learns to skip.
+//
+// Deliberately the same directory and the same session key as the markers, so a
+// session's hook state is one thing that appears and disappears together.
+//
+// STORED AS LINES, APPENDED on the hot path. An append is atomic enough for
+// this: two hooks racing can interleave whole lines but cannot corrupt one, and
+// a duplicate line is harmless because the reader is a Set. A read-modify-write
+// on every write would be the version that loses entries under a race — which
+// is why the common write stays a bare append. Left there the file would grow
+// without bound in a long session, so it is instead bounded by an occasional
+// atomic-rename compaction (see COMPACT_AT_BYTES below), never a per-write
+// rewrite.
+
+// Cap on how many ids are READ back per session — the newest N. Reading only
+// the newest N is enough for what this guards: the value of an id decays, and
+// re-showing a lesson from 600 injections ago is not the repetition the
+// shown-set exists to prevent.
+const MAX_SHOWN_IDS = 500;
+
+// Bound the file ON DISK, not just the read. The append-only writer keeps the
+// hot path race-safe, but on its own a long session would grow the file without
+// limit. Once the file passes this size the writer rewrites it down to the
+// newest MAX_SHOWN_IDS ids via a temp-file + atomic rename (see
+// `compactIfLarge`). The threshold sits well above what `shownLessons` ever
+// reads, so compaction is rare — amortized O(1) per append — and never drops an
+// id still inside the read window. It is session-scoped scratch in a
+// temp/plugin-data directory the host clears with the rest of the session's
+// hook state; compaction just keeps it bounded within one long-lived session.
+// Exported so the test asserts the bound against THIS value rather than a
+// restated literal that would silently stop proving it if the threshold moved.
+export const COMPACT_AT_BYTES = 256 * 1024;
+
+function shownPath(sessionId) {
+  return `${markerPath(sessionId, 'shown')}.ids`;
+}
+
+// Rewrite the append-only file down to its newest MAX_SHOWN_IDS ids once it has
+// grown past COMPACT_AT_BYTES, via a temp-file + atomic rename. rename(2) is
+// atomic on POSIX and the temp file lives in the same directory (so the same
+// filesystem), so a concurrent reader always sees a complete old-or-new file,
+// never a torn one. A racing append lost to the rename is the same "at worst a
+// repeat" trade the bare append already makes, and it can only happen on the
+// rare compaction — not the hot path. Best-effort: any failure leaves the file
+// as-is and never breaks the host.
+function compactIfLarge(file) {
+  try {
+    if (fs.statSync(file).size <= COMPACT_AT_BYTES) return;
+    const kept = fs
+      .readFileSync(file, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .slice(-MAX_SHOWN_IDS);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, kept.length ? `${kept.join('\n')}\n` : '');
+    fs.renameSync(tmp, file);
+  } catch {
+    // Compaction is best-effort; a failure just leaves the file large.
+  }
+}
+
+/**
+ * The set of `scope::key` ids already injected this session.
+ *
+ * Missing session id, missing file, or an unreadable one all yield an EMPTY
+ * set, which fails toward showing a lesson again rather than toward silence. A
+ * repeated lesson is a small annoyance; a lesson silently withheld because a
+ * state file could not be read is the failure nobody would ever diagnose.
+ */
+export function shownLessons(sessionId) {
+  if (!sessionId) return new Set();
+  try {
+    const lines = fs.readFileSync(shownPath(sessionId), 'utf8').split('\n');
+    const kept = lines.filter(Boolean).slice(-MAX_SHOWN_IDS);
+    return new Set(kept);
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Record ids as shown. Best-effort: a failed write means at worst a repeat.
+ *
+ * Called by BOTH injection paths — SessionStart records what it injected, and
+ * the per-prompt hook records what it added — because "already shown" has to
+ * mean shown by anything, not shown by this hook. A per-prompt hook that only
+ * remembered its own output would re-surface the SessionStart set one lesson at
+ * a time.
+ */
+export function recordShownLessons(sessionId, ids) {
+  if (!sessionId || !Array.isArray(ids) || ids.length === 0) return;
+  const clean = ids.filter((id) => typeof id === 'string' && id && !id.includes('\n'));
+  if (clean.length === 0) return;
+  try {
+    // No mkdir here: `shownPath` → `markerPath` → `stateDir`, which creates the
+    // directory as part of resolving the path.
+    const file = shownPath(sessionId);
+    fs.appendFileSync(file, `${clean.join('\n')}\n`);
+    // The append above is the race-safe hot path; this bounds the file on disk,
+    // rewriting down to the newest ids only once it has grown large.
+    compactIfLarge(file);
+  } catch {
+    // Never break the host over bookkeeping.
+  }
+}

package/src/doctor.mjs

@@ -11,6 +11,7 @@ import {
   CLAUDE_HOOK_EVENTS,
   installedHookEvents,
   hookModeFromEvents,
+  missingHookEvents,
   readLorekitServer,
   readMcpConfig,
   tokenKind,
@@ -23,7 +24,7 @@ import {
   probeTelemetryExport,
 } from './telemetry.mjs';
 import { deriveScope } from './scope.mjs';
-import { loadControl } from './control.mjs';
+import { loadControl, HOOK_INSTRUCTION_EVENTS } from './control.mjs';
 import { createStore } from './store/index.mjs';
 import { log, heading, status, c } from './util.mjs';
 
@@ -101,7 +102,22 @@ export async function doctor(args) {
       );
     } else {
       for (const { scope, events } of perScope) {
-        record('pass', `hooks ${scope}`, `${hookModeFromEvents(events)} — ${events.join(', ')}`);
+        // An install predating a lifecycle event still READS as its mode, so
+        // reporting the mode alone tells a legacy wiring it is current — the
+        // one state where this line is actively misleading. Stay a `pass` (the
+        // wiring works, it is just not the full set any more) and name the
+        // upgrade the same way `install`'s already-installed summary does, via
+        // the same `missingHookEvents` derivation.
+        const mode = hookModeFromEvents(events);
+        const missing = missingHookEvents(events);
+        // Name the SCOPE in the command. `install` prompts for project vs
+        // global when neither flag is given, so a bare command offered against
+        // a `hooks global` gap can just as easily rewire the project and leave
+        // the gap exactly where it was.
+        const upgrade = missing.length > 0
+          ? ` — missing ${missing.join(', ')}; run \`lorekit install --${scope} --hooks ${mode}\` to wire ${missing.length === 1 ? 'it' : 'them'}`
+          : '';
+        record('pass', `hooks ${scope}`, `${mode} — ${events.join(', ')}${upgrade}`);
       }
     }
   }
@@ -157,10 +173,9 @@ export async function doctor(args) {
   // 6. Hook instructions — show resolved per-event custom instructions when any are set.
   {
     const instr = control.hooksInstructions || {};
-    const EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
-    const configured = EVENTS.filter((ev) => instr[ev]);
+    const configured = HOOK_INSTRUCTION_EVENTS.filter((ev) => instr[ev]);
     if (configured.length > 0) {
-      for (const ev of EVENTS) {
+      for (const ev of HOOK_INSTRUCTION_EVENTS) {
         const text = instr[ev];
         if (text) {
           record('info', `hooks.instructions.${ev}`, c.dim(text.length > 80 ? text.slice(0, 77) + '…' : text));

package/src/hook.mjs

@@ -13,13 +13,22 @@ import {
   retrospectiveNudge,
   failureNudge,
   failureQuery,
+  promptQuery,
+  promptLessonsFromStore,
+  formatPromptLessons,
+  lessonId,
   relevantLessonsFromStore,
   formatRelevantLessons,
   writeConfirmation,
 } from './core/lessons.mjs';
 import { isFailure } from './core/failure.mjs';
 import { readSessionFriction, shouldRetrospect, FRICTION_FAILURE } from './core/friction.mjs';
-import { firstTimeThisSession, sessionMarkerExists } from './core/state.mjs';
+import {
+  firstTimeThisSession,
+  sessionMarkerExists,
+  shownLessons,
+  recordShownLessons,
+} from './core/state.mjs';
 import { recordFixture } from './core/record.mjs';
 import { claude } from './adapters/claude.mjs';
 import { cursor } from './adapters/cursor.mjs';
@@ -113,10 +122,64 @@ async function run(args) {
       maxChars: control.hooksSessionStartMaxChars,
       scopeCounts,
       applicable,
+      // Record what this injection RENDERED, so the per-prompt hook treats it as
+      // already seen. It must be the rendered subset, not the fetched set: the
+      // budget and the hard ceiling routinely drop lessons, and marking those
+      // shown would let the delta gate suppress — for the whole session —
+      // exactly the lessons the reader never saw. Bookkeeping only:
+      // `recordShownLessons` never throws, and a failure costs at most one
+      // repeated lesson later in the session.
+      onShown: (rendered) => recordShownLessons(parsed.sessionId, rendered.map(lessonId)),
     }));
     return 0;
   }
 
+  if (intent === 'relevant-read') {
+    // The per-turn relevance pull. Fires on EVERY prompt, so every branch below
+    // is a reason to stay silent — the hook's default answer is nothing.
+    //
+    // Config gate, and the ONLY off switch some users have. Via `install` the
+    // event is wired by hook mode `all` alone, so reaching here means the user
+    // opted into the full lifecycle and `hooks.userPrompt` lets them keep it
+    // while switching off just this one. Via the Claude marketplace plugin
+    // there is no mode at all — `plugins/lorekit-claude/hooks/hooks.json` wires
+    // the event unconditionally — so for a plugin install this setting is the
+    // whole opt-out.
+    if ((control.hooksUserPrompt || 'on') === 'off') return 0;
+
+    // Length gate. "yes" / "continue" / "do it" carry nothing worth querying,
+    // and a store lookup per acknowledgement is pure overhead on the user's
+    // critical path.
+    const terms = promptQuery(parsed.prompt);
+    if (terms.length === 0) return 0;
+
+    try {
+      const store = createStore(control);
+      if (!store) return 0;
+      const lessons = await promptLessonsFromStore(store, scope, terms, {
+        // Delta only. Includes the SessionStart set, because "already shown"
+        // has to mean shown by anything — a hook that only remembered its own
+        // output would resurface the session's opening injection one lesson at
+        // a time.
+        alreadyShown: shownLessons(parsed.sessionId),
+      });
+      // Relevance gate: nothing matched, or everything that matched was already
+      // on screen. Either way there is no news, and an "in case it helps" block
+      // attached to an unrelated prompt is how a reader learns to skip the
+      // block entirely — which would cost the SessionStart injection its
+      // credibility too.
+      if (lessons.length === 0) return 0;
+      recordShownLessons(parsed.sessionId, lessons.map(lessonId));
+      emit(formatPromptLessons(lessons, {
+        instruction: (control.hooksInstructions && control.hooksInstructions.UserPromptSubmit) || null,
+      }));
+    } catch {
+      // Best-effort, like every other branch: the user's turn proceeds either
+      // way, and a store hiccup must never cost them their prompt.
+    }
+    return 0;
+  }
+
   if (intent === 'confirm') {
     // Fire only when a lorekit memory write actually succeeded — the adapter's
     // isLoreWrite() inspects the tool name and the response shape. Any error

package/src/install.mjs

@@ -17,6 +17,7 @@ import {
   HOOK_MODES,
   hookEventsForMode,
   hookModeFromEvents,
+  missingHookEvents,
   installedHookEvents,
   resolveConnection,
   tokenKind,
@@ -120,7 +121,7 @@ export const HOOK_PROMPT_OPTIONS = [
   {
     label: 'Yes, all of them',
     value: 'all',
-    hint: 'inject lessons at session start; nudge on a tool failure and at end of turn',
+    hint: 'inject lessons at session start and as each prompt matches them; nudge on a tool failure and at end of turn',
   },
   {
     label: 'Read-only',
@@ -275,6 +276,22 @@ export async function install(args) {
         : `  ${c.dim('Hooks: none wired — the skills work, but only when the model invokes them')}`,
     );
 
+    // An install predating a lifecycle event still reads as its mode (see
+    // LEGACY_ALL_EVENT_SETS in config.mjs), but this branch returns before the
+    // hook step — so the upgrade is available and will not happen on its own.
+    // Say so here rather than leaving the user to infer it: silently keeping a
+    // stale event set is how a wired install stops firing the hooks it says it
+    // has. Only ever a HINT — rewiring stays an explicit `--hooks` / `--force`.
+    const wiredMode = hookModeFromEvents(wiredEvents);
+    // `missingHookEvents` owns the derivation (incl. why `custom` is excluded)
+    // so `doctor`'s hooks line reports the same upgrade this summary does.
+    const missingEvents = missingHookEvents(wiredEvents);
+    if (missingEvents.length > 0) {
+      log(
+        `  ${c.yellow(`Hook upgrade available: ${missingEvents.join(', ')} — run lorekit install --${scope} --hooks ${wiredMode} to wire ${missingEvents.length === 1 ? 'it' : 'them'}.`)}`,
+      );
+    }
+
     log('');
     log(`  Run ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);
     log(`  Change the hooks with ${c.cyan(`--hooks ${HOOK_MODES.join('|')}`)}.`);

package/src/lessons-pure.mjs

@@ -487,6 +487,134 @@ function seenCountFrom(entry) {
   return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : 0;
 }
 
+/**
+ * MMR λ (lambda) — weight given to relevance vs diversity in the MMR objective.
+ * At 0.7 the selector favours relevance, with 0.3 of the budget for diversity.
+ * Anchored to Carbonell & Goldstein (1998), the original MMR paper.
+ * Mirrored byte-identically in the edge twin and `packages/mcp-core/src/lesson-rank.ts`.
+ */
+export const MMR_LAMBDA = 0.7;
+
+/**
+ * Tokenise a lesson `value` into a deduplicated Set: case-fold, split on
+ * non-alphanumeric characters, drop empties. Dependency-free and deterministic
+ * so it mirrors the TS/Deno twin's `tokenizeValue`.
+ *
+ * PERF: `selectDiverse` calls this ONCE per candidate before the MMR loop and
+ * caches the result. `jaccardSimilarity` takes the cached Sets, so the O(k²)
+ * pairwise comparisons inside the loop cost no tokenisation. Do NOT re-introduce
+ * a `tokenize(value)` call inside the loop: that regresses the hot path to
+ * O(n·k²) tokenisations (measured 34s CPU at n=200/k=100 with 1.5KB values).
+ */
+function tokenizeValue(v) {
+  const tokens = String(v ?? '').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  return new Set(tokens);
+}
+
+/**
+ * Word/token Jaccard similarity between two PRE-TOKENISED value Sets:
+ * |A∩B| / |A∪B|. Both-empty → 0.
+ *
+ * Takes Sets rather than raw values on purpose — the caller tokenises each
+ * candidate once (see `tokenizeValue`) so this stays allocation-free on the
+ * O(k²) hot path.
+ */
+function jaccardSimilarity(setA, setB) {
+  if (setA.size === 0 && setB.size === 0) return 0;
+  let intersection = 0;
+  for (const t of setA) if (setB.has(t)) intersection += 1;
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+/**
+ * Select the top-K lessons from a ranked list using Maximal Marginal Relevance
+ * (Carbonell & Goldstein, 1998).
+ *
+ * Accepts bare entries (the shape `rankLessons` returns in the `.mjs` twin)
+ * plus a parallel `scores` array — REQUIRED, one score per entry. This is the
+ * MMR relevance term; there is no meaningful default. A missing `scores`, a
+ * non-array, or a length that does not match `entries` throws rather than
+ * silently defaulting to 0 for every entry (which would degrade selection to
+ * pure diversity and quietly discard the ranking). The TS twin cannot hit this
+ * footgun — it reads the score off each `{ entry, score }` input.
+ *
+ * Greedy MMR: seed with index 0 (highest-ranked), then at each step pick
+ * the unselected candidate that maximises
+ *   λ·quantise(score(i)) − (1−λ)·max_{j∈selected} jaccardSimilarity(value_i, value_j)
+ * Ties break by input order (first-wins) for determinism.
+ *
+ * SCORE QUANTISATION: the relevance term uses the score SNAPPED onto the
+ * `SCORE_EPSILON` grid — the exact grid `rankLessons` buckets on for its
+ * scope-precedence tie-break. Two scores within `SCORE_EPSILON` land in the same
+ * bucket, so the MMR objective sees them as equal and the input order (which
+ * `rankLessons` already sorted by scope precedence, then key) decides. Comparing
+ * the RAW score would let a 1e-10 float difference override scope precedence.
+ *
+ * PERF — the algorithm is O(n·k), and BOTH factors that could regress it to
+ * O(n·k²) are held down explicitly:
+ *   1. TOKENISE axis: each candidate's `value` is tokenised ONCE up front (the
+ *      `tokens` field) so the pairwise Jaccard comparisons never tokenise —
+ *      O(n) tokenisations total. See `tokenizeValue`.
+ *   2. INTERSECTION axis: each remaining candidate carries a RUNNING `maxSim`
+ *      (its greatest Jaccard similarity to anything selected so far). The
+ *      objective reads that cached scalar — it does NOT loop over `selected`.
+ *      After each pick we update `maxSim` for the still-remaining candidates
+ *      against the ONE just-selected entry only. That is k picks × n candidates
+ *      = O(n·k) Jaccard intersections total, not O(n·k²).
+ * Re-introducing either an in-loop `tokenizeValue` call OR an inner
+ * `for (… of selected)` maxSim recomputation silently restores O(n·k²) —
+ * measured 2.6s CPU at n=200/k=100 vs 58ms for the running form. Don't.
+ *
+ * Always-on for ranked mode — no optional param needed. The recency wire path is
+ * never affected.
+ */
+export function selectDiverse(entries, k, { lambda: lambdaOpt, scores } = {}) {
+  // Match the TS twin: fall back to MMR_LAMBDA unless `lambda` is a FINITE
+  // number. A bare destructuring default only catches `undefined`, so
+  // `{ lambda: NaN }` would otherwise poison every MMR objective here while the
+  // TS twin quietly used MMR_LAMBDA — a silent cross-twin divergence.
+  const lambda = typeof lambdaOpt === 'number' && Number.isFinite(lambdaOpt) ? lambdaOpt : MMR_LAMBDA;
+  if (!Array.isArray(entries) || entries.length === 0 || k <= 0) return [];
+  if (!Array.isArray(scores) || scores.length !== entries.length) {
+    throw new TypeError(
+      `selectDiverse: \`scores\` must be an array with one score per entry `
+        + `(got ${Array.isArray(scores) ? `length ${scores.length}` : typeof scores} `
+        + `for ${entries.length} entries)`,
+    );
+  }
+  const selected = [];
+  // Pre-tokenise every candidate ONCE and snap its score onto the SCORE_EPSILON
+  // grid up front. `maxSim` is the running greatest Jaccard similarity to any
+  // already-selected entry — 0 while nothing is selected. The loop below reads
+  // these caches; it never tokenises, re-quantises, or rescans `selected`.
+  const remaining = entries.map((e, i) => ({
+    entry: e,
+    tokens: tokenizeValue(e?.value),
+    qScore: Math.round((scores[i] ?? 0) / SCORE_EPSILON) * SCORE_EPSILON,
+    maxSim: 0,
+  }));
+  while (selected.length < k && remaining.length > 0) {
+    let bestIdx = 0;
+    let bestMmr = -Infinity;
+    for (let i = 0; i < remaining.length; i++) {
+      const candidate = remaining[i];
+      // Reads the cached running maxSim — no inner scan over `selected`.
+      const mmr = lambda * candidate.qScore - (1 - lambda) * candidate.maxSim;
+      if (mmr > bestMmr) { bestMmr = mmr; bestIdx = i; }
+    }
+    const [justSelected] = remaining.splice(bestIdx, 1);
+    selected.push(justSelected.entry);
+    // Fold the just-selected entry into every remaining candidate's running
+    // maxSim — one Jaccard per remaining candidate per pick, so O(n·k) total.
+    for (const candidate of remaining) {
+      const sim = jaccardSimilarity(candidate.tokens, justSelected.tokens);
+      if (sim > candidate.maxSim) candidate.maxSim = sim;
+    }
+  }
+  return selected;
+}
+
 /**
  * Rank lessons best-first, returning a NEW array — the input is never reordered
  * in place, because callers hold it (`fetchLessons` builds it from the
@@ -578,3 +706,42 @@ export function rankLessons(entries = [], {
   return scored.map((s) => s.entry);
 }
 
+/**
+ * Rank-then-diversify in one call — the `.mjs` twin's convenience for what the
+ * TS twin gets for free by carrying `{ entry, score }` pairs into `selectDiverse`.
+ *
+ * `selectDiverse` needs a parallel `scores` array, and those scores MUST be the
+ * same set-relative values the list was sorted on: the salience factor is
+ * normalised against the max `seen_count` in the candidate SET, so a score
+ * recomputed over a different population would not line up with the order. This
+ * helper recomputes the scores over exactly the list it diversifies, beside the
+ * unexported `seenCountFrom`/`scoreWithTerms`, so callers can apply MMR without
+ * reconstructing that alignment (and without `seenCountFrom` leaking out).
+ *
+ * `entries` is expected to be `rankLessons` output (best-first) so the seed of
+ * the greedy MMR is the top-ranked lesson; the pass-through
+ * `terms`/`weights`/`halfLifeDays`/`now` MUST match the `rankLessons` call that
+ * produced it, or the recomputed scores diverge from the sort. `k` caps the
+ * returned count (default: all). Empty/degenerate input returns `[]`.
+ */
+export function diversifyRankedLessons(entries = [], {
+  terms = [],
+  now = Date.now(),
+  weights = DEFAULT_RANK_WEIGHTS,
+  halfLifeDays = RECENCY_HALF_LIFE_DAYS,
+  k = Infinity,
+  lambda,
+} = {}) {
+  const list = Array.isArray(entries) ? entries.filter((e) => e && typeof e === 'object') : [];
+  if (list.length === 0) return [];
+  const termSet = distinctTerms(terms);
+  let maxSeenCount = 0;
+  for (const e of list) maxSeenCount = Math.max(maxSeenCount, seenCountFrom(e));
+  const scores = list.map((e) => scoreWithTerms(e, termSet, { now, weights, maxSeenCount, halfLifeDays }));
+  // `numberOr` is the module's coercion convention: a non-finite `k` (the
+  // `Infinity` default, `null`, or a stringy `'40'`) resolves to a real cap —
+  // the default falls through to the whole list, `'40'` becomes 40 — rather than
+  // silently returning everything on a shape a caller plausibly passes.
+  const limit = numberOr(k, list.length);
+  return selectDiverse(list, limit, { scores, lambda });
+}

package/src/store/local.mjs

@@ -235,17 +235,32 @@ class LocalStore {
   // this walks each scope EXACTLY ONCE — the failure hook passes all its terms
   // in one call rather than one call per term, so N terms no longer re-read the
   // store N times. An empty query (or empty list) returns everything, unchanged.
-  async search({ q, scopes, tags } = {}) {
+  // `walkLimit` bounds the walk for hot-path callers (the per-prompt hook): a
+  // local search re-reads every scope's files synchronously, which the remote
+  // `timeoutMs` cannot bound, so an unbounded store would stall the prompt.
+  // Once `walkLimit` matches are collected the walk stops — later scopes in
+  // `scopes` are skipped entirely. Scopes are visited most-specific-first, so
+  // the retained matches are the nearest-scope ones, consistent with this
+  // store's precedence. Omitted → unbounded, exactly as before. Named
+  // `walkLimit`, NOT `limit`, so it is local-only: `RemoteStore.search` reads
+  // `limit` (→ `body.limit`) and a shared name would truncate the remote hit
+  // set pre-ranking, which the per-prompt caller must not do.
+  async search({ q, scopes, tags, walkLimit } = {}) {
     const needles = (Array.isArray(q) ? q : [q])
       .map((n) => String(n || '').toLowerCase())
       .filter(Boolean);
     const matchAll = needles.length === 0;
+    const cap = Number.isInteger(walkLimit) && walkLimit > 0 ? walkLimit : Infinity;
     const out = [];
     for (const scope of scopes || []) {
+      if (out.length >= cap) break;
       const { entries } = await this.list({ scope, tags });
       for (const e of entries) {
         const hay = `${e.key}\n${(e.tags || []).join(' ')}\n${e.value || ''}`.toLowerCase();
-        if (matchAll || needles.some((n) => hay.includes(n))) out.push(e);
+        if (matchAll || needles.some((n) => hay.includes(n))) {
+          out.push(e);
+          if (out.length >= cap) break;
+        }
       }
     }
     return { ok: true, entries: out };
@@ -412,13 +427,34 @@ class TwoTierStore {
     return this.home.restore({ scope, key });
   }
 
-  async search({ q, scopes, tags } = {}) {
-    const homeRes = await this.home.search({ q, scopes, tags });
+  async search({ q, scopes, tags, walkLimit } = {}) {
+    const id = (e) => `${e.scope}\x00${e.key}`;
+    const homeRes = await this.home.search({ q, scopes, tags, walkLimit });
     const projRes = this.projectActive()
-      ? await this.project.search({ q, scopes, tags })
+      ? await this.project.search({ q, scopes, tags, walkLimit })
       : { entries: [] };
-    const merged = mergeByKey(projRes.entries, homeRes.entries, (e) => `${e.scope}\x00${e.key}`);
-    return { ok: true, entries: merged };
+    const merged = mergeByKey(projRes.entries, homeRes.entries, id);
+    if (!Number.isInteger(walkLimit) || walkLimit <= 0) return { ok: true, entries: merged };
+
+    // Each tier is walked under its OWN `walkLimit` (that bound exists to stop
+    // an unbounded synchronous file walk on the per-prompt hot path, so it has
+    // to stay per-tier). Slicing the project-first merge to `walkLimit` would
+    // then starve the home tier outright: a project tier that fills its own
+    // budget occupies every slot, and no home-tier lesson survives to reach
+    // `rankLessons`. Split the budget instead — each tier is guaranteed its
+    // half, and whatever the other tier leaves unused is handed straight back,
+    // so a single populated tier still fills the cap exactly as before.
+    const projectIds = new Set(projRes.entries.map(id));
+    const fromProject = merged.filter((e) => projectIds.has(id(e)));
+    const fromHome = merged.filter((e) => !projectIds.has(id(e)));
+    const projectTake = Math.min(
+      fromProject.length,
+      Math.max(Math.ceil(walkLimit / 2), walkLimit - fromHome.length),
+    );
+    return {
+      ok: true,
+      entries: [...fromProject.slice(0, projectTake), ...fromHome.slice(0, walkLimit - projectTake)],
+    };
   }
 
   // Merged, de-duplicated non-archived count across the given scopes.

package/src/store/remote.mjs

@@ -84,7 +84,11 @@ class RemoteStore {
     };
   }
 
-  async search({ q, scopes, tags, limit, cursor } = {}) {
+  // `timeoutMs` is optional and defaults to `restFetch`'s own budget, so every
+  // existing caller is unaffected. It exists for the callers on a user's
+  // critical path, which would rather answer nothing than stall (see
+  // `PROMPT_FETCH_TIMEOUT_MS` in `core/lessons.mjs`).
+  async search({ q, scopes, tags, limit, cursor, timeoutMs } = {}) {
     // A list of terms collapses into ONE `websearch` query joined by `OR`, so a
     // multi-term failure lookup is a single round-trip (the server FTS ORs them
     // and stems each). `failureQuery` distils terms to `[a-z0-9]+` tokens, so no
@@ -96,7 +100,7 @@ class RemoteStore {
     if (tags?.length) body.tags = tags;
     if (limit) body.limit = limit;
     if (cursor) body.cursor = cursor;
-    const res = await this._rest('/memories/search', { method: 'POST', body });
+    const res = await this._rest('/memories/search', { method: 'POST', body, timeoutMs });
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
     const data = res.data ?? {};
     return {