@lorekit/cli 1.66.0 → 1.67.0

package/bin/lorekit.mjs

@@ -103,7 +103,8 @@ ${c.bold('Commands')}
               purge: remote only, account-wide, irreversible, --yes required
               non-interactively. Takes no options.
   groom       Preview (default) or --run a retention sweep: --policy-id <id> or
-              --scope <s> [+ --min-age-days/--unseen-days/--max-seen-count/--max-read-count].
+              --scope <s> [+ --min-age-days/--unseen-days/--max-seen-count/
+              --max-read-count/--max-opened-count].
               Remote only. --run soft-archives matches (recoverable via
               restore); prompts for confirmation, --yes to skip. --json.
   policy      Manage saved retention rules: list / create / update / delete.
@@ -385,6 +386,7 @@ ${c.bold('Options')}
       --ttl-days <n>       Days until auto-expiry 1–365 (local or remote)
       --clear-ttl          Remove any existing expiry (make it permanent)
       --org <slug>         Write to this org's scope (remote only)
+      --cited <a,b>        \`scope::key\` refs this lesson applied (remote only)
       --origin-repo <o/n>  Override the derived provenance repository
       --origin-branch <b>  Override the derived provenance branch
       --origin-commit <s>  Override the derived provenance commit SHA
@@ -899,7 +901,8 @@ ${c.bold('Options')}
 
 ${c.bold('Usage')}
   lorekit groom --policy-id <id> [--run] [--yes] [--json]
-  lorekit groom --scope <s> [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>] [--max-read-count <n>] [--run] [--yes] [--json]
+  lorekit groom --scope <s> [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>]
+                            [--max-read-count <n>] [--max-opened-count <n>] [--run] [--yes] [--json]
 
 Resolves the SAME candidates a saved policy or an inline condition set would
 catch, via the retention-policy candidate query — a previewed count always
@@ -919,8 +922,11 @@ ${c.bold('Options')}
       --min-age-days <n>     Match only lessons at least n days old
       --unseen-days <n>      Match lessons unseen for at least n days (never-seen always matches)
       --max-seen-count <n>   Match only lessons that recurred at most n times (WRITES)
-      --max-read-count <n>   Match only lessons READ at most n times. Bulk list/search
-                             reads count here, unlike --unseen-days
+      --max-read-count <n>   Match only lessons DELIVERED at most n times. Bulk list/search
+                             reads count here, unlike --unseen-days, so this runs to
+                             the hundreds — a small value matches nothing
+      --max-opened-count <n> Match only lessons an agent DELIBERATELY fetched at most n
+                             times. Bulk reads do NOT count, so 0 means never chosen
       --run                  Archive the matches instead of previewing
   -y, --yes                  Confirm --run; required when non-interactive
       --json                 Machine-readable result
@@ -934,13 +940,14 @@ ${c.bold('Usage')}
   lorekit policy list [--json]
   lorekit policy create --scope <s> --name <n> [--mode review|auto] [--enabled]
                          [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>]
-                         [--max-read-count <n>]
+                         [--max-read-count <n>] [--max-opened-count <n>]
   lorekit policy update <id> [--name <n>] [--mode review|auto] [--enabled|--disabled]
                          [--min-age-days <n>|--clear-min-age-days] [...] [--json]
   lorekit policy delete <id> [--yes] [--json]
 
 A policy is a saved retention rule: a scope plus AND-ed conditions
-(min-age-days / unseen-days / max-seen-count / max-read-count). \`mode: review\` surfaces it for
+(min-age-days / unseen-days / max-seen-count / max-read-count / max-opened-count).
+\`mode: review\` surfaces it for
 you to run by hand with ${c.cyan('lorekit groom --policy-id')}; \`mode: auto\` gets swept
 nightly, but ONLY once you also pass --enabled — auto starts disabled on
 every new policy so a saved rule never archives anything unattended.
@@ -952,9 +959,11 @@ ${c.bold('Options')}
       --name <n>             Policy name (create) / new name (update)
       --mode <review|auto>   Match mode (create/update)
       --enabled / --disabled Turn auto-mode on/off (create/update)
-      --min-age-days <n>, --unseen-days <n>, --max-seen-count <n>, --max-read-count <n>
+      --min-age-days <n>, --unseen-days <n>, --max-seen-count <n>, --max-read-count <n>,
+      --max-opened-count <n>
                              Conditions (create/update)
-      --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count, --clear-max-read-count
+      --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count,
+      --clear-max-read-count, --clear-max-opened-count
                              Remove a condition (update only)
   -y, --yes                  Confirm delete; required when non-interactive
       --json                 Machine-readable result
@@ -1059,7 +1068,8 @@ const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'mcp-json', 'completions', 'complete', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'key', 'threshold', 'help', 'version', 'telemetry',
-  'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
+  'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'cited',
+  'remote', 'local',
   // `view` is accepted-and-IGNORED, not documented: the Explorer dropped the
   // scope/time tab so the flag is a no-op, but `link` is a HUMAN_COMMAND that
   // rejects UNKNOWN options — so keeping `view` listed for a release stops an
@@ -1074,9 +1084,10 @@ const KNOWN_FLAGS = [
   // `invariants candidates`
   'min-seen-count',
   // groom / policy / protect / pin / unpin
-  'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'run',
+  'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'max-opened-count', 'run',
   'name', 'mode', 'enabled', 'disabled',
-  'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'off',
+  'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count',
+  'clear-max-opened-count', 'off',
   // `obligations`
   'files', 'strict', 'strict-all',
 ];
@@ -1091,7 +1102,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'strict', 'strict-all'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'clear-max-opened-count', 'strict', 'strict-all'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/skill/lorekit-memory/rules/retrospective.md

@@ -69,7 +69,8 @@ memory.write {
   value:        "<observation in markdown>",
   tags:         ["skill::lorekit-memory", "source::stuck-loop"],
   source_agent: "<your agent name, if known>",
-  trigger:      "stuck-loop"
+  trigger:      "stuck-loop",
+  cited:        ["global::pnpm-first"]
 }
 ```
 
@@ -77,6 +78,25 @@ Pick `trigger` / `source::*` from what actually happened:
 `stuck-loop`, `command-failure`, `gotcha`, `near-miss`, `assumption-wrong`,
 `paid-off`, or `manual`.
 
+## 6b. Credit the lessons you actually applied
+
+`cited` is a list of `scope::key` references to lessons that **shaped this
+turn** — ones you were shown at session start or looked up, and then acted on.
+Omit it when nothing applied.
+
+This is the only signal that distinguishes a lesson that was *used* from one
+that was merely *shown*. LoreKit can count deliveries and deliberate fetches on
+its own, but a lesson injected at session start is already in your context and
+gets applied without ever being fetched again — so nothing but you can report it.
+
+- **Name only what you used.** Citing everything you were shown makes the
+  counter measure delivery again, which it already does.
+- **A wrong guess costs nothing.** A reference that does not resolve is dropped
+  silently, and a lesson cannot cite itself. Naming a lesson you are unsure of
+  is cheaper than omitting one you relied on.
+- **Copy the ref exactly as it was shown to you** (`global::pnpm-first`,
+  `repo::acme/app::migration-order`). Do not reconstruct it from memory.
+
 ## 7. Confirm
 
 State in one line what you recorded and where

package/src/commands/groom.mjs

@@ -31,6 +31,8 @@ export function parseGroomRequest(args) {
   if (maxSeen.error) return { error: maxSeen.error };
   const maxRead = parseIntFlag(args['max-read-count'], 'max-read-count');
   if (maxRead.error) return { error: maxRead.error };
+  const maxOpened = parseIntFlag(args['max-opened-count'], 'max-opened-count');
+  if (maxOpened.error) return { error: maxOpened.error };
 
   return {
     request: {
@@ -39,6 +41,7 @@ export function parseGroomRequest(args) {
       unseen_days: unseen.value,
       max_seen_count: maxSeen.value,
       max_read_count: maxRead.value,
+      max_opened_count: maxOpened.value,
     },
   };
 }

package/src/commands/hook.mjs

@@ -333,7 +333,11 @@ async function run(args, meter) {
     }
     if (!shouldRetrospect(stopMode, friction)) return 0;
     if (!firstTimeThisSession(parsed.sessionId, 'retro')) return 0;
-    emit(retrospectiveNudge(scope, control, { reasons }));
+    // The shown set is what BOTH injection paths recorded this session, so the
+    // citation ask names the actual candidates rather than a convention. Read
+    // here and not earlier: every return above this line emits nothing, and the
+    // read is a file the throttled path should not pay for.
+    emit(retrospectiveNudge(scope, control, { reasons, shown: [...shownLessons(parsed.sessionId)] }));
     return 0;
   }
 

package/src/commands/policy.mjs

@@ -31,6 +31,7 @@ function formatPolicy(p) {
   if (p.unseen_days != null) conditions.push(`unseen_days=${p.unseen_days}`);
   if (p.max_seen_count != null) conditions.push(`max_seen_count=${p.max_seen_count}`);
   if (p.max_read_count != null) conditions.push(`max_read_count=${p.max_read_count}`);
+  if (p.max_opened_count != null) conditions.push(`max_opened_count=${p.max_opened_count}`);
   const mode = p.mode === 'auto' ? (p.enabled ? c.green('auto (enabled)') : c.dim('auto (disabled)')) : c.dim('review');
   return `${c.cyan(p.id)}  ${c.bold(p.name)}  ${c.dim(p.scope)}  ${mode}${conditions.length ? `  ${c.dim(conditions.join(', '))}` : ''}`;
 }
@@ -51,7 +52,7 @@ async function list(args, store) {
 
 async function create(args, store) {
   if (!args.scope || !args.name) {
-    err(`${c.red('Usage:')} lorekit policy create --scope <scope> --name <name> [--mode review|auto] [--enabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N]`);
+    err(`${c.red('Usage:')} lorekit policy create --scope <scope> --name <name> [--mode review|auto] [--enabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N] [--max-opened-count N]`);
     return 1;
   }
   const minAge = parseIntFlag(args['min-age-days'], 'min-age-days');
@@ -62,6 +63,8 @@ async function create(args, store) {
   if (maxSeen.error) { err(`${c.red('Error:')} ${maxSeen.error}`); return 1; }
   const maxRead = parseIntFlag(args['max-read-count'], 'max-read-count');
   if (maxRead.error) { err(`${c.red('Error:')} ${maxRead.error}`); return 1; }
+  const maxOpened = parseIntFlag(args['max-opened-count'], 'max-opened-count');
+  if (maxOpened.error) { err(`${c.red('Error:')} ${maxOpened.error}`); return 1; }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
     err(`${c.red('Error:')} --mode must be "review" or "auto"`);
     return 1;
@@ -76,6 +79,7 @@ async function create(args, store) {
     unseen_days: unseen.value,
     max_seen_count: maxSeen.value,
     max_read_count: maxRead.value,
+    max_opened_count: maxOpened.value,
   });
   if (!res.ok) {
     const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
@@ -91,7 +95,7 @@ async function create(args, store) {
 async function update(args, store) {
   const id = args._[2];
   if (!id) {
-    err(`${c.red('Usage:')} lorekit policy update <id> [--name N] [--mode review|auto] [--enabled|--disabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N]`);
+    err(`${c.red('Usage:')} lorekit policy update <id> [--name N] [--mode review|auto] [--enabled|--disabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N] [--max-opened-count N]`);
     return 1;
   }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
@@ -109,6 +113,7 @@ async function update(args, store) {
     ['unseen-days', 'clear-unseen-days', 'unseen_days'],
     ['max-seen-count', 'clear-max-seen-count', 'max_seen_count'],
     ['max-read-count', 'clear-max-read-count', 'max_read_count'],
+    ['max-opened-count', 'clear-max-opened-count', 'max_opened_count'],
   ]) {
     if (args[clearFlag]) { patch[field] = null; continue; }
     if (args[flag] === undefined) continue;

package/src/commands/write.mjs

@@ -29,6 +29,14 @@
 //                          omitted, a configured default may apply — see below.
 //   --clear-ttl            Remove any existing expiry (make the memory permanent)
 //   --org <slug>           Write to this org (remote only)
+//   --cited <ref,ref>      `scope::key` refs this lesson APPLIED (remote only)
+//
+// `--cited` credits the lore that shaped the work being written up. It is the
+// only signal that distinguishes a lesson that was read from one that was used:
+// a lesson injected at SessionStart is already in context and is applied without
+// ever being fetched, so the delivered/chosen ratio cannot see it. Unresolvable
+// refs cost nothing — the server drops them — so naming a lesson you are unsure
+// of is cheaper than omitting one you relied on.
 //
 // Provenance — where the lesson is being recorded FROM. Derived automatically
 // from git + the CI environment (repo, branch, commit, and the pull request
@@ -222,6 +230,16 @@ export async function write(args) {
 
   const orgSlug = typeof args.org === 'string' ? args.org : undefined;
 
+  // Split on commas like `--tags`, so there is one list-flag convention. The
+  // refs themselves are NOT parsed here: `scope::key` splits on the first `::`
+  // whose left half is a legal scope, a rule that lives once in
+  // `parseMemoryRef` (mcp-core + its edge mirror) and would become a second,
+  // weaker implementation if this seam guessed at it. A ref this command cannot
+  // resolve is dropped server-side, silently and by design.
+  const cited = args.cited
+    ? String(args.cited).split(',').map((r) => r.trim()).filter(Boolean)
+    : [];
+
   // ── Provenance ────────────────────────────────────────────────────────────
   // Derived from git + CI unless --no-origin; explicit --origin-* flags win.
   // A field that is neither supplied nor derivable is omitted, never sent as
@@ -300,6 +318,16 @@ export async function write(args) {
     return 1;
   }
 
+  // The offline store has no citation ledger — migration 00107's table lives in
+  // Postgres — so a local write would accept the flag and record nothing. Named
+  // rather than dropped: a credit that silently went nowhere is invisible in
+  // exactly the place the whole signal exists to be visible.
+  if (cited.length && storeName === 'local') {
+    err(`${c.red('Error:')} --cited is remote-only (the offline store records no citations)`);
+    err(`Re-run with ${c.cyan('--remote')}, or drop --cited to write the lesson locally.`);
+    return 1;
+  }
+
   // ── Write ──────────────────────────────────────────────────────────────────
   const writeArgs = {
     scope,
@@ -313,6 +341,7 @@ export async function write(args) {
     ...(ttlDays ? { ttl_days: ttlDays } : {}),
     ...(clearTtl ? { clear_ttl: true } : {}),
     ...(orgSlug ? { org: orgSlug } : {}),
+    ...(cited.length ? { cited } : {}),
     ...origin,
   };
 
@@ -346,6 +375,7 @@ export async function write(args) {
       trigger: trigger || null,
       ttl_days: reportedTtlDays,
       ttl_source: reportedTtlSource,
+      cited,
       origin,
     }, null, 2));
   } else {

package/src/core/lessons.mjs

@@ -828,6 +828,43 @@ function ttlHint(writeScope, control) {
   return ` Set ttl_days: ${days} (this scope's configured default) unless the lesson is durable enough to keep forever.`;
 }
 
+// How many injected lesson refs the citation hint names before it summarises the
+// rest. The nudge competes for the same context the lessons themselves occupy, so
+// the list is a prompt for recall, not an inventory — an agent that applied a
+// lesson beyond the cap can still name it, because `cited` takes any ref.
+export const CITED_HINT_MAX = 8;
+
+// Build the citation clause appended to the retrospective nudge, from the
+// `scope::key` ids this session has already injected (core/state.mjs's shown
+// set). Empty string when nothing was injected — with no candidates the ask
+// would be an instruction to invent references.
+//
+// WHY THE ASK EXISTS. `opened_count / read_count` measures whether a lesson was
+// deliberately FETCHED, and a lesson injected at SessionStart is already in
+// context and gets applied without ever being fetched. So the ratio under-counts
+// the dominant delivery path by construction, and only the agent knows the
+// difference. `cited` (migration 00107) is where it says so.
+//
+// The ids are taken in the store's own order, which is injection order, so the
+// SessionStart set leads — it is both the largest and the one in context for the
+// whole turn. Taking the newest instead would favour a per-prompt injection that
+// arrived seconds before the nudge.
+export function citationHint(shown) {
+  const ids = (Array.isArray(shown) ? shown : [...(shown || [])]).filter(
+    (id) => typeof id === 'string' && id.length > 0,
+  );
+  if (ids.length === 0) return '';
+  const named = ids.slice(0, CITED_HINT_MAX);
+  const rest = ids.length - named.length;
+  const more = rest > 0 ? ` (+${rest} more)` : '';
+  return (
+    ` If any injected lesson shaped this turn, name it on the write as` +
+    ` cited: [${named.map((id) => JSON.stringify(id)).join(', ')}]${more} —` +
+    ` drop the ones you did not use. LoreKit can see which lessons were delivered,` +
+    ` never which were applied; this is the only signal that says so.`
+  );
+}
+
 // One-line phrases for the detected friction reason codes (see core/friction.mjs),
 // so the nudge names what happened instead of a generic prompt.
 const REASON_PHRASES = {
@@ -851,11 +888,14 @@ function describeReasons(reasons) {
 // scopeDefaults when the repo/user config defines them. `opts.reasons` is the
 // detected friction reason codes (from core/friction.mjs) when `hooks.stop` is
 // `friction`; when present the nudge names them so the reflection is grounded.
-// Kept to a single line — the lore deep-link lives on the write CONFIRMATION,
-// which is where a link is actually actionable.
-export function retrospectiveNudge(scope, control, { reasons = [] } = {}) {
+// `opts.shown` is the session's injected `scope::key` set (core/state.mjs), which
+// turns the citation ask into a list the agent can pick from rather than a
+// convention it has to remember; omitting it drops the clause entirely.
+// The lore deep-link lives on the write CONFIRMATION, which is where a link is
+// actually actionable.
+export function retrospectiveNudge(scope, control, { reasons = [], shown = [] } = {}) {
   const writeScope = scope.repoScope || 'global';
-  const hint = `${tagsHint(writeScope, control)}${ttlHint(writeScope, control)}`;
+  const hint = `${tagsHint(writeScope, control)}${ttlHint(writeScope, control)}${citationHint(shown)}`;
   const instruction = control && control.hooksInstructions && control.hooksInstructions.Stop
     ? `\n\nProject instruction: ${control.hooksInstructions.Stop}` : '';
   const detected = describeReasons(reasons);

package/src/shared/completions.mjs

@@ -55,6 +55,7 @@ const FLAG = {
   'ttl-days': { desc: 'Days until auto-expiry (1..365)', arg: 'n' },
   'clear-ttl': { desc: 'Remove any existing expiry' },
   org: { desc: "Write to this org's scope (remote)", arg: 'slug' },
+  cited: { desc: 'scope::key refs this lesson applied (remote)', arg: 'a,b' },
   'origin-repo': { desc: 'Override the provenance repository', arg: 'owner/name' },
   'origin-branch': { desc: 'Override the provenance branch', arg: 'branch' },
   'origin-commit': { desc: 'Override the provenance commit', arg: 'sha' },
@@ -77,7 +78,8 @@ const FLAG = {
   'min-age-days': { desc: 'Match lessons at least n days old', arg: 'n' },
   'unseen-days': { desc: 'Match lessons unseen for at least n days', arg: 'n' },
   'max-seen-count': { desc: 'Match lessons that recurred at most n times', arg: 'n' },
-  'max-read-count': { desc: 'Match lessons read at most n times (bulk reads count)', arg: 'n' },
+  'max-read-count': { desc: 'Match lessons delivered at most n times (bulk reads count)', arg: 'n' },
+  'max-opened-count': { desc: 'Match lessons deliberately fetched at most n times (0 = never chosen)', arg: 'n' },
   run: { desc: 'Archive the matches instead of previewing' },
   name: { desc: 'Policy name', arg: 'name' },
   enabled: { desc: 'Turn auto-mode on' },
@@ -86,6 +88,7 @@ const FLAG = {
   'clear-unseen-days': { desc: 'Remove the unseen-days condition' },
   'clear-max-seen-count': { desc: 'Remove the max-seen-count condition' },
   'clear-max-read-count': { desc: 'Remove the max-read-count condition' },
+  'clear-max-opened-count': { desc: 'Remove the max-opened-count condition' },
   off: { desc: 'Unprotect instead of protect' },
 };
 
@@ -138,7 +141,7 @@ const COMMANDS = [
     flags: ['yes', 'endpoint', 'token'] },
   { name: 'write', summary: 'Create or update a memory', positional: 'address',
     flags: ['dir', 'scope', 'key', 'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'clear-ttl',
-      'org', 'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin', 'remote', 'local',
+      'org', 'cited', 'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin', 'remote', 'local',
       'json', 'endpoint', 'token', 'store'] },
   { name: 'archive', summary: 'Hide a memory without losing it', positional: 'address',
     flags: ['scope', 'key', 'remote', 'local', 'json'] },
@@ -153,11 +156,13 @@ const COMMANDS = [
     flags: ['yes', 'json', 'endpoint', 'token'] },
   { name: 'groom', summary: 'Preview or run a retention sweep',
     values: { mode: ['review', 'auto'] },
-    flags: ['policy-id', 'scope', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'run', 'yes', 'json', 'endpoint', 'token'] },
+    flags: ['policy-id', 'scope', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'max-opened-count',
+      'run', 'yes', 'json', 'endpoint', 'token'] },
   { name: 'policy', summary: 'Manage saved retention rules',
     values: { mode: ['review', 'auto'] },
     flags: ['scope', 'name', 'mode', 'enabled', 'disabled', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count',
-      'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'yes', 'json', 'endpoint', 'token'] },
+      'max-opened-count', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count',
+      'clear-max-opened-count', 'yes', 'json', 'endpoint', 'token'] },
   { name: 'protect', summary: 'Mark a memory protected, excluded from every grooming sweep', positional: 'address',
     flags: ['off', 'scope', 'key', 'json', 'endpoint', 'token'] },
   { name: 'pin', summary: 'Shorthand for `protect` (protected=true)', positional: 'address',

package/src/store/remote.mjs

@@ -283,7 +283,7 @@ class RemoteStore {
   async write(args = {}) {
     const {
       scope, key, value, tags, source_agent, trigger, kind, host, org, ttl_days, clear_ttl, created_at,
-      origin_repo, origin_branch, origin_commit, origin_pr,
+      cited, origin_repo, origin_branch, origin_commit, origin_pr,
     } = args;
     const body = { scope, key, value };
     if (tags !== undefined) body.tags = tags;
@@ -295,6 +295,11 @@ class RemoteStore {
     if (ttl_days !== undefined) body.ttl_days = ttl_days;
     if (clear_ttl !== undefined) body.clear_ttl = clear_ttl;
     if (created_at !== undefined) body.created_at = created_at;
+    // Citations are a fact about the RUN this write belongs to, not a column on
+    // the row (migration 00107) — the server resolves each ref, records the
+    // credit, and drops what it cannot resolve. Sent verbatim: which refs are
+    // legal is the server's grammar to decide, not this transport's.
+    if (cited !== undefined) body.cited = cited;
     // Provenance — only sent when known. Omitting a field leaves whatever the
     // row already recorded intact (the RPC coalesces), which is what makes a
     // write from a machine with no git context non-destructive.
@@ -707,8 +712,8 @@ class RemoteStore {
   }
 
   // POST /policies → the created policy object.
-  async policyCreate({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count } = {}) {
-    const body = stripUndefined({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count });
+  async policyCreate({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
+    const body = stripUndefined({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
     const res = await this._rest('/memories/policies', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, policy: res.data };
@@ -735,8 +740,8 @@ class RemoteStore {
   // POST /groom/preview → { count, keys: [{ scope, key }] } — the SAME
   // candidates a groom() run would archive. Pass either `policy_id` or
   // `scope` (+ optional conditions), never both.
-  async groomPreview({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count });
+  async groomPreview({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
+    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
     const res = await this._rest('/memories/groom/preview', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, count: res.data?.count ?? 0, keys: Array.isArray(res.data?.keys) ? res.data.keys : [] };
@@ -744,8 +749,8 @@ class RemoteStore {
 
   // POST /groom/run → archives every previewed candidate, in one transaction.
   // Soft-archive only (recoverable via restore); never hard-deletes.
-  async groomRun({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count });
+  async groomRun({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
+    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
     const res = await this._rest('/memories/groom/run', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, archived: res.data?.archived ?? 0, keys: Array.isArray(res.data?.keys) ? res.data.keys : [] };

package/src/surfaces.generated.mjs

@@ -147,6 +147,13 @@ export const MCP_TOOL_DEFS = [
           "type": "integer",
           "minimum": 1,
           "description": "Provenance: the pull request number this memory was recorded from. Combined with origin_repo it renders as a link to the PR."
+        },
+        "cited": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The lessons that actually shaped this run, as `scope::key` strings — exactly the labels they were injected under. Name only the ones you applied; an empty or omitted list is the honest answer when none were. Silently ignored where a reference names nothing you can see, so a wrong guess costs nothing and the write always succeeds."
         }
       }
     }
@@ -535,6 +542,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -720,6 +733,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned. Omit to leave unchanged; pass explicit null to clear."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat. Omit to leave unchanged; pass explicit null to clear."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -906,6 +925,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -1076,6 +1101,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat."
+        },
         "tags": {
           "type": "array",
           "items": {