@empirical-gauzza/cli 1.0.9

package/lib/memoryCommands.js

@@ -0,0 +1,528 @@
+'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 } = require('./constants');
+const { withSelectedWorkspaceContext } = require('./workspaceContext');
+
+async function withCliAnalyticsContext(context, fn) {
+  globalThis.__empiricalCliAnalyticsContext = context || {};
+  try {
+    return await fn();
+  } finally {
+    globalThis.__empiricalCliAnalyticsContext = null;
+  }
+}
+
+async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl) {
+  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
+  let response;
+  try {
+    response = await httpJson(queryUrl, 'POST', { query: match, topK: 5 }, 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);
+
+  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 } };
+}
+
+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 ───────────────────────────────────────────────────────
+
+async function runMemoryQuery(args) {
+  const match = parseOption(args, '--match', '');
+  if (!match) {
+    warn('Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--pretty]');
+    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) : [];
+  const pretty = parseFlag(args, '--pretty');
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
+
+  const body = { query: match, topK };
+  const filters = {};
+  if (category) filters.category = category;
+  if (tags.length) filters.tags = tags;
+  if (Object.keys(filters).length) body.filters = filters;
+
+  let response;
+  try {
+    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const results = (response && response.data && Array.isArray(response.data.results))
+    ? response.data.results
+    : (Array.isArray(response) ? response : []);
+
+  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 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;
+  log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+}
+
+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 = parseOption(args, '--summary', '');
+
+    if (!category || !summary) {
+      warn('Usage: empirical memory record --category <cat> --summary <text> [--tags t1,t2] [--node-type observation]');
+      warn('Valid categories: ' + MEMORY_CATEGORIES.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');
+
+    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) };
+  }
+
+  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>) [--min-score 0.35]');
+    process.exit(1);
+  }
+
+  if (!match && !memoryId) {
+    warn('Usage: empirical memory note --text <note> (--match <query> | --memory-id <id>)');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+
+  let targetId = memoryId;
+  if (!targetId) {
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl);
+    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));
+}
+
+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>)');
+    process.exit(1);
+  }
+
+  if (!match && !memoryId) {
+    warn('Usage: empirical memory update (--match <query> | --memory-id <id>) (--patch-json <json> | --json-file <path>)');
+    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 result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl);
+    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 runMemoryDelete(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]');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+
+  let targetId = memoryId;
+  let targetSummary = '';
+
+  if (!targetId) {
+    const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl);
+    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);
+  }
+
+  const resolvedPath = path.resolve(outPath);
+  fs.writeFileSync(resolvedPath, JSON.stringify(response, null, 2) + '\n', 'utf8');
+
+  log(JSON.stringify({ exported: true, path: resolvedPath, memoryCount: response.memoryCount }));
+}
+
+async function runMemoryCommand(subArgs) {
+  const sub = subArgs[0];
+  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 === 'delete') return runMemoryDelete(rest);
+      if (sub === 'duplicates') return runMemoryDuplicates(rest);
+      if (sub === 'merge') return runMemoryMerge(rest);
+      if (sub === 'export') return runMemoryExport(rest);
+
+      warn('Unknown memory subcommand: ' + (sub || '(none)'));
+      warn('Usage: empirical memory <query|record|note|update|delete|duplicates|merge|export> [options]');
+      process.exit(1);
+    })
+  );
+}
+
+module.exports = {
+  withCliAnalyticsContext,
+  resolveMemoryByQuery,
+  printMemoryResolveError,
+  runMemoryQuery,
+  runMemoryGet,
+  runMemoryList,
+  runMemoryRecord,
+  runMemoryNote,
+  runMemoryUpdate,
+  runMemoryDelete,
+  runMemoryDuplicates,
+  runMemoryMerge,
+  runMemoryExport,
+  runMemoryCommand
+};