@lorekit/cli 1.64.1 → 1.65.0

package/bin/lorekit.mjs

@@ -103,7 +103,7 @@ ${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].
+              --scope <s> [+ --min-age-days/--unseen-days/--max-seen-count/--max-read-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.
@@ -899,7 +899,7 @@ ${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>] [--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]
 
 Resolves the SAME candidates a saved policy or an inline condition set would
 catch, via the retention-policy candidate query — a previewed count always
@@ -918,7 +918,9 @@ ${c.bold('Options')}
       --scope <s>            Inline scope to match (mutually exclusive with --policy-id)
       --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
+      --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
       --run                  Archive the matches instead of previewing
   -y, --yes                  Confirm --run; required when non-interactive
       --json                 Machine-readable result
@@ -932,12 +934,13 @@ ${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>]
   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). \`mode: review\` surfaces it for
+(min-age-days / unseen-days / max-seen-count / max-read-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.
@@ -949,9 +952,9 @@ ${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>
+      --min-age-days <n>, --unseen-days <n>, --max-seen-count <n>, --max-read-count <n>
                              Conditions (create/update)
-      --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count
+      --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count, --clear-max-read-count
                              Remove a condition (update only)
   -y, --yes                  Confirm delete; required when non-interactive
       --json                 Machine-readable result
@@ -1071,9 +1074,9 @@ const KNOWN_FLAGS = [
   // `invariants candidates`
   'min-seen-count',
   // groom / policy / protect / pin / unpin
-  'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'run',
+  'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'run',
   'name', 'mode', 'enabled', 'disabled',
-  'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'off',
+  'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'off',
   // `obligations`
   'files', 'strict', 'strict-all',
 ];
@@ -1088,7 +1091,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', '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', 'strict', 'strict-all'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/src/commands/groom.mjs

@@ -29,6 +29,8 @@ export function parseGroomRequest(args) {
   if (unseen.error) return { error: unseen.error };
   const maxSeen = parseIntFlag(args['max-seen-count'], 'max-seen-count');
   if (maxSeen.error) return { error: maxSeen.error };
+  const maxRead = parseIntFlag(args['max-read-count'], 'max-read-count');
+  if (maxRead.error) return { error: maxRead.error };
 
   return {
     request: {
@@ -36,6 +38,7 @@ export function parseGroomRequest(args) {
       min_age_days: minAge.value,
       unseen_days: unseen.value,
       max_seen_count: maxSeen.value,
+      max_read_count: maxRead.value,
     },
   };
 }

package/src/commands/policy.mjs

@@ -30,6 +30,7 @@ function formatPolicy(p) {
   if (p.min_age_days != null) conditions.push(`min_age_days=${p.min_age_days}`);
   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}`);
   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(', '))}` : ''}`;
 }
@@ -50,7 +51,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]`);
+    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]`);
     return 1;
   }
   const minAge = parseIntFlag(args['min-age-days'], 'min-age-days');
@@ -59,6 +60,8 @@ async function create(args, store) {
   if (unseen.error) { err(`${c.red('Error:')} ${unseen.error}`); return 1; }
   const maxSeen = parseIntFlag(args['max-seen-count'], 'max-seen-count');
   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; }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
     err(`${c.red('Error:')} --mode must be "review" or "auto"`);
     return 1;
@@ -72,6 +75,7 @@ async function create(args, store) {
     min_age_days: minAge.value,
     unseen_days: unseen.value,
     max_seen_count: maxSeen.value,
+    max_read_count: maxRead.value,
   });
   if (!res.ok) {
     const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
@@ -87,7 +91,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]`);
+    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]`);
     return 1;
   }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
@@ -104,6 +108,7 @@ async function update(args, store) {
     ['min-age-days', 'clear-min-age-days', 'min_age_days'],
     ['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'],
   ]) {
     if (args[clearFlag]) { patch[field] = null; continue; }
     if (args[flag] === undefined) continue;

package/src/shared/completions.mjs

@@ -77,6 +77,7 @@ 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' },
   run: { desc: 'Archive the matches instead of previewing' },
   name: { desc: 'Policy name', arg: 'name' },
   enabled: { desc: 'Turn auto-mode on' },
@@ -84,6 +85,7 @@ const FLAG = {
   'clear-min-age-days': { desc: 'Remove the min-age-days condition' },
   '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' },
   off: { desc: 'Unprotect instead of protect' },
 };
 
@@ -151,11 +153,11 @@ 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', 'run', 'yes', 'json', 'endpoint', 'token'] },
+    flags: ['policy-id', 'scope', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-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',
-      'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'yes', 'json', 'endpoint', 'token'] },
+    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'] },
   { 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

@@ -707,8 +707,8 @@ class RemoteStore {
   }
 
   // POST /policies → the created policy object.
-  async policyCreate({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count } = {}) {
-    const body = stripUndefined({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count });
+  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 });
     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 +735,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 } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count });
+  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 });
     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 +744,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 } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count });
+  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 });
     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

@@ -521,7 +521,7 @@ export const MCP_TOOL_DEFS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 3650,
-          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count). A never-opened lesson always matches."
+          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count). A never-opened lesson is measured from its creation date, so it matches only once it is itself this old."
         },
         "max_seen_count": {
           "type": "integer",
@@ -529,6 +529,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons that have recurred at most this many times."
         },
+        "max_read_count": {
+          "type": "integer",
+          "minimum": 0,
+          "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."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -700,7 +706,7 @@ export const MCP_TOOL_DEFS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 3650,
-          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count). Omit to leave unchanged; pass explicit null to clear."
+          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count); a never-opened lesson is measured from its creation date. Omit to leave unchanged; pass explicit null to clear."
         },
         "max_seen_count": {
           "type": "integer",
@@ -708,6 +714,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons that have recurred at most this many times. Omit to leave unchanged; pass explicit null to clear."
         },
+        "max_read_count": {
+          "type": "integer",
+          "minimum": 0,
+          "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."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -880,7 +892,7 @@ export const MCP_TOOL_DEFS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 3650,
-          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count). A never-opened lesson always matches."
+          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count). A never-opened lesson is measured from its creation date, so it matches only once it is itself this old."
         },
         "max_seen_count": {
           "type": "integer",
@@ -888,6 +900,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons that have recurred at most this many times."
         },
+        "max_read_count": {
+          "type": "integer",
+          "minimum": 0,
+          "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."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -1044,7 +1062,7 @@ export const MCP_TOOL_DEFS = [
           "type": "integer",
           "minimum": 1,
           "maximum": 3650,
-          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count). A never-opened lesson always matches."
+          "description": "Match lessons not individually opened via MCP or the CLI for at least this many days (a bulk list/search result or a dashboard view does not count). A never-opened lesson is measured from its creation date, so it matches only once it is itself this old."
         },
         "max_seen_count": {
           "type": "integer",
@@ -1052,6 +1070,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons that have recurred at most this many times."
         },
+        "max_read_count": {
+          "type": "integer",
+          "minimum": 0,
+          "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."
+        },
         "tags": {
           "type": "array",
           "items": {