quoxcli 0.4.0 → 0.6.0

package/lib/commands/mcp.js

@@ -0,0 +1,190 @@
+/**
+ * QuoxMCP setup from the CLI (VULCAN): the CLI rung under Settings > MCP credentials.
+ *
+ *   quox mcp token create --label <text> [--days <1-90>]   mint a personal MCP token (raw token shown ONCE)
+ *   quox mcp token list                                    your MCP tokens (never the token or its hash)
+ *   quox mcp token revoke <id>                             revoke one of your tokens
+ *   quox mcp bundle [--out <file>]                         personalised Claude Desktop .mcpb (EMBEDS a fresh token)
+ *
+ * Tokens: auth /api/auth/tokens/mcp (services/auth/routes/mcp-tokens.js). Bundle: collector /api/v1/mcp/bundle
+ * (services/collector/routes/mcp-bundle.js), which takes the raw token in the body and bakes it into the
+ * bundle manifest as QUOX_SERVICE_KEY, so the bundle file is a credential: written 0600, never printed.
+ */
+
+import { existsSync, writeFileSync, chmodSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { formatOutput, printSuccess, printInfo, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxError } from '../core/errors.js';
+
+const MAX_DAYS = 90;
+const OUTPUT_FORMATS = ['table', 'json', 'csv', 'quiet'];
+const DEFAULT_BUNDLE = 'quoxmcp.mcpb';
+
+function parseDays(raw) {
+  if (raw === undefined) return undefined;
+  const s = String(raw).trim();
+  const n = Number(s);
+  if (!/^\d+$/.test(s) || n < 1 || n > MAX_DAYS) {
+    throw new QuoxError(`--days must be a whole number from 1 to ${MAX_DAYS} (got "${raw}")`, 1);
+  }
+  return n;
+}
+
+function parseLabel(raw) {
+  const label = String(raw ?? '').trim();
+  if (!label) throw new QuoxError('--label must not be empty', 1);
+  if (label.length > 128) throw new QuoxError('--label must be 128 characters or fewer', 1);
+  return label;
+}
+
+const isJson = (program) => program.opts().output === 'json';
+
+export function registerMcpCommands(program, ctx) {
+  const { client, auth, config } = ctx;
+
+  async function mint(label, days) {
+    const ep = resolveEndpoint('mcp.tokens.create');
+    return client.post(ep.path, {
+      service: ep.service,
+      sensitive: true,
+      body: { label, ...(days !== undefined ? { expires_in_days: days } : {}) },
+    });
+  }
+
+  const mcp = program
+    .command('mcp')
+    .description('QuoxMCP setup: personal MCP tokens and the Claude Desktop bundle');
+
+  const token = mcp
+    .command('token')
+    .description('Personal MCP tokens (qmcp_...) for connecting an MCP client to Quox');
+
+  token
+    .command('create')
+    .description(`Mint a personal MCP token for your active org; the raw token is shown ONCE (expires in ${MAX_DAYS} days unless --days is lower)`)
+    .requiredOption('--label <text>', 'what this token is for, e.g. "work laptop" (max 128 chars)')
+    .option('--days <n>', `days until it expires, 1 to ${MAX_DAYS} (default ${MAX_DAYS})`)
+    .action(async (opts) => {
+      auth.requireAuth();
+      const label = parseLabel(opts.label);
+      const days = parseDays(opts.days);
+      const data = await mint(label, days);
+      if (isJson(program)) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      printSuccess(`MCP token ${data.id} created (label "${data.label ?? label}").`);
+      console.log('Token (shown once, store it now; it cannot be shown again):');
+      console.log(data.token);
+      console.log(`Expires: ${data.expires_at || 'no expiry'}`);
+      printInfo(`Revoke it any time with: quox mcp token revoke ${data.id}`);
+    });
+
+  token
+    .command('list')
+    .description('List your MCP tokens (id, label, created, last used, expiry, revoked); never shows a token value')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mcp.tokens.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      const tokens = Array.isArray(data?.tokens) ? data.tokens : [];
+      formatOutput({
+        columns: ['id', 'label', 'created_at', 'last_used_at', 'expires_at', 'revoked_at'],
+        headers: ['ID', 'Label', 'Created', 'Last used', 'Expires', 'Revoked'],
+        rows: tokens.map((t) => ({
+          id: t.id,
+          label: t.label,
+          created_at: t.created_at || '',
+          last_used_at: t.last_used_at || 'never',
+          expires_at: t.expires_at || 'no expiry',
+          revoked_at: t.revoked_at || 'no',
+        })),
+      }, { format: program.opts().output, raw: tokens, emptyMessage: 'No MCP tokens. Create one with: quox mcp token create --label <text>' });
+    });
+
+  token
+    .command('revoke')
+    .description('Revoke one of your MCP tokens (takes effect at the collector straight away)')
+    .argument('<id>', 'token id from `quox mcp token list`')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('mcp.tokens.revoke', { id });
+      try {
+        await client.delete(ep.path, { service: ep.service });
+      } catch (err) {
+        if (err?.status === 404) throw new QuoxError(`MCP token ${id} not found or already revoked.`, 1);
+        throw err;
+      }
+      printSuccess(`MCP token ${id} revoked.`);
+    });
+
+  mcp
+    .command('bundle')
+    .description('Download a personalised QuoxMCP bundle (.mcpb) for Claude Desktop. It mints a NEW MCP token and embeds a live MCP token in the file: treat the file as a secret (written 0600, never printed)')
+    .option('--out <path>', `where to save it (-o <path> also works); default ./${DEFAULT_BUNDLE}`)
+    .option('--label <text>', 'label for the token minted into the bundle', 'Claude Desktop')
+    .option('--days <n>', `days until the embedded token expires, 1 to ${MAX_DAYS} (default ${MAX_DAYS})`)
+    .option('--collector-url <url>', 'collector URL the bundle will call (default: this profile\'s collector URL)')
+    .option('--force', 'overwrite an existing file')
+    .addHelpText('after', '\nThe bundle embeds a live MCP token. Anyone holding the file can act as you over MCP until the token\nexpires or you revoke it (quox mcp token revoke <id>). Do not commit or share it.\n')
+    .action(async (opts) => {
+      auth.requireAuth();
+      const label = parseLabel(opts.label);
+      const days = parseDays(opts.days);
+      const collectorUrl = opts.collectorUrl || config?.getServiceUrl?.('collector');
+      try {
+        if (!collectorUrl) throw new Error('missing');
+        new URL(collectorUrl);
+      } catch {
+        throw new QuoxError(`--collector-url must be a valid URL (got "${collectorUrl ?? ''}")`, 1);
+      }
+      const g = program.opts().output;
+      const outArg = opts.out || (g && !OUTPUT_FORMATS.includes(g) ? g : undefined) || DEFAULT_BUNDLE;
+      const target = resolve(ctx.cwd || process.cwd(), outArg);
+      if (existsSync(target) && !opts.force) throw new QuoxError(`${target} already exists. Use --force to overwrite.`, 1);
+
+      const minted = await mint(label, days);
+      const revokeMinted = async () => {
+        try {
+          const rep = resolveEndpoint('mcp.tokens.revoke', { id: minted.id });
+          await client.delete(rep.path, { service: rep.service });
+          printWarning(`Revoked the token minted for this bundle (${minted.id}).`);
+        } catch {
+          printWarning(`Could not revoke the token minted for this bundle; revoke it with: quox mcp token revoke ${minted.id}`);
+        }
+      };
+
+      const bep = resolveEndpoint('mcp.bundle');
+      let buf;
+      try {
+        const res = await client.post(bep.path, {
+          service: bep.service,
+          raw: true,
+          sensitive: true,
+          timeout: 120000,
+          body: { token: minted.token, collector_url: collectorUrl, agent_id: 'quox' },
+        });
+        if (!res.ok) {
+          let detail = '';
+          try { const b = await res.json(); detail = b?.message || b?.error || ''; } catch { /* non-JSON body */ }
+          throw new QuoxError(`Bundle generation failed: HTTP ${res.status}${detail ? ` (${detail})` : ''}.`, 1);
+        }
+        buf = Buffer.from(await res.arrayBuffer());
+      } catch (err) {
+        await revokeMinted();
+        throw err;
+      }
+
+      writeFileSync(target, buf, { mode: 0o600 });
+      chmodSync(target, 0o600); // mode only applies on create; --force over an existing file must tighten it too
+      if (isJson(program)) {
+        console.log(JSON.stringify({ path: target, bytes: buf.length, token_id: minted.id, expires_at: minted.expires_at ?? null, collector_url: collectorUrl }, null, 2));
+        return;
+      }
+      printSuccess(`Saved ${target} (${buf.length} bytes, mode 0600).`);
+      console.log(`It embeds MCP token ${minted.id} (expires ${minted.expires_at || 'never'}) and calls ${collectorUrl}.`);
+      console.log('Open the file with Claude Desktop to install QuoxMCP. Treat it as a secret.');
+      printInfo(`Revoke it any time with: quox mcp token revoke ${minted.id}`);
+    });
+}

package/lib/commands/memory.js

@@ -27,12 +27,18 @@ import { QuoxError } from '../core/errors.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveMyAttach } from './agentAttach.js';
 import { hasExplicitProfile } from '../core/actingAs.js';
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { syncMemoryFiles, expandPaths, defaultMemoryDir } from './memorySync.js';
+import { announce, announceFailure } from '../core/announce.js';
 
 // QUOXIDENTITY P9: which agent this session acts as is resolved session-scoped
 // (QUOX_T subtree / QUOX_ATTACH_AGENT override / single-attach fallback), so
 // two sessions on one box no longer collide. See agentAttach.js resolveMyAttach.
 const detectSoleAttachLease = resolveMyAttach;
 
+// Short, single-line form of a memory's text for the announce line.
+const clip = (t) => { const x = String(t || '').replace(/\s+/g, ' ').trim(); return x.length > 28 ? x.slice(0, 27) + '…' : x; };
+
 /**
  * Call a governed collector memory tool (POST /api/v1/tools/execute).
  * Lease-aware: when exactly one attach lease is active, the call is made
@@ -161,6 +167,7 @@ export function registerMemoryCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('memory.reinstate', { id });
       const data = await client.post(ep.path, { service: ep.service, body: {} });
+      announce('memory', `reinstated ${data.reinstated?.id || id}`);
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       printSuccess(`Reinstated ${data.reinstated?.id}; retired ${data.retired?.id} (marked disputed, Dream will not re-apply it)`);
     });
@@ -180,10 +187,56 @@ export function registerMemoryCommands(program, ctx) {
       };
       if (options.tags) body.tags = options.tags.split(',').map(t => t.trim());
       if (options.agent) body.agent_id = options.agent;
-      await client.post(resolveEndpoint('memory.create').path, { service: resolveEndpoint('memory.create').service, body });
+      const label = `${options.type} "${clip(options.content)}"`;
+      let data;
+      try {
+        data = await client.post(resolveEndpoint('memory.create').path, { service: resolveEndpoint('memory.create').service, body });
+      } catch (err) { announceFailure('memory', `save ${label}`, err); throw err; }
+      announce('memory', `saved ${label}`, { result: data?.id || data?.memory?.id });
       printSuccess('Memory saved.');
     });
 
+  // Owner order 2026-10-29: do not replace Claude's file memory, ALSO save it to Quox memory.
+  // Additive and idempotent (see memorySync.js). One QuoxGlyph line per file saved or updated.
+  memory
+    .command('sync')
+    .description("Also save Claude Code's file memory (default: this project's memory dir) into Quox memory. Idempotent, additive, secrets refused")
+    .argument('[paths...]', 'memory files or directories (default: ~/.claude/projects/<this cwd>/memory)')
+    .option('--dry-run', 'show what would be saved without writing')
+    .action(async (paths, options) => {
+      auth.requireAuth();
+      const json = program.opts().output === 'json';
+      const targets = paths && paths.length ? paths : [defaultMemoryDir()];
+      const files = expandPaths(targets);
+      const ep = resolveEndpoint('memory.create');
+      const orgId = auth.getOrgId?.(program.opts().org) || 'default';
+      const results = await syncMemoryFiles({ client, orgId, files, dryRun: !!options.dryRun, memoryEp: ep });
+      const count = (a) => results.filter((r) => r.action === a).length;
+      const summary = {
+        created: count('created'), updated: count('updated'), unchanged: count('unchanged'),
+        refused: count('refused'), errors: count('error') + count('missing'),
+        would_create: count('would-create'), would_update: count('would-update'),
+      };
+      if (json) {
+        console.log(JSON.stringify({ dry_run: !!options.dryRun, summary, results }, null, 2));
+      } else {
+        const q = (r) => `"${r.name}"`;
+        for (const r of results) {
+          if (r.action === 'created') printEvent(glyphLine('memory', `also saved to Quox ${q(r)}`, { status: 'ok' }));
+          else if (r.action === 'updated') printEvent(glyphLine('memory', `updated in Quox ${q(r)}`, { status: 'ok' }));
+          else if (r.action === 'would-create') printEvent(glyphLine('memory', `would save to Quox ${q(r)}`, { status: 'busy' }));
+          else if (r.action === 'would-update') printEvent(glyphLine('memory', `would update in Quox ${q(r)}`, { status: 'busy' }));
+          else if (r.action === 'refused') printEvent(glyphLine('memory', `refused ${r.file.split('/').pop()}`, { result: `secret shape: ${r.kinds.join(', ')}`, status: 'warn' }));
+          else if (r.action === 'error' || r.action === 'missing') printEvent(glyphLine('memory', `sync ${r.file.split('/').pop()}`, { result: r.action === 'missing' ? 'file not found' : (r.error || 'failed').slice(0, 40), status: 'fail' }));
+        }
+        const bits = options.dryRun
+          ? `${summary.would_create} to save, ${summary.would_update} to update, ${summary.unchanged} unchanged`
+          : `${summary.created} saved, ${summary.updated} updated, ${summary.unchanged} unchanged`;
+        console.log(`Memory sync: ${bits}${summary.refused ? `, ${summary.refused} refused (secret shapes)` : ''}${summary.errors ? `, ${summary.errors} failed` : ''}.`);
+      }
+      if (summary.errors) process.exitCode = 1;
+    });
+
   memory
     .command('update')
     .description('Update a memory')
@@ -195,7 +248,10 @@ export function registerMemoryCommands(program, ctx) {
       const body = {};
       if (options.content) body.content = options.content;
       if (options.tags) body.tags = options.tags.split(',').map(t => t.trim());
-      await client.patch(resolveEndpoint('memory.update', { id }).path, { service: resolveEndpoint('memory.update', { id }).service, body });
+      try {
+        await client.patch(resolveEndpoint('memory.update', { id }).path, { service: resolveEndpoint('memory.update', { id }).service, body });
+      } catch (err) { announceFailure('memory', `update ${id}`, err); throw err; }
+      announce('memory', `updated ${id}`, { result: options.content ? `"${clip(options.content)}"` : undefined });
       printSuccess('Memory updated.');
     });
 
@@ -208,7 +264,10 @@ export function registerMemoryCommands(program, ctx) {
       auth.requireAuth();
       const query = {};
       if (options.hard) query.hard = 'true';
-      await client.delete(resolveEndpoint('memory.delete', { id }).path, { service: resolveEndpoint('memory.delete', { id }).service, query });
+      try {
+        await client.delete(resolveEndpoint('memory.delete', { id }).path, { service: resolveEndpoint('memory.delete', { id }).service, query });
+      } catch (err) { announceFailure('memory', `delete ${id}`, err); throw err; }
+      announce('memory', `deleted ${id}`, { result: options.hard ? 'permanent' : 'soft delete' });
       printSuccess('Memory deleted.');
     });
 
@@ -226,7 +285,10 @@ export function registerMemoryCommands(program, ctx) {
       const ep = resolveEndpoint('memory.delete', { id });
       const query = {};
       if (options.permanent) query.hard = 'true';
-      await client.delete(ep.path, { service: ep.service, query });
+      try {
+        await client.delete(ep.path, { service: ep.service, query });
+      } catch (err) { announceFailure('memory', `forget ${id}`, err); throw err; }
+      announce('memory', `forgot ${id}`, { result: options.permanent ? 'erased for good' : 'soft delete' });
       printSuccess(options.permanent ? `Permanently erased memory ${id}.` : `Forgot memory ${id}.`);
     });
 
@@ -333,6 +395,7 @@ export function registerMemoryCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('memory.pin', { id });
       const data = await client.post(ep.path, { service: ep.service, body: {} });
+      announce('memory', `pinned ${id}`, { result: 'core set' });
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       printSuccess(`Pinned ${id} into the core set.`);
     });
@@ -345,6 +408,7 @@ export function registerMemoryCommands(program, ctx) {
       auth.requireAuth();
       const ep = resolveEndpoint('memory.unpin', { id });
       const data = await client.delete(ep.path, { service: ep.service });
+      announce('memory', `unpinned ${id}`, { result: 'out of core set' });
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       printSuccess(`Unpinned ${id}: it stays a memory, but is no longer in the core set.`);
     });

package/lib/commands/memorySync.js

@@ -0,0 +1,158 @@
+/**
+ * `quox memory sync`: also save agent file memory (Claude Code's
+ * ~/.claude/projects/<slug>/memory/*.md) into Quox memory. ADDITIVE: the Claude
+ * files are only read, never written, and a removed file never deletes a Quox
+ * memory. Idempotent: each file has a stable source key
+ * (claude-memory:<slug>/<file>) and a content hash; unchanged files are skipped,
+ * changed files PATCH the same Quox memory. Files containing secret shapes are
+ * refused (named, never echoed).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, renameSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { secretKinds } from '../quoxon/secretShape.js';
+
+const MAX_CONTENT = 20000;
+
+/** Claude memory type -> closest Quox memory type (the API accepts fact, preference, decision, observation, entity). */
+export function quoxTypeFor(claudeType) {
+  switch (String(claudeType || '').toLowerCase()) {
+    case 'user': return 'preference';
+    case 'feedback': return 'decision';
+    case 'project': return 'fact';
+    case 'reference': return 'fact';
+    default: return 'observation';
+  }
+}
+
+const unquote = (v) => String(v ?? '').trim().replace(/^(["'])(.*)\1$/, '$2');
+
+/** -> { name, description, type, body } from a Claude memory file (frontmatter optional). */
+export function parseMemoryFile(text, fallbackName = '') {
+  const src = String(text ?? '').replace(/\r\n/g, '\n');
+  let front = '';
+  let body = src;
+  const m = src.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (m) { front = m[1]; body = src.slice(m[0].length); }
+  const out = { name: '', description: '', type: '' };
+  let inMeta = false;
+  for (const raw of front.split('\n')) {
+    const top = raw.match(/^([A-Za-z_]+):\s*(.*)$/);
+    if (top) {
+      inMeta = top[1] === 'metadata';
+      if (top[1] === 'name') out.name = unquote(top[2]);
+      else if (top[1] === 'description') out.description = unquote(top[2]);
+      else if (top[1] === 'type') out.type = unquote(top[2]);
+      continue;
+    }
+    const nested = raw.match(/^\s+type:\s*(.*)$/);
+    if (inMeta && nested) out.type = unquote(nested[1]);
+  }
+  return { name: out.name || fallbackName, description: out.description, type: out.type, body: body.trim() };
+}
+
+/** Stable key: claude-memory:<project slug>/<file>. */
+export function sourceKeyFor(file) {
+  const abs = resolve(file);
+  const parts = abs.split('/');
+  const mi = parts.lastIndexOf('memory');
+  const slug = mi > 0 ? parts[mi - 1] : createHash('sha256').update(dirname(abs)).digest('hex').slice(0, 8);
+  const rel = mi >= 0 ? parts.slice(mi + 1).join('/') : basename(abs);
+  return `claude-memory:${slug}/${rel}`;
+}
+
+/** Default memory dir for a cwd: ~/.claude/projects/<cwd with non-alnum -> '-'>/memory. */
+export function defaultMemoryDir(cwd = process.cwd()) {
+  return join(homedir(), '.claude', 'projects', cwd.replace(/[^A-Za-z0-9]/g, '-'), 'memory');
+}
+
+/** Expand dirs to their *.md files; MEMORY.md (the index) is skipped. */
+export function expandPaths(paths) {
+  const files = [];
+  for (const p of paths) {
+    const abs = resolve(p);
+    if (!existsSync(abs)) { files.push({ file: abs, missing: true }); continue; }
+    if (statSync(abs).isDirectory()) {
+      for (const f of readdirSync(abs).sort()) if (f.endsWith('.md')) files.push({ file: join(abs, f) });
+    } else files.push({ file: abs });
+  }
+  return files.filter((f) => f.missing || basename(f.file) !== 'MEMORY.md');
+}
+
+const statePathDefault = () => join(homedir(), '.quox', 'memory-sync-state.json');
+function loadState(p) { try { return JSON.parse(readFileSync(p, 'utf8')) || {}; } catch { return {}; } }
+function saveState(p, state) {
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2));
+  renameSync(tmp, p);
+}
+
+/**
+ * Sync files into Quox memory. client = the CLI http client; post/patch/get go to
+ * the memory service paths. Returns [{ file, key, name, action, id?, kinds?, error? }]
+ * where action is created | updated | unchanged | refused | missing | error | would-create | would-update.
+ */
+export async function syncMemoryFiles({ client, orgId = 'default', files, dryRun = false, statePath = statePathDefault(), memoryEp }) {
+  const state = loadState(statePath);
+  const mine = (state[orgId] ||= {});
+  let remote; // lazily loaded recovery index: source_key -> {id, hash}
+  const recover = async (key) => {
+    if (!remote) {
+      remote = {};
+      try {
+        const data = await client.get(memoryEp.path, { service: memoryEp.service, query: { limit: 1000 } });
+        for (const m of (data?.memories || [])) {
+          const sk = m?.metadata?.source_key;
+          if (sk) remote[sk] = { id: m.id, hash: m.metadata.content_hash };
+        }
+      } catch { /* recovery is best effort; worst case a first-time key creates */ }
+    }
+    return remote[key];
+  };
+
+  const results = [];
+  for (const entry of files) {
+    const { file } = entry;
+    const key = sourceKeyFor(file);
+    if (entry.missing) { results.push({ file, key, name: basename(file), action: 'missing' }); continue; }
+    let text;
+    try { text = readFileSync(file, 'utf8'); } catch (e) { results.push({ file, key, name: basename(file), action: 'error', error: e.message }); continue; }
+    const parsed = parseMemoryFile(text, basename(file, '.md'));
+    const kinds = secretKinds(text, { precise: true });
+    if (kinds.length) { results.push({ file, key, name: parsed.name, action: 'refused', rule: kinds[0], kinds }); continue; }
+    let content = [parsed.name, parsed.description].filter(Boolean).join(': ');
+    content = (content ? content + '\n\n' : '') + parsed.body;
+    content = content.slice(0, MAX_CONTENT);
+    const hash = createHash('sha256').update(content + '\0' + parsed.type).digest('hex');
+    const known = mine[key] || await recover(key);
+    if (known && known.hash === hash) { mine[key] = { id: known.id, hash }; results.push({ file, key, name: parsed.name, action: 'unchanged', id: known.id }); continue; }
+    const metadata = { source: 'claude-memory', source_key: key, content_hash: hash, source_file: basename(file), claude_type: parsed.type || null };
+    const tags = ['claude-memory', ...(parsed.type ? [`claude-memory:${parsed.type}`] : [])];
+    if (dryRun) { results.push({ file, key, name: parsed.name, action: known ? 'would-update' : 'would-create', id: known?.id }); continue; }
+    try {
+      let id = known?.id;
+      let action = 'created';
+      if (id) {
+        try {
+          await client.patch(`${memoryEp.path}/${id}`, { service: memoryEp.service, body: { content, tags, metadata } });
+          action = 'updated';
+        } catch (e) {
+          if (e?.status !== 404) throw e;
+          id = null; // the Quox memory was removed; make a fresh one
+        }
+      }
+      if (!id) {
+        const created = await client.post(memoryEp.path, { service: memoryEp.service, body: { type: quoxTypeFor(parsed.type), content, tags, metadata } });
+        id = created?.id || created?.memory?.id || null;
+      }
+      if (id) mine[key] = { id, hash };
+      results.push({ file, key, name: parsed.name, action, id });
+    } catch (e) {
+      results.push({ file, key, name: parsed.name, action: 'error', error: e?.message || String(e) });
+    }
+  }
+  if (!dryRun) { try { saveState(statePath, state); } catch { /* state is a cache; recovery covers it */ } }
+  return results;
+}