@lorekit/cli 1.57.0 → 1.59.0

package/bin/lorekit.mjs

@@ -97,6 +97,18 @@ ${c.bold('Commands')}
               Permanently delete every TTL-EXPIRED memory. Same posture as
               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].
+              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.
+              policy create --scope <s> --name <n> [--mode review|auto]
+              [--enabled] [conditions...]. policy update <id> [fields...].
+              policy delete <id> [--yes]. Remote only. --json.
+  protect     Mark a memory protected — excluded from every grooming sweep
+              regardless of policy. protect <scope::key> [--off] to unprotect.
+              Remote only. --json.
+  pin / unpin Shorthand for protect / protect --off. Remote only. --json.
   bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
               Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
               See docs/byod.md for setup instructions.
@@ -843,6 +855,108 @@ ${c.bold('Options')}
   -t, --token <token>     LoreKit token (needs write permission, unscoped)
 `,
 
+  groom: `${c.bold('lorekit groom')} — preview or run a retention sweep
+
+${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]
+
+Resolves the SAME candidates a saved policy or an inline condition set would
+catch, via the retention-policy candidate query — a previewed count always
+equals what --run would archive. Exactly one of --policy-id or --scope is
+required.
+
+Default (no --run) PREVIEWS: prints the count and up to 20 matching keys,
+changes nothing. --run ARCHIVES them (soft-archive, recoverable via
+${c.cyan('lorekit restore')}) — prompts for confirmation first, ${c.cyan('--yes')} to skip
+non-interactively.
+
+Remote only — retention policies have no local-store equivalent.
+
+${c.bold('Options')}
+      --policy-id <id>       Run/preview a saved policy (mutually exclusive with --scope)
+      --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
+      --run                  Archive the matches instead of previewing
+  -y, --yes                  Confirm --run; required when non-interactive
+      --json                 Machine-readable result
+  -e, --endpoint <url>       LoreKit endpoint (else LOREKIT_MCP_URL)
+  -t, --token <token>        LoreKit token (needs write permission for --run)
+`,
+
+  policy: `${c.bold('lorekit policy')} — manage saved retention rules
+
+${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>]
+  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
+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.
+
+Remote only — retention_policies has no local-store equivalent.
+
+${c.bold('Options')}
+      --scope <s>            Scope the policy matches (create)
+      --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>
+                             Conditions (create/update)
+      --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count
+                             Remove a condition (update only)
+  -y, --yes                  Confirm delete; required when non-interactive
+      --json                 Machine-readable result
+  -e, --endpoint <url>       LoreKit endpoint (else LOREKIT_MCP_URL)
+  -t, --token <token>        LoreKit token (needs write permission for create/update/delete)
+`,
+
+  protect: `${c.bold('lorekit protect')} — exclude a memory from every grooming sweep
+
+${c.bold('Usage')}
+  lorekit protect <scope::key> [--off] [--json]
+  lorekit protect <scope> <key> [--off] [--json]
+
+Marks (or, with --off, unmarks) a lesson as protected: excluded from
+${c.cyan('lorekit groom')} and every retention policy's candidate set, regardless of
+which policy would otherwise have matched it. See also ${c.cyan('lorekit pin')} /
+${c.cyan('lorekit unpin')}, the same operation under shorter names.
+
+Remote only.
+
+${c.bold('Options')}
+      --off                  Unprotect instead of protect
+      --scope <scope>        Name the scope explicitly, overriding the positional
+      --key <key>            Name the key explicitly
+      --json                 Machine-readable result
+  -e, --endpoint <url>       LoreKit endpoint (else LOREKIT_MCP_URL)
+  -t, --token <token>        LoreKit token (needs write permission)
+`,
+
+  pin: `${c.bold('lorekit pin')} — shorthand for \`lorekit protect\`
+
+${c.bold('Usage')}
+  lorekit pin <scope::key> [--json]
+
+Identical to \`lorekit protect <scope::key>\`. See ${c.cyan('lorekit protect --help')}.
+`,
+
+  unpin: `${c.bold('lorekit unpin')} — shorthand for \`lorekit protect --off\`
+
+${c.bold('Usage')}
+  lorekit unpin <scope::key> [--json]
+
+Identical to \`lorekit protect <scope::key> --off\`. See ${c.cyan('lorekit protect --help')}.
+`,
+
   hook: `${c.bold('lorekit hook')} — hook engine for Claude Code / Cursor / Codex
 
 ${c.bold('Usage')}
@@ -914,6 +1028,10 @@ const KNOWN_FLAGS = [
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
   // Scale-aware survey flags
   'all', 'max', 'since', 'until', 'key-prefix', 'cluster-by-key',
+  // groom / policy / protect / pin / unpin
+  'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'run',
+  'name', 'mode', 'enabled', 'disabled',
+  'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'off',
   // `obligations`
   'files', 'strict',
 ];
@@ -928,7 +1046,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', 'strict'],
+    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'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.57.0",
+  "version": "1.59.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

@@ -0,0 +1,149 @@
+// `lorekit groom` — preview or run a retention sweep.
+//
+//   groom [--policy-id ID | --scope SCOPE] [conditions...] [--dry-run]   preview candidates (default)
+//   groom [--policy-id ID | --scope SCOPE] [conditions...] --run [--yes] archive them
+//
+// Server-side only — retention policies and grooming have no local-store
+// equivalent (matching purge/purge-expired), so this command is REMOTE ONLY.
+// `--policy-id` reuses a saved rule; `--scope` + conditions build one inline.
+// Exactly one of the two is required.
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { loadControl, resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { log, err, c, select } from '../shared/util.mjs';
+import { parseIntFlag } from '../shared/flags.mjs';
+
+/** Resolve the groom.preview/groom.run request from CLI args. */
+export function parseGroomRequest(args) {
+  if (args['policy-id'] && args.scope) {
+    return { error: '--policy-id and --scope are mutually exclusive — pass one or the other' };
+  }
+  if (!args['policy-id'] && !args.scope) {
+    return { error: 'either --policy-id or --scope is required' };
+  }
+  if (args['policy-id']) return { request: { policy_id: args['policy-id'] } };
+
+  const minAge = parseIntFlag(args['min-age-days'], 'min-age-days');
+  if (minAge.error) return { error: minAge.error };
+  const unseen = parseIntFlag(args['unseen-days'], 'unseen-days');
+  if (unseen.error) return { error: unseen.error };
+  const maxSeen = parseIntFlag(args['max-seen-count'], 'max-seen-count');
+  if (maxSeen.error) return { error: maxSeen.error };
+
+  return {
+    request: {
+      scope: args.scope,
+      min_age_days: minAge.value,
+      unseen_days: unseen.value,
+      max_seen_count: maxSeen.value,
+    },
+  };
+}
+
+function pickRemote({ root, env, args }) {
+  const { remoteDenied } = resolveDenies(root, { env });
+  const { remote, connection } = resolveStores(root, { env, endpoint: args.endpoint, token: args.token });
+  if (remoteDenied) return { error: `remote store is disabled by deny constraint (${remoteDenied.source})` };
+  if (!remote.usable()) return { error: `remote store is not configured — ${remoteUnavailableReason(connection)}` };
+  return { store: remote };
+}
+
+export async function groom(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = process.env;
+  loadControl(root, { env });
+
+  const parsed = parseGroomRequest(args);
+  if (parsed.error) {
+    err(`${c.red('Error:')} ${parsed.error}`);
+    return 1;
+  }
+
+  const picked = pickRemote({ root, env, args });
+  if (picked.error) {
+    err(`${c.red('Error:')} ${picked.error}`);
+    return 1;
+  }
+
+  const run = Boolean(args.run);
+
+  // Preview is the default and is never gated — it changes nothing.
+  if (!run) {
+    const res = await picked.store.groomPreview(parsed.request);
+    if (!res.ok) {
+      const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
+      if (args.json) {
+        log(JSON.stringify({ ok: false, op: 'preview', count: null, keys: [], error: String(msg) }, null, 2));
+        return 1;
+      }
+      err(`${c.red('Error:')} ${msg}`);
+      return 1;
+    }
+    if (args.json) {
+      log(JSON.stringify({ ok: true, op: 'preview', count: res.count, keys: res.keys }, null, 2));
+      return 0;
+    }
+    log(`${c.cyan(String(res.count))} lesson${res.count === 1 ? '' : 's'} would be archived:`);
+    for (const k of res.keys.slice(0, 20)) log(`  ${c.dim(k.scope)}::${k.key}`);
+    if (res.keys.length > 20) log(c.dim(`  … and ${res.keys.length - 20} more`));
+    log(c.dim('Re-run with --run to archive them.'));
+    return 0;
+  }
+
+  // --run archives — a real, if recoverable (soft-archive), mutation. Gate it
+  // the same way as any lorekit action that changes state unattended: a
+  // preview count first, then confirm-or-`--yes`.
+  const preview = await picked.store.groomPreview(parsed.request);
+  if (!preview.ok) {
+    const msg = preview.error?.message ?? preview.error ?? preview.networkError ?? 'the server rejected the request';
+    err(`${c.red('Error:')} ${msg}`);
+    return 1;
+  }
+
+  if (preview.count === 0) {
+    if (args.json) {
+      log(JSON.stringify({ ok: true, op: 'run', archived: 0, keys: [] }, null, 2));
+      return 0;
+    }
+    log(`${c.dim('Nothing to archive — 0 lessons match.')}`);
+    return 0;
+  }
+
+  const decision = args.yes ? 'proceed' : (args.json || !process.stdin.isTTY) ? 'refuse' : 'prompt';
+  if (decision === 'refuse') {
+    err(`${c.red('Refusing:')} would archive ${preview.count} lesson${preview.count === 1 ? '' : 's'} with no terminal to confirm.`);
+    err(`Re-run with ${c.cyan('--yes')} to confirm.`);
+    return 1;
+  }
+  if (decision === 'prompt') {
+    const go = await select(
+      `${c.bold('Archive')} ${preview.count} lesson${preview.count === 1 ? '' : 's'}? Recoverable via restore.`,
+      [
+        { value: false, label: 'Cancel', hint: 'nothing is archived' },
+        { value: true, label: 'Yes, archive', hint: 'reversible' },
+      ],
+      { defaultIndex: 0 },
+    );
+    if (!go) {
+      log(`${c.dim('Cancelled — nothing was archived.')}`);
+      return 0;
+    }
+  }
+
+  const res = await picked.store.groomRun(parsed.request);
+  if (!res.ok) {
+    const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
+    if (args.json) {
+      log(JSON.stringify({ ok: false, op: 'run', archived: null, keys: [], error: String(msg) }, null, 2));
+      return 1;
+    }
+    err(`${c.red('Error:')} ${msg}`);
+    return 1;
+  }
+  if (args.json) {
+    log(JSON.stringify({ ok: true, op: 'run', archived: res.archived, keys: res.keys }, null, 2));
+    return 0;
+  }
+  log(`${c.green('✓')} archived ${c.cyan(String(res.archived))} lesson${res.archived === 1 ? '' : 's'} ${c.dim('(remote)')}`);
+  return 0;
+}

package/src/commands/policy.mjs

@@ -0,0 +1,185 @@
+// `lorekit policy <list|create|update|delete>` — manage saved retention rules.
+//
+//   policy list                                       list every saved policy
+//   policy create --scope S --name N [conditions...]   save a new rule
+//   policy update <id> [fields...]                     change a saved rule
+//   policy delete <id> [--yes]                          delete the RULE only
+//
+// Server-side only — retention_policies has no local-store equivalent
+// (matching groom/purge). `policy.create`/`update`/`delete` are catalog
+// `cliExempt` (they are actions of THIS command, not their own subcommands),
+// so only `policy.list` claims the `tool: 'memory.policy_list'`... no —
+// `policy.list` claims `tool: 'policy.list'` in the registry; the other three
+// verbs are dispatched here without a catalog tool binding of their own.
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { loadControl, resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { log, err, c, select } from '../shared/util.mjs';
+import { parseIntFlag } from '../shared/flags.mjs';
+
+function pickRemote({ root, env, args }) {
+  const { remoteDenied } = resolveDenies(root, { env });
+  const { remote, connection } = resolveStores(root, { env, endpoint: args.endpoint, token: args.token });
+  if (remoteDenied) return { error: `remote store is disabled by deny constraint (${remoteDenied.source})` };
+  if (!remote.usable()) return { error: `remote store is not configured — ${remoteUnavailableReason(connection)}` };
+  return { store: remote };
+}
+
+function formatPolicy(p) {
+  const conditions = [];
+  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}`);
+  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(', '))}` : ''}`;
+}
+
+async function list(args, store) {
+  const res = await store.policyList();
+  if (!res.ok) {
+    const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
+    if (args.json) { log(JSON.stringify({ ok: false, entries: [], error: String(msg) }, null, 2)); return 1; }
+    err(`${c.red('Error:')} ${msg}`);
+    return 1;
+  }
+  if (args.json) { log(JSON.stringify({ ok: true, entries: res.entries }, null, 2)); return 0; }
+  if (res.entries.length === 0) { log(c.dim('No retention policies yet. Create one with `lorekit policy create`.')); return 0; }
+  for (const p of res.entries) log(formatPolicy(p));
+  return 0;
+}
+
+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]`);
+    return 1;
+  }
+  const minAge = parseIntFlag(args['min-age-days'], 'min-age-days');
+  if (minAge.error) { err(`${c.red('Error:')} ${minAge.error}`); return 1; }
+  const unseen = parseIntFlag(args['unseen-days'], 'unseen-days');
+  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; }
+  if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
+    err(`${c.red('Error:')} --mode must be "review" or "auto"`);
+    return 1;
+  }
+
+  const res = await store.policyCreate({
+    scope: args.scope,
+    name: args.name,
+    mode: args.mode,
+    enabled: args.enabled ? true : undefined,
+    min_age_days: minAge.value,
+    unseen_days: unseen.value,
+    max_seen_count: maxSeen.value,
+  });
+  if (!res.ok) {
+    const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
+    if (args.json) { log(JSON.stringify({ ok: false, policy: null, error: String(msg) }, null, 2)); return 1; }
+    err(`${c.red('Error:')} ${msg}`);
+    return 1;
+  }
+  if (args.json) { log(JSON.stringify({ ok: true, policy: res.policy }, null, 2)); return 0; }
+  log(`${c.green('✓')} created policy ${formatPolicy(res.policy)}`);
+  return 0;
+}
+
+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]`);
+    return 1;
+  }
+  if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
+    err(`${c.red('Error:')} --mode must be "review" or "auto"`);
+    return 1;
+  }
+
+  const patch = {};
+  if (args.name !== undefined) patch.name = args.name;
+  if (args.mode !== undefined) patch.mode = args.mode;
+  if (args.enabled) patch.enabled = true;
+  if (args.disabled) patch.enabled = false;
+  for (const [flag, clearFlag, field] of [
+    ['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'],
+  ]) {
+    if (args[clearFlag]) { patch[field] = null; continue; }
+    if (args[flag] === undefined) continue;
+    const parsed = parseIntFlag(args[flag], flag);
+    if (parsed.error) { err(`${c.red('Error:')} ${parsed.error}`); return 1; }
+    patch[field] = parsed.value;
+  }
+  if (Object.keys(patch).length === 0) {
+    err(`${c.red('Error:')} at least one field to update is required`);
+    return 1;
+  }
+
+  const res = await store.policyUpdate(id, patch);
+  if (!res.ok) {
+    const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
+    if (args.json) { log(JSON.stringify({ ok: false, policy: null, error: String(msg) }, null, 2)); return 1; }
+    err(`${c.red('Error:')} ${msg}${res.httpStatus === 404 ? ` — no policy found for id ${id}` : ''}`);
+    return 1;
+  }
+  if (args.json) { log(JSON.stringify({ ok: true, policy: res.policy }, null, 2)); return 0; }
+  log(`${c.green('✓')} updated policy ${formatPolicy(res.policy)}`);
+  return 0;
+}
+
+async function del(args, store) {
+  const id = args._[2];
+  if (!id) {
+    err(`${c.red('Usage:')} lorekit policy delete <id>`);
+    return 1;
+  }
+  const decision = args.yes ? 'proceed' : (args.json || !process.stdin.isTTY) ? 'refuse' : 'prompt';
+  if (decision === 'refuse') {
+    err(`${c.red('Refusing:')} deletes the policy with no terminal to confirm. Re-run with ${c.cyan('--yes')}.`);
+    return 1;
+  }
+  if (decision === 'prompt') {
+    const go = await select(
+      `${c.bold('Delete policy')} ${id}? The lessons it matched are untouched.`,
+      [
+        { value: false, label: 'Cancel' },
+        { value: true, label: 'Yes, delete' },
+      ],
+      { defaultIndex: 0 },
+    );
+    if (!go) { log(c.dim('Cancelled.')); return 0; }
+  }
+
+  const res = await store.policyDelete(id);
+  if (!res.ok) {
+    const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
+    if (args.json) { log(JSON.stringify({ ok: false, deleted: false, error: String(msg) }, null, 2)); return 1; }
+    err(`${c.red('Error:')} ${msg}${res.httpStatus === 404 ? ` — no policy found for id ${id}` : ''}`);
+    return 1;
+  }
+  if (args.json) { log(JSON.stringify({ ok: true, deleted: true }, null, 2)); return 0; }
+  log(`${c.green('✓')} deleted policy ${c.cyan(id)}`);
+  return 0;
+}
+
+export async function policy(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = process.env;
+  loadControl(root, { env });
+
+  const picked = pickRemote({ root, env, args });
+  if (picked.error) {
+    err(`${c.red('Error:')} ${picked.error}`);
+    return 1;
+  }
+
+  const sub = args._[1];
+  if (sub === 'list') return list(args, picked.store);
+  if (sub === 'create') return create(args, picked.store);
+  if (sub === 'update') return update(args, picked.store);
+  if (sub === 'delete') return del(args, picked.store);
+
+  err(`${c.red('Usage:')} lorekit policy <list|create|update|delete> [options]`);
+  return 1;
+}

package/src/commands/protect.mjs

@@ -0,0 +1,73 @@
+// `lorekit protect <scope::key> [--off]` / `lorekit pin|unpin <scope::key>`
+//
+// Marks or unmarks a lesson as protected — excluded from every grooming
+// candidate set regardless of policy. `protect` is the catalog's
+// `memory.protect` operation (pass `--off` to unprotect); `pin`/`unpin` are
+// convenience commands that call the SAME underlying REST call with the value
+// fixed, matching the plan's "pin/unpin aliases handled in the handler" —
+// implemented as two extra COMMANDS entries rather than catalog cliAliases,
+// since an alias only renames a command to an identical-behaviour canonical
+// one and pin/unpin invert the boolean.
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { loadControl, resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { log, err, c } from '../shared/util.mjs';
+import { resolveScopeKeyArgs, scopeIssue } from '../shared/lessons-view.mjs';
+
+function pickRemote({ root, env, args }) {
+  const { remoteDenied } = resolveDenies(root, { env });
+  const { remote, connection } = resolveStores(root, { env, endpoint: args.endpoint, token: args.token });
+  if (remoteDenied) return { error: `remote store is disabled by deny constraint (${remoteDenied.source})` };
+  if (!remote.usable()) return { error: `remote store is not configured — ${remoteUnavailableReason(connection)}` };
+  return { store: remote };
+}
+
+// One implementation for all four verbs; `isProtected` selects the value,
+// `verb` only changes the printed word.
+async function run(args, isProtected, verb) {
+  const root = resolveProjectRoot(args.dir);
+  const env = process.env;
+  loadControl(root, { env });
+
+  const positionals = args._.slice(1);
+  const { scope, key } = resolveScopeKeyArgs(positionals, { scope: args.scope, key: args.key });
+
+  const badScope = scope ? scopeIssue(scope) : null;
+  if (badScope) {
+    err(`${c.red('Error:')} invalid scope ${c.cyan(scope)} — ${badScope}`);
+    return 1;
+  }
+  if (!scope || !key) {
+    err(`${c.red('Usage:')} lorekit ${verb} <scope::key>`);
+    err(`       lorekit ${verb} <scope> <key>`);
+    return 1;
+  }
+
+  const picked = pickRemote({ root, env, args });
+  if (picked.error) {
+    err(`${c.red('Error:')} ${picked.error}`);
+    return 1;
+  }
+
+  const res = await picked.store.protect({ scope, key, protected: isProtected });
+  if (!res.ok) {
+    const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
+    if (args.json) {
+      log(JSON.stringify({ ok: false, scope, key, protected: null, error: String(msg) }, null, 2));
+      return 1;
+    }
+    err(`${c.red('Error:')} could not ${verb} ${c.cyan(`${scope}::${key}`)} — ${msg}`);
+    return 1;
+  }
+  if (args.json) {
+    log(JSON.stringify({ ok: true, scope, key, protected: res.protected }, null, 2));
+    return 0;
+  }
+  const past = isProtected ? 'protected' : 'unprotected';
+  log(`${c.green('✓')} ${past} ${c.cyan(`${scope}::${key}`)} ${c.dim('(remote)')}`);
+  return 0;
+}
+
+export function protect(args) { return run(args, !args.off, 'protect'); }
+export function pin(args) { return run(args, true, 'pin'); }
+export function unpin(args) { return run(args, false, 'unpin'); }

package/src/commands.mjs

@@ -54,6 +54,9 @@ import { migrate } from './commands/migrate.mjs';
 import { bootstrap } from './commands/bootstrap.mjs';
 import { mcpServer } from './commands/mcp-server.mjs';
 import { purge, purgeExpired } from './commands/purge.mjs';
+import { groom } from './commands/groom.mjs';
+import { policy } from './commands/policy.mjs';
+import { protect, pin, unpin } from './commands/protect.mjs';
 import { completion } from './commands/completion.mjs';
 
 /**
@@ -89,6 +92,11 @@ export const COMMANDS = [
   { name: 'restore', run: restore, traced: true, strictFlags: true, tool: 'memory.restore' },
   { name: 'purge', run: purge, traced: true, strictFlags: true, tool: 'memory.purge' },
   { name: 'purge-expired', run: purgeExpired, traced: true, strictFlags: true, tool: 'memory.purge_expired' },
+  { name: 'groom', run: groom, traced: true, strictFlags: true, tool: 'groom.preview' },
+  { name: 'policy', run: policy, traced: true, strictFlags: true, tool: 'policy.list' },
+  { name: 'protect', run: protect, traced: true, strictFlags: true, tool: 'memory.protect' },
+  { name: 'pin', run: pin, traced: true, strictFlags: true, native: 'shorthand for `protect` (protected=true)' },
+  { name: 'unpin', run: unpin, traced: true, strictFlags: true, native: 'shorthand for `protect --off` (protected=false)' },
 
   // ── Machine-facing ──────────────────────────────────────────────────────────
   // `completion` is machine-facing for the same reason hook/mcp are: its stdout

package/src/shared/completions.mjs

@@ -71,6 +71,18 @@ const FLAG = {
   'retention-days': { desc: 'Only purge archived older than n days', arg: 'n' },
   files: { desc: 'Changed files to check', arg: 'path' },
   strict: { desc: 'Exit non-zero on any unmet obligation' },
+  'policy-id': { desc: 'Run/preview a saved policy', arg: 'id' },
+  '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' },
+  run: { desc: 'Archive the matches instead of previewing' },
+  name: { desc: 'Policy name', arg: 'name' },
+  enabled: { desc: 'Turn auto-mode on' },
+  disabled: { desc: 'Turn auto-mode off' },
+  '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' },
+  off: { desc: 'Unprotect instead of protect' },
 };
 
 // Every command's completion shape, in the top-level help order. `flags` lists
@@ -133,6 +145,19 @@ const COMMANDS = [
     flags: ['retention-days', 'yes', 'json', 'endpoint', 'token'] },
   { name: 'purge-expired', summary: 'Delete every TTL-expired memory',
     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'] },
+  { 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'] },
+  { 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',
+    flags: ['json', 'endpoint', 'token'] },
+  { name: 'unpin', summary: 'Shorthand for `protect --off` (protected=false)', positional: 'address',
+    flags: ['json', 'endpoint', 'token'] },
   { name: 'completion', summary: 'Print a shell completion script', positional: 'shell' },
 ];
 

package/src/shared/flags.mjs

@@ -0,0 +1,16 @@
+// Shared CLI flag-value parsers. Zero-dependency, following the package convention.
+
+/**
+ * Parse an optional non-negative-integer flag value.
+ *
+ * Returns `{ value: undefined }` when the flag was omitted, `{ value: N }` on a
+ * valid whole number, or `{ error }` naming the flag on anything else — never
+ * coerces a half-understood value (`12abc`, `1.5`) into a number silently.
+ */
+export function parseIntFlag(raw, name) {
+  if (raw === undefined) return { value: undefined };
+  if (!/^\d+$/.test(String(raw).trim())) {
+    return { error: `--${name} must be a whole number, got ${JSON.stringify(String(raw))}` };
+  }
+  return { value: Number(String(raw).trim()) };
+}

package/src/shared/mcp.mjs

@@ -1,5 +1,8 @@
 // Minimal MCP-over-HTTP (JSON-RPC 2.0) client for the LoreKit endpoint.
-// Zero dependencies — uses the global fetch (Node 18+).
+// Zero EXTERNAL dependencies — uses the global fetch (Node 18+). Imports
+// below are same-package sibling modules (`./origin.mjs`), not npm deps.
+
+import { prNumberFromEnv, isValidRepo } from './origin.mjs';
 
 // Split a configured server URL like ".../mcp?token=lk_rw_x" into
 // { endpoint: ".../mcp", token: "lk_rw_x" }.
@@ -170,6 +173,94 @@ export function normalizeCorrelationId(raw) {
   return /^[A-Za-z0-9_\-./:#@]+$/.test(t) ? t : null;
 }
 
+/**
+ * The bounded `session_kind` vocabulary (migration 00082) — sent via
+ * `X-LoreKit-Session-Kind`, validated edge-side by the CROSS-LANGUAGE twin of
+ * this file's derivation, `packages/mcp-core/src/telemetry/session-kind.ts`
+ * (`parseSessionKind`). Kept here rather than imported: this package has no
+ * dependency on `@lorekit/core`, and the two are guarded for behavioural
+ * parity by `session-kind-parity.spec.ts` rather than a byte comparison,
+ * which is what a cross-language pair (this `.mjs` vs that `.ts`) needs.
+ */
+const SESSION_KINDS = ['local', 'ci', 'pr', 'unknown'];
+
+/**
+ * Derive `{ correlationId, sessionKind }` from the ambient environment, for
+ * every call site that does not have an EXPLICIT `LOREKIT_CORRELATION_ID` —
+ * the caller checks that first and skips this entirely when it is set, since
+ * an explicit value always wins.
+ *
+ * Precedence, first match wins:
+ *   1. PR context — `prNumberFromEnv` (LOREKIT_PR / GITHUB_REF / GITHUB_PR_NUMBER,
+ *      see `origin.mjs`) resolves a PR number AND a repo is known → `pr` +
+ *      `pr:<owner>/<repo>#<n>`.
+ *   2. CI environment (`GITHUB_ACTIONS`/`CI`) — `ci` always; a correlation id
+ *      of `ci:<owner>/<repo>#<run_id>` when both a repo and GITHUB_RUN_ID are
+ *      known, otherwise no correlation id (still `ci` — the session KIND is
+ *      known even when a stable id to group by is not).
+ *   3. A host-provided session id (`LOREKIT_SESSION_ID`, or the handful of
+ *      well-known agent-host env vars below) — `local` +
+ *      `session:<id>`. The raw id itself is never logged or stored anywhere
+ *      beyond this derived correlation id.
+ *   4. Otherwise `unknown`, no correlation id — never a guess.
+ *
+ * TOTAL and fail-safe: reads only `env` (never throws on a missing/odd
+ * value), and every branch degrades to the next rather than throwing. A
+ * derived value that fails `normalizeCorrelationId`'s charset/length check is
+ * dropped (session_kind is still reported; only the drill-down id is not).
+ */
+export function deriveSessionContext(env = process.env) {
+  const repo = isValidRepo(env.GITHUB_REPOSITORY);
+  const prNumber = prNumberFromEnv(env);
+
+  if (prNumber !== null && repo) {
+    const correlationId = normalizeCorrelationId(`pr:${repo}#${prNumber}`);
+    if (correlationId) return { correlationId, sessionKind: 'pr' };
+  }
+
+  const isCI = env.GITHUB_ACTIONS === 'true' || env.CI === 'true' || env.CI === '1';
+  if (isCI) {
+    const runId = typeof env.GITHUB_RUN_ID === 'string' ? env.GITHUB_RUN_ID.trim() : '';
+    if (repo && runId) {
+      const correlationId = normalizeCorrelationId(`ci:${repo}#${runId}`);
+      if (correlationId) return { correlationId, sessionKind: 'ci' };
+    }
+    return { correlationId: null, sessionKind: 'ci' };
+  }
+
+  // Well-known agent-host session id env vars. Best-effort: hosts differ and
+  // this is not an exhaustive registry, so an unrecognised host still falls
+  // through to `unknown` rather than fabricating an id.
+  const sessionId = firstNonEmptyEnv(env, ['LOREKIT_SESSION_ID', 'CLAUDE_SESSION_ID']);
+  if (sessionId) {
+    // A local session IS known even when the specific id fails the
+    // correlation-id charset/length check — report the kind either way, and
+    // let the id itself degrade to null rather than losing the whole reading.
+    return { correlationId: normalizeCorrelationId(`session:${sessionId}`), sessionKind: 'local' };
+  }
+
+  return { correlationId: null, sessionKind: 'unknown' };
+}
+
+function firstNonEmptyEnv(env, keys) {
+  for (const key of keys) {
+    const v = env[key];
+    if (typeof v === 'string' && v.trim() !== '') return v.trim();
+  }
+  return null;
+}
+
+/**
+ * Validate a `session_kind` value against the closed vocabulary. Total and
+ * fail-safe — mirrors `parseSessionKind`'s behaviour (never used to VALIDATE
+ * an incoming value here, since this process only ever sends a value it just
+ * derived itself, but kept as the single place the vocabulary is spelled out
+ * so `deriveSessionContext` and any future caller cannot drift from it).
+ */
+export function isSessionKind(value) {
+  return SESSION_KINDS.includes(value);
+}
+
 /**
  * Normalise a deployment-environment marker restFetch attaches as
  * X-LoreKit-Deployment-Environment when DEPLOYMENT_ENVIRONMENT (or
@@ -219,11 +310,17 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const url = `${baseUrl}${path}`;
-    // Opt-in usage correlation: when LOREKIT_CORRELATION_ID is set (e.g. by a CI
-    // job or a hook to a PR/session id), tag every REST call so GET
-    // /memories/usage?correlation_id=… can report "usage for this PR". Absent env
-    // ⇒ no header ⇒ existing behaviour unchanged.
-    const correlationId = normalizeCorrelationId(process.env.LOREKIT_CORRELATION_ID);
+    // Usage correlation: an EXPLICIT LOREKIT_CORRELATION_ID always wins (e.g. a
+    // CI job or a hook hand-setting a PR/session id). Otherwise, derive one
+    // from the ambient environment (CI/PR/session — see `deriveSessionContext`)
+    // so GET /memories/usage?correlation_id=… and the session_kind dimension
+    // are populated without anyone having to export anything by hand. Both
+    // stay unset only when neither an explicit value nor a derivable one
+    // exists (`sessionKind: 'unknown'`, no correlationId).
+    const explicitCorrelationId = normalizeCorrelationId(process.env.LOREKIT_CORRELATION_ID);
+    const derived = explicitCorrelationId ? null : deriveSessionContext(process.env);
+    const correlationId = explicitCorrelationId ?? derived?.correlationId ?? null;
+    const sessionKind = derived?.sessionKind ?? null;
     // Opt-in test-run marker: when DEPLOYMENT_ENVIRONMENT is set (a deploy/CI
     // smoke sets it to `test`), tell the edge to report that
     // `deployment.environment.name` for this request so Dash0 can filter synthetic
@@ -238,6 +335,7 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
       ...(token ? { authorization: `Bearer ${token}` } : {}),
       ...(traceparent ? { traceparent } : {}),
       ...(correlationId ? { 'x-lorekit-correlation-id': correlationId } : {}),
+      ...(sessionKind ? { 'x-lorekit-session-kind': sessionKind } : {}),
       ...(runEnv ? { 'x-lorekit-deployment-environment': runEnv } : {}),
       // Name the calling surface so usage analytics can tell a CLI read from a
       // dashboard one. Not cosmetic: `GET /memories/read-activity` EXCLUDES the

package/src/shared/mirror-pairs.mjs

@@ -54,6 +54,12 @@ export const mirrorPairs = [
   { core: 'packages/mcp-core/src/webhook/github-app-jwt.ts', edge: 'supabase/functions/mcp/github-app-jwt.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/telemetry/trace-context.ts', edge: 'supabase/functions/_shared/telemetry/trace-context.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/rest/rest-tool-name.ts', edge: 'supabase/functions/_shared/rest/rest-tool-name.ts', driftChecked: true },
+  // The `X-LoreKit-Session-Kind` validator (migration 00082). Also has a
+  // SECOND, cross-LANGUAGE twin — the CLI's `deriveSessionContext` in
+  // `packages/cli/src/shared/mcp.mjs` — guarded behaviourally by
+  // `packages/cli/test/session-context.test.mjs`, the same split
+  // `lesson-rank.ts` uses below.
+  { core: 'packages/mcp-core/src/telemetry/session-kind.ts', edge: 'supabase/functions/_shared/telemetry/session-kind.ts', driftChecked: true },
   // Has a SECOND, cross-LANGUAGE twin no byte comparison can cover — the
   // CLI's own `lessons-pure.mjs` — guarded behaviourally by
   // `lesson-rank-parity.spec.ts` instead.
@@ -70,6 +76,12 @@ export const mirrorPairs = [
   { core: 'packages/mcp-core/src/auth/account-wide-tools.ts', edge: 'supabase/functions/_shared/auth/account-wide-tools.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/telemetry/io-ledger.ts', edge: 'supabase/functions/_shared/telemetry/io-ledger.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/telemetry/db-query-metrics.ts', edge: 'supabase/functions/_shared/telemetry/db-query-metrics.ts', driftChecked: true },
+  // Retention-policy candidate/precedence logic. The SQL RPC
+  // (`lorekit_groom_candidates`, migration 00088) is authoritative; this is the
+  // unit-testable mirror the edge groom/policy handlers use to resolve a
+  // `policy_id` or inline request into the conditions struct the RPC takes.
+  // Both copies are import-free, so the byte-comparison drift check applies.
+  { core: 'packages/mcp-core/src/retention/groom.ts', edge: 'supabase/functions/_shared/retention/groom.ts', driftChecked: true },
   // Excluded from the byte-comparison drift check: the edge copy types the
   // client as `ReturnType<typeof createClient>` off an `npm:` specifier where
   // mcp-core imports a typed `SupabaseClient`, and additionally carries

package/src/store/remote.mjs

@@ -695,6 +695,70 @@ class RemoteStore {
     };
   }
 
+  // ── Retention policies ("grooming") → REST ────────────────────────────────
+  // Server-side only (retention_policies table + pg_cron sweep) — v1 has no
+  // local-store equivalent, matching the account-wide sweeps just above.
+
+  // GET /policies → { entries: [...] }
+  async policyList() {
+    const res = await this._rest('/memories/policies');
+    if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
+    return { ok: true, entries: Array.isArray(res.data?.entries) ? res.data.entries : [] };
+  }
+
+  // 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 });
+    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 };
+  }
+
+  // PATCH /policies/:id → the updated policy object. An omitted field is left
+  // unchanged; pass an explicit `null` in the patch to clear a condition —
+  // this method does not strip nulls, only `undefined` (stripUndefined keeps
+  // that distinction, which is the whole point of the RPC's JSONB-patch design).
+  async policyUpdate(id, patch = {}) {
+    const body = stripUndefined(patch);
+    const res = await this._rest(`/memories/policies/${encodeURIComponent(id)}`, { method: 'PATCH', body });
+    if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
+    return { ok: true, policy: res.data };
+  }
+
+  // DELETE /policies/:id → deletes the RULE only; never touches the lessons it matched.
+  async policyDelete(id) {
+    const res = await this._rest(`/memories/policies/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
+    return { ok: true, deleted: true };
+  }
+
+  // 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 });
+    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 : [] };
+  }
+
+  // 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 });
+    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 : [] };
+  }
+
+  // POST /protect → { protected }. Excludes/includes a lesson from every
+  // grooming candidate set regardless of policy.
+  async protect({ scope, key, protected: isProtected } = {}) {
+    const res = await this._rest('/memories/protect', { method: 'POST', body: { scope, key, protected: isProtected } });
+    if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
+    return { ok: true, protected: res.data?.protected ?? isProtected };
+  }
+
   // Authentication probe for doctor — does the configured token STILL work?
   //
   // `ping()` deliberately hits the PUBLIC `/health` function, so it stays green

package/src/surfaces.generated.mjs

@@ -21,7 +21,14 @@ export const MCP_TOOL_NAMES = [
   "org.create",
   "org.list",
   "org.rename",
-  "org.delete"
+  "org.delete",
+  "policy.list",
+  "policy.create",
+  "policy.update",
+  "policy.delete",
+  "groom.preview",
+  "groom.run",
+  "memory.protect"
 ];
 
 /** The `memory.*` family — dispatched against a store (local or remote). */
@@ -36,7 +43,8 @@ export const MEMORY_TOOL_NAMES = [
   "memory.list_archived",
   "memory.restore",
   "memory.purge",
-  "memory.purge_expired"
+  "memory.purge_expired",
+  "memory.protect"
 ];
 
 /** The `org.*` family — always proxied to the REST API, never the local store. */
@@ -462,6 +470,229 @@ export const MCP_TOOL_DEFS = [
         }
       }
     }
+  },
+  {
+    "name": "policy.list",
+    "description": "List every retention policy you own",
+    "inputSchema": {
+      "type": "object",
+      "properties": {}
+    }
+  },
+  {
+    "name": "policy.create",
+    "description": "Create a scoped retention policy that auto-archives (never hard-deletes) matching lessons",
+    "inputSchema": {
+      "type": "object",
+      "required": [
+        "scope",
+        "name"
+      ],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`."
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable name for the policy."
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "review",
+            "auto"
+          ],
+          "default": "review",
+          "description": "`review` — surfaced for a human to run manually. `auto` — swept nightly, if enabled."
+        },
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether `auto` mode is active. Always starts false, even when mode is `auto`."
+        },
+        "min_age_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match only lessons at least this many days old."
+        },
+        "unseen_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match lessons unseen for at least this many days. A never-seen lesson always matches."
+        },
+        "max_seen_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons that have recurred at most this many times."
+        }
+      }
+    }
+  },
+  {
+    "name": "policy.update",
+    "description": "Update a retention policy. Every field but id is optional",
+    "inputSchema": {
+      "type": "object",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The policy id to update."
+        },
+        "name": {
+          "type": "string",
+          "description": "New name for the policy."
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "review",
+            "auto"
+          ],
+          "description": "`review` — surfaced for a human to run manually. `auto` — swept nightly, if enabled."
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether `auto` mode is active."
+        },
+        "min_age_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match only lessons at least this many days old. Omit to leave unchanged; pass explicit null to clear."
+        },
+        "unseen_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match lessons unseen for at least this many days. Omit to leave unchanged; pass explicit null to clear."
+        },
+        "max_seen_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons that have recurred at most this many times. Omit to leave unchanged; pass explicit null to clear."
+        }
+      }
+    }
+  },
+  {
+    "name": "policy.delete",
+    "description": "Delete a retention policy. Deletes the rule only — never touches the lessons it matched",
+    "inputSchema": {
+      "type": "object",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The policy id to delete."
+        }
+      }
+    }
+  },
+  {
+    "name": "groom.preview",
+    "description": "Preview the lessons a saved policy or an inline condition set would archive, without changing anything",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "policy_id": {
+          "type": "string",
+          "description": "Preview an existing saved policy. Mutually exclusive with `scope`/conditions."
+        },
+        "scope": {
+          "type": "string",
+          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`."
+        },
+        "min_age_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match only lessons at least this many days old."
+        },
+        "unseen_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match lessons unseen for at least this many days. A never-seen lesson always matches."
+        },
+        "max_seen_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons that have recurred at most this many times."
+        }
+      }
+    }
+  },
+  {
+    "name": "groom.run",
+    "description": "Archive every lesson a saved policy or an inline condition set matches. Soft-archive only — never hard-deletes",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "policy_id": {
+          "type": "string",
+          "description": "Run an existing saved policy. Mutually exclusive with `scope`/conditions."
+        },
+        "scope": {
+          "type": "string",
+          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`."
+        },
+        "min_age_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match only lessons at least this many days old."
+        },
+        "unseen_days": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650,
+          "description": "Match lessons unseen for at least this many days. A never-seen lesson always matches."
+        },
+        "max_seen_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons that have recurred at most this many times."
+        }
+      }
+    }
+  },
+  {
+    "name": "memory.protect",
+    "description": "Mark or unmark a lesson as protected — excluded from every grooming candidate set regardless of policy",
+    "inputSchema": {
+      "type": "object",
+      "required": [
+        "scope",
+        "key",
+        "protected"
+      ],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "description": "Canonical scope string, e.g. `repo::mthines/lorekit`."
+        },
+        "key": {
+          "type": "string",
+          "description": "Lesson identifier, unique within the scope. Max 512 characters."
+        },
+        "protected": {
+          "type": "boolean",
+          "description": "true to protect, false to unprotect."
+        }
+      }
+    }
   }
 ];
 
@@ -476,7 +707,10 @@ export const CLI_BINDINGS = {
   "scopes": "memory.scopes",
   "restore": "memory.restore",
   "purge": "memory.purge",
-  "purge-expired": "memory.purge_expired"
+  "purge-expired": "memory.purge_expired",
+  "policy": "policy.list",
+  "groom": "groom.preview",
+  "protect": "memory.protect"
 };
 
 /** CLI alias -> canonical command name. */
@@ -495,14 +729,25 @@ export const CLI_EXEMPT = {
   "org.create": "org management reaches the CLI via the local stdio MCP server (`lorekit mcp`), not a `lorekit` subcommand",
   "org.list": "org management reaches the CLI via the local stdio MCP server (`lorekit mcp`), not a `lorekit` subcommand",
   "org.rename": "org management reaches the CLI via the local stdio MCP server (`lorekit mcp`), not a `lorekit` subcommand",
-  "org.delete": "org management reaches the CLI via the local stdio MCP server (`lorekit mcp`), not a `lorekit` subcommand"
+  "org.delete": "org management reaches the CLI via the local stdio MCP server (`lorekit mcp`), not a `lorekit` subcommand",
+  "policy.create": "an action of the `lorekit policy` command",
+  "policy.update": "an action of the `lorekit policy` command",
+  "policy.delete": "an action of the `lorekit policy` command",
+  "groom.run": "the `--run` mode of `lorekit groom` (`groom.preview` claims the `groom` binding)"
 };
 
 /** Op -> why the local stdio MCP server does not dispatch it. */
 export const LOCAL_MCP_EXEMPT = {
   "memory.list_archived": "reachable through memory.list's archived filter on the offline store",
   "memory.purge": "account-wide sweep against server-side state; the offline store has no equivalent",
-  "memory.purge_expired": "account-wide sweep against server-side state; the offline store has no equivalent"
+  "memory.purge_expired": "account-wide sweep against server-side state; the offline store has no equivalent",
+  "policy.list": "server-side retention_policies table; the offline store has no equivalent",
+  "policy.create": "server-side retention_policies table; the offline store has no equivalent",
+  "policy.update": "server-side retention_policies table; the offline store has no equivalent",
+  "policy.delete": "server-side retention_policies table; the offline store has no equivalent",
+  "groom.preview": "server-side candidate query against retention_policies + memories; the offline store has no equivalent",
+  "groom.run": "server-side candidate query against retention_policies + memories; the offline store has no equivalent",
+  "memory.protect": "the offline store has no protected column in v1"
 };
 
 /**