@empirical-gauzza/cli 1.0.19 → 1.0.21

package/lib/memoryCommands.js

@@ -6,9 +6,69 @@ const { log, warn } = require('./ui');
 const { httpJson, printApiError } = require('./http');
 const { parseOption, parseFlag } = require('./env');
 const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
-const { MEMORY_CATEGORIES } = require('./constants');
+const { MEMORY_CATEGORIES, 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 || '',
+    summary: truncateForTable(m.summary, 60),
+    score: m.rankScore != null ? m.rankScore : (m.similarityScore != null ? m.similarityScore : '')
+  }));
+  return renderTable(rows, ['id', 'category', 'summary', 'score']);
+}
+
+// ─── 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>] [--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> [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link]',
+  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]',
+  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]',
+  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 {
@@ -18,11 +78,13 @@ async function withCliAnalyticsContext(context, fn) {
   }
 }
 
-async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl) {
+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', { query: match, topK: 5 }, buildApiAuthHeaders(accessToken));
+    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
   } catch (error) {
     return { found: false, reason: 'error', message: error.message };
   }
@@ -43,6 +105,19 @@ async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl) {
 
   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];
 
@@ -57,6 +132,23 @@ async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl) {
   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.' }));
@@ -96,6 +188,7 @@ async function runMemoryQuery(args) {
   const tagsRaw = parseOption(args, '--tags', '');
   const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
   const pretty = parseFlag(args, '--pretty');
+  const format = parseOption(args, '--format', 'json');
 
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
@@ -119,6 +212,11 @@ async function runMemoryQuery(args) {
     ? response.data.results
     : (Array.isArray(response) ? response : []);
 
+  if (format === 'table') {
+    log(renderMemoryResultsTable(results));
+    return;
+  }
+
   if (pretty) {
     log(JSON.stringify(results, null, 2));
   } else {
@@ -158,6 +256,7 @@ async function runMemoryList(args) {
   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);
@@ -180,6 +279,13 @@ async function runMemoryList(args) {
     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));
 }
 
@@ -199,7 +305,7 @@ async function runMemoryRecord(args) {
     const summary = parseOption(args, '--summary', '');
 
     if (!category || !summary) {
-      warn('Usage: empirical memory record --category <cat> --summary <text> [--tags t1,t2] [--node-type observation]');
+      warn('Usage: empirical memory record --category <cat> --summary <text> [--tags t1,t2] [--node-type observation] [--no-dedupe] [--no-auto-link]');
       warn('Valid categories: ' + MEMORY_CATEGORIES.join(', '));
       process.exit(1);
     }
@@ -230,6 +336,19 @@ async function runMemoryRecord(args) {
     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;
+  }
+
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
   const recordUrl = new URL('/api/v1/memories', baseUrl).toString();
@@ -253,12 +372,12 @@ async function runMemoryNote(args) {
   const minScore = Number(parseOption(args, '--min-score', '0.35'));
 
   if (!text) {
-    warn('Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--min-score 0.35]');
+    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>)');
+    warn('Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>) [--tags <t1,t2>]');
     process.exit(1);
   }
 
@@ -267,7 +386,8 @@ async function runMemoryNote(args) {
 
   let targetId = memoryId;
   if (!targetId) {
-    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl);
+    const filters = parseMatchFilters(args);
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
     if (!result.found) {
       printMemoryResolveError(result);
       process.exit(1);
@@ -296,12 +416,12 @@ async function runMemoryUpdate(args) {
   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>)');
+    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>)');
+    warn('Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>) [--tags <t1,t2>]');
     process.exit(1);
   }
 
@@ -327,7 +447,8 @@ async function runMemoryUpdate(args) {
 
   let targetId = memoryId;
   if (!targetId) {
-    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl);
+    const filters = parseMatchFilters(args);
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters);
     if (!result.found) {
       printMemoryResolveError(result);
       process.exit(1);
@@ -348,14 +469,57 @@ async function runMemoryUpdate(args) {
   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>) [--confirm] [--min-score 0.35]');
+    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);
   }
 
@@ -366,7 +530,8 @@ async function runMemoryDelete(args) {
   let targetSummary = '';
 
   if (!targetId) {
-    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl);
+    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
@@ -479,14 +644,188 @@ async function runMemoryExport(args) {
     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(response, null, 2) + '\n', 'utf8');
+  fs.writeFileSync(resolvedPath, JSON.stringify(envelope, null, 2) + '\n', 'utf8');
 
-  log(JSON.stringify({ exported: true, path: resolvedPath, memoryCount: response.memoryCount }));
+  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 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 sub = subArgs[0];
+  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(
@@ -502,9 +841,12 @@ async function runMemoryCommand(subArgs) {
       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 === '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> [options]');
+      warn('Usage: empirical memory <query|record|note|update|delete|duplicates|merge|export|import|stats|compact> [options]');
       process.exit(1);
     })
   );
@@ -524,5 +866,9 @@ module.exports = {
   runMemoryDuplicates,
   runMemoryMerge,
   runMemoryExport,
+  runMemoryImport,
+  runMemoryStats,
+  runMemoryCompact,
+  runMemoryDeleteBulk,
   runMemoryCommand
 };