@lorekit/cli 1.71.0 → 1.71.2

package/README.md

@@ -667,6 +667,75 @@ The server's refusal is printed verbatim with a one-line next step; the CLI make
 exactly one request and never retries, splits the sweep, or re-scopes around it.
 Use an unscoped `lk_rw_*` / `lk_wo_*` token for maintenance.
 
+### `lorekit groom` / `lorekit policy` / `lorekit protect` (aliases: `pin` / `unpin`)
+
+Retention automation — the CLI counterpart to the MCP `groom.*`/`policy.*`/
+`memory.protect` tools and the REST `/groom/*`/`/policies*`/`/protect` routes.
+**Remote only**, matching `purge`: `retention_policies` has no local-store
+equivalent.
+
+```bash
+# Preview what a rule would catch, without changing anything
+lorekit groom --scope repo::acme/app --unseen-days 90
+
+# Archive the matches (soft-archive, recoverable via `lorekit restore`)
+lorekit groom --scope repo::acme/app --unseen-days 90 --run --yes
+
+# Save it as a policy you can re-run by name, or let it sweep nightly
+lorekit policy create --scope repo::acme/app --name "stale repo lore" \
+  --unseen-days 90 --mode review
+lorekit policy list
+lorekit policy update <id> --mode auto --enabled
+lorekit policy delete <id>
+
+# Exempt one lesson from every rule and every manual sweep
+lorekit pin repo::acme/app::the-load-bearing-lesson
+lorekit unpin repo::acme/app::the-load-bearing-lesson
+```
+
+`groom [--policy-id <id> | --scope <s> [conditions…]] [--run] [--yes]` previews
+by default; `--run` archives. Exactly one of `--policy-id`/`--scope` is
+required. `policy <list|create|update|delete>` manages the SAVED rules
+`--policy-id` runs; `delete` removes the rule only, never the lessons it
+matched.
+
+Every condition ANDs together: the five age/activity fields
+(`--min-age-days`/`--unseen-days`/`--max-seen-count`/`--max-read-count`/
+`--max-opened-count`) plus the same **eight dimension filters** the Lore
+Explorer's filter bar offers —
+
+| Flag | `--<dim>-mode` values (default) |
+|------|----------------------------------|
+| `--tags <a,b>` | `any` \| `all` \| `none` (`any`) |
+| `--kind <a,b>` | `in` \| `nin` (`in`) |
+| `--host <a,b>` | `in` \| `nin` (`in`) |
+| `--trigger <a,b>` | `in` \| `nin` (`in`) |
+| `--source-agent <a,b>` | `in` \| `nin` (`in`) |
+| `--origin-repo <a,b>` | `in` \| `nin` (`in`) |
+| `--origin-branch <a,b>` | `in` \| `nin` (`in`) |
+| `--origin-pr <a,b>` | `in` \| `nin` (`in`) |
+
+— all comma-separated, same convention as `write --tags a,b,c`:
+
+```bash
+lorekit policy create --scope repo::acme/app --name "stale ci review events" \
+  --kind bus --kind-mode in --tags ci::pr-review-state --tags-mode all \
+  --min-age-days 30
+```
+
+`policy update` pairs every condition — age/count AND every dimension — with
+a `--clear-<field>` boolean (e.g. `--clear-kind`, `--clear-min-age-days`) that
+sends an explicit `null` rather than omitting the field: omitting a field on
+update leaves it unchanged, `null` clears it.
+
+```bash
+lorekit policy update <id> --clear-kind --host reviewer,aw
+```
+
+`protect <scope::key> [--off]` (or the shorter `pin`/`unpin`) marks a lesson as
+excluded from every policy and every `groom --run`, regardless of which rule
+would otherwise match it — persists until explicitly cleared.
+
 ### `lorekit hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.

package/bin/lorekit.mjs

@@ -935,7 +935,10 @@ ${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>] [--max-opened-count <n>] [--run] [--yes] [--json]
+                            [--max-read-count <n>] [--max-opened-count <n>]
+                            [--tags a,b --tags-mode any|all|none]
+                            [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b [--<dim>-mode in|nin]]
+                            [--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
@@ -960,6 +963,12 @@ ${c.bold('Options')}
                              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
+      --tags <a,b>, --tags-mode <any|all|none>
+                             Match lessons carrying these labels (default: any)
+      --kind, --host, --trigger, --source-agent,
+      --origin-repo, --origin-branch, --origin-pr <a,b>
+      --<dim>-mode <in|nin>  Match lessons whose dimension is one of these
+                             values (default: in); comma-separated
       --run                  Archive the matches instead of previewing
   -y, --yes                  Confirm --run; required when non-interactive
       --json                 Machine-readable result
@@ -974,12 +983,17 @@ ${c.bold('Usage')}
   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-opened-count <n>]
+                         [--tags a,b --tags-mode any|all|none]
+                         [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b [--<dim>-mode in|nin]]
   lorekit policy update <id> [--name <n>] [--mode review|auto] [--enabled|--disabled]
-                         [--min-age-days <n>|--clear-min-age-days] [...] [--json]
+                         [--min-age-days <n>|--clear-min-age-days] [...]
+                         [--tags a,b|--clear-tags] [--<dim> a,b|--clear-<dim>] [--<dim>-mode in|nin] [--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 / max-opened-count).
+(min-age-days / unseen-days / max-seen-count / max-read-count / max-opened-count,
+plus the eight dimension filters — tags/kind/host/trigger/source-agent/
+origin-repo/origin-branch/origin-pr).
 \`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
@@ -995,8 +1009,14 @@ ${c.bold('Options')}
       --min-age-days <n>, --unseen-days <n>, --max-seen-count <n>, --max-read-count <n>,
       --max-opened-count <n>
                              Conditions (create/update)
+      --tags <a,b>, --tags-mode <any|all|none>
+      --kind, --host, --trigger, --source-agent,
+      --origin-repo, --origin-branch, --origin-pr <a,b>
+      --<dim>-mode <in|nin>  Dimension conditions (create/update); comma-separated
       --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count,
-      --clear-max-read-count, --clear-max-opened-count
+      --clear-max-read-count, --clear-max-opened-count,
+      --clear-tags, --clear-kind, --clear-host, --clear-trigger,
+      --clear-source-agent, --clear-origin-repo, --clear-origin-branch, --clear-origin-pr
                              Remove a condition (update only)
   -y, --yes                  Confirm delete; required when non-interactive
       --json                 Machine-readable result
@@ -1121,6 +1141,16 @@ const KNOWN_FLAGS = [
   'name', 'mode', 'enabled', 'disabled',
   'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count',
   'clear-max-opened-count', 'off',
+  // The eight retention dimension filters' `*-mode` value flags (the value
+  // flags themselves — tags/source-agent/trigger/kind/host/origin-repo/
+  // origin-branch/origin-pr — are already listed above for `write`) plus
+  // their `clear-*` booleans (policy update only). See
+  // `shared/flags.mjs`'s `parseDimensionConditions`, the one place that
+  // owns the flag-name ↔ field-name ↔ mode-enum table these mirror.
+  'tags-mode', 'source-agent-mode', 'trigger-mode', 'kind-mode', 'host-mode',
+  'origin-repo-mode', 'origin-branch-mode', 'origin-pr-mode',
+  'clear-tags', 'clear-source-agent', 'clear-trigger', 'clear-kind', 'clear-host',
+  'clear-origin-repo', 'clear-origin-branch', 'clear-origin-pr',
   // `obligations`
   'files', 'strict', 'strict-all',
   // `update`
@@ -1137,7 +1167,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', 'clear-max-opened-count', 'strict', 'strict-all', 'check'],
+    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', 'clear-tags', 'clear-source-agent', 'clear-trigger', 'clear-kind', 'clear-host', 'clear-origin-repo', 'clear-origin-branch', 'clear-origin-pr', 'check'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/src/commands/groom.mjs

@@ -11,7 +11,7 @@ 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';
+import { parseIntFlag, parseDimensionConditions } from '../shared/flags.mjs';
 
 /** Resolve the groom.preview/groom.run request from CLI args. */
 export function parseGroomRequest(args) {
@@ -33,6 +33,8 @@ export function parseGroomRequest(args) {
   if (maxRead.error) return { error: maxRead.error };
   const maxOpened = parseIntFlag(args['max-opened-count'], 'max-opened-count');
   if (maxOpened.error) return { error: maxOpened.error };
+  const dims = parseDimensionConditions(args, { clearable: false });
+  if (dims.error) return { error: dims.error };
 
   return {
     request: {
@@ -42,6 +44,7 @@ export function parseGroomRequest(args) {
       max_seen_count: maxSeen.value,
       max_read_count: maxRead.value,
       max_opened_count: maxOpened.value,
+      ...dims.conditions,
     },
   };
 }

package/src/commands/policy.mjs

@@ -15,7 +15,19 @@ 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';
+import { parseIntFlag, parseDimensionConditions } from '../shared/flags.mjs';
+
+/** `field` → display label for `formatPolicy`'s dimension summary. */
+const DIMENSION_DISPLAY = [
+  ['tags', 'tags_mode', 'tags'],
+  ['source_agent', 'source_agent_mode', 'source_agent'],
+  ['trigger', 'trigger_mode', 'trigger'],
+  ['kind', 'kind_mode', 'kind'],
+  ['host', 'host_mode', 'host'],
+  ['origin_repo', 'origin_repo_mode', 'origin_repo'],
+  ['origin_branch', 'origin_branch_mode', 'origin_branch'],
+  ['origin_pr', 'origin_pr_mode', 'origin_pr'],
+];
 
 function pickRemote({ root, env, args }) {
   const { remoteDenied } = resolveDenies(root, { env });
@@ -32,6 +44,12 @@ function formatPolicy(p) {
   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}`);
+  for (const [field, modeField, label] of DIMENSION_DISPLAY) {
+    const values = p[field];
+    if (!Array.isArray(values) || values.length === 0) continue;
+    const mode = p[modeField];
+    conditions.push(`${label}${mode ? `:${mode}` : ''}=[${values.join(',')}]`);
+  }
   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(', '))}` : ''}`;
 }
@@ -52,7 +70,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] [--max-opened-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] [--tags a,b --tags-mode any|all|none] [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b [--<dim>-mode in|nin]]`);
     return 1;
   }
   const minAge = parseIntFlag(args['min-age-days'], 'min-age-days');
@@ -69,6 +87,8 @@ async function create(args, store) {
     err(`${c.red('Error:')} --mode must be "review" or "auto"`);
     return 1;
   }
+  const dims = parseDimensionConditions(args, { clearable: false });
+  if (dims.error) { err(`${c.red('Error:')} ${dims.error}`); return 1; }
 
   const res = await store.policyCreate({
     scope: args.scope,
@@ -80,6 +100,7 @@ async function create(args, store) {
     max_seen_count: maxSeen.value,
     max_read_count: maxRead.value,
     max_opened_count: maxOpened.value,
+    ...dims.conditions,
   });
   if (!res.ok) {
     const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
@@ -95,7 +116,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] [--max-opened-count N]`);
+    err(`${c.red('Usage:')} lorekit policy update <id> [--name N] [--mode review|auto] [--enabled|--disabled] [--min-age-days N|--clear-min-age-days] [...] [--tags a,b|--clear-tags] [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b|--clear-<dim>] [--<dim>-mode ...]`);
     return 1;
   }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
@@ -121,6 +142,9 @@ async function update(args, store) {
     if (parsed.error) { err(`${c.red('Error:')} ${parsed.error}`); return 1; }
     patch[field] = parsed.value;
   }
+  const dims = parseDimensionConditions(args, { clearable: true });
+  if (dims.error) { err(`${c.red('Error:')} ${dims.error}`); return 1; }
+  Object.assign(patch, dims.conditions);
   if (Object.keys(patch).length === 0) {
     err(`${c.red('Error:')} at least one field to update is required`);
     return 1;

package/src/shared/flags.mjs

@@ -14,3 +14,76 @@ export function parseIntFlag(raw, name) {
   }
   return { value: Number(String(raw).trim()) };
 }
+
+/**
+ * The eight dimension filters a retention policy / inline groom call can
+ * carry (migration 00093) — the CLI's flag-name ↔ field-name ↔ valid-mode
+ * table. Mirrors `groomDimensionFilterProperties` in
+ * `packages/schemas/src/shared/tool-catalog.ts` and `GROOM_DIMENSION_FIELDS`
+ * in `supabase/functions/mcp/tools.ts`; kept as ONE list here (not three) so
+ * `policy create`/`policy update`/`groom` cannot describe the dimensions
+ * differently.
+ */
+const DIMENSIONS = [
+  { flag: 'tags', field: 'tags', modes: ['any', 'all', 'none'] },
+  { flag: 'source-agent', field: 'source_agent', modes: ['in', 'nin'] },
+  { flag: 'trigger', field: 'trigger', modes: ['in', 'nin'] },
+  { flag: 'kind', field: 'kind', modes: ['in', 'nin'] },
+  { flag: 'host', field: 'host', modes: ['in', 'nin'] },
+  { flag: 'origin-repo', field: 'origin_repo', modes: ['in', 'nin'] },
+  { flag: 'origin-branch', field: 'origin_branch', modes: ['in', 'nin'] },
+  { flag: 'origin-pr', field: 'origin_pr', modes: ['in', 'nin'] },
+];
+
+/**
+ * Parse the eight retention dimension filters (`--tags`/`--kind`/`--host`/
+ * `--trigger`/`--source-agent`/`--origin-repo`/`--origin-branch`/`--origin-pr`,
+ * each with a `--<dim>-mode`) out of a parsed-args object.
+ *
+ * Comma-separated values — matching the existing `write --tags a,b,c`
+ * convention. The minimal flag parser (`bin/lorekit.mjs`'s `parseArgs`) is
+ * last-wins on a repeated flag, so comma-splitting is the established
+ * multi-value shape in this CLI, not a new one invented here.
+ *
+ * `--<dim>-mode` is validated against that DIMENSION's own enum (`tags-mode`
+ * accepts any/all/none; every other dimension accepts in/nin) — an invalid
+ * value is rejected rather than silently forwarded to the RPC as a raw
+ * Postgres enum error.
+ *
+ * With `clearable: true` (policy update), `--clear-<dim>` sends an explicit
+ * `null` for the VALUE field only, and skips both the value and mode flags for
+ * that dimension entirely — matching how `policy update --clear-min-age-days`
+ * already ignores `--min-age-days` when both are passed. The MODE field is
+ * left untouched by a clear: it is meaningless once the value is null, and
+ * silently dropping it if the caller separately set it would be a second
+ * surprise on top of the clear.
+ *
+ * Returns `{ conditions }` containing only the fields the caller actually
+ * named — never a full 16-key object of undefineds, so a caller can spread it
+ * straight into a request body without a second `stripUndefined` pass losing
+ * an intentional `null` — or `{ error }` naming the offending flag.
+ */
+export function parseDimensionConditions(args, { clearable = false } = {}) {
+  const conditions = {};
+  for (const { flag, field, modes } of DIMENSIONS) {
+    if (clearable && args[`clear-${flag}`]) {
+      conditions[field] = null;
+      continue;
+    }
+    const raw = args[flag];
+    if (raw !== undefined) {
+      conditions[field] = String(raw)
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    }
+    const modeRaw = args[`${flag}-mode`];
+    if (modeRaw !== undefined) {
+      if (!modes.includes(modeRaw)) {
+        return { error: `--${flag}-mode must be one of ${modes.join('|')}, got ${JSON.stringify(String(modeRaw))}` };
+      }
+      conditions[`${field}_mode`] = modeRaw;
+    }
+  }
+  return { conditions };
+}

package/src/store/remote.mjs

@@ -42,6 +42,20 @@ function stripUndefined(obj) {
   return out;
 }
 
+// Drop only `undefined` — keeps an explicit `null`. Bare `stripUndefined`
+// above is right for a CREATE body, where an omitted dimension and an
+// explicit `null` mean the same "not filtered". It is wrong for a PATCH,
+// where `null` is the caller's explicit instruction to CLEAR a
+// previously-set condition (`policy update --clear-kind`) — dropping it
+// there means the field silently stays whatever it already was, which is
+// the opposite of what was asked. Named for what it keeps, not what it
+// drops, since "strip" alone reads as "strip everything falsy-ish".
+function stripUndefinedKeepNull(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) if (v !== undefined) out[k] = v;
+  return out;
+}
+
 /**
  * A read that could not be answered — a transport failure or a non-2xx status,
  * as opposed to "the lesson is not there".
@@ -768,9 +782,20 @@ class RemoteStore {
     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, 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 });
+  // POST /policies → the created policy object. `...dims` carries whichever
+  // of the eight dimension filters (+ their `_mode` companions) the caller
+  // named — see `parseDimensionConditions` in `shared/flags.mjs`, the shared
+  // parser policy create/update and groom all go through.
+  async policyCreate({
+    scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+    tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+    origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+  } = {}) {
+    const body = stripUndefined({
+      scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+      tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+      origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+    });
     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 };
@@ -778,10 +803,11 @@ class RemoteStore {
 
   // 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).
+  // this method does not strip nulls, only `undefined` (stripUndefinedKeepNull
+  // keeps that distinction, which is the whole point of the RPC's JSONB-patch
+  // design and of `policy update --clear-*`).
   async policyUpdate(id, patch = {}) {
-    const body = stripUndefined(patch);
+    const body = stripUndefinedKeepNull(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 };
@@ -796,9 +822,18 @@ 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, max_opened_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
+  // `scope` (+ optional conditions, including the eight dimension filters —
+  // see policyCreate's comment), never both.
+  async groomPreview({
+    policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+    tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+    origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+  } = {}) {
+    const body = stripUndefined({
+      policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+      tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+      origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+    });
     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 : [] };
@@ -806,8 +841,16 @@ 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, max_opened_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
+  async groomRun({
+    policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+    tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+    origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+  } = {}) {
+    const body = stripUndefined({
+      policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+      tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+      origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+    });
     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

@@ -56,7 +56,8 @@ export const ORG_TOOL_NAMES = [
 ];
 
 /**
- * The `tools/list` payload: name, description and inputSchema per op.
+ * The `tools/list` payload: name, description, inputSchema and MCP
+ * annotations per op.
  * Identical projection to the edge server's, from the same declaration, so the
  * local stdio server and the hosted server advertise the same contract.
  */
@@ -156,6 +157,12 @@ export const MCP_TOOL_DEFS = [
           "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."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": false,
+      "openWorldHint": false
     }
   },
   {
@@ -180,6 +187,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Batch mode: one or more `scope::key` references, fetched in a single call. Cannot be combined with `scope`/`key`. Each entry is parsed by the same reference grammar `memory.write`'s `cited` field uses (`scope::key`, verbatim scope — never lowercased). Silently truncated past 32 entries."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -242,6 +255,12 @@ export const MCP_TOOL_DEFS = [
           "description": "full (default) returns each entry's complete `value`. summary omits `value` and returns `value_bytes` + a 200-character `preview` instead — the cheap discovery read for deciding WHICH lessons to then fetch with `memory.read`."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -272,6 +291,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Org slug to delete under (org-owned delete). Omit for a personal memory. Soft-archive requires a member/admin/owner role; hard-delete (force: true) requires admin/owner — verified server-side."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -313,6 +338,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Opaque cursor from a previous response's `nextCursor`. Omit to start from the first page."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -334,6 +365,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Lesson identifier, unique within the scope. Max 512 characters."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -342,6 +379,12 @@ export const MCP_TOOL_DEFS = [
     "inputSchema": {
       "type": "object",
       "properties": {}
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -362,6 +405,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Maximum entries to return."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -383,6 +432,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Lesson identifier, unique within the scope. Max 512 characters."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -399,6 +454,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Only purge archived lessons older than this many days."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -407,6 +468,12 @@ export const MCP_TOOL_DEFS = [
     "inputSchema": {
       "type": "object",
       "properties": {}
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -428,6 +495,12 @@ export const MCP_TOOL_DEFS = [
           "description": "Human-readable display name"
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": false
     }
   },
   {
@@ -436,6 +509,12 @@ export const MCP_TOOL_DEFS = [
     "inputSchema": {
       "type": "object",
       "properties": {}
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -457,6 +536,12 @@ export const MCP_TOOL_DEFS = [
           "description": "New display name"
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -473,6 +558,12 @@ export const MCP_TOOL_DEFS = [
           "description": "The org slug to delete"
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -481,6 +572,12 @@ export const MCP_TOOL_DEFS = [
     "inputSchema": {
       "type": "object",
       "properties": {}
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -675,6 +772,12 @@ export const MCP_TOOL_DEFS = [
           "description": "How the origin_pr filter combines."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": false
     }
   },
   {
@@ -866,6 +969,12 @@ export const MCP_TOOL_DEFS = [
           "description": "How the origin_pr filter combines. Omit to leave unchanged; pass explicit null to clear."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -882,6 +991,12 @@ export const MCP_TOOL_DEFS = [
           "description": "The policy id to delete."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -1058,6 +1173,12 @@ export const MCP_TOOL_DEFS = [
           "description": "How the origin_pr filter combines."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -1234,6 +1355,12 @@ export const MCP_TOOL_DEFS = [
           "description": "How the origin_pr filter combines."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   },
   {
@@ -1260,6 +1387,12 @@ export const MCP_TOOL_DEFS = [
           "description": "true to protect, false to unprotect."
         }
       }
+    },
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": false
     }
   }
 ];