@empirical-gauzza/cli 1.0.20 → 1.0.21

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

@@ -78,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 };
   }
@@ -103,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];
 
@@ -117,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.' }));
@@ -340,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);
   }
 
@@ -354,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);
@@ -383,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);
   }
 
@@ -414,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);
@@ -484,7 +518,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 +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

package/lib/skillPaths.js

@@ -1,25 +1,25 @@
-'use strict';
-
-// Per-agent skill file path conventions, mirrored exactly from the hardcoded paths already used
-// by installers/claude.js, installers/codex.js, installers/copilot.js (for the single
-// empirical-memory skill) — parameterized by skill name instead of hardcoded to it.
-//
-// Split out of skillSync.js into its own dependency-free module so both skillSync.js and
-// installers/nativePlugin.js (C-001's mode-aware Skill overwrite) can use the same path
-// convention without creating a require cycle: skillSync.js -> installers/detect.js ->
-// installers/claude.js|codex.js|copilot.js -> installers/nativePlugin.js would loop straight
-// back into skillSync.js if nativePlugin.js required it directly.
-const os = require('os');
-const path = require('path');
-
-function skillFilePath(targetId, skillName) {
-  const home = os.homedir();
-  if (targetId === 'claude') return path.join(home, '.claude', 'skills', skillName, 'SKILL.md');
-  if (targetId === 'codex') return path.join(home, '.agents', 'skills', skillName, 'SKILL.md');
-  if (targetId === 'copilot') return path.join(home, '.copilot', 'skills', skillName, 'SKILL.md');
-  return null;
-}
-
-module.exports = {
-  skillFilePath
-};
+'use strict';
+
+// Per-agent skill file path conventions, mirrored exactly from the hardcoded paths already used
+// by installers/claude.js, installers/codex.js, installers/copilot.js (for the single
+// empirical-memory skill) — parameterized by skill name instead of hardcoded to it.
+//
+// Split out of skillSync.js into its own dependency-free module so both skillSync.js and
+// installers/nativePlugin.js (C-001's mode-aware Skill overwrite) can use the same path
+// convention without creating a require cycle: skillSync.js -> installers/detect.js ->
+// installers/claude.js|codex.js|copilot.js -> installers/nativePlugin.js would loop straight
+// back into skillSync.js if nativePlugin.js required it directly.
+const os = require('os');
+const path = require('path');
+
+function skillFilePath(targetId, skillName) {
+  const home = os.homedir();
+  if (targetId === 'claude') return path.join(home, '.claude', 'skills', skillName, 'SKILL.md');
+  if (targetId === 'codex') return path.join(home, '.agents', 'skills', skillName, 'SKILL.md');
+  if (targetId === 'copilot') return path.join(home, '.copilot', 'skills', skillName, 'SKILL.md');
+  return null;
+}
+
+module.exports = {
+  skillFilePath
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@empirical-gauzza/cli",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Persistent cross-tool memory for AI agents. Give Claude Code, Codex, Copilot, Cursor, and ChatGPT one shared memory: save project context once, recall it everywhere via CLI or MCP.",
   "keywords": [
     "memory",