@lorekit/cli 1.53.0 → 1.55.0

package/src/mcp-server.mjs

@@ -31,191 +31,17 @@ import { createRemoteStore } from './store/remote.mjs';
 import { deriveOrigin, mergeOrigin } from './origin.mjs';
 import { readScopeInventory } from './store/scope-inventory.mjs';
 import { inferKindHostFromTags } from './lessons-view.mjs';
+// Generated from packages/schemas/src/tool-catalog.ts — the same declaration the
+// hosted MCP server renders `tools/list` from. Committed and zero-dep because
+// this is a published package that cannot import the workspace schemas.
+import { MCP_TOOL_DEFS, MCP_TOOL_NAMES } from './surfaces.generated.mjs';
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_INFO = { name: 'lorekit-local', version: '1.0.0' };
 
-// Tool advertisements — names + input schemas mirror the production MCP server
-// (supabase/functions/mcp/mcp-handler.ts) so a client sees the same contract
-// whether it points at the hosted endpoint or this local server.
-export const MEMORY_TOOL_DEFS = [
-  {
-    name: 'memory.write',
-    description: 'Store or update a memory',
-    inputSchema: {
-      type: 'object',
-      required: ['scope', 'key', 'value'],
-      properties: {
-        scope: { type: 'string' },
-        key: { type: 'string' },
-        value: { type: 'string' },
-        tags: { type: 'array', items: { type: 'string' } },
-        source_agent: { type: 'string' },
-        trigger: { type: 'string' },
-        created_at: {
-          type: 'string',
-          format: 'date-time',
-          description:
-            'Optional ISO 8601 creation date for migrating a pre-existing memory. Rejected if invalid or in the future. Applies only when the memory is first created.',
-        },
-        ttl_days: {
-          type: 'integer',
-          minimum: 1,
-          maximum: 365,
-          description:
-            'Optional time-to-live in days (1–365). The memory auto-expires that many days after this write and is then hidden from reads.',
-        },
-        clear_ttl: {
-          type: 'boolean',
-          description:
-            'Remove any existing expiry, making the memory permanent again. Takes precedence over ttl_days when both are supplied.',
-        },
-        origin_repo: {
-          type: 'string',
-          description:
-            'Provenance: the owner/name of the repository this memory was recorded from. Derived from the working directory when omitted.',
-        },
-        origin_branch: {
-          type: 'string',
-          description:
-            'Provenance: the git branch this memory was recorded from. Derived from the working directory when omitted.',
-        },
-        origin_commit: {
-          type: 'string',
-          description:
-            'Provenance: the commit SHA checked out when this memory was recorded. Derived from the working directory when omitted.',
-        },
-        origin_pr: {
-          type: 'integer',
-          minimum: 1,
-          description:
-            'Provenance: the pull request number this memory came out of. Pass it when you know it — the server can only infer it from CI environment variables.',
-        },
-      },
-    },
-  },
-  {
-    name: 'memory.read',
-    description: 'Read a memory by scope and key',
-    inputSchema: { type: 'object', required: ['scope', 'key'] },
-  },
-  {
-    name: 'memory.list',
-    description: 'List memories for a scope',
-    inputSchema: {
-      type: 'object',
-      required: ['scope'],
-      properties: {
-        scope: { type: 'string' },
-        tags: { type: 'array', items: { type: 'string' } },
-        limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
-        cursor: { type: 'string', description: 'Opaque cursor from a previous response\'s nextCursor. Omit to start from the first page. Ignored when kind or host is set — a taxonomy-filtered list is a single bounded page (nextCursor is always null); raise limit rather than paginating.' },
-        kind: { type: 'string', enum: ['lesson', 'bus', 'signal'], description: 'Filter to one bucket family. Narrowed server-side against the remote store; post-filtered client-side against the local store, whose rows carry no kind/host columns and are classified from their loop:: tag.' },
-        host: { type: 'string', description: 'Filter to the owning skill or agent, e.g. `reviewer`. Same server-side/client-side split as kind.' },
-        view: { type: 'string', enum: ['full', 'summary'], default: 'full', description: 'summary omits each entry\'s value and returns value_bytes + a 200-character preview instead.' },
-      },
-    },
-  },
-  {
-    name: 'memory.search',
-    description: 'Keyword search across memories',
-    inputSchema: {
-      type: 'object',
-      required: ['q'],
-      properties: {
-        q: { type: 'string' },
-        scopes: { type: 'array', items: { type: 'string' } },
-        tags: { type: 'array', items: { type: 'string' } },
-        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
-        cursor: { type: 'string', description: 'Opaque cursor from a previous response\'s nextCursor. Omit to start from the first page.' },
-      },
-    },
-  },
-  {
-    name: 'memory.delete',
-    description:
-      'Soft-archive a memory (default) or hard-delete it (force: true). ' +
-      'Archived memories are hidden from reads but can be restored.',
-    inputSchema: {
-      type: 'object',
-      required: ['scope', 'key'],
-      properties: {
-        scope: { type: 'string' },
-        key: { type: 'string' },
-        force: { type: 'boolean' },
-      },
-    },
-  },
-  {
-    name: 'memory.archive',
-    description: 'Soft-archive a memory. Hidden from reads but restorable.',
-    inputSchema: { type: 'object', required: ['scope', 'key'] },
-  },
-  {
-    name: 'memory.scopes',
-    // The description tells the model WHEN to reach for this, not just what it
-    // returns: every other read tool needs a scope named up front, so this is
-    // the one that answers "what is there?" before you can ask "what is in it?".
-    description:
-      'List every scope in the store with how many active memories it holds — '
-      + 'the inventory to consult when you do not already know which scope to read. '
-      + 'Takes no arguments and is store-wide, NOT limited to the current directory.',
-    inputSchema: { type: 'object', properties: {} },
-  },
-];
-
-// Org tools — always advertised regardless of memory mode. They always route
-// through the remote MCP endpoint because org management requires JWT auth
-// (SECURITY DEFINER RPCs resolve actor via auth.uid(), never a passed user_id).
-export const ORG_TOOL_DEFS = [
-  {
-    name: 'org.create',
-    description:
-      'Create a new organization. You become its owner automatically. ' +
-      'The slug must be globally unique and lowercase (letters, digits, hyphens).',
-    inputSchema: {
-      type: 'object',
-      required: ['slug', 'name'],
-      properties: {
-        slug: { type: 'string', description: 'Unique lowercase identifier, e.g. "my-team"' },
-        name: { type: 'string', description: 'Human-readable display name' },
-      },
-    },
-  },
-  {
-    name: 'org.list',
-    description: 'List all organizations you are a member of, with your role in each.',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'org.rename',
-    description: 'Rename an organization\'s display name. Requires admin or owner role.',
-    inputSchema: {
-      type: 'object',
-      required: ['slug', 'name'],
-      properties: {
-        slug: { type: 'string', description: 'The org slug to update' },
-        name: { type: 'string', description: 'New display name' },
-      },
-    },
-  },
-  {
-    name: 'org.delete',
-    description:
-      'Permanently delete an organization. Requires owner role. ' +
-      'All org-owned memories and memberships are cascade-deleted. Unrecoverable.',
-    inputSchema: {
-      type: 'object',
-      required: ['slug'],
-      properties: {
-        slug: { type: 'string', description: 'The org slug to delete' },
-      },
-    },
-  },
-];
-
-// Legacy alias kept so existing code that imports TOOL_DEFS still compiles.
-export const TOOL_DEFS = [...MEMORY_TOOL_DEFS, ...ORG_TOOL_DEFS];
+// Tool advertisements are DERIVED from the canonical catalog rather than
+// restated here — see the derivation below the dispatch maps, which is where
+// the set of dispatchable ops is known.
 
 /** Characters of `value` echoed in a `view: "summary"` entry's `preview`. */
 export const LIST_PREVIEW_CHARS = 200;
@@ -398,6 +224,12 @@ const MEMORY_DISPATCH = {
   'memory.search': (store, a) => store.search(a),
   'memory.delete': (store, a) => store.delete(a),
   'memory.archive': (store, a) => store.archive(a),
+  // The counterpart to archive. Both stores have implemented `restore` all
+  // along (local.mjs, remote.mjs, and the two-tier store that fronts them), so
+  // its absence here left an agent able to archive a lesson through this server
+  // but not undo it — with no stated reason. Surfaced by giving the catalog a
+  // `localMcpExempt` field and finding this op had no honest reason to fill it.
+  'memory.restore': (store, a) => store.restore(a),
   'memory.scopes': (store) => listScopes(store),
 };
 
@@ -492,6 +324,61 @@ const ORG_DISPATCH = {
   'org.delete': (remote, a) => remote.orgDelete(a),
 };
 
+// ── Tool advertisements, derived ─────────────────────────────────────────────
+// These used to be ~180 lines of hand-written `name` + `description` +
+// `inputSchema` literals — a THIRD copy of the tool list, after the catalog and
+// the edge handler, that nothing cross-checked. It had already drifted: the
+// descriptions said "memory" where the catalog says "lesson", most properties
+// carried no description at all, and `org.delete` claimed org lore was
+// "cascade-deleted. Unrecoverable." when the edge in fact SOFT-deletes it.
+//
+// Deriving from the same projection the hosted server advertises (`wireTools()`)
+// makes the local and hosted contracts identical by construction, which was the
+// stated intent of the copy all along.
+//
+// Advertise only what we can actually DISPATCH: the dispatch maps are the
+// hand-written half (a name cannot become a function by itself), so they decide
+// membership and the catalog supplies the content. An op the catalog declares
+// but this server does not back carries a `localMcpExempt` reason there.
+const CATALOG_DEFS_BY_NAME = new Map(MCP_TOOL_DEFS.map((def) => [def.name, def]));
+
+/** Catalog order, so the advertisement lists ops the way `tools/list` does. */
+const CATALOG_ORDER = new Map(MCP_TOOL_NAMES.map((name, index) => [name, index]));
+
+/**
+ * Resolve dispatchable names to their catalog advertisement, in catalog order.
+ *
+ * Driven by the DISPATCH keys, not by the catalog. Iterating the catalog and
+ * filtering to what is dispatchable reads more naturally and is wrong: every
+ * name would then be a catalog name by construction, so the check below could
+ * never fire, and the case it exists for — a dispatch key the catalog does not
+ * declare — would instead be SILENTLY DROPPED from `tools/list` while
+ * `tools/call` went on serving it. An op that is served but not advertised is
+ * precisely the drift this file stopped hand-maintaining its defs to avoid.
+ *
+ * Exported so the failure is directly testable; nothing else calls it.
+ */
+export function advertise(dispatch) {
+  return Object.keys(dispatch)
+    .map((name) => {
+      const def = CATALOG_DEFS_BY_NAME.get(name);
+      if (!def) {
+        throw new Error(
+          `mcp-server dispatches "${name}", which the tool catalog does not declare. `
+          + 'Add it to packages/schemas/src/tool-catalog.ts (and regenerate: node scripts/gen-surfaces.mjs).',
+        );
+      }
+      return def;
+    })
+    .sort((a, b) => CATALOG_ORDER.get(a.name) - CATALOG_ORDER.get(b.name));
+}
+
+export const MEMORY_TOOL_DEFS = advertise(MEMORY_DISPATCH);
+export const ORG_TOOL_DEFS = advertise(ORG_DISPATCH);
+
+// Legacy alias kept so existing code that imports TOOL_DEFS still compiles.
+export const TOOL_DEFS = [...MEMORY_TOOL_DEFS, ...ORG_TOOL_DEFS];
+
 function reply(id, result) {
   return { jsonrpc: '2.0', id, result };
 }

package/src/mcp.mjs

@@ -26,6 +26,20 @@ export function buildRemoteUrl(endpoint, token) {
 
 let idCounter = 0;
 
+/**
+ * Response header naming the account the request authenticated as, set by the
+ * edge REST router for every non-service-role caller.
+ *
+ * The CLI's only way to know its own account id without a dedicated `/me`
+ * round-trip: it rides along on calls the CLI was making anyway. Cached by
+ * `RemoteStore._rest` so LOCAL, fully-offline runs can still report which
+ * account they belong to — see `telemetry-identity.mjs`.
+ *
+ * Kept in step with `CALLER_USER_ID_HEADER` in
+ * `supabase/functions/_shared/api/router.ts`.
+ */
+export const USER_ID_HEADER = 'x-lorekit-user-id';
+
 // Returns { ok, httpStatus, result, error, networkError }.
 //
 // `opts.traceparent` is an optional W3C traceparent header value (see
@@ -223,10 +237,20 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
     const text = await res.text();
     let data = null;
     try { data = text ? JSON.parse(text) : null; } catch { /* non-JSON body */ }
+    // The account this call authenticated as, as the server resolved it. Read on
+    // BOTH the success and failure paths: a 429 or a 404 is still an
+    // authenticated request, and rate-limited traffic is exactly when knowing
+    // whose it is matters most. Surfaced, not cached, here — `mcp.mjs` is in
+    // `control.mjs`'s import graph (`splitEndpoint`), and the identity module
+    // reads `homeRoot` from `control.mjs`, so importing it here would close an
+    // import cycle. `RemoteStore._rest` — the ONE caller of this function, so
+    // nothing is missed by doing it a layer out — does the caching.
+    const userId = res.headers?.get?.(USER_ID_HEADER) ?? null;
     if (!res.ok) {
       return {
         ok: false,
         httpStatus: res.status,
+        userId,
         // How long the server asked the caller to wait, in seconds, or null when
         // it did not say. Only a 429 carries one today (`tooManyRequests` sets
         // BOTH a `retryAfterSeconds` body field and the `Retry-After` header),
@@ -236,7 +260,7 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
         error: data?.error ? { message: data.error, code: data.code } : { code: res.status, message: text.slice(0, 200) || res.statusText },
       };
     }
-    return { ok: true, httpStatus: res.status, data };
+    return { ok: true, httpStatus: res.status, data, userId };
   } catch (e) {
     return { ok: false, networkError: String(e?.message ?? e) };
   } finally {

package/src/purge.mjs

@@ -0,0 +1,191 @@
+// `lorekit purge` / `lorekit purge-expired` — the two maintenance sweeps.
+//
+//   purge [--retention-days N]   permanently delete archived lore older than N days
+//   purge-expired                permanently delete TTL-expired lore
+//
+// Both are IRREVERSIBLE and account-wide: they carry no scope, and the row set
+// is chosen inside the RPC rather than by anything the caller passes. Three
+// consequences shape this module.
+//
+// 1. REMOTE ONLY. These sweep server-side state; the offline `.lorekit/` store
+//    has no equivalent operation. `--local` is refused explicitly rather than
+//    silently succeeding against a store it cannot affect.
+//
+// 2. NO DRY RUN IS POSSIBLE. The purge RPCs return their count only AFTER
+//    deleting, and the REST dry-run header stops before the write and returns
+//    nothing previewable — so "would purge N" cannot be answered honestly. The
+//    gate is therefore a confirmation, not a preview: prompt on an interactive
+//    terminal, and REQUIRE `--yes` when there is nobody to ask (a pipe, CI, or
+//    `--json`). An agent loop must not be able to trigger one by omission.
+//
+// 3. A SCOPED KEY IS REFUSED BY THE SERVER, and that refusal is passed through
+//    verbatim. `_shared/account-wide-tools.ts` refuses these two operations for
+//    any token carrying a scope allowlist — a key narrowed to one repo has no
+//    business sweeping the whole account. The CLI makes exactly one request and
+//    reports the server's answer; it never retries, never splits the sweep and
+//    never re-scopes to work around it.
+import { resolveProjectRoot } from './config.mjs';
+import { loadControl, resolveDenies } from './control.mjs';
+import { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { log, err, c, select } from './util.mjs';
+import { PURGE_RETENTION_DAYS_DEFAULT } from './surfaces.generated.mjs';
+
+/** The window `retention_days` accepts, mirroring `PurgeMemoriesBodySchema`. */
+export const RETENTION_DAYS_MIN = 1;
+export const RETENTION_DAYS_MAX = 365;
+
+export { PURGE_RETENTION_DAYS_DEFAULT };
+
+/**
+ * Validate `--retention-days` before any request goes out.
+ *
+ * Client-side on purpose: the server would answer an out-of-range value with a
+ * schema 4xx, and paying a round trip to be told "365 is the maximum" is a
+ * worse experience than being told immediately. Pure, so the boundaries are
+ * directly testable.
+ */
+export function parseRetentionDays(raw) {
+  if (raw === undefined || raw === null || raw === '') {
+    return { days: PURGE_RETENTION_DAYS_DEFAULT };
+  }
+  // Reject `12abc` and `1.5` rather than coercing: a value only half understood
+  // is a value the caller did not mean.
+  if (!/^\d+$/.test(String(raw).trim())) {
+    return { error: `--retention-days must be a whole number, got ${JSON.stringify(String(raw))}` };
+  }
+  const days = Number(String(raw).trim());
+  if (days < RETENTION_DAYS_MIN || days > RETENTION_DAYS_MAX) {
+    return { error: `--retention-days must be between ${RETENTION_DAYS_MIN} and ${RETENTION_DAYS_MAX}, got ${days}` };
+  }
+  return { days };
+}
+
+/**
+ * Decide how to gate an irreversible sweep.
+ *
+ * `proceed` — the caller said `--yes`.
+ * `prompt`  — a human is present, so ask.
+ * `refuse`  — nobody is present to ask and consent was not given. Refusing is
+ *             the only safe answer: defaulting to yes would let an unattended
+ *             agent loop purge, and defaulting to no while reporting success
+ *             would lie about what happened.
+ *
+ * `--json` counts as non-interactive even on a TTY: its caller is a script
+ * parsing stdout, and a prompt would corrupt that stream.
+ */
+export function confirmationDecision({ yes, json, isTTY }) {
+  if (yes) return 'proceed';
+  if (json || !isTTY) return 'refuse';
+  return 'prompt';
+}
+
+/**
+ * Render a failed sweep.
+ *
+ * A 403 is almost always the account-wide refusal for a scoped key, and the
+ * server's own sentence explains it better than any translation — so it is
+ * printed VERBATIM and only a next step is added. Collapsing it into a generic
+ * "purge failed" is what would leave someone re-running the command with the
+ * same key, which is the one thing that cannot work.
+ */
+export function describeFailure({ error, httpStatus, networkError } = {}) {
+  if (networkError) return { message: networkError, hint: null };
+  const message = error?.message ?? error ?? 'the server rejected the request';
+  if (httpStatus === 403) {
+    return {
+      message: String(message),
+      hint: 'Maintenance sweeps need an UNSCOPED token — a key restricted to specific scopes is refused for account-wide operations.',
+    };
+  }
+  if (httpStatus === 429) {
+    return { message: String(message), hint: 'Rate limited. Wait for the window to reset and run it again.' };
+  }
+  return { message: String(message), hint: null };
+}
+
+/** Resolve the remote store, or explain why there isn't one. */
+function pickRemote({ root, env, args }) {
+  if (args.local) {
+    return {
+      error:
+        'purge is a remote maintenance operation — it sweeps server-side lore, '
+        + 'and the offline store has no equivalent. Drop --local to run it against the API.',
+    };
+  }
+  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 both verbs; `op` selects the store method, the label
+// and whether `--retention-days` applies.
+async function run(args, op) {
+  const root = resolveProjectRoot(args.dir);
+  const env = process.env;
+  loadControl(root, { env });
+
+  const retention = op === 'purge' ? parseRetentionDays(args['retention-days']) : { days: null };
+  if (retention.error) {
+    err(`${c.red('Error:')} ${retention.error}`);
+    return 1;
+  }
+
+  const picked = pickRemote({ root, env, args });
+  if (picked.error) {
+    err(`${c.red('Error:')} ${picked.error}`);
+    return 1;
+  }
+
+  const what = op === 'purge'
+    ? `archived lore older than ${retention.days} day${retention.days === 1 ? '' : 's'}`
+    : 'all TTL-expired lore';
+
+  const decision = confirmationDecision({ yes: args.yes, json: args.json, isTTY: Boolean(process.stdin.isTTY) });
+  if (decision === 'refuse') {
+    err(`${c.red('Refusing:')} ${op} permanently deletes ${what} and cannot be undone.`);
+    err(`Re-run with ${c.cyan('--yes')} to confirm. (Required when there is no terminal to prompt.)`);
+    return 1;
+  }
+  if (decision === 'prompt') {
+    const go = await select(
+      `${c.bold('Permanently delete')} ${what}? This cannot be undone.`,
+      [
+        { value: false, label: 'Cancel', hint: 'nothing is deleted' },
+        { value: true, label: `Yes, ${op}`, hint: 'irreversible' },
+      ],
+      { defaultIndex: 0 },
+    );
+    if (!go) {
+      log(`${c.dim('Cancelled — nothing was deleted.')}`);
+      return 0;
+    }
+  }
+
+  const res = op === 'purge'
+    ? await picked.store.purge({ retentionDays: retention.days })
+    : await picked.store.purgeExpired();
+
+  if (!res?.ok) {
+    const { message, hint } = describeFailure(res);
+    if (args.json) {
+      log(JSON.stringify({ ok: false, op, purged: null, error: message, httpStatus: res?.httpStatus ?? null }, null, 2));
+      return 1;
+    }
+    err(`${c.red('Error:')} ${message}`);
+    if (hint) err(hint);
+    return 1;
+  }
+
+  if (args.json) {
+    log(JSON.stringify({ ok: true, op, purged: res.purged ?? 0, error: null }, null, 2));
+    return 0;
+  }
+  const n = res.purged ?? 0;
+  log(`${c.green('✓')} purged ${c.cyan(String(n))} ${n === 1 ? 'memory' : 'memories'} ${c.dim('(remote)')}`);
+  return 0;
+}
+
+export function purge(args) { return run(args, 'purge'); }
+export function purgeExpired(args) { return run(args, 'purge-expired'); }

package/src/store/remote.mjs

@@ -19,6 +19,7 @@
 // no longer a transport for this store.
 // Zero-dependency.
 import { restFetch, mcpToRestBase } from '../mcp.mjs';
+import { rememberAccountId } from '../telemetry-identity.mjs';
 import { getActiveTraceparent } from '../telemetry.mjs';
 import { withReadFields } from './entry-fields.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
@@ -139,7 +140,26 @@ class RemoteStore {
 
   async _rest(path, opts = {}) {
     if (!this.usable()) return { ok: false, unusable: true };
-    return restFetch(this.restBase, this.token, path, { ...opts, traceparent: this._tp() });
+    const res = await restFetch(this.restBase, this.token, path, { ...opts, traceparent: this._tp() });
+    // Learn (and persist) which account this token belongs to, from the
+    // `X-LoreKit-User-Id` header the edge sets on every authenticated response.
+    // This is the ONE choke point for the CLI's remote traffic, so a single call
+    // site covers every command.
+    //
+    // Why cache it at all, when the server already knows: a run that never
+    // leaves the machine (`--offline`, the local two-tier store, `lorekit hook`)
+    // makes no request, so there is no server-side span to carry `auth.user_id`.
+    // Persisting it here is what lets THOSE runs report an account and join to
+    // server-side `usage_events` / `auth.user_id`.
+    //
+    // `rememberAccountId` is total, is a no-op when the value is unchanged, and
+    // never creates the identity file — so a user who opted out of telemetry
+    // gets nothing written even though they still receive the header. Guarded
+    // anyway so a store operation can never fail on a telemetry concern.
+    try {
+      rememberAccountId(res?.userId);
+    } catch { /* identity is an enrichment, never a precondition */ }
+    return res;
   }
 
   // ── Memory operations → REST ──────────────────────────────────────────────
@@ -516,6 +536,65 @@ class RemoteStore {
     return { ok: res.ok, error: res.error, networkError: res.networkError };
   }
 
+  // ── Maintenance sweeps → REST ─────────────────────────────────────────────
+  // `POST /memories/purge` and `/purge-expired` (handlers/purge.ts). Both are
+  // account-wide and irreversible, and both refuse a token carrying a scope
+  // allowlist with a 403 (`refuseAccountWideSweep`). `httpStatus` is passed
+  // through so the caller can print that refusal verbatim instead of a generic
+  // failure — the real status lives ONLY there, never in `error.code` (see
+  // `listScopes` above for why).
+
+  // `retention_days` is always SENT, never left to the server's default. For an
+  // irreversible sweep the request should record the exact window it used, and
+  // the caller has to know that number anyway to say what it is about to delete
+  // — `lorekit purge`'s confirmation names it. The default itself is derived
+  // from the tool catalog (`PURGE_RETENTION_DAYS_DEFAULT`), so sending it
+  // explicitly cannot disagree with what the server would have applied.
+  //
+  // An earlier version omitted the body when the argument was absent, to "let
+  // the server default apply". That branch was unreachable — the CLI resolves
+  // the default before calling — so it was dead code guarded by a comment that
+  // described behaviour the code did not have.
+  // Refuses an absent window LOUDLY rather than defaulting to one. `= {}` plus
+  // a bare pass-through would send `retention_days: undefined`, which
+  // JSON.stringify drops — so a caller that forgot the window would silently
+  // get the server's default and hard-delete against a window nobody chose.
+  // On an irreversible account-wide sweep that is the worst of the three
+  // options; throwing names the mistake at the call site instead. Unreachable
+  // today (`parseRetentionDays` resolves and validates before this is called),
+  // and cheap insurance for the day a second caller appears.
+  async purge({ retentionDays } = {}) {
+    if (!Number.isInteger(retentionDays)) {
+      throw new Error(
+        `purge requires an explicit integer retentionDays (got ${JSON.stringify(retentionDays)}); `
+        + 'an account-wide hard delete must never run against an unstated window.',
+      );
+    }
+    const res = await this._rest('/memories/purge', {
+      method: 'POST',
+      body: { retention_days: retentionDays },
+    });
+    return {
+      ok: res.ok,
+      purged: res.ok ? (res.data?.purged ?? 0) : null,
+      error: res.error,
+      httpStatus: res.httpStatus,
+      networkError: res.networkError,
+    };
+  }
+
+  // Takes no body — the row set is every TTL-expired memory the caller owns.
+  async purgeExpired() {
+    const res = await this._rest('/memories/purge-expired', { method: 'POST' });
+    return {
+      ok: res.ok,
+      purged: res.ok ? (res.data?.purged ?? 0) : null,
+      error: res.error,
+      httpStatus: res.httpStatus,
+      networkError: res.networkError,
+    };
+  }
+
   // ── Org operations → REST ─────────────────────────────────────────────────
   // `supabase/functions/orgs/` serves `lk_*` tokens on every route as of
   // 00041_org_actor_override.sql (see the file header). Each method's RETURN