@lorekit/cli 1.37.0 → 1.39.0

package/README.md

@@ -672,6 +672,30 @@ Both files share this schema — all fields optional:
                            //  transcript; on Cursor/Codex there is none, so "friction"
                            //  falls back to firing so no lesson is silently lost)
 
+  "hooks.sessionStart": "hybrid",
+                           // shape of the block injected at session start:
+                           //   "hybrid" (default) — fill the character budget with the
+                           //     highest-ranked memories, then add one line naming what
+                           //     was left out and where it lives
+                           //   "index"            — the same list, no trailing map
+                           //                        (truncation is silent)
+                           //   "map"              — lead with the scope map plus the
+                           //                        three most salient memories
+                           // repo wins over user; an unrecognised value is ignored and the
+                           // 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
+                           // 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
+                           // still claims the decision (a typo'd project policy degrades to
+                           // the default rather than silently becoming a per-machine one)
+                           // memories are RANKED before the budget is spent, so what
+                           // survives is the most-recurring and most-recent, not the newest
+
   "hooks.adapter": "claude",
                            // explicit adapter when auto-detection is ambiguous
                            // values: "claude" | "cursor" | "codex"

package/package.json

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

package/src/control.mjs

@@ -8,6 +8,8 @@
 //   ttl.default     — days until a write with no explicit TTL expires
 //   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.adapter   — explicit adapter override ("claude" | "cursor" | "codex")
 //
 // Two layers of config, two kinds of statement:
@@ -55,6 +57,56 @@ export function normalizeStopMode(v) {
   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.
+//   hybrid (default) — top-ranked lessons, then a one-line scope map naming what
+//                      was left out, so nothing is silently invisible.
+//   index            — lessons only. The pre-budget behaviour, minus the magic
+//                      count: a big store is simply truncated with no map.
+//   map              — the scope map plus a handful of the most salient lessons.
+//                      For a large store where the inventory matters more than
+//                      any particular lesson.
+// Friendly spellings for the same reason `normalizeStopMode` has them: these are
+// hand-edited JSON files.
+export const SESSION_START_MODES = ['hybrid', 'index', 'map'];
+export function normalizeSessionStartMode(v) {
+  if (typeof v !== 'string') return null;
+  const s = v.trim().toLowerCase();
+  if (['hybrid', 'both', 'auto', 'default'].includes(s)) return 'hybrid';
+  if (['index', 'list', 'lessons', 'full'].includes(s)) return 'index';
+  if (['map', 'scopes', 'summary', 'toc'].includes(s)) return 'map';
+  return null;
+}
+
+// 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.
+//
+// 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 MIN_SESSION_START_MAX_CHARS = 200;
+export const MAX_SESSION_START_MAX_CHARS = 20000;
+
+// 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 —
+// 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.
+export function normalizeSessionStartMaxChars(v) {
+  const n = firstNumber(v);
+  if (n === null) return null;
+  const i = Math.round(n);
+  if (i < MIN_SESSION_START_MAX_CHARS) return MIN_SESSION_START_MAX_CHARS;
+  if (i > MAX_SESSION_START_MAX_CHARS) return MAX_SESSION_START_MAX_CHARS;
+  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.
@@ -204,6 +256,30 @@ export function resolveControl({
     normalizeStopMode(userConfig['hooks.stop']) ||
     'friction';
 
+  // `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
+  // default, exactly like `hooks.stop`: a mistyped shape must degrade to the
+  // sensible one, never blank the injection.
+  const hooksSessionStart =
+    normalizeSessionStartMode(repoConfig['hooks.sessionStart']) ||
+    normalizeSessionStartMode(userConfig['hooks.sessionStart']) ||
+    'hybrid';
+
+  // `hooks.sessionStart.maxChars` — the character budget that block may spend.
+  //
+  // The LAYER is chosen before the value is parsed, the `ttl.default` rule (see
+  // declaresScalar): a repo that declared a budget owns the decision even when
+  // the value it declared is garbage, so a typo degrades to the default rather
+  // than silently handing the decision to whatever the developer happens to have
+  // in their home directory. Two people on the same commit must get the same
+  // block.
+  const sessionStartMaxCharsRaw = declaresScalar(repoConfig['hooks.sessionStart.maxChars'])
+    ? repoConfig['hooks.sessionStart.maxChars']
+    : userConfig['hooks.sessionStart.maxChars'];
+  const hooksSessionStartMaxChars =
+    normalizeSessionStartMaxChars(sessionStartMaxCharsRaw) ?? DEFAULT_SESSION_START_MAX_CHARS;
+
   // `hooks.adapter` — repo layer wins over user layer (explicit project override).
   const hooksAdapter =
     (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
@@ -242,6 +318,8 @@ export function resolveControl({
     scopeDefaults,
     hooksDisabled,
     hooksStop,
+    hooksSessionStart,
+    hooksSessionStartMaxChars,
     hooksAdapter,
     hooksInstructions,
   };

package/src/core/lessons.mjs

@@ -8,7 +8,11 @@ import { deriveScope } from '../scope.mjs';
 // can't drift from it, and the hot path never pulls in the `lessons-view.mjs`
 // render/`util` stack. (Failure-relevance matching is the store's job now, so
 // the hook no longer needs `matchesQuery` — `search` still does.)
-import { resolvePrecedence } from '../lessons-pure.mjs';
+// `rankLessons` comes from the same dependency-free module for the same reason:
+// 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';
 // The deep-link builder is the SAME pure module the `link` command and the
 // `--link` flag use, so the hook's confirmation/nudge links are JSON-encoded
 // correctly (a raw `?scope=global` silently means "all scopes") and can't drift
@@ -20,9 +24,45 @@ import { loreScopeUrl, buildLessonUrl } from '../deeplink-pure.mjs';
 // over MCP, in the agent's context. Advising the number is the only lever the
 // hook has, which is exactly why it must not be a second, hand-kept copy.
 import { resolveDefaultTtlDays, matchesScopePrefix } from '../store/ttl.mjs';
+// The budget default lives with the rest of the config vocabulary in
+// `control.mjs`, so the resolver and the renderer cannot disagree about what an
+// 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 { FRICTION_FAILURE, FRICTION_STUCK_LOOP } from './friction.mjs';
 
-const MAX_LESSONS = 15;
+// THE INJECTED SET IS BOUNDED BY A CHARACTER BUDGET, NOT BY A COUNT.
+//
+// It used to be `MAX_LESSONS = 15` — a number with no derivation. Fifteen of
+// what? A fifteen-line index of terse keys and a fifteen-line index of long ones
+// differ by an order of magnitude in what they cost the context window, and the
+// number said nothing about either. Worse, it was a HARD floor as well as a
+// ceiling: a workspace with six lessons and a workspace with six hundred both
+// got fifteen, so the small store was padded to a number and the large one was
+// truncated to it, silently, with no way for the reader to know which had
+// happened.
+//
+// What actually matters is how much of the window the block occupies, so that is
+// what is spent. `hooks.sessionStart.maxChars` (control.mjs) sets it; the shape
+// the remainder takes is `hooks.sessionStart`. Characters, not tokens: a real
+// tokenizer is a dependency this package does not have and will not take, and
+// 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 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
+// lessons is just `index` with extra steps.
+const MAP_TOP_K = 3;
+
 // Cap on lessons injected on a failure — a small, focused "you've seen this
 // before" set, never the whole applicable corpus.
 const MAX_RELEVANT = 3;
@@ -42,26 +82,112 @@ 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).
-export async function fetchLessons(store, cwd) {
+// 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.
+export const SCOPE_READ_LIMIT = 25;
+
+export async function fetchLessons(store, cwd, { now = Date.now() } = {}) {
   const scope = deriveScope(cwd);
   const groups = [];
+  // Per scope: did the read come back full? Then the count below is a floor,
+  // 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: 25 });
+    const res = await store.list({ scope: s, limit: SCOPE_READ_LIMIT });
     if (!res || !res.ok) continue; // best-effort: a failed scope contributes nothing
-    const entries = (Array.isArray(res.entries) ? res.entries : [])
+    const raw = Array.isArray(res.entries) ? res.entries : [];
+    if (raw.length >= SCOPE_READ_LIMIT) truncatedScopes.add(s);
+    const entries = raw
       .filter((e) => e && e.key)
       .map((e) => ({ ...e, scope: s }));
     groups.push({ scope: s, error: null, entries });
   }
   // First value per key wins (most-specific scope, since `readOrder` is
   // narrow→broad) — exactly what the old inline `byKey` merge did, now via the
-  // one shared resolver. The winners, in group order, are the injected set.
+  // one shared resolver.
   const { groups: resolved } = resolvePrecedence({ groups });
-  const lessons = [];
+  const winners = [];
   for (const g of resolved) {
-    for (const e of g.entries) if (e.winning) lessons.push(e);
+    for (const e of g.entries) if (e.winning) winners.push(e);
   }
-  return { scope, lessons: lessons.slice(0, MAX_LESSONS) };
+
+  // THE TWO STEPS ANSWER DIFFERENT QUESTIONS, AND THE ORDER MATTERS.
+  //
+  // `resolvePrecedence` decides WHICH COPY of a key survives — a project
+  // lesson shadows the global lesson of the same name — and that is a
+  // correctness rule, not a preference. `rankLessons` then decides WHICH OF THE
+  // SURVIVORS a reader sees first. Ranking runs on the winners only, so a
+  // shadowed lesson can never be promoted back into the set by scoring well;
+  // precedence still owns the merge, exactly as `tree` renders it.
+  //
+  // Before this, the cap took whatever the group order happened to hand it,
+  // which is recency within a scope. On an active repo the newest cluster is
+  // one task's iteration log, so a dozen near-identical one-offs took the whole
+  // budget and evicted the lessons that had been re-learned all month. Recency
+  // is one factor now, not the ordering.
+  //
+  // WHAT PRECEDENCE DOES *NOT* DO, STATED SO IT IS NOT MISREAD AS A BUG.
+  // Precedence only settles same-key collisions. Across DIFFERENT keys the cap
+  // is now a single cross-scope ranking in which `scopeOrder` is a TIEBREAK
+  // (`rankLessons` sorts on score first and only compares `scopeRank` inside
+  // `SCORE_EPSILON`) — so a recurring `global::` lesson can and will take a
+  // slot from a fresher-but-one-off `project::` one, where the old narrow-first
+  // group order always filled the budget from the most-specific scope down.
+  // That is the intended trade: the budget goes to what has been re-learned,
+  // wherever it lives, and a scope-major sort would reinstate exactly the
+  // "whatever the group order hands it" behaviour this change removes. If a
+  // narrow scope should instead be guaranteed floor space, that is a weighting
+  // change in `rankLessons`, not something to re-derive here.
+  //
+  // `terms: []` is the SessionStart case: nothing has been asked yet, so the
+  // relevance factor contributes nothing and the order is recency + salience.
+  // `scopeOrder` is passed explicitly rather than left to the scorer's
+  // first-appearance default — they agree today, but the hierarchy is
+  // `readOrder`'s to state, not an artefact of how this function happens to
+  // build its array.
+  const ranked = rankLessons(winners, { terms: [], now, scopeOrder: scope.readOrder });
+
+  // The scope map is built from the SAME pass, over the winners — the set a
+  // reader could actually act on, so a shadowed duplicate is not counted twice.
+  // Order follows `readOrder` (most-specific first) rather than count, because
+  // the map is a map: it should read like the hierarchy it describes.
+  const scopeCounts = scopeInventory(ranked, scope.readOrder, truncatedScopes);
+
+  // `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),
+    scopeCounts,
+    applicable: ranked.length,
+  };
+}
+
+// Per-scope counts over an already-ranked lesson list, in the given scope order.
+// A scope with no surviving lesson is omitted — a map row reading `0` is noise,
+// and the reader cannot act on an empty scope. Pure.
+export function scopeInventory(lessons, scopeOrder = [], truncated = new Set()) {
+  const counts = new Map();
+  for (const l of Array.isArray(lessons) ? lessons : []) {
+    const s = l?.scope;
+    if (!s) continue;
+    counts.set(s, (counts.get(s) || 0) + 1);
+  }
+  // `scopeOrder` first (the hierarchy), then anything else that turned up, so a
+  // lesson carrying an unexpected scope is still counted rather than dropped.
+  const ordered = [...scopeOrder.filter((s) => counts.has(s))];
+  for (const s of counts.keys()) if (!ordered.includes(s)) ordered.push(s);
+  return ordered.map((s) => ({
+    scope: s,
+    count: counts.get(s),
+    atReadLimit: truncated.has ? truncated.has(s) : false,
+  }));
 }
 
 // Cap on a lesson's one-line hook in the injected index. Long enough to jog
@@ -97,23 +223,103 @@ 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.
-export function formatLessons(lessons, scope, { instruction = null } = {}) {
-  const noun = lessons && lessons.length === 1 ? 'memory' : 'memories';
-  if (!lessons || lessons.length === 0) {
+export function formatLessons(lessons, scope, {
+  instruction = null,
+  mode = 'hybrid',
+  maxChars = DEFAULT_SESSION_START_MAX_CHARS,
+  scopeCounts = null,
+  applicable = null,
+} = {}) {
+  const all = Array.isArray(lessons) ? lessons : [];
+  if (all.length === 0) {
     // No lessons — only emit if there is a custom instruction to show.
     if (!instruction) return null;
     return (
-      `LoreKit: 0 ${noun} loaded · ${scope.repoScope || 'this workspace'} ` +
+      `LoreKit: 0 memories loaded · ${scope.repoScope || 'this workspace'} ` +
       `— considerations, not rules; read any in full with memory.read.\n\n` +
       `Project instruction: ${instruction}`
     );
   }
+
+  const budget = Number.isFinite(maxChars) && maxChars > 0
+    ? maxChars
+    : DEFAULT_SESSION_START_MAX_CHARS;
+  const shape = SESSION_START_MODES.includes(mode) ? mode : 'hybrid';
+  const total = typeof applicable === 'number' && applicable >= all.length ? applicable : all.length;
+
+  // The map line is composed BEFORE the lessons are chosen, because in `hybrid`
+  // its length has to be reserved out of the budget. Appending it afterwards
+  // would let the block overrun the very number the config asked for — a budget
+  // you can exceed by one more line is not a budget.
+  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;
+  const { shown } = fitLines(all, budget - reserve, ceiling);
+
+  // `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
+  // a "…and here is what you are missing" line would be a lie. `index` never
+  // shows it, which is the whole difference between `index` and `hybrid`.
+  const showMap = Boolean(map) && (shape === 'map' || (shape === 'hybrid' && shown.length < total));
+
+  // Say `8 of 50` whenever the two differ. The old header reported only what it
+  // had rendered, so a truncated block was indistinguishable from a complete one
+  // and the agent had no way to know that reaching for `memory.search` was worth
+  // it. The count is what makes the truncation self-describing.
+  const counted = shown.length === total
+    ? `${total} ${total === 1 ? 'memory' : 'memories'}`
+    : `${shown.length} of ${total} memories`;
   const header =
-    `LoreKit: ${lessons.length} ${noun} loaded · ${scope.repoScope || 'this workspace'} ` +
+    `LoreKit: ${counted} loaded · ${scope.repoScope || 'this workspace'} ` +
     `— considerations, not rules; read any in full with memory.read.`;
-  const body = lessons.map((l) => `- (${l.scope}) ${l.key} — ${lessonHook(l.value)}`).join('\n');
+
+  const parts = [header, ...shown.map((s) => s.line)];
+  if (showMap) parts.push(map);
   const instructionBlock = instruction ? `\n\nProject instruction: ${instruction}` : '';
-  return `${header}\n${body}${instructionBlock}`;
+  return `${parts.join('\n')}${instructionBlock}`;
+}
+
+// One index line for a lesson. Pure.
+function lessonLine(l) {
+  return `- (${l.scope}) ${l.key} — ${lessonHook(l.value)}`;
+}
+
+// Take lessons in order until the next line would not fit, or the ceiling is
+// reached. Returns `{ shown, used }`.
+//
+// THE FIRST LINE IS ALWAYS TAKEN, even when it alone exceeds the budget. A
+// header with nothing under it is strictly worse than one over-long line: the
+// reader learns nothing and cannot tell whether the store is empty or the budget
+// is misconfigured. One line over budget is a visible, self-explaining overrun;
+// zero lines is a silent one. Pure.
+function fitLines(lessons, budget, ceiling) {
+  const shown = [];
+  let used = 0;
+  for (const l of lessons) {
+    if (shown.length >= ceiling) break;
+    const line = lessonLine(l);
+    const cost = line.length + 1; // the newline that joins it
+    if (shown.length > 0 && used + cost > budget) break;
+    used += cost;
+    shown.push({ lesson: l, line });
+  }
+  return { shown, used };
+}
+
+// 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
+// describe. Pure.
+export function renderScopeMap(scopeCounts) {
+  const rows = (Array.isArray(scopeCounts) ? scopeCounts : [])
+    .filter((s) => s && s.scope && Number(s.count) > 0);
+  if (rows.length === 0) return null;
+  const body = rows
+    .map((s) => `${s.scope} ${s.count}${s.atReadLimit ? '+' : ''}`)
+    .join(' · ');
+  return `More lore: ${body} — memory.search or memory.read to drill in.`;
 }
 
 // Distil a small set of significant, lowercased search TERMS from a tool

package/src/deeplink-pure.mjs

@@ -30,7 +30,12 @@ export const DEFAULT_APP_BASE = 'https://lorekit.io';
 export const LORE_PARAM_DEFAULTS = {
   scope: null, // string | null — null means "all scopes"
   q: '', // string search query
-  range: null, // { from, to } | null (DateRange, "YYYY-MM-DD")
+  // { from, to } | { preset } | null. The CLI emits only the { from, to } arm
+  // (day strings via --range/--from/--to), which the Explorer still reads as
+  // whole UTC days with an INCLUSIVE end day — unchanged. The web model also
+  // accepts ISO instants in that arm and a relative { preset: '7d' } arm
+  // (packages/web/src/lib/time-range.ts); neither has a CLI flag yet.
+  range: null,
   owner: 'all', // 'all' | 'personal' | { orgId }
   // Filter[] | null — the Explorer's multi-dimension filter bar (label / agent /
   // trigger / repo / branch / pr). `null`, NOT `[]`, is the default on purpose:
@@ -42,7 +47,14 @@ export const LORE_PARAM_DEFAULTS = {
   filters: null,
   tags: [], // string[] — legacy label filter (AND across labels); [] means "no filter". Still READ by the app, superseded by `filters`
   view: 'scope', // 'scope' | 'time'
-  archived: false, // boolean
+  // 'active' | 'archived' | 'expiring' | null — the Explorer's Status control.
+  // `null`, NOT 'active', is the default for `filters`' reason: the app has to
+  // tell "absent" from an explicit choice, because an absent `status` falls back
+  // to the legacy `archived` flag while an explicit `status=active` overrides it.
+  status: null,
+  // boolean — SUPERSEDED by `status`, still READ by the app so existing links
+  // (and `lorekit link --archived`) keep resolving to the archived view.
+  archived: false,
   lesson: null, // { scope, key } | null — opens the detail sheet
 };
 
@@ -50,7 +62,7 @@ export const LORE_PARAM_DEFAULTS = {
 // Mirrors the `useUrlState` call order in `LoreExplorer.tsx` (+ the `lesson`
 // param last), so `filters` and `tags` sit between `owner` and `view`. `scope`
 // precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
-const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'filters', 'tags', 'view', 'archived', 'lesson'];
+const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'filters', 'tags', 'view', 'status', 'archived', 'lesson'];
 
 // Strip trailing slashes from a base URL, falling back to the default when the
 // input is empty/absent. Pure.

package/src/hook.mjs

@@ -106,8 +106,14 @@ async function run(args) {
       }
       return 0;
     }
-    const { scope: readScope, lessons } = await fetchLessons(store, root);
-    emit(formatLessons(lessons, readScope, { instruction: sessionInstruction }));
+    const { scope: readScope, lessons, scopeCounts, applicable } = await fetchLessons(store, root);
+    emit(formatLessons(lessons, readScope, {
+      instruction: sessionInstruction,
+      mode: control.hooksSessionStart,
+      maxChars: control.hooksSessionStartMaxChars,
+      scopeCounts,
+      applicable,
+    }));
     return 0;
   }
 

package/src/lessons-pure.mjs

@@ -199,3 +199,344 @@ export function resolveScopeKeyArgs(positionals = [], options = {}) {
   const { scope, key } = resolveScopeArg(first, isScope);
   return { scope: scope || '', key, consumed: 1 };
 }
+
+// ── ranking: which lessons are worth the context budget ──────────────────────
+//
+// `resolvePrecedence` above answers "which SCOPE's copy of a key wins". This
+// answers the different question the injection path actually has: given the
+// winners, which ones does a reader most need to see FIRST.
+//
+// It exists because ordering by recency alone is actively harmful on a busy
+// repo. The newest cluster of writes is usually one task's iteration log — a
+// dozen near-identical one-off lessons — and under a recency sort that cluster
+// takes every slot, evicting the durable lessons that have been re-learned a
+// dozen times. Recency is a signal, not the ranking.
+//
+// The score is a weighted sum of three factors, each normalised to [0,1]:
+//
+//   recency   — exponential decay on age. Half-life, not a cliff: a lesson does
+//               not stop mattering on a particular day.
+//   salience  — log(1 + seenCount), normalised across the candidate set. A
+//               lesson written eight times has been re-learned; one written
+//               once may just be noise. Logarithmic because the interesting
+//               step is 1 → 3, not 40 → 42, and normalised across the set
+//               because "recurring" only means anything relative to its peers.
+//   relevance — how much of the caller's query this lesson matches. Exactly 0
+//               when no terms are supplied, which is the SessionStart case: it
+//               then contributes the same constant to every candidate and the
+//               ordering is recency + salience alone.
+//
+// PURE AND TOTAL, with one scoped exception. `now` is a PARAMETER: the
+// arithmetic never reads the clock, every factor is a function of the value
+// passed in, and a caller that supplies one gets a ranking that is exactly
+// reproducible in a test and in a bug report. `scoreLesson` and `rankLessons`
+// default it to `Date.now()` at the call boundary so the common caller need not
+// thread a clock through — that default is the ONLY clock read, it happens once
+// per call, and passing `now` explicitly removes it. Every missing or malformed
+// field degrades to its zero rather than throwing — this runs on the
+// SessionStart hot path behind a hook that must exit 0, and losing the whole
+// injection to save one unparseable timestamp is a bad trade.
+
+// Age at which a lesson's recency factor halves. Two weeks is roughly the span
+// over which a repo's "what am I working on" context turns over: yesterday's
+// lesson should clearly outrank last month's, without last month's dropping to
+// nothing — a year-old lesson that has recurred 30 times still deserves a slot.
+export const RECENCY_HALF_LIFE_DAYS = 14;
+
+// Equal thirds. Deliberately not tuned: with no corpus to tune against, an
+// invented weighting is a guess wearing a decimal point. They are a parameter
+// so a caller can experiment, and so a future PR can change them with evidence.
+//
+// FROZEN. An exported mutable object is shared state, and this one is the
+// fallback the totality guarantee rests on: a caller that zeroed its fields
+// turned `scoreLesson`'s "fall back to the defaults" branch into unbounded
+// recursion (a real `RangeError`, raised inside a hook the header promises will
+// never throw). Freezing makes the corruption a `TypeError` at the assignment,
+// in the caller's own frame, instead of a stack overflow three layers down.
+export const DEFAULT_RANK_WEIGHTS = Object.freeze({ recency: 1, salience: 1, relevance: 1 });
+
+// Two scores closer than this are the same score. Sized well below any
+// difference the factors can produce meaningfully (a one-second age gap moves a
+// score by ~1e-6 at the default half-life) and well above float noise.
+export const SCORE_EPSILON = 1e-9;
+
+const MS_PER_DAY = 86400000;
+
+// Milliseconds since the epoch for a value that may be an ISO string, a Date, a
+// number, or junk. `null` when it cannot be read as a time — never NaN, which
+// would propagate silently through the arithmetic below and sort the entry to
+// wherever NaN happens to land.
+function timeOf(value) {
+  if (value == null || value === '') return null;
+  const t = value instanceof Date ? value.getTime() : new Date(value).getTime();
+  return Number.isFinite(t) ? t : null;
+}
+
+/**
+ * Recency factor in [0,1]: 1 for something written now, 0.5 at one half-life.
+ *
+ * An unknown timestamp scores 0, NOT 0.5. The alternative — treating unknown as
+ * average — would let a lesson with no `updatedAt` outrank a real one that is
+ * merely a month old, on the strength of having less information about it.
+ *
+ * A FUTURE timestamp is clamped to 1 rather than allowed to exceed it. Clock
+ * skew between a writer and a reader is ordinary; a lesson from thirty seconds
+ * in the future is simply new, and letting age go negative would hand it an
+ * unbounded score that beats every honestly-dated lesson in the set.
+ */
+export function recencyFactor(updatedAt, now, halfLifeDays = RECENCY_HALF_LIFE_DAYS) {
+  const t = timeOf(updatedAt);
+  const nowMs = timeOf(now);
+  if (t === null || nowMs === null) return 0;
+  const halfLife = Number.isFinite(halfLifeDays) && halfLifeDays > 0
+    ? halfLifeDays
+    : RECENCY_HALF_LIFE_DAYS;
+  const ageDays = Math.max(0, (nowMs - t) / MS_PER_DAY);
+  return Math.exp((-Math.LN2 * ageDays) / halfLife);
+}
+
+/**
+ * Salience factor in [0,1] — recurrence, relative to the most-recurring lesson
+ * in the same candidate set.
+ *
+ * `maxSeenCount` is passed in rather than derived here because the factor is
+ * only meaningful within a set: eight sightings is remarkable next to a set of
+ * one-offs and unremarkable next to a set of hundreds. `rankLessons` computes
+ * it once for the whole set.
+ *
+ * A set whose maximum is 0 or 1 yields 0 for every member — no lesson in it has
+ * recurred, so salience has nothing to say and the other factors decide. Note
+ * this makes a set of all-one-offs rank purely on recency, which is correct:
+ * the ranking only claims to separate recurring from non-recurring.
+ *
+ * A `seenCount` ABOVE `maxSeenCount` is clamped to 1 rather than allowed to
+ * exceed it, for the same reason `recencyFactor` clamps a future timestamp.
+ * `rankLessons` derives the maximum from the set, so in-set the clamp never
+ * binds; it binds when a caller reaches this (or `scoreLesson`) directly with a
+ * maximum that is not the set's, and without it the `[0,1]` both docblocks
+ * promise would simply be false — `salienceFactor(5, 2)` is 1.63.
+ */
+export function salienceFactor(seenCount, maxSeenCount) {
+  const n = Number.isFinite(seenCount) ? Math.max(0, seenCount) : 0;
+  const max = Number.isFinite(maxSeenCount) ? Math.max(0, maxSeenCount) : 0;
+  if (max <= 1) return 0;
+  return Math.min(1, Math.log1p(n) / Math.log1p(max));
+}
+
+/**
+ * Relevance factor in [0,1] — the fraction of the caller's terms this lesson
+ * matches.
+ *
+ * Matching is `matchesQuery`'s: a LITERAL, case-insensitive substring of the
+ * key or the value. That is the same primitive `search` and the failure hook
+ * use, so a lesson that a `lorekit search <term>` would surface is a lesson
+ * this ranks up — one matcher, one meaning of "matches".
+ *
+ * The fraction is over DISTINCT terms, so a term repeated in the caller's list
+ * cannot inflate a lesson's score, and it is a fraction rather than a count so
+ * a three-term query and a ten-term query produce comparable numbers.
+ *
+ * Empty terms is 0, never 1. This is the SessionStart case and it must not
+ * silently become "everything is maximally relevant" — which, being a constant,
+ * would not change the ORDER but would compress the score range and make every
+ * downstream threshold meaningless.
+ *
+ * `terms` is a list, a lone term, or any `Set` — every form is normalised the
+ * same way, so `new Set([' Timeout '])` and `[' Timeout ']` score identically.
+ * Normalisation is NOT a caller responsibility and there is no pre-normalised
+ * fast path on this function: an unnormalised `Set` reaching the matcher scored
+ * `''` as a match on everything and a padded term as a match on nothing.
+ * `rankLessons` gets the once-per-ranking saving from the internal
+ * `relevanceFromTerms` instead, where the set is one this module built.
+ */
+export function relevanceFactor(entry, terms) {
+  return relevanceFromTerms(entry, distinctTerms(terms));
+}
+
+// The matcher, over a set this module has already normalised. Internal on
+// purpose: it is the seam that lets `rankLessons` normalise the query ONCE for
+// the whole ranking instead of once per candidate (O(entries × terms) for a
+// result that cannot differ between entries) without turning "hand me a
+// correctly-shaped Set" into part of the public contract.
+function relevanceFromTerms(entry, distinct) {
+  if (distinct.size === 0) return 0;
+  let hits = 0;
+  for (const term of distinct) if (matchesQuery(entry, term)) hits += 1;
+  return hits / distinct.size;
+}
+
+// The caller's query as a set of distinct, lowercased, non-empty terms. Accepts
+// a list, a `Set`, or a lone value, and normalises the CONTENTS in every case —
+// an earlier version short-circuited on `instanceof Set`, which let a
+// hand-built set skip trimming and empty-filtering and diverge from the list
+// path.
+function distinctTerms(terms) {
+  const list = Array.isArray(terms) || terms instanceof Set ? [...terms] : [terms];
+  return new Set(
+    list
+      .map((t) => String(t == null ? '' : t).toLowerCase().trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Score one lesson in [0,1].
+ *
+ * `maxSeenCount` belongs to the candidate SET, so this is normally reached
+ * through `rankLessons` rather than called directly; it is exported so a caller
+ * can explain a ranking ("why is this one third?") without re-deriving the
+ * arithmetic.
+ *
+ * The weighted sum is divided by the total weight, so the result stays in [0,1]
+ * whatever weights are supplied and two runs with different weightings remain
+ * comparable. A weight set that sums to zero falls back to the defaults rather
+ * than dividing by zero — ONCE, by substitution rather than by recursion. The
+ * recursive form was total only while `DEFAULT_RANK_WEIGHTS` still summed above
+ * zero, which made a totality guarantee depend on an exported object nobody had
+ * mutated yet. If even the defaults are degenerate every lesson scores 0, which
+ * is honest (no weighted signal is left) and hands the ordering to the
+ * tiebreakers instead of to a stack overflow.
+ */
+export function scoreLesson(entry, {
+  terms = [],
+  now = Date.now(),
+  weights = DEFAULT_RANK_WEIGHTS,
+  maxSeenCount = 0,
+  halfLifeDays = RECENCY_HALF_LIFE_DAYS,
+} = {}) {
+  return scoreWithTerms(entry, distinctTerms(terms), { now, weights, maxSeenCount, halfLifeDays });
+}
+
+// `scoreLesson` with the query already normalised. `rankLessons` calls this so
+// the whole ranking normalises the query once; `scoreLesson` normalises and
+// delegates, so no caller has to know a normalised set exists.
+function scoreWithTerms(entry, termSet, { now, weights, maxSeenCount, halfLifeDays }) {
+  let w = {
+    recency: numberOr(weights?.recency, DEFAULT_RANK_WEIGHTS.recency),
+    salience: numberOr(weights?.salience, DEFAULT_RANK_WEIGHTS.salience),
+    relevance: numberOr(weights?.relevance, DEFAULT_RANK_WEIGHTS.relevance),
+  };
+  let total = w.recency + w.salience + w.relevance;
+  if (!(total > 0)) {
+    w = {
+      recency: numberOr(DEFAULT_RANK_WEIGHTS.recency, 0),
+      salience: numberOr(DEFAULT_RANK_WEIGHTS.salience, 0),
+      relevance: numberOr(DEFAULT_RANK_WEIGHTS.relevance, 0),
+    };
+    total = w.recency + w.salience + w.relevance;
+  }
+  if (!(total > 0)) return 0;
+  const recency = recencyFactor(entry?.updatedAt ?? entry?.updated_at ?? entry?.updated, now, halfLifeDays);
+  const salience = salienceFactor(seenCountFrom(entry), maxSeenCount);
+  const relevance = relevanceFromTerms(entry, termSet);
+  return (w.recency * recency + w.salience * salience + w.relevance * relevance) / total;
+}
+
+// A non-negative finite number, or the fallback. Guards a caller passing a
+// string, null, or NaN as a weight.
+function numberOr(value, fallback) {
+  const n = typeof value === 'string' ? Number(value) : value;
+  return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+// The recurrence count off an entry, in either the store-projected form
+// (`seenCount`, what `store/entry-fields.mjs` produces) or the raw REST/
+// frontmatter spelling. Anything unreadable is 0 — no evidence of recurrence,
+// which is not the same claim as one sighting.
+function seenCountFrom(entry) {
+  const raw = entry?.seenCount ?? entry?.seen_count;
+  const n = typeof raw === 'string' ? Number(raw) : raw;
+  return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Rank lessons best-first, returning a NEW array — the input is never reordered
+ * in place, because callers hold it (`fetchLessons` builds it from the
+ * precedence resolution and `tree` renders the same objects).
+ *
+ * Ties are broken deterministically, and the order of the tiebreakers is the
+ * design:
+ *
+ *   1. score, descending.
+ *   2. SCOPE PRECEDENCE — the position of the entry's scope in `scopeOrder`,
+ *      which defaults to the order scopes first appear in the input. That
+ *      default is not a convenience: `fetchLessons` hands entries over in
+ *      `readOrder`, most-specific first, so the default IS the precedence
+ *      hierarchy, and a project lesson beats a global one it ties with, for
+ *      free and without this module knowing what a scope is.
+ *   3. key, lexicographically — the last resort, so the answer cannot depend on
+ *      hash iteration order or on which page a row arrived in.
+ *
+ * Sorting on floats makes exact ties rarer than they look, so tiebreaker 2 also
+ * quietly matters for NEAR ties: two lessons written in the same minute with
+ * the same count differ in the tenth decimal place, which is noise, not a
+ * preference. `SCORE_EPSILON` treats a difference that small as a tie so the
+ * meaningful tiebreaker decides instead of floating-point dust.
+ *
+ * That tie is applied by QUANTISING each score onto a `SCORE_EPSILON` grid, not
+ * by an `abs(a - b) <= SCORE_EPSILON` comparison. The comparison form reads
+ * more naturally and is wrong: approximate equality is not TRANSITIVE, so three
+ * scores a grid-step apart give a≈b, b≈c and c>a, the comparator stops being a
+ * strict weak ordering, and the result depends on the order the rows arrived in
+ * — exactly the determinism this docblock claims. Measured before the fix:
+ * three lessons 3ms apart produced three different orderings across the six
+ * permutations of one input. Rounding first makes "same score" an equivalence
+ * relation, so the scope/key tiebreak is what decides every near tie.
+ *
+ * The residual cost is a boundary: two scores closer than a grid step can still
+ * land in adjacent buckets and be ordered by score. That is unavoidable for any
+ * transitive notion of approximate equality, and it is a far smaller defect
+ * than an ordering that changes with input order.
+ */
+export function rankLessons(entries = [], {
+  terms = [],
+  now = Date.now(),
+  weights = DEFAULT_RANK_WEIGHTS,
+  halfLifeDays = RECENCY_HALF_LIFE_DAYS,
+  scopeOrder = null,
+} = {}) {
+  const list = Array.isArray(entries) ? entries.filter((e) => e && typeof e === 'object') : [];
+  if (list.length === 0) return [];
+
+  // Normalise the query ONCE for the whole ranking, not once per candidate —
+  // `scoreWithTerms` takes the set this module built straight through.
+  const termSet = distinctTerms(terms);
+
+  // One pass for the set-relative normaliser, so scoring stays O(n).
+  let maxSeenCount = 0;
+  for (const e of list) maxSeenCount = Math.max(maxSeenCount, seenCountFrom(e));
+
+  // Scope precedence: an explicit order wins, else first-appearance order.
+  const rankByScope = new Map();
+  for (const s of Array.isArray(scopeOrder) ? scopeOrder : []) {
+    if (!rankByScope.has(s)) rankByScope.set(s, rankByScope.size);
+  }
+  for (const e of list) {
+    const s = e.scope;
+    if (s !== undefined && !rankByScope.has(s)) rankByScope.set(s, rankByScope.size);
+  }
+
+  const scored = list.map((entry, index) => ({
+    entry,
+    index,
+    // The score rounded onto the SCORE_EPSILON grid. Comparing THIS rather than
+    // the raw score is what keeps "close enough to be a tie" transitive — see
+    // the docblock. A score is in [0,1] and the grid is 1e-9, so the bucket is
+    // always a safe integer.
+    bucket: Math.round(
+      scoreWithTerms(entry, termSet, { now, weights, maxSeenCount, halfLifeDays }) / SCORE_EPSILON,
+    ),
+    scopeRank: rankByScope.has(entry.scope) ? rankByScope.get(entry.scope) : Number.MAX_SAFE_INTEGER,
+    key: String(entry.key ?? ''),
+  }));
+
+  scored.sort((a, b) => {
+    if (a.bucket !== b.bucket) return b.bucket - a.bucket;
+    if (a.scopeRank !== b.scopeRank) return a.scopeRank - b.scopeRank;
+    if (a.key !== b.key) return a.key < b.key ? -1 : 1;
+    return a.index - b.index; // stable: equal in every respect keeps input order
+  });
+
+  return scored.map((s) => s.entry);
+}
+

package/src/store/entry-fields.mjs

@@ -0,0 +1,79 @@
+// The read-shape fields a ranking layer needs, derived from a store row.
+//
+// Both stores answer with rows in their OWN vocabulary — the remote store hands
+// back a REST `MemoryEntry` (`seen_count`, `updated_at`), the local store hands
+// back parsed frontmatter (`seen_count`, `updated`). A ranker cannot care which
+// one it is holding, so the READ-FIELD projection lives here, once, and both
+// stores apply it on the way out. Two copies of "which key holds the timestamp"
+// is exactly the drift the repo's mirror guards exist to prevent — see
+// `updatedAtOf` for the one other place in the CLI that maps the same pair, and
+// why it is not the same projection.
+//
+// TOTAL FUNCTIONS. Every entry point below is defined for any input — a null
+// row, a string where a number belongs, a hand-edited frontmatter scalar, a
+// response from a backend deployed before the column existed. This code runs on
+// the SessionStart hot path behind a hook that must always exit 0, so a throw
+// here would cost the user their lesson injection to save a field nobody
+// promised. Missing or unusable degrades to the documented default and the
+// caller ranks on what it does have.
+//
+// Zero-dependency: no imports, not even node builtins.
+
+/**
+ * How many times this lesson has been written.
+ *
+ * `0` — not `1` — is the absent case, and the distinction is load-bearing.
+ * A live remote row always carries at least `1` (the column is `NOT NULL
+ * DEFAULT 1`), so `0` can only mean "this store did not tell me", which a
+ * salience score should read as no evidence rather than as one sighting.
+ * Fractions are floored and negatives clamped: the count is a tally.
+ */
+export function seenCountOf(row) {
+  const raw = row?.seen_count;
+  const n = typeof raw === 'string' ? Number(raw) : raw;
+  if (typeof n !== 'number' || !Number.isFinite(n)) return 0;
+  return Math.max(0, Math.floor(n));
+}
+
+/**
+ * When this lesson was last written, as an ISO 8601 string, or `null`.
+ *
+ * Accepts either store's spelling (`updated_at` remote, `updated` local) and
+ * normalises through `Date` so a caller can compare two stores' entries without
+ * knowing which produced them. An unparseable value is `null`, never `Invalid
+ * Date` and never the raw text: a recency decay fed `NaN` silently sinks the
+ * entry to the bottom, which is a worse failure than admitting the timestamp is
+ * unknown.
+ *
+ * `normalizeEntry` (`src/lessons-view.mjs`) maps the same two spellings at the
+ * OPPOSITE precedence — `updated ?? updated_at`, local first — and that is
+ * deliberate, not drift: it builds the human/`--json` VIEW row, where a local
+ * file's own `updated` is the authoritative one and the value is passed through
+ * verbatim for rendering. This function builds the RANKING row, where the
+ * remote column is authoritative and the value is normalised through `Date`.
+ * Two different projections over one pair of keys, so neither can call the
+ * other; keep them in step by hand when a spelling changes.
+ */
+export function updatedAtOf(row) {
+  const raw = row?.updated_at ?? row?.updated;
+  if (raw == null || raw === '') return null;
+  const d = new Date(raw);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+/**
+ * A store row plus the two derived read fields.
+ *
+ * ADDITIVE by construction: the row is spread through untouched, so every
+ * existing caller keeps reading the exact keys it always did and only a caller
+ * that asks for `seenCount` / `updatedAt` sees anything new. A non-object row
+ * yields the defaults rather than throwing, so a malformed page cannot take
+ * down a whole listing.
+ */
+export function withReadFields(row) {
+  return {
+    ...(row && typeof row === 'object' ? row : {}),
+    seenCount: seenCountOf(row),
+    updatedAt: updatedAtOf(row),
+  };
+}

package/src/store/format.mjs

@@ -28,6 +28,12 @@ export const FIELDS = [
   // ttl.mjs). Null / absent means it never expires. Appended like the origin
   // 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
+  // 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.
+  'seen_count',
 ];
 
 // Serialize an entry ({ ...columns, value }) into file text.

package/src/store/local.mjs

@@ -10,6 +10,7 @@ import path from 'node:path';
 import { serializeEntry, parseEntry, slugify, scopeToDir } from './format.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
 import { isLive, resolveExpiresAt } from './ttl.mjs';
+import { seenCountOf, withReadFields } from './entry-fields.mjs';
 
 export function createLocalStore(baseDir) {
   return new LocalStore(baseDir);
@@ -73,13 +74,18 @@ class LocalStore {
     }
     rows.sort((a, b) => String(b.updated || '').localeCompare(String(a.updated || '')));
     if (limit) rows = rows.slice(0, limit);
-    return { ok: true, entries: rows };
+    // The same additive projection the remote store applies, so a caller that
+    // ranks entries never has to ask which store produced them.
+    return { ok: true, entries: rows.map(withReadFields) };
   }
 
   // read({ scope, key }) → { ok, entry } — null when absent, archived, or expired.
   async read({ scope, key } = {}) {
     const found = this._findByKey(scope, key);
-    return { ok: true, entry: found && isLive(found.entry) ? found.entry : null };
+    return {
+      ok: true,
+      entry: found && isLive(found.entry) ? withReadFields(found.entry) : null,
+    };
   }
 
   // write(...) → { ok, entry } — upsert by scope+key. Preserves `created` and
@@ -127,6 +133,21 @@ class LocalStore {
       updated: existing ? now : override || now,
       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
+      // 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.
+      //
+      // Reviving an ARCHIVED entry restarts at 1, matching the hosted RPC.
+      // The two stores get there differently — every conflict predicate on
+      // `memories` is partial on `archived_at is null`, so the server INSERTS a
+      // fresh row, while this store revives the file in place (see the docblock
+      // above) — but the count means the same thing on both: the lesson was
+      // retired and is being learned again, not seen once more.
+      seen_count: existing && !existing.entry.archived_at
+        ? seenCountOf(existing.entry) + 1
+        : 1,
       value: value == null ? '' : String(value),
     };
     const file = existing ? existing.file : this._freshPath(dir, key);
@@ -158,6 +179,10 @@ class LocalStore {
       updated: entry.updated ?? now,
       archived_at: entry.archived_at ?? null,
       expires_at: entry.expires_at ?? null,
+      // Verbatim, like every field here: migrate relocates a store, it does not
+      // re-sight its lessons, so a relocated entry must keep the count it had.
+      // An entry that never carried one lands as null and reads back as 0.
+      seen_count: entry.seen_count ?? null,
       value: entry.value == null ? '' : String(entry.value),
     };
     const file = existing ? existing.file : this._freshPath(dir, entry.key);

package/src/store/remote.mjs

@@ -20,6 +20,7 @@
 // Zero-dependency.
 import { restFetch, mcpToRestBase } from '../mcp.mjs';
 import { getActiveTraceparent } from '../telemetry.mjs';
+import { withReadFields } from './entry-fields.mjs';
 
 // Drop undefined/null args so JSON payloads stay tidy.
 function stripUndefined(obj) {
@@ -74,7 +75,10 @@ class RemoteStore {
     const data = res.data ?? {};
     return {
       ok: true,
-      entries: data.entries ?? [],
+      // `withReadFields` is additive — every key the route returned survives —
+      // so this projection costs existing callers nothing and gives a ranker
+      // the same `seenCount`/`updatedAt` pair the local store answers with.
+      entries: (data.entries ?? []).map(withReadFields),
       hasMore: data.hasMore ?? false,
       nextCursor: data.nextCursor ?? null,
     };
@@ -97,12 +101,45 @@ class RemoteStore {
     const data = res.data ?? {};
     return {
       ok: true,
-      entries: data.entries ?? [],
+      entries: (data.entries ?? []).map(withReadFields),
       hasMore: data.hasMore ?? false,
       nextCursor: data.nextCursor ?? null,
     };
   }
 
+  // Top-K lessons RANKED for a query — `GET /memories/relevant`.
+  //
+  // The difference from `search()` is the ordering, and it is the whole point:
+  // search returns what MATCHES (ordered `updated_at desc` by the handler),
+  // this returns what is worth READING, scored on recency + salience +
+  // relevance by the same ranking the SessionStart hook applies. It answers in
+  // a compact index — scope, key, a one-line hook, the score — never full
+  // bodies, so a caller pays for the shortlist and fetches only what it wants.
+  //
+  // `scopes` is ordered MOST-SPECIFIC FIRST and that order is meaningful: the
+  // server uses it to break ties, so passing `deriveScope().readOrder` verbatim
+  // gives a project lesson precedence over the global one it ties with.
+  //
+  // Returns the store's standard `{ ok, entries }` envelope so a caller can
+  // treat it like any other read, plus `candidates` — how many the FTS matched
+  // before ranking — so it can say "3 of 47" rather than implying it saw
+  // everything.
+  async relevant({ q, scopes, limit, minScore } = {}) {
+    const p = new URLSearchParams();
+    if (q) p.set('q', q);
+    if (scopes?.length) p.set('scopes', Array.isArray(scopes) ? scopes.join(',') : scopes);
+    if (limit) p.set('limit', String(limit));
+    if (minScore != null) p.set('min_score', String(minScore));
+    const res = await this._rest(`/memories/relevant?${p}`);
+    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
+    const data = res.data ?? {};
+    return {
+      ok: true,
+      entries: Array.isArray(data.entries) ? data.entries : [],
+      candidates: Number(data.candidates) || 0,
+    };
+  }
+
   async read({ scope, key } = {}) {
     const p = new URLSearchParams();
     if (scope) p.set('scope', scope);
@@ -112,7 +149,9 @@ class RemoteStore {
     const res = await this._rest(`/memories?${p}`);
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
     const entries = res.data?.entries ?? [];
-    return { ok: true, entry: entries[0] ?? null };
+    // Same projection as list/search — a single read must not answer with a
+    // different shape than the listing the caller found the key in.
+    return { ok: true, entry: entries[0] ? withReadFields(entries[0]) : null };
   }
 
   async write(args = {}) {

package/src/tree.mjs

@@ -9,9 +9,16 @@
 // first) and keeps the FIRST value seen per key, so a more-specific scope
 // shadows a broader scope's same-key lesson. `tree` resolves over that same
 // `readOrder` set via the pure `resolvePrecedence`, so it shows the same
-// resolution order the agent is injected with (the hook additionally caps the
-// injected set at MAX_LESSONS; `tree` is uncapped, so a large workspace may list
-// more winners than the hook injects).
+// RESOLUTION — which copy of a key wins and which are shadowed — that the agent
+// is injected under.
+//
+// It does NOT show the injected ORDER. The hook ranks the precedence winners
+// with the pure `rankLessons` (recency + salience + relevance, scope only a
+// tiebreak) and then spends a character budget on them
+// (`hooks.sessionStart.maxChars`), so what the agent reads first is the
+// scorer's order, not `readOrder`'s. `tree` stays a precedence view: unbudgeted,
+// unranked, grouped narrow→broad, so a large workspace may list more winners
+// than the hook injects and in a different order.
 //
 // NOTE on scope coverage: `readOrder` is the injected set. As of the smart-hooks
 // PR it INCLUDES `project::` (project is the most-specific scope and now wins /