@empirical-gauzza/cli 1.0.37 → 1.0.38

package/lib/memoryCommands.js

@@ -1,1222 +1,1267 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { log, warn } = require('./ui');
-const { httpJson, printApiError } = require('./http');
-const { parseOption, parseFlag } = require('./env');
-const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
-const { MEMORY_CATEGORIES, NODE_TYPES, DOC_TOPICS } = require('./constants');
-const { withSelectedWorkspaceContext } = require('./workspaceContext');
-
-// ─── Table rendering (--format table) ─────────────────────────────────────────
-
-function truncateForTable(value, maxLen) {
-  const str = value === undefined || value === null ? '' : String(value);
-  return str.length > maxLen ? `${str.slice(0, maxLen - 1)}…` : str;
-}
-
-function renderTable(rows, columns) {
-  if (!Array.isArray(rows) || rows.length === 0) return '(no rows)';
-  const cols = columns && columns.length ? columns : Object.keys(rows[0]);
-  const cellText = (row, col) => (row[col] === undefined || row[col] === null ? '' : String(row[col]));
-  const widths = cols.map((col) => Math.max(col.length, ...rows.map((row) => cellText(row, col).length)));
-  const renderRow = (cells) => cells.map((cell, i) => String(cell).padEnd(widths[i])).join('  ');
-  const lines = [renderRow(cols), renderRow(widths.map((w) => '-'.repeat(w)))];
-  for (const row of rows) {
-    lines.push(renderRow(cols.map((col) => cellText(row, col))));
-  }
-  return lines.join('\n');
-}
-
-function renderMemoryResultsTable(items) {
-  const rows = (Array.isArray(items) ? items : []).map((m) => ({
-    id: m.id || m._id || '',
-    category: m.category || '',
-    // A row marked usage 'style_preference_only' (a writing voice memory) says so, so a person
-    // reading the table sees what an agent reading the JSON sees.
-    summary: truncateForTable(m.summary, 60) + (m.usage === 'style_preference_only' ? ' [style]' : ''),
-    // The recall front door emits `score` (toQueryRow plus score in mcp/tools/memory.ts); the
-    // older /query route emitted rankScore/similarityScore. Read all three so the column is not
-    // blank against a real /recall row. On the list pathways score is deliberately absent, and
-    // an empty cell is the honest rendering of "this pathway does not rank".
-    score: m.score != null ? m.score : (m.rankScore != null ? m.rankScore : (m.similarityScore != null ? m.similarityScore : ''))
-  }));
-  return renderTable(rows, ['id', 'category', 'summary', 'score']);
-}
-
-// The retrieval pathways `memory query --path` may pin. Same four names the server's shared
-// normalizer accepts (packages/server/src/services/recallParams.service.ts). Omitting --path
-// leaves the classifier deciding, exactly as before.
-const RECALL_PATHS = ['semantic', 'list', 'graph', 'hebbian'];
-const RECALL_HOPS = [1, 2];
-// Hops only mean something on a pathway that walks relationships.
-const RECALL_HOP_PATHS = ['graph', 'hebbian'];
-// Reminder states `memory query --remind-state` may keep. Same enum the server's shared
-// normalizer and Memory.remindState declare.
-const REMIND_STATES = ['pending', 'notified', 'acknowledged', 'cancelled'];
-
-// ─── Scoped `--help` (C-005 item 5) ───────────────────────────────────────────
-// `empirical memory --help` / `empirical memory <sub> --help` print scoped usage instead of
-// the 90-line global help wall bin/empirical.js otherwise short-circuits every --help to.
-
-const MEMORY_SUBCOMMAND_USAGE = {
-  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--due-before <ISO date>] [--due-after <ISO date>] [--remind-state pending,notified] [--path semantic|list|graph|hebbian] [--hops 1|2] [--workspaces <n|name|id,...>] [--all-workspaces] [--pretty] [--format table]',
-  get: 'Usage: empirical memory get --memory-id <id> [--pretty]',
-  list: 'Usage: empirical memory list [--category <cat>] [--tags <t1,t2>] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]',
-  record: 'Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent]',
-  note: 'Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--min-score 0.35]',
-  update: 'Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--min-score 0.35]',
-  acknowledge: 'Usage: empirical memory acknowledge --memory-id <id> [--cancel]   (marks a due reminder done, or dropped with --cancel; frees its slot and clears the alert)',
-  delete: 'Usage: empirical memory delete (--match <query> | --memory-id <id>) [--confirm] [--min-score 0.35]\nUsage: empirical memory delete (--tag <t> | --category <c> | --all) --confirm',
-  duplicates: 'Usage: empirical memory duplicates --memory-id <id>',
-  merge: 'Usage: empirical memory merge --canonical-id <id> --duplicate-id <id> [--no-merge-tags] [--no-merge-relationships]',
-  export: 'Usage: empirical memory export --scope <personal|workspace> [--out <path>] [--workspace-id <id>]',
-  import: 'Usage: empirical memory import <file> [--dry-run]',
-  'bulk-import': 'Usage: empirical memory bulk-import <file> [--dry-run]\nFile format: { "memories": [{ "localKey": "...", "category": "...", "nodeType": "...", "summary": "...", "data": {...} }], "relationships": [{ "fromLocalKey": "...", "toLocalKey": "...", "type": "..." }] }',
-  stats: 'Usage: empirical memory stats [--format table]',
-  compact: 'Usage: empirical memory compact [--apply] [--category <cat>]'
-};
-
-function printMemoryHelp(sub) {
-  if (sub && MEMORY_SUBCOMMAND_USAGE[sub]) {
-    log(MEMORY_SUBCOMMAND_USAGE[sub]);
-    return;
-  }
-  log(DOC_TOPICS.memory);
-  log('');
-  log('Subcommands: ' + Object.keys(MEMORY_SUBCOMMAND_USAGE).join(', '));
-}
-
-async function withCliAnalyticsContext(context, fn) {
-  globalThis.__empiricalCliAnalyticsContext = context || {};
-  try {
-    return await fn();
-  } finally {
-    globalThis.__empiricalCliAnalyticsContext = null;
-  }
-}
-
-async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters) {
-  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
-  const body = { query: match, topK: 5 };
-  if (filters && Object.keys(filters).length) body.filters = filters;
-  let response;
-  try {
-    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    return { found: false, reason: 'error', message: error.message };
-  }
-
-  const results = (response && response.data && Array.isArray(response.data.results))
-    ? response.data.results
-    : (Array.isArray(response) ? response : []);
-
-  if (!results.length) {
-    return { found: false, reason: 'no_results' };
-  }
-
-  const scored = results.map((r) => ({
-    id: r.id,
-    summary: r.summary,
-    score: r.rankScore != null ? r.rankScore : (r.similarityScore != null ? r.similarityScore : 0)
-  }));
-
-  scored.sort((a, b) => b.score - a.score);
-
-  // A caller-supplied filter (e.g. --tags) that narrows the server-side result set to exactly
-  // one memory is already a stronger disambiguation signal than the semantic score - trust it
-  // outright rather than falling through to the score check below. This matters because Atlas
-  // vector search has a real async indexing lag: a memory created moments ago can come back
-  // with score 0 (unindexed, not "not this one") even when a tag filter already proves it is
-  // the only candidate. Fixes a real bug found 2026-08-25 where delete --match failed on a
-  // memory `query` found instantly, because delete had no way to trust a filtered, unambiguous
-  // result over a stale/zero semantic score.
-  if (filters && Object.keys(filters).length && results.length === 1) {
-    const only = scored[0];
-    return { found: true, memory: { id: only.id, summary: only.summary, score: only.score } };
-  }
-
-  const top = scored[0];
-  const second = scored[1];
-
-  if (top.score < minScore) {
-    return { found: false, reason: 'low_score', candidates: scored.slice(0, 3) };
-  }
-
-  if (second && (top.score - second.score) <= 0.05) {
-    return { found: false, reason: 'ambiguous', candidates: scored.slice(0, 3) };
-  }
-
-  return { found: true, memory: { id: top.id, summary: top.summary, score: top.score } };
-}
-
-// --match resolution depends on Atlas vector search, which has a real async indexing lag:
-// a memory created moments ago can be invisible to $vectorSearch even though it is already
-// findable by tag. Letting --match commands pass --tags narrows the candidate pool directly
-// instead of hoping semantic ranking surfaces the right one - the fix for a real bug found
-// 2026-08-25 where delete --match returned unrelated score-0 candidates for a memory that
-// `query` found instantly. Deliberately --tags (plural) only, not --category: `delete` already
-// uses singular --tag/--category to mean "bulk delete everything in this category", so adding
-// --category here would silently reroute a --match delete into a bulk delete instead of
-// narrowing it - --tags never collides with that bulk-mode gate.
-function parseMatchFilters(args) {
-  const tagsRaw = parseOption(args, '--tags', '');
-  const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
-  const filters = {};
-  if (tags.length) filters.tags = tags;
-  return filters;
-}
-
-function printMemoryResolveError(result) {
-  if (result.reason === 'no_results') {
-    warn(JSON.stringify({ error: true, code: 'no_results', message: 'No memories matched the query.' }));
-  } else if (result.reason === 'low_score') {
-    warn(JSON.stringify({
-      error: true,
-      code: 'low_score',
-      message: 'Top result score was below --min-score threshold.',
-      candidates: result.candidates
-    }));
-  } else if (result.reason === 'ambiguous') {
-    warn(JSON.stringify({
-      error: true,
-      code: 'ambiguous',
-      message: 'Multiple memories matched with similar scores. Use --memory-id to target one directly.',
-      candidates: result.candidates
-    }));
-  } else if (result.reason === 'error') {
-    warn(JSON.stringify({ error: true, code: 'query_error', message: result.message }));
-  } else {
-    warn(JSON.stringify({ error: true, code: 'resolve_failed', message: 'Could not resolve memory.' }));
-  }
-}
-
-// ─── Memory subcommands ───────────────────────────────────────────────────────
-
-/**
- * Turn `--workspaces` selectors (list numbers, names, or ids) into workspace ids using the
- * per-user listing (/api/v1/users/me/workspaces, the same list `workspace list` prints; number 1
- * is always the Default Workspace). An id (ws_...) passes through without a lookup. An unknown
- * name is fatal at the terminal rather than a 403 or an empty answer after the round trip.
- */
-async function resolveWorkspaceIdsForQuery({ baseUrl, accessToken, selectors = [], all = false }) {
-  const needsListing = all || selectors.some((s) => !/^ws_/.test(s));
-  let options = [];
-  if (needsListing) {
-    const listUrl = new URL('/api/v1/users/me/workspaces', baseUrl).toString();
-    let payload;
-    try {
-      payload = await httpJson(listUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
-    } catch (error) {
-      printApiError(error);
-      process.exit(1);
-    }
-    options = [
-      ...(payload?.defaultOption ? [payload.defaultOption] : []),
-      ...(Array.isArray(payload?.workspaces) ? payload.workspaces : [])
-    ].filter((o) => o && o.workspaceId);
-  }
-  if (all) return [...new Set(options.map((o) => o.workspaceId))];
-
-  const ids = [];
-  for (const selector of selectors) {
-    if (/^ws_/.test(selector)) { ids.push(selector); continue; }
-    const asNumber = Number(selector);
-    let match = null;
-    if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= options.length) {
-      match = options[asNumber - 1];
-    } else {
-      const lower = selector.toLowerCase();
-      const byLabel = options.filter((o) => String(o.label || '').toLowerCase() === lower || String(o.key || '').toLowerCase() === lower);
-      if (byLabel.length > 1) {
-        warn(`Ambiguous workspace "${selector}". Use its list number or workspace id.`);
-        process.exit(1);
-      }
-      match = byLabel[0] || null;
-    }
-    if (!match) {
-      warn(`Workspace not found: "${selector}". Run \`empirical workspace list\` to see names and numbers.`);
-      process.exit(1);
-    }
-    ids.push(match.workspaceId);
-  }
-  return [...new Set(ids)];
-}
-
-async function runMemoryQuery(args) {
-  const match = parseOption(args, '--match', '');
-  if (!match) {
-    warn(MEMORY_SUBCOMMAND_USAGE.query);
-    process.exit(1);
-  }
-
-  const topKRaw = Number(parseOption(args, '--top-k', '3'));
-  const topK = Math.min(100, Math.max(1, Number.isFinite(topKRaw) ? topKRaw : 3));
-  const category = parseOption(args, '--category', '');
-  const tagsRaw = parseOption(args, '--tags', '');
-  const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
-  // R3 (2026-09-06): --tags-all is an AND match (all must be present), unlike --tags' OR match;
-  // --status filters data.status. Both are optional and additive to --tags/--category.
-  const tagsAllRaw = parseOption(args, '--tags-all', '');
-  const tagsAll = tagsAllRaw ? tagsAllRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
-  // Multi-workspace recall (2026-09-24). --workspaces takes list numbers, names, or ids; names
-  // and numbers are resolved against the same listing `workspace list` prints, so the server
-  // contract stays ids-only. --all-workspaces sends every selectable workspace. Without either
-  // flag the query is scoped to the single active workspace exactly as before.
-  const workspacesRaw = parseOption(args, '--workspaces', '');
-  const workspaceSelectors = workspacesRaw ? workspacesRaw.split(',').map((w) => w.trim()).filter(Boolean) : [];
-  const allWorkspaces = parseFlag(args, '--all-workspaces');
-  if (workspaceSelectors.length && allWorkspaces) {
-    warn('Pass either --workspaces or --all-workspaces, not both.');
-    process.exit(1);
-  }
-  const statusRaw = parseOption(args, '--status', '');
-  const status = statusRaw ? statusRaw.split(',').map((s) => s.trim()).filter(Boolean) : [];
-  const pretty = parseFlag(args, '--pretty');
-  const format = parseOption(args, '--format', 'json');
-
-  // Reminder filters. Dates are parsed HERE as well as server-side, for the same reason --due
-  // is on record: a typo fails at the terminal, not as a 400 after the round trip. Anything
-  // Date can parse is accepted and sent as the caller typed it.
-  const dueFilters = {};
-  for (const [flag, key] of [['--due-before', 'dueBefore'], ['--due-after', 'dueAfter']]) {
-    const raw = parseOption(args, flag, '');
-    if (!raw) continue;
-    if (Number.isNaN(new Date(raw).getTime())) {
-      warn(`Invalid ${flag} "${raw}". Use an ISO 8601 date, for example 2026-10-14 or 2026-10-14T09:00:00Z.`);
-      process.exit(1);
-    }
-    dueFilters[key] = String(raw).trim();
-  }
-  const remindStateRaw = parseOption(args, '--remind-state', '');
-  const remindState = remindStateRaw
-    ? remindStateRaw.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)
-    : [];
-  const unknownStates = remindState.filter((s) => !REMIND_STATES.includes(s));
-  if (unknownStates.length) {
-    warn(`--remind-state must be one of: ${REMIND_STATES.join(', ')} (received ${JSON.stringify(unknownStates)})`);
-    process.exit(1);
-  }
-
-  // --path / --hops are validated HERE, where the value is decided, so a typo costs no round
-  // trip and the message names the four pathways. The server validates the same way (the shared
-  // normalizer in packages/server/src/services/recallParams.service.ts); this is a fast local
-  // echo of that contract, never a second, looser one.
-  const pathRaw = parseOption(args, '--path', '');
-  let path = '';
-  if (pathRaw) {
-    path = String(pathRaw).trim().toLowerCase();
-    if (!RECALL_PATHS.includes(path)) {
-      warn(`--path must be one of: ${RECALL_PATHS.join(', ')} (received ${JSON.stringify(pathRaw)})`);
-      process.exit(1);
-    }
-  }
-
-  const hopsRaw = parseOption(args, '--hops', '');
-  let hops = null;
-  if (hopsRaw) {
-    const parsedHops = Number(hopsRaw);
-    if (!RECALL_HOPS.includes(parsedHops)) {
-      warn(`--hops must be 1 or 2 (received ${JSON.stringify(hopsRaw)})`);
-      process.exit(1);
-    }
-    // Silently ignoring --hops on a ranked or list pathway would look like it took effect.
-    if (!RECALL_HOP_PATHS.includes(path)) {
-      warn(`--hops only applies with --path graph or --path hebbian${path ? ` (received --path ${path})` : ' (no --path given)'}`);
-      process.exit(1);
-    }
-    hops = parsedHops;
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  // The recall front door: the same answer the MCP query_memories tool gives, which /query never
-  // gave (classifier routing, the list block, the exact-tag retry, agent-note exclusion,
-  // retrievalPath). It takes its parameters FLAT, matching the shared normalizer, not nested
-  // under `filters` the way the older /query route did. Send one shape only.
-  const queryUrl = new URL('/api/v1/memories/recall', baseUrl).toString();
-
-  const body = { query: match, topK };
-  if (category) body.category = category;
-  if (tags.length) body.tags = tags;
-  if (tagsAll.length) body.tagsAll = tagsAll;
-  if (workspaceSelectors.length || allWorkspaces) {
-    body.workspaceIds = await resolveWorkspaceIdsForQuery({
-      baseUrl,
-      accessToken,
-      selectors: workspaceSelectors,
-      all: allWorkspaces
-    });
-  }
-  if (status.length) body.status = status;
-  if (dueFilters.dueBefore) body.dueBefore = dueFilters.dueBefore;
-  if (dueFilters.dueAfter) body.dueAfter = dueFilters.dueAfter;
-  if (remindState.length) body.remindState = remindState;
-  if (path) body.path = path;
-  if (hops !== null) body.hops = hops;
-
-  let response;
-  try {
-    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    // A 404 here means the server predates the recall front door. Say that plainly instead of
-    // rerouting to /query: that fallback would quietly answer through a different routing path
-    // with different defaults (topK 10 against 3) and keep the old route alive forever.
-    if (error && error.statusCode === 404) {
-      warn(JSON.stringify({
-        error: true,
-        code: 'recall_route_missing',
-        message: 'This server does not serve /api/v1/memories/recall yet. Upgrade the Empirical server, or use an older CLI against it.'
-      }));
-      process.exit(1);
-    }
-    printApiError(error);
-    process.exit(1);
-  }
-
-  // The front door answers with data.memories; the older /query route answered with data.results.
-  // Both are accepted so a CLI pointed at a server that predates /recall still prints rows.
-  const data = response && response.data ? response.data : null;
-  const results = (data && Array.isArray(data.memories))
-    ? data.memories
-    : ((data && Array.isArray(data.results))
-      ? data.results
-      : (Array.isArray(response) ? response : []));
-
-  if (format === 'table') {
-    log(renderMemoryResultsTable(results));
-    return;
-  }
-
-  if (pretty) {
-    log(JSON.stringify(results, null, 2));
-  } else {
-    log(JSON.stringify(results));
-  }
-}
-
-async function runMemoryGet(args) {
-  const memoryId = parseOption(args, '--memory-id', '');
-  const pretty = parseFlag(args, '--pretty');
-  if (!memoryId) {
-    warn('Usage: empirical memory get --memory-id <id> [--pretty]');
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}`, baseUrl).toString();
-  let response;
-  try {
-    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-  const data = response && response.data ? response.data : response;
-  log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
-}
-
-async function runMemoryList(args) {
-  const category = parseOption(args, '--category', '');
-  const tags = parseOption(args, '--tags', '');
-  const startDate = parseOption(args, '--start-date', '');
-  const endDate = parseOption(args, '--end-date', '');
-  const limitRaw = Number(parseOption(args, '--limit', '20'));
-  const limit = Math.min(100, Math.max(1, Number.isFinite(limitRaw) ? limitRaw : 20));
-  const cursor = parseOption(args, '--cursor', '');
-  const sortOrder = parseFlag(args, '--oldest') ? 'asc' : 'desc';
-  const pretty = parseFlag(args, '--pretty');
-  const format = parseOption(args, '--format', 'json');
-
-  const params = new URLSearchParams();
-  if (category) params.set('category', category);
-  if (tags) params.set('tags', tags);
-  if (startDate) params.set('startDate', startDate);
-  if (endDate) params.set('endDate', endDate);
-  params.set('limit', String(limit));
-  if (cursor) params.set('cursor', cursor);
-  params.set('sortBy', 'createdAt');
-  params.set('sortOrder', sortOrder);
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL(`/api/v1/memories?${params.toString()}`, baseUrl).toString();
-  let response;
-  try {
-    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-  const data = response && response.data ? response.data : response;
-
-  if (format === 'table') {
-    const items = Array.isArray(data && data.memories) ? data.memories : (Array.isArray(data) ? data : []);
-    log(renderMemoryResultsTable(items));
-    return;
-  }
-
-  log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
-}
-
-// Shell substitution silently eats code out of a double-quoted --summary: backticks become
-// command substitution and ${...} becomes variable expansion BEFORE the CLI ever sees the
-// text, and the write still succeeds, so the memory looks fine with the code gone. Two
-// defenses: (1) inputs that never pass through shell quoting -- `--summary-file <path>` and
-// `--summary -` (stdin, pair it with a single-quoted heredoc); (2) a warning when an inline
-// summary carries the residue of an eaten substitution.
-function resolveSummaryInput(args, { readFile = (p) => fs.readFileSync(path.resolve(p), 'utf8'), readStdin = () => fs.readFileSync(0, 'utf8') } = {}) {
-  const summaryFile = parseOption(args, '--summary-file', '');
-  if (summaryFile) {
-    return { summary: String(readFile(summaryFile)).replace(/\r?\n$/, ''), source: 'file' };
-  }
-  const inline = parseOption(args, '--summary', '');
-  if (inline === '-') {
-    return { summary: String(readStdin()).replace(/\r?\n$/, ''), source: 'stdin' };
-  }
-  return { summary: inline, source: inline ? 'inline' : 'none' };
-}
-
-function detectShellMangling(summary) {
-  const text = String(summary || '');
-  const reasons = [];
-  if (/``/.test(text)) reasons.push('an empty backtick pair (a `command` was probably substituted away)');
-  if (/\$(\s|$|[^A-Za-z0-9_{(])/.test(text) && !/\$\d/.test(text)) reasons.push('a lone "$" (a ${VAR} or $(cmd) was probably expanded to nothing)');
-  if (/\$\{\s*\}/.test(text)) reasons.push('an empty ${} placeholder');
-  return reasons;
-}
-
-async function runMemoryRecord(args) {
-  const jsonFile = parseOption(args, '--json-file', '');
-  let payload;
-
-  if (jsonFile) {
-    try {
-      payload = JSON.parse(fs.readFileSync(path.resolve(jsonFile), 'utf8'));
-    } catch (error) {
-      warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
-      process.exit(1);
-    }
-  } else {
-    const category = parseOption(args, '--category', '');
-    const { summary, source: summarySource } = resolveSummaryInput(args);
-
-    if (summarySource === 'inline') {
-      const mangled = detectShellMangling(summary);
-      if (mangled.length) {
-        warn(JSON.stringify({
-          warning: 'possible_shell_substitution',
-          message: 'The summary looks like the shell altered it before the CLI saw it: ' + mangled.join('; ') + '. Recording anyway. For text containing backticks or ${...}, use --summary-file <path>, or --summary - with a single-quoted heredoc, or the MCP record_graph_memory tool.'
-        }));
-      }
-    }
-
-    if (!category || !summary) {
-      warn('Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent]');
-      warn('Valid categories: ' + MEMORY_CATEGORIES.join(', '));
-      warn('Valid node types: ' + NODE_TYPES.join(', '));
-      process.exit(1);
-    }
-
-    if (!MEMORY_CATEGORIES.includes(category)) {
-      warn(JSON.stringify({
-        error: true,
-        code: 'invalid_category',
-        message: `Invalid category "${category}". Valid: ${MEMORY_CATEGORIES.join(', ')}`
-      }));
-      process.exit(1);
-    }
-
-    const tagsRaw = parseOption(args, '--tags', '');
-    const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
-    const nodeType = parseOption(args, '--node-type', 'observation');
-
-    if (!NODE_TYPES.includes(nodeType)) {
-      warn(JSON.stringify({
-        error: true,
-        code: 'invalid_node_type',
-        message: `Invalid nodeType "${nodeType}". Valid: ${NODE_TYPES.join(', ')}`
-      }));
-      process.exit(1);
-    }
-
-    payload = { category, summary, nodeType, data: { text: String(summary) } };
-    if (tags.length) payload.tags = tags;
-  }
-
-  if (
-    payload
-    && payload.summary !== undefined
-    && payload.data === undefined
-    && payload.originalPayload === undefined
-  ) {
-    payload.data = { text: String(payload.summary) };
-  }
-
-  // C-002 (docs/prd-cli-and-plugin-fixes.md): the server now dedupes/auto-links every
-  // POST /api/v1/memories write by default, matching the MCP record_graph_memory tool's
-  // guarantee. Only send dedupeEnabled/autoLink at all when the caller explicitly opted
-  // out here -- omitting them entirely lets the server's own default-on behavior apply,
-  // rather than this CLI baking in a redundant "true" that could drift from the server's
-  // actual default over time.
-  if (parseFlag(args, '--no-dedupe')) {
-    payload.dedupeEnabled = false;
-  }
-  if (parseFlag(args, '--no-auto-link')) {
-    payload.autoLink = false;
-  }
-
-  // Authorship (2026-09-09). `source` is observable truth: this is the CLI, so say so.
-  // Until now the CLI sent nothing, the server fell back to the transport it saw ('api'),
-  // and api maps to authorType 'user' because that mapping was written for the web portal.
-  // Every agent write through this command was therefore stored as authored by the user.
-  // 'cli' resolves to authorType 'unknown', which is the honest answer when nobody says.
-  if (payload.source === undefined) payload.source = 'cli';
-
-  // --author-type lets the caller state what the transport cannot know. An agent recording
-  // its own session notes should pass 'agent'; an agent recording something the user said
-  // or decided should pass 'user'. Omitted, it stays 'unknown' rather than being guessed.
-  const authorType = parseOption(args, '--author-type', '');
-  if (authorType) {
-    if (!['user', 'agent', 'system'].includes(authorType)) {
-      warn(JSON.stringify({
-        error: true,
-        code: 'invalid_author_type',
-        message: `Invalid --author-type "${authorType}". Valid: user, agent, system`
-      }));
-      process.exit(1);
-    }
-    payload.authorType = authorType;
-  }
-
-  // --due turns the memory into a reminder. Parsed and rejected HERE as well as server-side, so
-  // a typo fails immediately at the terminal instead of coming back as a 400 after the write was
-  // composed. Accepts anything Date can parse, so '2026-10-14' and a full ISO timestamp both work.
-  const dueRaw = parseOption(args, '--due', '');
-  if (dueRaw) {
-    const parsedDue = new Date(dueRaw);
-    if (Number.isNaN(parsedDue.getTime())) {
-      warn(JSON.stringify({
-        error: true,
-        code: 'invalid_due',
-        message: `Invalid --due "${dueRaw}". Use an ISO 8601 date, for example 2026-10-14 or 2026-10-14T09:00:00Z.`
-      }));
-      process.exit(1);
-    }
-    payload.dueAt = parsedDue.toISOString();
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const recordUrl = new URL('/api/v1/memories', baseUrl).toString();
-
-  let response;
-  try {
-    response = await httpJson(recordUrl, 'POST', payload, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const created = (response && response.data) ? response.data : response;
-  log(JSON.stringify(created));
-}
-
-async function runMemoryNote(args) {
-  const match = parseOption(args, '--match', '');
-  const text = parseOption(args, '--text', '');
-  const memoryId = parseOption(args, '--memory-id', '');
-  const minScore = Number(parseOption(args, '--min-score', '0.35'));
-
-  if (!text) {
-    warn('Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--tags <t1,t2>] [--min-score 0.35]');
-    process.exit(1);
-  }
-
-  if (!match && !memoryId) {
-    warn('Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--tags <t1,t2>]');
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-
-  let targetId = memoryId;
-  if (!targetId) {
-    const filters = parseMatchFilters(args);
-    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
-    if (!result.found) {
-      printMemoryResolveError(result);
-      process.exit(1);
-    }
-    targetId = result.memory.id;
-  }
-
-  const noteUrl = new URL(`/api/v1/memories/${encodeURIComponent(targetId)}/notes`, baseUrl).toString();
-  let response;
-  try {
-    response = await httpJson(noteUrl, 'POST', { text }, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const created = (response && response.data) ? response.data : response;
-  log(JSON.stringify(created));
-}
-
-// Closing a reminder from the terminal or from an agent reading a CLI banner. One PUT, the same
-// transition the portal's Mark done / Cancel make; the server retires the alert on every surface.
-async function runMemoryAcknowledge(args) {
-  const memoryId = parseOption(args, '--memory-id', '');
-  const cancel = parseFlag(args, '--cancel');
-  if (!memoryId) {
-    warn(MEMORY_SUBCOMMAND_USAGE.acknowledge);
-    process.exit(1);
-  }
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}`, baseUrl).toString();
-  let response;
-  try {
-    response = await httpJson(url, 'PUT', { remindState: cancel ? 'cancelled' : 'acknowledged' }, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-  const data = response && response.data ? response.data : response;
-  log(JSON.stringify({ id: data.id, remindState: data.remindState, dueAt: data.dueAt || null, message: cancel ? 'Reminder cancelled. Its slot is free.' : 'Reminder marked done. Its slot is free.' }, null, 2));
-}
-
-async function runMemoryUpdate(args) {
-  const match = parseOption(args, '--match', '');
-  const patchJson = parseOption(args, '--patch-json', '');
-  const jsonFile = parseOption(args, '--json-file', '');
-  const memoryId = parseOption(args, '--memory-id', '');
-  const minScore = Number(parseOption(args, '--min-score', '0.35'));
-
-  if (!patchJson && !jsonFile) {
-    warn('Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--tags <t1,t2>]');
-    process.exit(1);
-  }
-
-  if (!match && !memoryId) {
-    warn('Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--tags <t1,t2>]');
-    process.exit(1);
-  }
-
-  let patch;
-  if (jsonFile) {
-    try {
-      patch = JSON.parse(fs.readFileSync(path.resolve(jsonFile), 'utf8'));
-    } catch (error) {
-      warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
-      process.exit(1);
-    }
-  } else {
-    try {
-      patch = JSON.parse(patchJson);
-    } catch (error) {
-      warn(JSON.stringify({ error: true, code: 'invalid_json', message: `--patch-json parse error: ${error.message}` }));
-      process.exit(1);
-    }
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-
-  let targetId = memoryId;
-  if (!targetId) {
-    const filters = parseMatchFilters(args);
-    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
-    if (!result.found) {
-      printMemoryResolveError(result);
-      process.exit(1);
-    }
-    targetId = result.memory.id;
-  }
-
-  const updateUrl = new URL(`/api/v1/memories/${encodeURIComponent(targetId)}`, baseUrl).toString();
-  let response;
-  try {
-    response = await httpJson(updateUrl, 'PUT', patch, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const updated = (response && response.data) ? response.data : response;
-  log(JSON.stringify(updated));
-}
-
-async function runMemoryDeleteBulk(args) {
-  const tag = parseOption(args, '--tag', '');
-  const category = parseOption(args, '--category', '');
-  const all = parseFlag(args, '--all');
-  const confirm = parseFlag(args, '--confirm');
-
-  const selectorCount = [Boolean(tag), Boolean(category), all].filter(Boolean).length;
-  if (selectorCount !== 1) {
-    warn('Usage: empirical memory delete (--tag <t> | --category <c> | --all) --confirm');
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL('/api/v1/memory-bulk-delete', baseUrl).toString();
-  const body = { confirm };
-  if (tag) body.tag = tag;
-  if (category) body.category = category;
-  if (all) body.all = true;
-
-  let response;
-  try {
-    response = await httpJson(url, 'POST', body, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  // Server always reports the count first: without --confirm it's a dry-run preview and no
-  // writes happened; with --confirm it reports what it just deleted. Either way the count is
-  // printed, matching the single-memory delete's dry-run-by-default convention above.
-  const data = (response && response.data) ? response.data : response;
-  log(JSON.stringify(data));
-}
-
-async function runMemoryDelete(args) {
-  const tag = parseOption(args, '--tag', '');
-  const category = parseOption(args, '--category', '');
-  const all = parseFlag(args, '--all');
-  if (tag || category || all) {
-    return runMemoryDeleteBulk(args);
-  }
-
-  const match = parseOption(args, '--match', '');
-  const memoryId = parseOption(args, '--memory-id', '');
-  const minScore = Number(parseOption(args, '--min-score', '0.35'));
-  const confirm = parseFlag(args, '--confirm');
-
-  if (!match && !memoryId) {
-    warn('Usage: empirical memory delete (--match <query> | --memory-id <id>) [--tags <t1,t2>] [--confirm] [--min-score 0.35]');
-    warn('   or: empirical memory delete (--tag <t> | --category <c> | --all) --confirm');
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-
-  let targetId = memoryId;
-  let targetSummary = '';
-
-  if (!targetId) {
-    const filters = parseMatchFilters(args);
-    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
-    if (!result.found) {
-      if (!confirm && (result.reason === 'ambiguous' || result.reason === 'low_score')) {
-        // Dry-run: return candidates info
-        log(JSON.stringify({ dryRun: true, wouldDelete: false, reason: result.reason, candidates: result.candidates }));
-        process.exit(0);
-      }
-      printMemoryResolveError(result);
-      process.exit(1);
-    }
-    targetId = result.memory.id;
-    targetSummary = result.memory.summary;
-  }
-
-  if (!confirm) {
-    log(JSON.stringify({ dryRun: true, wouldDelete: true, id: targetId, summary: targetSummary }));
-    process.exit(0);
-  }
-
-  const deleteUrl = new URL(`/api/v1/memories/${encodeURIComponent(targetId)}`, baseUrl).toString();
-  try {
-    await httpJson(deleteUrl, 'DELETE', null, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  log(JSON.stringify({ deleted: true, id: targetId, summary: targetSummary }));
-}
-
-async function runMemoryDuplicates(args) {
-  const memoryId = parseOption(args, '--memory-id', '');
-  if (!memoryId) {
-    warn('Usage: empirical memory duplicates --memory-id <id>');
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}/duplicate-candidates`, baseUrl).toString();
-
-  let response;
-  try {
-    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const data = (response && response.data) ? response.data : response;
-  log(JSON.stringify(data));
-}
-
-async function runMemoryMerge(args) {
-  const canonicalId = parseOption(args, '--canonical-id', '');
-  const duplicateId = parseOption(args, '--duplicate-id', '');
-  const mergeTags = !parseFlag(args, '--no-merge-tags');
-  const mergeRelationships = !parseFlag(args, '--no-merge-relationships');
-
-  if (!canonicalId || !duplicateId) {
-    warn('Usage: empirical memory merge --canonical-id <id> --duplicate-id <id> [--no-merge-tags] [--no-merge-relationships]');
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL('/api/v1/memories/merge', baseUrl).toString();
-
-  let response;
-  try {
-    response = await httpJson(url, 'POST', { canonicalId, duplicateId, mergeTags, mergeRelationships }, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const data = (response && response.data) ? response.data : response;
-  log(JSON.stringify(data));
-}
-
-async function runMemoryExport(args) {
-  const scope = parseOption(args, '--scope', '');
-  if (scope !== 'personal' && scope !== 'workspace') {
-    warn('Usage: empirical memory export --scope <personal|workspace> [--out <path>] [--workspace-id <id>]');
-    process.exit(1);
-  }
-
-  const workspaceId = parseOption(args, '--workspace-id', '');
-  if (scope === 'workspace' && !workspaceId) {
-    warn('Usage: empirical memory export --scope workspace --workspace-id <id> [--out <path>]');
-    process.exit(1);
-  }
-
-  const dateStamp = new Date().toISOString().slice(0, 10);
-  const outPath = parseOption(args, '--out', `./empirical-memory-export-${scope}-${dateStamp}.json`);
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL(`/api/v1/memories/export?scope=${encodeURIComponent(scope)}`, baseUrl).toString();
-
-  const headers = buildApiAuthHeaders(accessToken);
-  if (workspaceId) {
-    headers['x-workspace-id'] = workspaceId;
-  }
-
-  let response;
-  try {
-    response = await httpJson(url, 'GET', undefined, headers);
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  // The raw server response is the export envelope itself (streamed as one JSON body, not the
-  // standard {status,data} wrapper): {schemaVersion, generatedAt, scope, workspaceId,
-  // memoryCount, truncated, memories: [...]}. Re-shape it into the versioned, round-trippable
-  // format `memory import` consumes: {schemaVersion: 1, exportedAt, memories: [{category,
-  // summary, tags, nodeType, data, mass, gravity, timeContext, notes, relationships}]}.
-  const rawMemories = Array.isArray(response && response.memories) ? response.memories : [];
-  const envelope = {
-    schemaVersion: 1,
-    exportedAt: new Date().toISOString(),
-    memories: rawMemories.map((m) => ({
-      category: m.category,
-      summary: m.summary,
-      tags: Array.isArray(m.tags) ? m.tags : [],
-      nodeType: m.nodeType,
-      data: m.data,
-      mass: m.mass,
-      gravity: m.gravity,
-      timeContext: m.timeContext || null,
-      notes: Array.isArray(m.notes) ? m.notes.map((n) => ({ text: n.text })) : [],
-      relationships: Array.isArray(m.relationships)
-        ? m.relationships.map((r) => ({ type: r.type, targetId: r.targetId, weight: r.weight }))
-        : []
-    }))
-  };
-
-  const resolvedPath = path.resolve(outPath);
-  fs.writeFileSync(resolvedPath, JSON.stringify(envelope, null, 2) + '\n', 'utf8');
-
-  log(JSON.stringify({ exported: true, path: resolvedPath, schemaVersion: envelope.schemaVersion, memoryCount: envelope.memories.length }));
-}
-
-async function runMemoryImport(args) {
-  const filePath = args.find((a) => a && !a.startsWith('--')) || '';
-  const dryRun = parseFlag(args, '--dry-run');
-
-  if (!filePath) {
-    warn('Usage: empirical memory import <file> [--dry-run]');
-    process.exit(1);
-  }
-
-  let doc;
-  try {
-    doc = JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8'));
-  } catch (error) {
-    warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
-    process.exit(1);
-  }
-
-  const memories = Array.isArray(doc && doc.memories) ? doc.memories : null;
-  if (!memories) {
-    warn(JSON.stringify({
-      error: true,
-      code: 'invalid_format',
-      message: 'File is not a valid Empirical memory export: missing a top-level "memories" array. Re-export with `empirical memory export`.'
-    }));
-    process.exit(1);
-  }
-
-  if (dryRun) {
-    log(JSON.stringify({ dryRun: true, wouldImport: memories.length, schemaVersion: doc.schemaVersion || null }));
-    return;
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  // Every row goes through the normal create endpoint, so imports get the same dedupe and
-  // auto-link treatment as any other write, no special-casing needed here.
-  const recordUrl = new URL('/api/v1/memories', baseUrl).toString();
-
-  let imported = 0;
-  let failed = 0;
-  const errors = [];
-
-  for (const row of memories) {
-    const payload = {
-      category: row.category,
-      summary: row.summary,
-      nodeType: row.nodeType || 'observation',
-      tags: Array.isArray(row.tags) ? row.tags : [],
-      data: row.data !== undefined
-        ? row.data
-        : (row.summary !== undefined ? { text: String(row.summary) } : undefined)
-    };
-    if (Array.isArray(row.relationships) && row.relationships.length) payload.relationships = row.relationships;
-    if (row.mass !== undefined && row.mass !== null) payload.mass = row.mass;
-    if (row.gravity !== undefined && row.gravity !== null) payload.gravity = row.gravity;
-    if (row.timeContext) payload.timeContext = row.timeContext;
-
-    let created;
-    try {
-      const response = await httpJson(recordUrl, 'POST', payload, buildApiAuthHeaders(accessToken));
-      created = (response && response.data) ? response.data : response;
-      imported++;
-    } catch (error) {
-      failed++;
-      errors.push({ summary: row.summary, message: error.message });
-      continue;
-    }
-
-    const notes = Array.isArray(row.notes) ? row.notes : [];
-    const createdId = created && (created.id || created._id);
-    if (notes.length && createdId) {
-      const noteUrl = new URL(`/api/v1/memories/${encodeURIComponent(createdId)}/notes`, baseUrl).toString();
-      for (const note of notes) {
-        const text = typeof note === 'string' ? note : (note && note.text);
-        if (!text) continue;
-        try {
-          await httpJson(noteUrl, 'POST', { text }, buildApiAuthHeaders(accessToken));
-        } catch (_error) {
-          // Best-effort: a note failing to re-attach shouldn't fail the whole import.
-        }
-      }
-    }
-  }
-
-  log(JSON.stringify({ imported, failed, total: memories.length, errors: errors.slice(0, 20) }));
-}
-
-async function runMemoryBulkImport(args) {
-  const filePath = args.find((a) => a && !a.startsWith('--')) || '';
-  const dryRun = parseFlag(args, '--dry-run');
-
-  if (!filePath) {
-    warn('Usage: empirical memory bulk-import <file> [--dry-run]');
-    process.exit(1);
-  }
-
-  let plan;
-  try {
-    plan = JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8'));
-  } catch (error) {
-    warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
-    process.exit(1);
-  }
-
-  const memories = Array.isArray(plan && plan.memories) ? plan.memories : null;
-  if (!memories) {
-    warn(JSON.stringify({
-      error: true,
-      code: 'invalid_format',
-      message: 'File must have a top-level "memories" array. See `empirical memory bulk-import --help`.'
-    }));
-    process.exit(1);
-  }
-  const relationships = Array.isArray(plan.relationships) ? plan.relationships : [];
-
-  if (dryRun) {
-    log(JSON.stringify({ dryRun: true, wouldImportMemories: memories.length, wouldImportRelationships: relationships.length }));
-    return;
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const bulkUrl = new URL('/api/v1/memories/bulk', baseUrl).toString();
-
-  try {
-    const enqueueResponse = await httpJson(bulkUrl, 'POST', { memories, relationships }, buildApiAuthHeaders(accessToken));
-    const { jobId } = (enqueueResponse && enqueueResponse.data) ? enqueueResponse.data : enqueueResponse;
-    const statusUrl = new URL(`/api/v1/memories/bulk/${jobId}`, baseUrl).toString();
-
-    const pollIntervalMs = 3000;
-    const maxPolls = 200;
-    for (let i = 0; i < maxPolls; i += 1) {
-      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-      const statusResponse = await httpJson(statusUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
-      const job = (statusResponse && statusResponse.data) ? statusResponse.data : statusResponse;
-      if (job.status === 'succeeded') { log(JSON.stringify(job)); return; }
-      if (job.status === 'failed') { warn(JSON.stringify(job)); process.exit(1); }
-    }
-    warn(JSON.stringify({ error: true, code: 'timeout', message: `Job ${jobId} did not complete within ${(maxPolls * pollIntervalMs) / 1000}s` }));
-    process.exit(1);
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-}
-
-async function runMemoryStats(args) {
-  const format = parseOption(args, '--format', 'json');
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL('/api/v1/memory-stats', baseUrl).toString();
-
-  let response;
-  try {
-    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const data = (response && response.data) ? response.data : response;
-
-  if (format === 'table') {
-    log(`Total memories: ${data.total}`);
-    log(`Oldest: ${data.oldest || '(none)'}`);
-    log(`Newest: ${data.newest || '(none)'}`);
-    log('');
-    log('By category:');
-    log(renderTable(data.byCategory || [], ['category', 'count']));
-    log('');
-    log('By tag:');
-    log(renderTable(data.byTag || [], ['tag', 'count']));
-    return;
-  }
-
-  log(JSON.stringify(data));
-}
-
-async function runMemoryCompact(args) {
-  const apply = parseFlag(args, '--apply');
-  const category = parseOption(args, '--category', '');
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const url = new URL('/api/v1/memory-compaction', baseUrl).toString();
-  const body = { apply };
-  if (category) body.category = category;
-
-  let response;
-  try {
-    response = await httpJson(url, 'POST', body, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const data = (response && response.data) ? response.data : response;
-  log(JSON.stringify(data));
-}
-
-async function runMemoryCommand(subArgs) {
-  const helpRequested = subArgs.includes('--help') || subArgs.includes('-h');
-  const sub = subArgs[0] && !subArgs[0].startsWith('-') ? subArgs[0] : undefined;
-
-  if (helpRequested || !sub) {
-    printMemoryHelp(sub);
-    return;
-  }
-
-  const rest = subArgs.slice(1);
-
-  return withCliAnalyticsContext(
-    { command: `memory.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
-    async () => withSelectedWorkspaceContext(async () => {
-      if (sub === 'query') return runMemoryQuery(rest);
-      if (sub === 'get') return runMemoryGet(rest);
-      if (sub === 'list') return runMemoryList(rest);
-      if (sub === 'record') return runMemoryRecord(rest);
-      if (sub === 'note') return runMemoryNote(rest);
-      if (sub === 'update') return runMemoryUpdate(rest);
-      if (sub === 'acknowledge' || sub === 'ack' || sub === 'done') return runMemoryAcknowledge(rest);
-      if (sub === 'delete') return runMemoryDelete(rest);
-      if (sub === 'duplicates') return runMemoryDuplicates(rest);
-      if (sub === 'merge') return runMemoryMerge(rest);
-      if (sub === 'export') return runMemoryExport(rest);
-      if (sub === 'import') return runMemoryImport(rest);
-      if (sub === 'bulk-import') return runMemoryBulkImport(rest);
-      if (sub === 'stats') return runMemoryStats(rest);
-      if (sub === 'compact') return runMemoryCompact(rest);
-
-      warn('Unknown memory subcommand: ' + (sub || '(none)'));
-      warn('Usage: empirical memory <query|record|note|update|delete|duplicates|merge|export|import|stats|compact> [options]');
-      process.exit(1);
-    })
-  );
-}
-
-module.exports = {
-  resolveSummaryInput,
-  detectShellMangling,
-  withCliAnalyticsContext,
-  resolveMemoryByQuery,
-  printMemoryResolveError,
-  resolveWorkspaceIdsForQuery,
-  runMemoryQuery,
-  runMemoryGet,
-  runMemoryList,
-  runMemoryRecord,
-  runMemoryNote,
-  runMemoryUpdate,
-  runMemoryAcknowledge,
-  runMemoryDelete,
-  runMemoryDuplicates,
-  runMemoryMerge,
-  runMemoryExport,
-  runMemoryImport,
-  runMemoryBulkImport,
-  runMemoryStats,
-  runMemoryCompact,
-  runMemoryDeleteBulk,
-  runMemoryCommand
-};
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { log, warn } = require('./ui');
+const { httpJson, printApiError } = require('./http');
+const { parseOption, parseFlag } = require('./env');
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { MEMORY_CATEGORIES, NODE_TYPES, DOC_TOPICS } = require('./constants');
+const { withSelectedWorkspaceContext } = require('./workspaceContext');
+const { resolveMemoryByQuery, parseMatchFilters, printMemoryResolveError } = require('./memoryResolve');
+const { runAttachmentCommand, ATTACHMENT_SUBCOMMAND_USAGE } = require('./attachmentCommands');
+
+// ─── Table rendering (--format table) ─────────────────────────────────────────
+
+function truncateForTable(value, maxLen) {
+  const str = value === undefined || value === null ? '' : String(value);
+  return str.length > maxLen ? `${str.slice(0, maxLen - 1)}…` : str;
+}
+
+function renderTable(rows, columns) {
+  if (!Array.isArray(rows) || rows.length === 0) return '(no rows)';
+  const cols = columns && columns.length ? columns : Object.keys(rows[0]);
+  const cellText = (row, col) => (row[col] === undefined || row[col] === null ? '' : String(row[col]));
+  const widths = cols.map((col) => Math.max(col.length, ...rows.map((row) => cellText(row, col).length)));
+  const renderRow = (cells) => cells.map((cell, i) => String(cell).padEnd(widths[i])).join('  ');
+  const lines = [renderRow(cols), renderRow(widths.map((w) => '-'.repeat(w)))];
+  for (const row of rows) {
+    lines.push(renderRow(cols.map((col) => cellText(row, col))));
+  }
+  return lines.join('\n');
+}
+
+function renderMemoryResultsTable(items) {
+  const rows = (Array.isArray(items) ? items : []).map((m) => ({
+    id: m.id || m._id || '',
+    category: m.category || '',
+    // A row marked usage 'style_preference_only' (a writing voice memory) says so, so a person
+    // reading the table sees what an agent reading the JSON sees.
+    summary: truncateForTable(m.summary, 60) + (m.usage === 'style_preference_only' ? ' [style]' : ''),
+    // The recall front door emits `score` (toQueryRow plus score in mcp/tools/memory.ts); the
+    // older /query route emitted rankScore/similarityScore. Read all three so the column is not
+    // blank against a real /recall row. On the list pathways score is deliberately absent, and
+    // an empty cell is the honest rendering of "this pathway does not rank".
+    score: m.score != null ? m.score : (m.rankScore != null ? m.rankScore : (m.similarityScore != null ? m.similarityScore : ''))
+  }));
+  return renderTable(rows, ['id', 'category', 'summary', 'score']);
+}
+
+// The retrieval pathways `memory query --path` may pin. Same four names the server's shared
+// normalizer accepts (packages/server/src/services/recallParams.service.ts). Omitting --path
+// leaves the classifier deciding, exactly as before.
+const RECALL_PATHS = ['semantic', 'list', 'graph', 'hebbian'];
+const RECALL_HOPS = [1, 2];
+// Hops only mean something on a pathway that walks relationships.
+const RECALL_HOP_PATHS = ['graph', 'hebbian'];
+// Reminder states `memory query --remind-state` may keep. Same enum the server's shared
+// normalizer and Memory.remindState declare.
+const REMIND_STATES = ['pending', 'notified', 'acknowledged', 'cancelled'];
+
+// ─── Scoped `--help` (C-005 item 5) ───────────────────────────────────────────
+// `empirical memory --help` / `empirical memory <sub> --help` print scoped usage instead of
+// the 90-line global help wall bin/empirical.js otherwise short-circuits every --help to.
+
+const MEMORY_SUBCOMMAND_USAGE = {
+  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--due-before <ISO date>] [--due-after <ISO date>] [--remind-state pending,notified] [--path semantic|list|graph|hebbian] [--hops 1|2] [--workspaces <n|name|id,...>] [--all-workspaces] [--pretty] [--format table]',
+  get: 'Usage: empirical memory get --memory-id <id> [--pretty]',
+  list: 'Usage: empirical memory list [--category <cat>] [--tags <t1,t2>] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]',
+  record: 'Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent] [--item-type <key>] [--item-status <key>] [--parent <memoryId>] [--assignee <userId>] [--field name=value ...]\n  The five item arguments only mean something in a TEAM workspace that has a shape: elsewhere they are accepted and stored as nothing.',
+  note: 'Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--min-score 0.35]',
+  update: 'Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--min-score 0.35]',
+  acknowledge: 'Usage: empirical memory acknowledge --memory-id <id> [--cancel]   (marks a due reminder done, or dropped with --cancel; frees its slot and clears the alert)',
+  delete: 'Usage: empirical memory delete (--match <query> | --memory-id <id>) [--confirm] [--min-score 0.35]\nUsage: empirical memory delete (--tag <t> | --category <c> | --all) --confirm',
+  attachment: `Files attached to a memory. Up to 20 per memory, 25MB each; a delete is reversible for 30 days.\n${Object.values(ATTACHMENT_SUBCOMMAND_USAGE).join('\n')}`,
+  attach: ATTACHMENT_SUBCOMMAND_USAGE.add + '\n  (shorthand for `empirical memory attachment add`)',
+  attachments: ATTACHMENT_SUBCOMMAND_USAGE.list + '\n  (shorthand for `empirical memory attachment list`)',
+  tree: 'Usage: empirical memory tree (--memory-id <id> | --match <query>) [--depth 10] [--max-nodes 500] [--no-notes] [--format markdown|json] [--out <path>] [--pretty]\n  One item and everything nested under it, as a readable document. Markdown by default.',
+  duplicates: 'Usage: empirical memory duplicates --memory-id <id>',
+  merge: 'Usage: empirical memory merge --canonical-id <id> --duplicate-id <id> [--no-merge-tags] [--no-merge-relationships]',
+  export: 'Usage: empirical memory export --scope <personal|workspace> [--out <path>] [--workspace-id <id>]',
+  import: 'Usage: empirical memory import <file> [--dry-run]',
+  'bulk-import': 'Usage: empirical memory bulk-import <file> [--dry-run]\nFile format: { "memories": [{ "localKey": "...", "category": "...", "nodeType": "...", "summary": "...", "data": {...} }], "relationships": [{ "fromLocalKey": "...", "toLocalKey": "...", "type": "..." }] }',
+  stats: 'Usage: empirical memory stats [--format table]',
+  compact: 'Usage: empirical memory compact [--apply] [--category <cat>]'
+};
+
+function printMemoryHelp(sub) {
+  if (sub && MEMORY_SUBCOMMAND_USAGE[sub]) {
+    log(MEMORY_SUBCOMMAND_USAGE[sub]);
+    return;
+  }
+  log(DOC_TOPICS.memory);
+  log('');
+  log('Subcommands: ' + Object.keys(MEMORY_SUBCOMMAND_USAGE).join(', '));
+}
+
+async function withCliAnalyticsContext(context, fn) {
+  globalThis.__empiricalCliAnalyticsContext = context || {};
+  try {
+    return await fn();
+  } finally {
+    globalThis.__empiricalCliAnalyticsContext = null;
+  }
+}
+
+
+// ─── Memory subcommands ───────────────────────────────────────────────────────
+
+/**
+ * Turn `--workspaces` selectors (list numbers, names, or ids) into workspace ids using the
+ * per-user listing (/api/v1/users/me/workspaces, the same list `workspace list` prints; number 1
+ * is always the Default Workspace). An id (ws_...) passes through without a lookup. An unknown
+ * name is fatal at the terminal rather than a 403 or an empty answer after the round trip.
+ */
+async function resolveWorkspaceIdsForQuery({ baseUrl, accessToken, selectors = [], all = false }) {
+  const needsListing = all || selectors.some((s) => !/^ws_/.test(s));
+  let options = [];
+  if (needsListing) {
+    const listUrl = new URL('/api/v1/users/me/workspaces', baseUrl).toString();
+    let payload;
+    try {
+      payload = await httpJson(listUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
+    } catch (error) {
+      printApiError(error);
+      process.exit(1);
+    }
+    options = [
+      ...(payload?.defaultOption ? [payload.defaultOption] : []),
+      ...(Array.isArray(payload?.workspaces) ? payload.workspaces : [])
+    ].filter((o) => o && o.workspaceId);
+  }
+  if (all) return [...new Set(options.map((o) => o.workspaceId))];
+
+  const ids = [];
+  for (const selector of selectors) {
+    if (/^ws_/.test(selector)) { ids.push(selector); continue; }
+    const asNumber = Number(selector);
+    let match = null;
+    if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= options.length) {
+      match = options[asNumber - 1];
+    } else {
+      const lower = selector.toLowerCase();
+      const byLabel = options.filter((o) => String(o.label || '').toLowerCase() === lower || String(o.key || '').toLowerCase() === lower);
+      if (byLabel.length > 1) {
+        warn(`Ambiguous workspace "${selector}". Use its list number or workspace id.`);
+        process.exit(1);
+      }
+      match = byLabel[0] || null;
+    }
+    if (!match) {
+      warn(`Workspace not found: "${selector}". Run \`empirical workspace list\` to see names and numbers.`);
+      process.exit(1);
+    }
+    ids.push(match.workspaceId);
+  }
+  return [...new Set(ids)];
+}
+
+async function runMemoryQuery(args) {
+  const match = parseOption(args, '--match', '');
+  if (!match) {
+    warn(MEMORY_SUBCOMMAND_USAGE.query);
+    process.exit(1);
+  }
+
+  const topKRaw = Number(parseOption(args, '--top-k', '3'));
+  const topK = Math.min(100, Math.max(1, Number.isFinite(topKRaw) ? topKRaw : 3));
+  const category = parseOption(args, '--category', '');
+  const tagsRaw = parseOption(args, '--tags', '');
+  const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
+  // R3 (2026-09-06): --tags-all is an AND match (all must be present), unlike --tags' OR match;
+  // --status filters data.status. Both are optional and additive to --tags/--category.
+  const tagsAllRaw = parseOption(args, '--tags-all', '');
+  const tagsAll = tagsAllRaw ? tagsAllRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
+  // Multi-workspace recall (2026-09-24). --workspaces takes list numbers, names, or ids; names
+  // and numbers are resolved against the same listing `workspace list` prints, so the server
+  // contract stays ids-only. --all-workspaces sends every selectable workspace. Without either
+  // flag the query is scoped to the single active workspace exactly as before.
+  const workspacesRaw = parseOption(args, '--workspaces', '');
+  const workspaceSelectors = workspacesRaw ? workspacesRaw.split(',').map((w) => w.trim()).filter(Boolean) : [];
+  const allWorkspaces = parseFlag(args, '--all-workspaces');
+  if (workspaceSelectors.length && allWorkspaces) {
+    warn('Pass either --workspaces or --all-workspaces, not both.');
+    process.exit(1);
+  }
+  const statusRaw = parseOption(args, '--status', '');
+  const status = statusRaw ? statusRaw.split(',').map((s) => s.trim()).filter(Boolean) : [];
+  const pretty = parseFlag(args, '--pretty');
+  const format = parseOption(args, '--format', 'json');
+
+  // Reminder filters. Dates are parsed HERE as well as server-side, for the same reason --due
+  // is on record: a typo fails at the terminal, not as a 400 after the round trip. Anything
+  // Date can parse is accepted and sent as the caller typed it.
+  const dueFilters = {};
+  for (const [flag, key] of [['--due-before', 'dueBefore'], ['--due-after', 'dueAfter']]) {
+    const raw = parseOption(args, flag, '');
+    if (!raw) continue;
+    if (Number.isNaN(new Date(raw).getTime())) {
+      warn(`Invalid ${flag} "${raw}". Use an ISO 8601 date, for example 2026-10-14 or 2026-10-14T09:00:00Z.`);
+      process.exit(1);
+    }
+    dueFilters[key] = String(raw).trim();
+  }
+  const remindStateRaw = parseOption(args, '--remind-state', '');
+  const remindState = remindStateRaw
+    ? remindStateRaw.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean)
+    : [];
+  const unknownStates = remindState.filter((s) => !REMIND_STATES.includes(s));
+  if (unknownStates.length) {
+    warn(`--remind-state must be one of: ${REMIND_STATES.join(', ')} (received ${JSON.stringify(unknownStates)})`);
+    process.exit(1);
+  }
+
+  // --path / --hops are validated HERE, where the value is decided, so a typo costs no round
+  // trip and the message names the four pathways. The server validates the same way (the shared
+  // normalizer in packages/server/src/services/recallParams.service.ts); this is a fast local
+  // echo of that contract, never a second, looser one.
+  const pathRaw = parseOption(args, '--path', '');
+  let path = '';
+  if (pathRaw) {
+    path = String(pathRaw).trim().toLowerCase();
+    if (!RECALL_PATHS.includes(path)) {
+      warn(`--path must be one of: ${RECALL_PATHS.join(', ')} (received ${JSON.stringify(pathRaw)})`);
+      process.exit(1);
+    }
+  }
+
+  const hopsRaw = parseOption(args, '--hops', '');
+  let hops = null;
+  if (hopsRaw) {
+    const parsedHops = Number(hopsRaw);
+    if (!RECALL_HOPS.includes(parsedHops)) {
+      warn(`--hops must be 1 or 2 (received ${JSON.stringify(hopsRaw)})`);
+      process.exit(1);
+    }
+    // Silently ignoring --hops on a ranked or list pathway would look like it took effect.
+    if (!RECALL_HOP_PATHS.includes(path)) {
+      warn(`--hops only applies with --path graph or --path hebbian${path ? ` (received --path ${path})` : ' (no --path given)'}`);
+      process.exit(1);
+    }
+    hops = parsedHops;
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  // The recall front door: the same answer the MCP query_memories tool gives, which /query never
+  // gave (classifier routing, the list block, the exact-tag retry, agent-note exclusion,
+  // retrievalPath). It takes its parameters FLAT, matching the shared normalizer, not nested
+  // under `filters` the way the older /query route did. Send one shape only.
+  const queryUrl = new URL('/api/v1/memories/recall', baseUrl).toString();
+
+  const body = { query: match, topK };
+  if (category) body.category = category;
+  if (tags.length) body.tags = tags;
+  if (tagsAll.length) body.tagsAll = tagsAll;
+  if (workspaceSelectors.length || allWorkspaces) {
+    body.workspaceIds = await resolveWorkspaceIdsForQuery({
+      baseUrl,
+      accessToken,
+      selectors: workspaceSelectors,
+      all: allWorkspaces
+    });
+  }
+  if (status.length) body.status = status;
+  if (dueFilters.dueBefore) body.dueBefore = dueFilters.dueBefore;
+  if (dueFilters.dueAfter) body.dueAfter = dueFilters.dueAfter;
+  if (remindState.length) body.remindState = remindState;
+  if (path) body.path = path;
+  if (hops !== null) body.hops = hops;
+
+  let response;
+  try {
+    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    // A 404 here means the server predates the recall front door. Say that plainly instead of
+    // rerouting to /query: that fallback would quietly answer through a different routing path
+    // with different defaults (topK 10 against 3) and keep the old route alive forever.
+    if (error && error.statusCode === 404) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'recall_route_missing',
+        message: 'This server does not serve /api/v1/memories/recall yet. Upgrade the Empirical server, or use an older CLI against it.'
+      }));
+      process.exit(1);
+    }
+    printApiError(error);
+    process.exit(1);
+  }
+
+  // The front door answers with data.memories; the older /query route answered with data.results.
+  // Both are accepted so a CLI pointed at a server that predates /recall still prints rows.
+  const data = response && response.data ? response.data : null;
+  const results = (data && Array.isArray(data.memories))
+    ? data.memories
+    : ((data && Array.isArray(data.results))
+      ? data.results
+      : (Array.isArray(response) ? response : []));
+
+  if (format === 'table') {
+    log(renderMemoryResultsTable(results));
+    return;
+  }
+
+  if (pretty) {
+    log(JSON.stringify(results, null, 2));
+  } else {
+    log(JSON.stringify(results));
+  }
+}
+
+async function runMemoryGet(args) {
+  const memoryId = parseOption(args, '--memory-id', '');
+  const pretty = parseFlag(args, '--pretty');
+  if (!memoryId) {
+    warn('Usage: empirical memory get --memory-id <id> [--pretty]');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+  const data = response && response.data ? response.data : response;
+  log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+}
+
+async function runMemoryList(args) {
+  const category = parseOption(args, '--category', '');
+  const tags = parseOption(args, '--tags', '');
+  const startDate = parseOption(args, '--start-date', '');
+  const endDate = parseOption(args, '--end-date', '');
+  const limitRaw = Number(parseOption(args, '--limit', '20'));
+  const limit = Math.min(100, Math.max(1, Number.isFinite(limitRaw) ? limitRaw : 20));
+  const cursor = parseOption(args, '--cursor', '');
+  const sortOrder = parseFlag(args, '--oldest') ? 'asc' : 'desc';
+  const pretty = parseFlag(args, '--pretty');
+  const format = parseOption(args, '--format', 'json');
+
+  const params = new URLSearchParams();
+  if (category) params.set('category', category);
+  if (tags) params.set('tags', tags);
+  if (startDate) params.set('startDate', startDate);
+  if (endDate) params.set('endDate', endDate);
+  params.set('limit', String(limit));
+  if (cursor) params.set('cursor', cursor);
+  params.set('sortBy', 'createdAt');
+  params.set('sortOrder', sortOrder);
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/memories?${params.toString()}`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+  const data = response && response.data ? response.data : response;
+
+  if (format === 'table') {
+    const items = Array.isArray(data && data.memories) ? data.memories : (Array.isArray(data) ? data : []);
+    log(renderMemoryResultsTable(items));
+    return;
+  }
+
+  log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+}
+
+// Shell substitution silently eats code out of a double-quoted --summary: backticks become
+// command substitution and ${...} becomes variable expansion BEFORE the CLI ever sees the
+// text, and the write still succeeds, so the memory looks fine with the code gone. Two
+// defenses: (1) inputs that never pass through shell quoting -- `--summary-file <path>` and
+// `--summary -` (stdin, pair it with a single-quoted heredoc); (2) a warning when an inline
+// summary carries the residue of an eaten substitution.
+function resolveSummaryInput(args, { readFile = (p) => fs.readFileSync(path.resolve(p), 'utf8'), readStdin = () => fs.readFileSync(0, 'utf8') } = {}) {
+  const summaryFile = parseOption(args, '--summary-file', '');
+  if (summaryFile) {
+    return { summary: String(readFile(summaryFile)).replace(/\r?\n$/, ''), source: 'file' };
+  }
+  const inline = parseOption(args, '--summary', '');
+  if (inline === '-') {
+    return { summary: String(readStdin()).replace(/\r?\n$/, ''), source: 'stdin' };
+  }
+  return { summary: inline, source: inline ? 'inline' : 'none' };
+}
+
+function detectShellMangling(summary) {
+  const text = String(summary || '');
+  const reasons = [];
+  if (/``/.test(text)) reasons.push('an empty backtick pair (a `command` was probably substituted away)');
+  if (/\$(\s|$|[^A-Za-z0-9_{(])/.test(text) && !/\$\d/.test(text)) reasons.push('a lone "$" (a ${VAR} or $(cmd) was probably expanded to nothing)');
+  if (/\$\{\s*\}/.test(text)) reasons.push('an empty ${} placeholder');
+  return reasons;
+}
+
+async function runMemoryRecord(args) {
+  const jsonFile = parseOption(args, '--json-file', '');
+  let payload;
+
+  if (jsonFile) {
+    try {
+      payload = JSON.parse(fs.readFileSync(path.resolve(jsonFile), 'utf8'));
+    } catch (error) {
+      warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
+      process.exit(1);
+    }
+  } else {
+    const category = parseOption(args, '--category', '');
+    const { summary, source: summarySource } = resolveSummaryInput(args);
+
+    if (summarySource === 'inline') {
+      const mangled = detectShellMangling(summary);
+      if (mangled.length) {
+        warn(JSON.stringify({
+          warning: 'possible_shell_substitution',
+          message: 'The summary looks like the shell altered it before the CLI saw it: ' + mangled.join('; ') + '. Recording anyway. For text containing backticks or ${...}, use --summary-file <path>, or --summary - with a single-quoted heredoc, or the MCP record_graph_memory tool.'
+        }));
+      }
+    }
+
+    if (!category || !summary) {
+      // The canonical string, not a second copy: this line used to hold its own and had already
+      // drifted from MEMORY_SUBCOMMAND_USAGE.record, so a flag added to one was missing from the
+      // other, which is the message a person actually sees when they get the arguments wrong.
+      warn(MEMORY_SUBCOMMAND_USAGE.record);
+      warn('Valid categories: ' + MEMORY_CATEGORIES.join(', '));
+      warn('Valid node types: ' + NODE_TYPES.join(', '));
+      process.exit(1);
+    }
+
+    if (!MEMORY_CATEGORIES.includes(category)) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_category',
+        message: `Invalid category "${category}". Valid: ${MEMORY_CATEGORIES.join(', ')}`
+      }));
+      process.exit(1);
+    }
+
+    const tagsRaw = parseOption(args, '--tags', '');
+    const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
+    const nodeType = parseOption(args, '--node-type', 'observation');
+
+    if (!NODE_TYPES.includes(nodeType)) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_node_type',
+        message: `Invalid nodeType "${nodeType}". Valid: ${NODE_TYPES.join(', ')}`
+      }));
+      process.exit(1);
+    }
+
+    payload = { category, summary, nodeType, data: { text: String(summary) } };
+    if (tags.length) payload.tags = tags;
+  }
+
+  if (
+    payload
+    && payload.summary !== undefined
+    && payload.data === undefined
+    && payload.originalPayload === undefined
+  ) {
+    payload.data = { text: String(payload.summary) };
+  }
+
+  // C-002 (docs/prd-cli-and-plugin-fixes.md): the server now dedupes/auto-links every
+  // POST /api/v1/memories write by default, matching the MCP record_graph_memory tool's
+  // guarantee. Only send dedupeEnabled/autoLink at all when the caller explicitly opted
+  // out here -- omitting them entirely lets the server's own default-on behavior apply,
+  // rather than this CLI baking in a redundant "true" that could drift from the server's
+  // actual default over time.
+  if (parseFlag(args, '--no-dedupe')) {
+    payload.dedupeEnabled = false;
+  }
+  if (parseFlag(args, '--no-auto-link')) {
+    payload.autoLink = false;
+  }
+
+  // Authorship (2026-09-09). `source` is observable truth: this is the CLI, so say so.
+  // Until now the CLI sent nothing, the server fell back to the transport it saw ('api'),
+  // and api maps to authorType 'user' because that mapping was written for the web portal.
+  // Every agent write through this command was therefore stored as authored by the user.
+  // 'cli' resolves to authorType 'unknown', which is the honest answer when nobody says.
+  if (payload.source === undefined) payload.source = 'cli';
+
+  // --author-type lets the caller state what the transport cannot know. An agent recording
+  // its own session notes should pass 'agent'; an agent recording something the user said
+  // or decided should pass 'user'. Omitted, it stays 'unknown' rather than being guessed.
+  const authorType = parseOption(args, '--author-type', '');
+  if (authorType) {
+    if (!['user', 'agent', 'system'].includes(authorType)) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_author_type',
+        message: `Invalid --author-type "${authorType}". Valid: user, agent, system`
+      }));
+      process.exit(1);
+    }
+    payload.authorType = authorType;
+  }
+
+  // PRD 8.1 item arguments. Sent under the names the REST door takes (ITEM_WRITE_ARGUMENTS in
+  // @empirical/shared): itemType, itemStatus, parentId, assignee and fields. The CLI deliberately
+  // does NOT check them against a shape; it has no shape and the server refuses with the
+  // workspace's own vocabulary, which is a better message than anything guessed here.
+  //
+  // Guarded on payload being an object: --json-file accepts whatever parses, so a file holding a
+  // bare array or null would otherwise crash here on assignment rather than in the request.
+  const canCarryItemArguments = payload && typeof payload === 'object' && !Array.isArray(payload);
+  for (const [flag, key] of [
+    ['--item-type', 'itemType'],
+    ['--item-status', 'itemStatus'],
+    ['--parent', 'parentId'],
+    ['--assignee', 'assignee']
+  ]) {
+    const value = parseOption(args, flag, '');
+    if (value && canCarryItemArguments) payload[key] = value;
+  }
+
+  // --field is repeatable and collected into one object, so `--field notes=hi --field source=web`
+  // sends { notes: 'hi', source: 'web' }. Split on the FIRST '=' only, or a value that contains one
+  // ('query=a=b') would be truncated. A malformed pair fails here rather than as a 400, because the
+  // person is at a terminal and the fix is in what they just typed.
+  const fieldPairs = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] !== '--field') continue;
+    fieldPairs.push(args[i + 1]);
+    i += 1;
+  }
+  if (fieldPairs.length) {
+    const fields = {};
+    for (const pair of fieldPairs) {
+      const at = typeof pair === 'string' ? pair.indexOf('=') : -1;
+      const name = at > 0 ? pair.slice(0, at).trim() : '';
+      if (!name) {
+        warn(JSON.stringify({
+          error: true,
+          code: 'invalid_field',
+          message: `Invalid --field ${JSON.stringify(pair === undefined ? '' : pair)}. Use the form --field name=value, for example --field notes=hello. Repeat --field for more than one.`
+        }));
+        process.exit(1);
+      }
+      fields[name] = pair.slice(at + 1);
+    }
+    if (canCarryItemArguments) payload.fields = fields;
+  }
+
+  // --due turns the memory into a reminder. Parsed and rejected HERE as well as server-side, so
+  // a typo fails immediately at the terminal instead of coming back as a 400 after the write was
+  // composed. Accepts anything Date can parse, so '2026-10-14' and a full ISO timestamp both work.
+  const dueRaw = parseOption(args, '--due', '');
+  if (dueRaw) {
+    const parsedDue = new Date(dueRaw);
+    if (Number.isNaN(parsedDue.getTime())) {
+      warn(JSON.stringify({
+        error: true,
+        code: 'invalid_due',
+        message: `Invalid --due "${dueRaw}". Use an ISO 8601 date, for example 2026-10-14 or 2026-10-14T09:00:00Z.`
+      }));
+      process.exit(1);
+    }
+    payload.dueAt = parsedDue.toISOString();
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const recordUrl = new URL('/api/v1/memories', baseUrl).toString();
+
+  let response;
+  try {
+    response = await httpJson(recordUrl, 'POST', payload, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const created = (response && response.data) ? response.data : response;
+  log(JSON.stringify(created));
+}
+
+async function runMemoryNote(args) {
+  const match = parseOption(args, '--match', '');
+  const text = parseOption(args, '--text', '');
+  const memoryId = parseOption(args, '--memory-id', '');
+  const minScore = Number(parseOption(args, '--min-score', '0.35'));
+
+  if (!text) {
+    warn('Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--tags <t1,t2>] [--min-score 0.35]');
+    process.exit(1);
+  }
+
+  if (!match && !memoryId) {
+    warn('Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--tags <t1,t2>]');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+
+  let targetId = memoryId;
+  if (!targetId) {
+    const filters = parseMatchFilters(args);
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
+    if (!result.found) {
+      printMemoryResolveError(result);
+      process.exit(1);
+    }
+    targetId = result.memory.id;
+  }
+
+  const noteUrl = new URL(`/api/v1/memories/${encodeURIComponent(targetId)}/notes`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(noteUrl, 'POST', { text }, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const created = (response && response.data) ? response.data : response;
+  log(JSON.stringify(created));
+}
+
+// Closing a reminder from the terminal or from an agent reading a CLI banner. One PUT, the same
+// transition the portal's Mark done / Cancel make; the server retires the alert on every surface.
+async function runMemoryAcknowledge(args) {
+  const memoryId = parseOption(args, '--memory-id', '');
+  const cancel = parseFlag(args, '--cancel');
+  if (!memoryId) {
+    warn(MEMORY_SUBCOMMAND_USAGE.acknowledge);
+    process.exit(1);
+  }
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(url, 'PUT', { remindState: cancel ? 'cancelled' : 'acknowledged' }, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+  const data = response && response.data ? response.data : response;
+  log(JSON.stringify({ id: data.id, remindState: data.remindState, dueAt: data.dueAt || null, message: cancel ? 'Reminder cancelled. Its slot is free.' : 'Reminder marked done. Its slot is free.' }, null, 2));
+}
+
+async function runMemoryUpdate(args) {
+  const match = parseOption(args, '--match', '');
+  const patchJson = parseOption(args, '--patch-json', '');
+  const jsonFile = parseOption(args, '--json-file', '');
+  const memoryId = parseOption(args, '--memory-id', '');
+  const minScore = Number(parseOption(args, '--min-score', '0.35'));
+
+  if (!patchJson && !jsonFile) {
+    warn('Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--tags <t1,t2>]');
+    process.exit(1);
+  }
+
+  if (!match && !memoryId) {
+    warn('Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--tags <t1,t2>]');
+    process.exit(1);
+  }
+
+  let patch;
+  if (jsonFile) {
+    try {
+      patch = JSON.parse(fs.readFileSync(path.resolve(jsonFile), 'utf8'));
+    } catch (error) {
+      warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
+      process.exit(1);
+    }
+  } else {
+    try {
+      patch = JSON.parse(patchJson);
+    } catch (error) {
+      warn(JSON.stringify({ error: true, code: 'invalid_json', message: `--patch-json parse error: ${error.message}` }));
+      process.exit(1);
+    }
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+
+  let targetId = memoryId;
+  if (!targetId) {
+    const filters = parseMatchFilters(args);
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
+    if (!result.found) {
+      printMemoryResolveError(result);
+      process.exit(1);
+    }
+    targetId = result.memory.id;
+  }
+
+  const updateUrl = new URL(`/api/v1/memories/${encodeURIComponent(targetId)}`, baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(updateUrl, 'PUT', patch, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const updated = (response && response.data) ? response.data : response;
+  log(JSON.stringify(updated));
+}
+
+async function runMemoryDeleteBulk(args) {
+  const tag = parseOption(args, '--tag', '');
+  const category = parseOption(args, '--category', '');
+  const all = parseFlag(args, '--all');
+  const confirm = parseFlag(args, '--confirm');
+
+  const selectorCount = [Boolean(tag), Boolean(category), all].filter(Boolean).length;
+  if (selectorCount !== 1) {
+    warn('Usage: empirical memory delete (--tag <t> | --category <c> | --all) --confirm');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/memory-bulk-delete', baseUrl).toString();
+  const body = { confirm };
+  if (tag) body.tag = tag;
+  if (category) body.category = category;
+  if (all) body.all = true;
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  // Server always reports the count first: without --confirm it's a dry-run preview and no
+  // writes happened; with --confirm it reports what it just deleted. Either way the count is
+  // printed, matching the single-memory delete's dry-run-by-default convention above.
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify(data));
+}
+
+async function runMemoryDelete(args) {
+  const tag = parseOption(args, '--tag', '');
+  const category = parseOption(args, '--category', '');
+  const all = parseFlag(args, '--all');
+  if (tag || category || all) {
+    return runMemoryDeleteBulk(args);
+  }
+
+  const match = parseOption(args, '--match', '');
+  const memoryId = parseOption(args, '--memory-id', '');
+  const minScore = Number(parseOption(args, '--min-score', '0.35'));
+  const confirm = parseFlag(args, '--confirm');
+
+  if (!match && !memoryId) {
+    warn('Usage: empirical memory delete (--match <query> | --memory-id <id>) [--tags <t1,t2>] [--confirm] [--min-score 0.35]');
+    warn('   or: empirical memory delete (--tag <t> | --category <c> | --all) --confirm');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+
+  let targetId = memoryId;
+  let targetSummary = '';
+
+  if (!targetId) {
+    const filters = parseMatchFilters(args);
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
+    if (!result.found) {
+      if (!confirm && (result.reason === 'ambiguous' || result.reason === 'low_score')) {
+        // Dry-run: return candidates info
+        log(JSON.stringify({ dryRun: true, wouldDelete: false, reason: result.reason, candidates: result.candidates }));
+        process.exit(0);
+      }
+      printMemoryResolveError(result);
+      process.exit(1);
+    }
+    targetId = result.memory.id;
+    targetSummary = result.memory.summary;
+  }
+
+  if (!confirm) {
+    log(JSON.stringify({ dryRun: true, wouldDelete: true, id: targetId, summary: targetSummary }));
+    process.exit(0);
+  }
+
+  const deleteUrl = new URL(`/api/v1/memories/${encodeURIComponent(targetId)}`, baseUrl).toString();
+  try {
+    await httpJson(deleteUrl, 'DELETE', null, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  log(JSON.stringify({ deleted: true, id: targetId, summary: targetSummary }));
+}
+
+// `memory tree` is the terminal's answer to "give me this idea with everything under it". The
+// server assembles the document (one indexed query over the item hierarchy), so this is a fetch
+// and a write: no walking, no per-level calls.
+async function runMemoryTree(args) {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+
+  const memoryId = parseOption(args, '--memory-id', '');
+  const match = parseOption(args, '--match', '');
+  if (!memoryId && !match) {
+    warn(MEMORY_SUBCOMMAND_USAGE.tree);
+    process.exit(1);
+  }
+
+  let targetId = memoryId;
+  if (!targetId) {
+    const minScore = Number(parseOption(args, '--min-score', '0.35'));
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, parseMatchFilters(args));
+    if (!result.found) {
+      printMemoryResolveError(result);
+      process.exit(1);
+    }
+    targetId = result.memory.id;
+  }
+
+  const query = new URLSearchParams();
+  const depth = parseOption(args, '--depth', '');
+  if (depth) query.set('depth', depth);
+  const maxNodes = parseOption(args, '--max-nodes', '');
+  if (maxNodes) query.set('maxNodes', maxNodes);
+  if (parseFlag(args, '--no-notes')) query.set('includeNotes', 'false');
+
+  const url = new URL(
+    `/api/v1/memories/${encodeURIComponent(targetId)}/tree${query.toString() ? `?${query}` : ''}`,
+    baseUrl
+  ).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+
+  // Markdown is the default here, unlike every other memory subcommand, because the whole point
+  // of this one is a document a person reads. --format json gives the nodes for scripting.
+  if (parseOption(args, '--format', 'markdown') === 'json') {
+    log(parseFlag(args, '--pretty') ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+    return;
+  }
+
+  const out = parseOption(args, '--out', '');
+  if (out) {
+    const target = path.resolve(out);
+    try {
+      fs.writeFileSync(target, data.markdown);
+    } catch (error) {
+      warn(JSON.stringify({ error: true, code: 'write_failed', message: `Could not write ${target}: ${error.message}` }));
+      process.exit(1);
+    }
+    log(JSON.stringify({ written: true, path: target, nodeCount: data.nodeCount, depth: data.depth, truncated: data.truncated }));
+    return;
+  }
+
+  log(data.markdown);
+  // Truncation goes to stderr so it cannot end up inside a redirected document.
+  if (data.truncated) {
+    warn(JSON.stringify({
+      warning: true,
+      code: 'truncated',
+      message: `Document cut off at ${data.nodes.length} items. Raise --max-nodes or start lower in the tree.`
+    }));
+  }
+}
+
+async function runMemoryDuplicates(args) {
+  const memoryId = parseOption(args, '--memory-id', '');
+  if (!memoryId) {
+    warn('Usage: empirical memory duplicates --memory-id <id>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}/duplicate-candidates`, baseUrl).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify(data));
+}
+
+async function runMemoryMerge(args) {
+  const canonicalId = parseOption(args, '--canonical-id', '');
+  const duplicateId = parseOption(args, '--duplicate-id', '');
+  const mergeTags = !parseFlag(args, '--no-merge-tags');
+  const mergeRelationships = !parseFlag(args, '--no-merge-relationships');
+
+  if (!canonicalId || !duplicateId) {
+    warn('Usage: empirical memory merge --canonical-id <id> --duplicate-id <id> [--no-merge-tags] [--no-merge-relationships]');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/memories/merge', baseUrl).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', { canonicalId, duplicateId, mergeTags, mergeRelationships }, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify(data));
+}
+
+async function runMemoryExport(args) {
+  const scope = parseOption(args, '--scope', '');
+  if (scope !== 'personal' && scope !== 'workspace') {
+    warn('Usage: empirical memory export --scope <personal|workspace> [--out <path>] [--workspace-id <id>]');
+    process.exit(1);
+  }
+
+  const workspaceId = parseOption(args, '--workspace-id', '');
+  if (scope === 'workspace' && !workspaceId) {
+    warn('Usage: empirical memory export --scope workspace --workspace-id <id> [--out <path>]');
+    process.exit(1);
+  }
+
+  const dateStamp = new Date().toISOString().slice(0, 10);
+  const outPath = parseOption(args, '--out', `./empirical-memory-export-${scope}-${dateStamp}.json`);
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL(`/api/v1/memories/export?scope=${encodeURIComponent(scope)}`, baseUrl).toString();
+
+  const headers = buildApiAuthHeaders(accessToken);
+  if (workspaceId) {
+    headers['x-workspace-id'] = workspaceId;
+  }
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, headers);
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  // The raw server response is the export envelope itself (streamed as one JSON body, not the
+  // standard {status,data} wrapper): {schemaVersion, generatedAt, scope, workspaceId,
+  // memoryCount, truncated, memories: [...]}. Re-shape it into the versioned, round-trippable
+  // format `memory import` consumes: {schemaVersion: 1, exportedAt, memories: [{category,
+  // summary, tags, nodeType, data, mass, gravity, timeContext, notes, relationships}]}.
+  const rawMemories = Array.isArray(response && response.memories) ? response.memories : [];
+  const envelope = {
+    schemaVersion: 1,
+    exportedAt: new Date().toISOString(),
+    memories: rawMemories.map((m) => ({
+      category: m.category,
+      summary: m.summary,
+      tags: Array.isArray(m.tags) ? m.tags : [],
+      nodeType: m.nodeType,
+      data: m.data,
+      mass: m.mass,
+      gravity: m.gravity,
+      timeContext: m.timeContext || null,
+      notes: Array.isArray(m.notes) ? m.notes.map((n) => ({ text: n.text })) : [],
+      relationships: Array.isArray(m.relationships)
+        ? m.relationships.map((r) => ({ type: r.type, targetId: r.targetId, weight: r.weight }))
+        : []
+    }))
+  };
+
+  const resolvedPath = path.resolve(outPath);
+  fs.writeFileSync(resolvedPath, JSON.stringify(envelope, null, 2) + '\n', 'utf8');
+
+  log(JSON.stringify({ exported: true, path: resolvedPath, schemaVersion: envelope.schemaVersion, memoryCount: envelope.memories.length }));
+}
+
+async function runMemoryImport(args) {
+  const filePath = args.find((a) => a && !a.startsWith('--')) || '';
+  const dryRun = parseFlag(args, '--dry-run');
+
+  if (!filePath) {
+    warn('Usage: empirical memory import <file> [--dry-run]');
+    process.exit(1);
+  }
+
+  let doc;
+  try {
+    doc = JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8'));
+  } catch (error) {
+    warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
+    process.exit(1);
+  }
+
+  const memories = Array.isArray(doc && doc.memories) ? doc.memories : null;
+  if (!memories) {
+    warn(JSON.stringify({
+      error: true,
+      code: 'invalid_format',
+      message: 'File is not a valid Empirical memory export: missing a top-level "memories" array. Re-export with `empirical memory export`.'
+    }));
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    log(JSON.stringify({ dryRun: true, wouldImport: memories.length, schemaVersion: doc.schemaVersion || null }));
+    return;
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  // Every row goes through the normal create endpoint, so imports get the same dedupe and
+  // auto-link treatment as any other write, no special-casing needed here.
+  const recordUrl = new URL('/api/v1/memories', baseUrl).toString();
+
+  let imported = 0;
+  let failed = 0;
+  const errors = [];
+
+  for (const row of memories) {
+    const payload = {
+      category: row.category,
+      summary: row.summary,
+      nodeType: row.nodeType || 'observation',
+      tags: Array.isArray(row.tags) ? row.tags : [],
+      data: row.data !== undefined
+        ? row.data
+        : (row.summary !== undefined ? { text: String(row.summary) } : undefined)
+    };
+    if (Array.isArray(row.relationships) && row.relationships.length) payload.relationships = row.relationships;
+    if (row.mass !== undefined && row.mass !== null) payload.mass = row.mass;
+    if (row.gravity !== undefined && row.gravity !== null) payload.gravity = row.gravity;
+    if (row.timeContext) payload.timeContext = row.timeContext;
+
+    let created;
+    try {
+      const response = await httpJson(recordUrl, 'POST', payload, buildApiAuthHeaders(accessToken));
+      created = (response && response.data) ? response.data : response;
+      imported++;
+    } catch (error) {
+      failed++;
+      errors.push({ summary: row.summary, message: error.message });
+      continue;
+    }
+
+    const notes = Array.isArray(row.notes) ? row.notes : [];
+    const createdId = created && (created.id || created._id);
+    if (notes.length && createdId) {
+      const noteUrl = new URL(`/api/v1/memories/${encodeURIComponent(createdId)}/notes`, baseUrl).toString();
+      for (const note of notes) {
+        const text = typeof note === 'string' ? note : (note && note.text);
+        if (!text) continue;
+        try {
+          await httpJson(noteUrl, 'POST', { text }, buildApiAuthHeaders(accessToken));
+        } catch (_error) {
+          // Best-effort: a note failing to re-attach shouldn't fail the whole import.
+        }
+      }
+    }
+  }
+
+  log(JSON.stringify({ imported, failed, total: memories.length, errors: errors.slice(0, 20) }));
+}
+
+async function runMemoryBulkImport(args) {
+  const filePath = args.find((a) => a && !a.startsWith('--')) || '';
+  const dryRun = parseFlag(args, '--dry-run');
+
+  if (!filePath) {
+    warn('Usage: empirical memory bulk-import <file> [--dry-run]');
+    process.exit(1);
+  }
+
+  let plan;
+  try {
+    plan = JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8'));
+  } catch (error) {
+    warn(JSON.stringify({ error: true, code: 'json_file_error', message: error.message }));
+    process.exit(1);
+  }
+
+  const memories = Array.isArray(plan && plan.memories) ? plan.memories : null;
+  if (!memories) {
+    warn(JSON.stringify({
+      error: true,
+      code: 'invalid_format',
+      message: 'File must have a top-level "memories" array. See `empirical memory bulk-import --help`.'
+    }));
+    process.exit(1);
+  }
+  const relationships = Array.isArray(plan.relationships) ? plan.relationships : [];
+
+  if (dryRun) {
+    log(JSON.stringify({ dryRun: true, wouldImportMemories: memories.length, wouldImportRelationships: relationships.length }));
+    return;
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const bulkUrl = new URL('/api/v1/memories/bulk', baseUrl).toString();
+
+  try {
+    const enqueueResponse = await httpJson(bulkUrl, 'POST', { memories, relationships }, buildApiAuthHeaders(accessToken));
+    const { jobId } = (enqueueResponse && enqueueResponse.data) ? enqueueResponse.data : enqueueResponse;
+    const statusUrl = new URL(`/api/v1/memories/bulk/${jobId}`, baseUrl).toString();
+
+    const pollIntervalMs = 3000;
+    const maxPolls = 200;
+    for (let i = 0; i < maxPolls; i += 1) {
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      const statusResponse = await httpJson(statusUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
+      const job = (statusResponse && statusResponse.data) ? statusResponse.data : statusResponse;
+      if (job.status === 'succeeded') { log(JSON.stringify(job)); return; }
+      if (job.status === 'failed') { warn(JSON.stringify(job)); process.exit(1); }
+    }
+    warn(JSON.stringify({ error: true, code: 'timeout', message: `Job ${jobId} did not complete within ${(maxPolls * pollIntervalMs) / 1000}s` }));
+    process.exit(1);
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+async function runMemoryStats(args) {
+  const format = parseOption(args, '--format', 'json');
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/memory-stats', baseUrl).toString();
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+
+  if (format === 'table') {
+    log(`Total memories: ${data.total}`);
+    log(`Oldest: ${data.oldest || '(none)'}`);
+    log(`Newest: ${data.newest || '(none)'}`);
+    log('');
+    log('By category:');
+    log(renderTable(data.byCategory || [], ['category', 'count']));
+    log('');
+    log('By tag:');
+    log(renderTable(data.byTag || [], ['tag', 'count']));
+    return;
+  }
+
+  log(JSON.stringify(data));
+}
+
+async function runMemoryCompact(args) {
+  const apply = parseFlag(args, '--apply');
+  const category = parseOption(args, '--category', '');
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const url = new URL('/api/v1/memory-compaction', baseUrl).toString();
+  const body = { apply };
+  if (category) body.category = category;
+
+  let response;
+  try {
+    response = await httpJson(url, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify(data));
+}
+
+async function runMemoryCommand(subArgs) {
+  const helpRequested = subArgs.includes('--help') || subArgs.includes('-h');
+  const sub = subArgs[0] && !subArgs[0].startsWith('-') ? subArgs[0] : undefined;
+
+  if (helpRequested || !sub) {
+    printMemoryHelp(sub);
+    return;
+  }
+
+  const rest = subArgs.slice(1);
+
+  return withCliAnalyticsContext(
+    { command: `memory.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
+    async () => withSelectedWorkspaceContext(async () => {
+      if (sub === 'query') return runMemoryQuery(rest);
+      if (sub === 'get') return runMemoryGet(rest);
+      if (sub === 'list') return runMemoryList(rest);
+      if (sub === 'record') return runMemoryRecord(rest);
+      if (sub === 'note') return runMemoryNote(rest);
+      if (sub === 'update') return runMemoryUpdate(rest);
+      if (sub === 'acknowledge' || sub === 'ack' || sub === 'done') return runMemoryAcknowledge(rest);
+      if (sub === 'delete') return runMemoryDelete(rest);
+      // `attachments` and `attach` are shorthands for the two subcommands that get used most.
+      if (sub === 'attachment') return runAttachmentCommand(rest);
+      if (sub === 'attachments') return runAttachmentCommand(['list', ...rest]);
+      if (sub === 'attach') return runAttachmentCommand(['add', ...rest]);
+      if (sub === 'tree') return runMemoryTree(rest);
+      if (sub === 'duplicates') return runMemoryDuplicates(rest);
+      if (sub === 'merge') return runMemoryMerge(rest);
+      if (sub === 'export') return runMemoryExport(rest);
+      if (sub === 'import') return runMemoryImport(rest);
+      if (sub === 'bulk-import') return runMemoryBulkImport(rest);
+      if (sub === 'stats') return runMemoryStats(rest);
+      if (sub === 'compact') return runMemoryCompact(rest);
+
+      warn('Unknown memory subcommand: ' + (sub || '(none)'));
+      warn('Usage: empirical memory <query|record|note|update|delete|attachment|tree|duplicates|merge|export|import|stats|compact> [options]');
+      process.exit(1);
+    })
+  );
+}
+
+module.exports = {
+  resolveSummaryInput,
+  detectShellMangling,
+  withCliAnalyticsContext,
+  resolveMemoryByQuery,
+  printMemoryResolveError,
+  resolveWorkspaceIdsForQuery,
+  runMemoryQuery,
+  runMemoryGet,
+  runMemoryList,
+  runMemoryRecord,
+  runMemoryNote,
+  runMemoryUpdate,
+  runMemoryAcknowledge,
+  runMemoryDelete,
+  runMemoryTree,
+  runMemoryDuplicates,
+  runMemoryMerge,
+  runMemoryExport,
+  runMemoryImport,
+  runMemoryBulkImport,
+  runMemoryStats,
+  runMemoryCompact,
+  runMemoryDeleteBulk,
+  runMemoryCommand
+};