@empirical-gauzza/cli 1.0.20 → 1.0.22

package/lib/installers/skillVariants.js

@@ -1,59 +1,59 @@
-'use strict';
-
-// C-001 (docs/prd-cli-and-plugin-fixes.md): mode-aware empirical-memory Skill content.
-//
-// The plugin marketplace (mattgauzza/empirical-memory-plugin) is the source of truth for Skill
-// content, but its manifest schema (see meta/manifests.json / build-manifests.mjs in that repo)
-// has no field that selects among sibling SKILL.*.md files at install time -- every host's native
-// plugin mechanism resolves a plugin's skill from the literal filename `SKILL.md`. So the
-// marketplace always ships the "both" variant as SKILL.md, and this CLI is what actually makes
-// the user's chosen integration mode matter: it vendors its own copy of all three variants and
-// overwrites the on-disk SKILL.md for each host after a native plugin install/update (see
-// nativePlugin.js's applySkillModeVariant) and after a Kit sync (see skillSync.js).
-//
-// These files are copied from, and must be kept in sync with,
-// M:\Projects\empirical-memory-plugin\skills\empirical-memory\SKILL.{mcp,cli,both}.md. There is no
-// automated sync between the two repos; a human updates both when skill content changes.
-const fs = require('fs');
-const path = require('path');
-
-const VARIANTS_DIR = path.join(__dirname, 'skill-variants');
-
-const VARIANT_FILES = {
-  mcp: 'SKILL.mcp.md',
-  cli: 'SKILL.cli.md',
-  both: 'SKILL.both.md'
-};
-
-// installWizard.js's `integrationMode`: 1 = MCP, 2 = CLI-direct, 3 = both.
-function variantNameForIntegrationMode(integrationMode) {
-  if (integrationMode === 2) return 'cli';
-  if (integrationMode === 3) return 'both';
-  return 'mcp';
-}
-
-// Returns the variant's markdown content, or null if the vendored file is missing (e.g. a stale
-// CLI release published before a variant existed). Never throws -- callers must treat a missing
-// variant as "leave whatever is already installed" per the PRD's own risk mitigation, not as a
-// fatal error.
-function readSkillVariantContent(variantName) {
-  const fileName = VARIANT_FILES[variantName];
-  if (!fileName) return null;
-  const filePath = path.join(VARIANTS_DIR, fileName);
-  try {
-    return fs.readFileSync(filePath, 'utf8');
-  } catch (_error) {
-    return null;
-  }
-}
-
-function readSkillVariantForIntegrationMode(integrationMode) {
-  return readSkillVariantContent(variantNameForIntegrationMode(integrationMode));
-}
-
-module.exports = {
-  VARIANT_FILES,
-  variantNameForIntegrationMode,
-  readSkillVariantContent,
-  readSkillVariantForIntegrationMode
-};
+'use strict';
+
+// C-001 (docs/prd-cli-and-plugin-fixes.md): mode-aware empirical-memory Skill content.
+//
+// The plugin marketplace (mattgauzza/empirical-memory-plugin) is the source of truth for Skill
+// content, but its manifest schema (see meta/manifests.json / build-manifests.mjs in that repo)
+// has no field that selects among sibling SKILL.*.md files at install time -- every host's native
+// plugin mechanism resolves a plugin's skill from the literal filename `SKILL.md`. So the
+// marketplace always ships the "both" variant as SKILL.md, and this CLI is what actually makes
+// the user's chosen integration mode matter: it vendors its own copy of all three variants and
+// overwrites the on-disk SKILL.md for each host after a native plugin install/update (see
+// nativePlugin.js's applySkillModeVariant) and after a Kit sync (see skillSync.js).
+//
+// These files are copied from, and must be kept in sync with,
+// M:\Projects\empirical-memory-plugin\skills\empirical-memory\SKILL.{mcp,cli,both}.md. There is no
+// automated sync between the two repos; a human updates both when skill content changes.
+const fs = require('fs');
+const path = require('path');
+
+const VARIANTS_DIR = path.join(__dirname, 'skill-variants');
+
+const VARIANT_FILES = {
+  mcp: 'SKILL.mcp.md',
+  cli: 'SKILL.cli.md',
+  both: 'SKILL.both.md'
+};
+
+// installWizard.js's `integrationMode`: 1 = MCP, 2 = CLI-direct, 3 = both.
+function variantNameForIntegrationMode(integrationMode) {
+  if (integrationMode === 2) return 'cli';
+  if (integrationMode === 3) return 'both';
+  return 'mcp';
+}
+
+// Returns the variant's markdown content, or null if the vendored file is missing (e.g. a stale
+// CLI release published before a variant existed). Never throws -- callers must treat a missing
+// variant as "leave whatever is already installed" per the PRD's own risk mitigation, not as a
+// fatal error.
+function readSkillVariantContent(variantName) {
+  const fileName = VARIANT_FILES[variantName];
+  if (!fileName) return null;
+  const filePath = path.join(VARIANTS_DIR, fileName);
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (_error) {
+    return null;
+  }
+}
+
+function readSkillVariantForIntegrationMode(integrationMode) {
+  return readSkillVariantContent(variantNameForIntegrationMode(integrationMode));
+}
+
+module.exports = {
+  VARIANT_FILES,
+  variantNameForIntegrationMode,
+  readSkillVariantContent,
+  readSkillVariantForIntegrationMode
+};

package/lib/memoryCommands.js

@@ -55,6 +55,7 @@ const MEMORY_SUBCOMMAND_USAGE = {
   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>]'
 };
@@ -78,11 +79,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 };
   }
@@ -103,6 +106,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];
 
@@ -117,6 +133,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.' }));
@@ -340,12 +373,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);
   }
 
@@ -354,7 +387,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);
@@ -383,12 +417,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);
   }
 
@@ -414,7 +448,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);
@@ -484,7 +519,7 @@ async function runMemoryDelete(args) {
   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);
   }
@@ -496,7 +531,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
@@ -727,6 +763,53 @@ async function runMemoryImport(args) {
   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 response = await httpJson(bulkUrl, 'POST', { memories, relationships }, buildApiAuthHeaders(accessToken));
+    const data = (response && response.data) ? response.data : response;
+    log(JSON.stringify(data));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
 async function runMemoryStats(args) {
   const format = parseOption(args, '--format', 'json');
 
@@ -807,6 +890,7 @@ async function runMemoryCommand(subArgs) {
       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);
 
@@ -832,6 +916,7 @@ module.exports = {
   runMemoryMerge,
   runMemoryExport,
   runMemoryImport,
+  runMemoryBulkImport,
   runMemoryStats,
   runMemoryCompact,
   runMemoryDeleteBulk,