@empirical-gauzza/cli 1.0.37 → 1.0.39

package/lib/installers/skill-variants/SKILL.both.md

@@ -195,6 +195,26 @@ Use these when connected: `get_empirical_policy`, `query_memories`, `list_memori
 graph work, use `get_memory_neighbors` and `update_memory_relationships` when available instead of
 reconstructing relationships through many unrelated calls.
 
+## Shared workspaces: shape, and the setup interview
+
+When the current team workspace has been shaped, `get_current_workspace` also returns `shape` (its
+kinds of item, with their keys, statuses and fields) and `policy` (the rules its managers
+confirmed). Read them before saving into that workspace and follow them. A workspace with no shape
+returns neither.
+
+Setting up or changing a shared workspace is an interview the person answers. It is available only
+when `list_guided_setups` lists `setup_workspace`; when it is not listed, do not offer it. Call
+`start_guided_setup` with that setupId to create a new workspace. To change an existing one, also
+pass `reshapeWorkspaceId` with that workspace's id, and only when the person asked to change that
+workspace: leaving it out always creates a new one, and the selected workspace is never the target.
+A start can first return a cost: tell the person and call again with `acceptEmpiricalTokenCost`
+true only after they agree. Ask each question, send the person's own words with
+`continue_guided_setup`, show the whole draft, and call `confirm_guided_setup` with its draftHash
+only after they clearly say yes. Confirming creates the workspace or saves its shape and emails the
+invitations the draft lists. From the CLI, the same interview
+runs with `empirical workspace create --interview` and `empirical workspace shape --workspace-id <id>`;
+`empirical setup abandon <sessionId>` stops one and does not return what it cost.
+
 ## Reminders — set them, relay them, close them
 
 Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry

package/lib/installers/skill-variants/SKILL.cli.md

@@ -179,6 +179,16 @@ token error, run `empirical oauth bootstrap headless --write-env`. When in doubt
 subcommand's flags, run `empirical doc memory`, `empirical doc kit`, or `empirical doc skill`
 rather than guessing.
 
+## Shared workspaces: setup interview
+
+`empirical workspace create --interview` sets up a new shared workspace by interview, and
+`empirical workspace shape --workspace-id <id>` re-shapes one you manage. Both ask the person
+questions at the terminal, show a draft, and create or change the workspace only after they type
+yes. A new interview is charged, and `empirical setup abandon <sessionId>` stops one without
+returning what it cost, so say that before suggesting it. If the command says the interview is not
+switched on for the account, stop: nothing was started or charged. Run `empirical doc workspace`
+for the details.
+
 ## Reminders — set them, relay them, close them
 
 Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry

package/lib/installers/skill-variants/SKILL.mcp.md

@@ -167,6 +167,24 @@ An `empirical` CLI may also be installed on this machine for diagnostics (`empir
 manual account setup, but it is not the point of this variant — do not lead with CLI commands for
 query or record workflows here.
 
+## Shared workspaces: shape, and the setup interview
+
+When the current team workspace has been shaped, `get_current_workspace` also returns `shape` (its
+kinds of item, with their keys, statuses and fields) and `policy` (the rules its managers
+confirmed). Read them before saving into that workspace and follow them. A workspace with no shape
+returns neither.
+
+Setting up or changing a shared workspace is an interview the person answers. It is available only
+when `list_guided_setups` lists `setup_workspace`; when it is not listed, do not offer it. Call
+`start_guided_setup` with that setupId to create a new workspace. To change an existing one, also
+pass `reshapeWorkspaceId` with that workspace's id, and only when the person asked to change that
+workspace: leaving it out always creates a new one, and the selected workspace is never the target.
+A start can first return a cost: tell the person and call again with `acceptEmpiricalTokenCost`
+true only after they agree. Ask each question, send the person's own words with
+`continue_guided_setup`, show the whole draft, and call `confirm_guided_setup` with its draftHash
+only after they clearly say yes. Confirming creates the workspace or saves its shape and emails the
+invitations the draft lists.
+
 ## Reminders — set them, relay them, close them
 
 Any memory can carry a due date. Empirical then brings it back: an email with a calendar entry

package/lib/memoryCommands.js

@@ -8,6 +8,8 @@ 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) ─────────────────────────────────────────
 
@@ -64,11 +66,15 @@ 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]',
+  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>]',
@@ -97,100 +103,6 @@ async function withCliAnalyticsContext(context, fn) {
   }
 }
 
-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 ───────────────────────────────────────────────────────
 
@@ -514,7 +426,10 @@ async function runMemoryRecord(args) {
     }
 
     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]');
+      // 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);
@@ -591,6 +506,52 @@ async function runMemoryRecord(args) {
     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.
@@ -843,6 +804,84 @@ async function runMemoryDelete(args) {
   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) {
@@ -1180,6 +1219,11 @@ async function runMemoryCommand(subArgs) {
       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);
@@ -1189,7 +1233,7 @@ async function runMemoryCommand(subArgs) {
       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]');
+      warn('Usage: empirical memory <query|record|note|update|delete|attachment|tree|duplicates|merge|export|import|stats|compact> [options]');
       process.exit(1);
     })
   );
@@ -1210,6 +1254,7 @@ module.exports = {
   runMemoryUpdate,
   runMemoryAcknowledge,
   runMemoryDelete,
+  runMemoryTree,
   runMemoryDuplicates,
   runMemoryMerge,
   runMemoryExport,

package/lib/memoryResolve.js

@@ -0,0 +1,112 @@
+'use strict';
+
+// Resolving "which memory did the user mean" from a --match query, shared by every memory
+// subcommand that accepts --match. It lives in its own module so attachmentCommands.js can use
+// it without a require cycle back through memoryCommands.js; memoryCommands.js re-exports the
+// three names so existing importers and tests are unaffected.
+
+const { warn } = require('./ui');
+const { httpJson } = require('./http');
+const { parseOption } = require('./env');
+const { buildApiAuthHeaders } = require('./auth');
+
+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.' }));
+  }
+}
+
+module.exports = {
+  resolveMemoryByQuery,
+  parseMatchFilters,
+  printMemoryResolveError
+};