@yugabytedb/meko-mcp 1.0.4 → 1.0.6

package/README.md

@@ -79,7 +79,7 @@ The installer performs up to 5 steps (some are skippable via flags):
 |------|--------|------------------------|
 | 1 | Register MCP server | `claude mcp add meko <url> --transport http --scope user` (with `-H "API_KEY: <key>"` for cloud) |
 | 2 | Set hook environment vars | Writes `MEKO_MCP_URL` and `MEKO_API_KEY` into `~/.claude/settings.json` under the `env` key |
-| 3 | Register plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --sparse skills --scope user` |
+| 3 | Register plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --sparse .claude-plugin,skills --scope user` |
 | 4 | Install skills plugin | `claude plugin install meko-agent-skills --scope user` |
 | 5 | Validate setup | Config check via `claude mcp list`, MCP `initialize` handshake, `tools/list` verification |
 
@@ -215,6 +215,37 @@ create-meko-setup --migrate-stop
 create-meko-setup --migrate --scope user --no-extract
 ```
 
+### Reading `--migrate-status` output
+
+```
+run-id:       20260429-000912-74dbe6
+status:       running         (pending → running → done | failed | stopped)
+scope:        user
+started:      2026-04-29T00:09:12.673Z
+finished:     (in progress)
+current:      claude-code:-Users-.../meko-test / a2f6a1d6-...  (<adapter>:<source-session> / <message-id>)
+sessions:     76 / 111        (processed / discovered)
+messages:     674
+memory pairs: 674              (memory_add from Mem0 extractor)
+memory (MD):  0                (memory_add from CLAUDE.md / memory files)
+warnings:     0                (non-fatal; run continues)
+memory errs:  0                (failed memory_add calls; re-run with --force to retry)
+```
+
+| Field | Meaning |
+|---|---|
+| `run-id` | Unique ID; also the directory name under `~/.meko/migrate/<run-id>/`. |
+| `status` | Terminal states are `done`, `failed`, `stopped`. A `running` row that hasn't advanced in >30 s may indicate the daemon died — check `~/.meko/migrate/<run-id>/stdout.log`. |
+| `scope` | Matches the `--scope` flag used at start (`user` or `project`). |
+| `started` / `finished` | UTC timestamps. `finished` shows `(in progress)` until a terminal state is reached. |
+| `current` | Which source item is being replayed — `<adapter>:<source-session>` (adapter = `claude-code` / `cursor` / `memory-md`). Becomes stale on `done`/`failed`/`stopped`. |
+| `sessions` | Conversation sessions processed / discovered across all adapters. Climbs during the run. |
+| `messages` | Total messages replayed so far via `conversation_add_message`. |
+| `memory pairs` | `memory_add` calls made via the Mem0 extractor path (messages-style input). Usually close to `messages` when the extractor is enabled. |
+| `memory (MD)` | `memory_add` calls from `CLAUDE.md` / memory-file sources (plain-text input). |
+| `warnings` | Non-fatal issues (skipped item, partial parse). Run keeps going. |
+| `memory errs` | `memory_add` calls that failed. Non-zero means the memory extractor couldn't reach the server or rejected the payload — check the per-run log. Re-run with `--force` to retry only the failed items. |
+
 ### Behavior around install
 
 - **Interactive install** (no `--yes`): after a successful install, the installer dry-runs the enumerator, prints how much local data would be migrated, and asks `Y/n`. Declining prints a reminder to run `--migrate` later.

package/bin/create-meko-setup.mjs

@@ -6,8 +6,10 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
 import { install, uninstall } from '../lib/installer.mjs';
-import { askChoice, askText, askSecret, askYesNo, close as closePrompts } from '../lib/prompt.mjs';
+import { askChoice, askMultiChoice, askText, askSecret, askYesNo, close as closePrompts } from '../lib/prompt.mjs';
 import { banner, error, dim } from '../lib/logger.mjs';
+import { isPackagedInstall, selfInvocation } from '../lib/clients/common.mjs';
+import { getClientAdapters } from '../lib/clients/index.mjs';
 import { startMigration, runChildMigration, readStatus, stopMigration } from '../lib/migrate.mjs';
 
 // ---------------------------------------------------------------------------
@@ -146,6 +148,35 @@ function isValidScope(scope) {
   return ['user', 'project'].includes(scope);
 }
 
+/**
+ * Did the user pass --client on the CLI? parseArgs always materializes the
+ * default ("claude-code"), so we can't tell from flags alone — have to sniff
+ * argv. Used to decide whether to show the interactive client picker.
+ */
+function userPassedClientFlag() {
+  return process.argv.some(
+    (a) => a === '--client' || a.startsWith('--client='),
+  );
+}
+
+/**
+ * Which clients are actually installed on this machine? Uses each adapter's
+ * isInstalled() probe (CLI binary for Claude Code, config dir for Claude
+ * Desktop and Cursor). NOT detectPrerequisites — that checks deps like npx,
+ * which are present on basically any Node.js machine and would default the
+ * picker to "install everything". Returns a Set of client IDs.
+ */
+function detectInstalledClients() {
+  const adapters = getClientAdapters();
+  const detected = new Set();
+  for (const [id, adapter] of Object.entries(adapters)) {
+    if (typeof adapter.isInstalled === "function" && adapter.isInstalled()) {
+      detected.add(id);
+    }
+  }
+  return detected;
+}
+
 function isValidCursorHookMode(mode) {
   return ['native', 'claude-compat', 'hybrid'].includes(mode);
 }
@@ -251,7 +282,7 @@ async function main() {
     process.exit(out.ok ? 0 : 1);
   }
 
-  const { clients, invalid } = parseClients(flags.client);
+  let { clients, invalid } = parseClients(flags.client);
   if (invalid.length > 0) {
     error(`Unknown client(s): ${invalid.join(', ')}. Valid values: ${ALL_CLIENTS.join(', ')}, all.`);
     process.exit(1);
@@ -295,15 +326,69 @@ async function main() {
     apiKey = null;
   }
 
+  // Client picker — runs for any interactive invocation (including
+  // semi-interactive `--url ...` without `--client`). Historically the
+  // installer silently defaulted to --client=claude-code, so a user with
+  // Cursor or Claude Desktop also installed would never know those
+  // clients weren't configured. Skip when the user explicitly passed
+  // --client, or --yes (non-interactive).
+  if (!userPassedClientFlag() && !flags.yes) {
+    const detected = detectInstalledClients();
+    const pickerOptions = ALL_CLIENTS.map((id) => {
+      const displayName = {
+        'claude-code': 'Claude Code',
+        'claude-desktop': 'Claude Desktop',
+        cursor: 'Cursor',
+      }[id];
+      return {
+        label: id,
+        description: detected.has(id) ? `${displayName} (detected)` : `${displayName} (not detected)`,
+      };
+    });
+    if (detected.size === 1) {
+      clients = [[...detected][0]];
+      dim(`Only ${pickerOptions.find((o) => o.label === clients[0]).description.replace(' (detected)', '')} detected; installing for it.`);
+    } else if (detected.size === 0) {
+      // No client detected — fall through to the existing default.
+      // Validation later in the install will raise a clearer error than a
+      // blank picker would.
+      dim('No supported clients auto-detected. Defaulting to Claude Code; pass --client to override.');
+    } else {
+      const picked = await askMultiChoice(
+        'Install Meko for which client(s)?',
+        pickerOptions,
+        { defaults: [...detected] },
+      );
+      if (picked.length === 0) {
+        error('No clients selected. Aborting.');
+        process.exit(1);
+      }
+      clients = picked;
+    }
+  }
+
   // Interactive mode: URL not provided and not auto-accepting defaults
   if (!url && !flags.yes) {
-    banner();
-
-    // Step 1 — connection type
-    const connectionType = await askChoice('Connection type:', [
+    banner('Meko Setup');
+
+    // Step 1 — connection type. Local Meko only makes sense for users who
+    // have the server repo cloned locally (docker-compose stack on :8000);
+    // npm/npx users have no way to run it, so hide the option for them.
+    // When only Cloud is available, skip the prompt entirely — asking to
+    // pick between one option is pointless UX.
+    const connectionOptions = [
       { label: 'Cloud Meko', description: 'Hosted at mekodev.com (requires URL + API key)' },
-      { label: 'Local Meko', description: 'Local docker stack at localhost:8000' },
-    ]);
+    ];
+    if (!isPackagedInstall()) {
+      connectionOptions.push({
+        label: 'Local Meko',
+        description: 'Local stack at localhost:8000',
+      });
+    }
+    const connectionType =
+      connectionOptions.length === 1
+        ? connectionOptions[0].label
+        : await askChoice('Connection type:', connectionOptions);
 
     if (connectionType === 'Cloud Meko') {
       // Step 2 — MCP URL
@@ -393,7 +478,7 @@ async function main() {
       });
     } else if (flags.yes) {
       console.log('');
-      dim('Tip: run `create-meko-setup --migrate` to import existing conversations and memories.');
+      dim(`Tip: run \`${selfInvocation()} --migrate\` to import existing conversations and memories.`);
     } else if (process.stdin.isTTY) {
       await maybeOfferMigration({
         url,
@@ -422,7 +507,7 @@ async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
     console.log(out.message);
     if (!out.ok) {
       // Don't fail the install; the user can retry with --migrate.
-      dim('Migration did not start cleanly. Install succeeded; try `create-meko-setup --migrate` later.');
+      dim(`Migration did not start cleanly. Install succeeded; try \`${selfInvocation()} --migrate\` later.`);
     }
   } catch (err) {
     dim(`Migration could not be started: ${err.message ?? err}`);
@@ -468,7 +553,7 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
       true,
     );
     if (!proceed) {
-      dim('Skipped. Run `create-meko-setup --migrate` later when you\'re ready.');
+      dim(`Skipped. Run \`${selfInvocation()} --migrate\` later when you're ready.`);
       return;
     }
     const out = await startMigration({

package/lib/clients/claude-code.mjs

@@ -64,6 +64,10 @@ export function createClaudeCodeAdapter(options = {}) {
         log.dim(`  Claude CLI: ${claude.path} (${claude.version})`);
       }
     },
+    /** Is Claude Code actually installed on this machine? */
+    isInstalled() {
+      return detectClaude().found;
+    },
     detectExisting(name) {
       return detectExistingMeko(name);
     },
@@ -142,7 +146,7 @@ export function createClaudeCodeAdapter(options = {}) {
     },
     installSkills({ scope, dryRun, verbose, log }) {
       const marketplaceCmd =
-        `claude plugin marketplace add yugabyte/meko-mcp-server --sparse skills --scope ${scope}`;
+        `claude plugin marketplace add yugabyte/meko-mcp-server --sparse .claude-plugin,skills --scope ${scope}`;
       const pluginCmd = `claude plugin install meko-agent-skills --scope ${scope}`;
 
       if (dryRun) {
@@ -161,7 +165,8 @@ export function createClaudeCodeAdapter(options = {}) {
           marketplaceStatus = "already";
         } else {
           marketplaceStatus = "error";
-          log.warn(`Non-critical: ${msg}`);
+          log.warn("Marketplace install skipped (non-critical).");
+          log.dim(msg.trim());
         }
       }
 
@@ -175,7 +180,8 @@ export function createClaudeCodeAdapter(options = {}) {
           skillStatus = "already";
         } else {
           skillStatus = "error";
-          log.warn(`Non-critical: ${msg}`);
+          log.warn("Skills plugin install skipped (non-critical).");
+          log.dim(msg.trim());
         }
       }
 

package/lib/clients/claude-desktop.mjs

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 import {
   getClaudeDesktopConfigPath,
@@ -61,6 +61,16 @@ export function createClaudeDesktopAdapter(options = {}) {
         log.dim(`  npx: ${npx.path}${npx.version ? ` (${npx.version})` : ""}`);
       }
     },
+    /**
+     * Is Claude Desktop actually installed? The app creates its config
+     * directory on first launch, so the presence of that directory is a
+     * strong signal the app has been run at least once on this machine.
+     * (A user who installed the app but never opened it would produce a
+     * false negative — acceptable; they'd pass --client explicitly.)
+     */
+    isInstalled() {
+      return existsSync(dirname(configPathResolver()));
+    },
     detectExisting(name) {
       const cfg = readJsonFile(configPathResolver());
       const entry = cfg?.mcpServers?.[name];

package/lib/clients/common.mjs

@@ -31,6 +31,32 @@ export function getAssetRoot() {
   return join(getRepoRoot(), "skills");
 }
 
+/**
+ * True when the installer is running from an npm tarball (prepack-bundled
+ * `installer/assets/` exists), false when running from a source checkout.
+ * Use this to branch UX between the two install paths — e.g. hiding options
+ * that only make sense for repo cloners.
+ *
+ * @returns {boolean}
+ */
+export function isPackagedInstall() {
+  const libDir = dirname(fileURLToPath(import.meta.url));
+  return existsSync(resolve(libDir, "..", "..", "assets"));
+}
+
+/**
+ * The command a user would run to re-invoke this installer from a fresh
+ * shell. Differs between npm/npx (no global bin — must re-invoke via npx)
+ * and repo clones (bin isn't on PATH either, so use `node ...`).
+ *
+ * @returns {string}
+ */
+export function selfInvocation() {
+  return isPackagedInstall()
+    ? "npx @yugabytedb/meko-mcp"
+    : "node installer/bin/create-meko-setup.mjs";
+}
+
 /**
  * @param {string} name - skill directory name (e.g. "meko-mcp-tools")
  * @returns {string} absolute path to the skill source directory

package/lib/clients/cursor.mjs

@@ -5,6 +5,7 @@ import {
   writeFileSync,
   mkdirSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
 import {
@@ -51,6 +52,16 @@ export function createCursorAdapter(customPaths = {}) {
     async detectPrerequisites() {
       // No CLI dependency for Cursor config-mode installs.
     },
+    /**
+     * Is Cursor actually installed? Cursor creates `~/.cursor/` on first
+     * launch for MCP / hooks / skills config, so its existence is a strong
+     * signal the app has been run at least once on this machine. A user who
+     * installed Cursor but never opened it produces a false negative —
+     * acceptable; they'd pass --client explicitly.
+     */
+    isInstalled() {
+      return existsSync(join(homedir(), ".cursor"));
+    },
     detectExisting(name, { scope, projectRoot }) {
       const path = paths.getMcpPath(scope, projectRoot);
       const cfg = readJsonFile(path);

package/lib/installer.mjs

@@ -4,7 +4,6 @@ import {
   dim,
   error,
   info,
-  step,
   stepFail,
   stepOk,
   success,
@@ -107,7 +106,6 @@ export async function install(options) {
   let currentStep = 1;
 
   if (!skipMcpRegistration) {
-    step(currentStep, totalSteps, "Registering MCP server...");
     try {
       adapter.registerServer({
         name,
@@ -119,18 +117,17 @@ export async function install(options) {
         log: LOG,
         projectRoot,
       });
-      stepOk(currentStep, totalSteps, dryRun ? "Registering MCP server (dry-run)" : "MCP server registered.");
+      stepOk(currentStep, totalSteps, dryRun ? "Registering MCP server (dry-run)." : "MCP server registered.");
     } catch (err) {
       stepFail(currentStep, totalSteps, "Failed to register MCP server.");
       error(err.stderr || err.message);
       throw new Error("MCP server registration failed.");
     }
   } else {
-    step(currentStep, totalSteps, "Registering MCP server... skipped (existing config kept).");
+    stepOk(currentStep, totalSteps, "MCP server registration skipped (existing config kept).");
   }
   currentStep++;
 
-  step(currentStep, totalSteps, "Configuring hook environment...");
   try {
     adapter.setHookEnvironment({
       url,
@@ -143,7 +140,7 @@ export async function install(options) {
       projectRoot,
       cursorHookMode,
     });
-    stepOk(currentStep, totalSteps, dryRun ? "Configuring hook environment (dry-run)" : "Hook environment configured.");
+    stepOk(currentStep, totalSteps, dryRun ? "Configuring hook environment (dry-run)." : "Hook environment configured.");
   } catch (err) {
     stepFail(currentStep, totalSteps, "Failed to configure hook environment.");
     error(err.message);
@@ -152,7 +149,6 @@ export async function install(options) {
   currentStep++;
 
   if (!skipSkills) {
-    step(currentStep, totalSteps, "Installing skills support...");
     try {
       const result = adapter.installSkills({
         scope,
@@ -164,7 +160,7 @@ export async function install(options) {
       if (!dryRun && result?.marketplace === "manual") {
         warn("Skills installation requires manual action for this client.");
       }
-      stepOk(currentStep, totalSteps, dryRun ? "Installing skills support (dry-run)" : "Skills support configured.");
+      stepOk(currentStep, totalSteps, dryRun ? "Installing skills support (dry-run)." : "Skills support configured.");
     } catch (err) {
       stepFail(currentStep, totalSteps, "Failed to configure skills support.");
       warn(`Non-critical: ${err.message}`);
@@ -173,10 +169,9 @@ export async function install(options) {
   }
 
   if (!skipValidation) {
-    step(currentStep, totalSteps, "Validating setup...");
     if (dryRun) {
-      dim("  Would validate config, MCP connectivity, and tool availability.");
-      stepOk(currentStep, totalSteps, "Validating setup (dry-run)");
+      dim("Would validate config, MCP connectivity, and tool availability.");
+      stepOk(currentStep, totalSteps, "Validating setup (dry-run).");
     } else {
       try {
         const results = await runValidation(url, apiKey, name, {
@@ -190,8 +185,8 @@ export async function install(options) {
           { label: "Tools", ...results.tools },
         ];
         for (const check of checks) {
-          if (check.ok) success(`  ${check.label}: ${check.message}`);
-          else warn(`  ${check.label}: ${check.message}`);
+          if (check.ok) success(`${check.label}: ${check.message}`);
+          else warn(`${check.label}: ${check.message}`);
         }
 
         if (results.allPassed) {

package/lib/logger.mjs

@@ -55,26 +55,26 @@ export function error(msg) {
 
 /**
  * Print a numbered step that is in progress.
- * Example:   [1/5] Registering MCP server...
+ * Example: [1/5] Registering MCP server...
  */
 export function step(n, total, msg) {
-  console.log(`  ${BLUE}[${n}/${total}]${RESET} ${msg}`);
+  console.log(`${BLUE}[${n}/${total}]${RESET} ${msg}`);
 }
 
 /**
  * Print a numbered step that succeeded.
- * Example:   [1/5] Registering MCP server...          ✓
+ * Example: ✓ [1/5] MCP server registered.
  */
 export function stepOk(n, total, msg) {
-  console.log(`  ${GREEN}${CHECK}${RESET} ${BLUE}[${n}/${total}]${RESET} ${msg}`);
+  console.log(`${GREEN}${CHECK}${RESET} ${BLUE}[${n}/${total}]${RESET} ${msg}`);
 }
 
 /**
  * Print a numbered step that failed.
- * Example:   [3/5] Registering plugin marketplace...   ✗ Failed: ...
+ * Example: ✗ [3/5] Registering plugin marketplace failed: ...
  */
 export function stepFail(n, total, msg) {
-  console.log(`  ${RED}${CROSS}${RESET} ${BLUE}[${n}/${total}]${RESET} ${msg}`);
+  console.log(`${RED}${CROSS}${RESET} ${BLUE}[${n}/${total}]${RESET} ${msg}`);
 }
 
 /**

package/lib/migrate/orchestrator.mjs

@@ -283,11 +283,17 @@ export async function runMigration(opts) {
       const [, memRes] = await Promise.all([addMsgPromise, memPromise]);
       messagesSent++;
       if (!opts.noExtract) {
-        if (memRes && memRes.ok) {
+        if (memRes && memRes.ok && !isErrorText(memRes.text)) {
           memoryPairsSent++;
           prog.counts.memoryPairsSent++;
         } else if (memRes) {
           prog.counts.memoryErrors++;
+          log.warn("memory_add_failed", {
+            agentId: ref.agentId,
+            sessionUuid: ref.sessionUuid,
+            userUuid: ex.user_uuid,
+            detail: errorDetail(memRes),
+          });
         }
       }
       lastUuid = ex.user_uuid;
@@ -361,7 +367,7 @@ export async function runMigration(opts) {
       metadata: JSON.stringify(item.metadata),
     }, { fireAndForget: true });
 
-    if (res.ok) {
+    if (res.ok && !isErrorText(res.text)) {
       state.markMemory(st, item.agentId, item.hash, {
         memoryId: extractId(res.text) || "",
         name: item.name,
@@ -370,7 +376,12 @@ export async function runMigration(opts) {
       prog.counts.memoriesFromMD++;
     } else {
       prog.counts.memoryErrors++;
-      log.warn("memory_md_failed", { agentId: item.agentId, name: item.name, error: res.error?.message });
+      log.warn("memory_md_failed", {
+        agentId: item.agentId,
+        name: item.name,
+        error: res.error?.message,
+        detail: errorDetail(res),
+      });
     }
     if (++opsSinceFlush >= FLUSH_EVERY) flushState();
     writeProgress();
@@ -441,3 +452,34 @@ function extractId(text) {
     return null;
   }
 }
+
+/**
+ * The MCP transport returns `{ok:true}` whenever the HTTP call itself
+ * succeeded, even if the tool's body encoded a failure. memory_add in
+ * older server builds returned plain "Error adding memory: ..." strings
+ * on exception; newer builds return JSON `{"error":"memory_add_failed",...}`.
+ * Either way, the text content is the authoritative success signal.
+ */
+function isErrorText(text) {
+  if (!text) return false;
+  const trimmed = text.trim();
+  if (trimmed.startsWith("Error adding memory")) return true;
+  if (trimmed.startsWith("{")) {
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj && typeof obj === "object" && obj.error) return true;
+    } catch { /* not JSON; fall through */ }
+  }
+  return false;
+}
+
+function errorDetail(res) {
+  if (!res) return null;
+  if (res.error?.message) return res.error.message;
+  if (!res.text) return null;
+  try {
+    const obj = JSON.parse(res.text);
+    if (obj?.error) return obj.detail || obj.error;
+  } catch { /* not JSON */ }
+  return res.text.slice(0, 200);
+}

package/lib/migrate.mjs

@@ -17,6 +17,7 @@ import { createLogger } from "./migrate/logger.mjs";
 import { generateRunId, forkDetached, migrateRoot } from "./migrate/daemon.mjs";
 import * as lockfile from "./migrate/lockfile.mjs";
 import * as progress from "./migrate/progress.mjs";
+import { selfInvocation } from "./clients/common.mjs";
 
 function home() {
   return process.env.HOME || "";
@@ -183,7 +184,7 @@ export async function startMigration(opts) {
     message:
       `Migration started. run-id=${runId}, pid=${pid}\n` +
       `Logs:   ${P.logFile(runId)}\n` +
-      `Status: create-meko-setup --migrate-status`,
+      `Status: ${selfInvocation()} --migrate-status`,
   };
 }
 
@@ -268,19 +269,27 @@ export function readStatus(opts = {}) {
   if (!prog) {
     return { ok: false, runId, progress: null, message: `No progress file for run-id=${runId}.` };
   }
+  // Gray annotations next to each field. Keeps the output self-documenting
+  // without forcing the reader to cross-reference README docs for common
+  // fields. Respects NO_COLOR.
+  const useColor = !process.env.NO_COLOR;
+  const GRAY = useColor ? "\x1b[90m" : "";
+  const RESET = useColor ? "\x1b[0m" : "";
+  const note = (s) => (s ? `  ${GRAY}${s}${RESET}` : "");
+
   const lines = [
     `run-id:       ${prog.runId}`,
-    `status:       ${prog.status}`,
+    `status:       ${prog.status}${note("(pending → running → done | failed | stopped)")}`,
     `scope:        ${prog.scope}`,
     `started:      ${prog.startedAt}`,
     `finished:     ${prog.finishedAt ?? "(in progress)"}`,
-    `current:      ${prog.currentAgent ?? "-"} / ${prog.currentSession ?? "-"}`,
-    `sessions:     ${prog.counts.sessionsDone} / ${prog.counts.sessionsPlanned}`,
+    `current:      ${prog.currentAgent ?? "-"} / ${prog.currentSession ?? "-"}${note("(<adapter>:<source-session> / <message-id>)")}`,
+    `sessions:     ${prog.counts.sessionsDone} / ${prog.counts.sessionsPlanned}${note("(processed / discovered)")}`,
     `messages:     ${prog.counts.messagesSent}`,
-    `memory pairs: ${prog.counts.memoryPairsSent}`,
-    `memory (MD):  ${prog.counts.memoriesFromMD}`,
-    `warnings:     ${prog.counts.warnings}`,
-    `memory errs:  ${prog.counts.memoryErrors}`,
+    `memory pairs: ${prog.counts.memoryPairsSent}${note("(memory_add from Mem0 extractor)")}`,
+    `memory (MD):  ${prog.counts.memoriesFromMD}${note("(memory_add from CLAUDE.md / memory files)")}`,
+    `warnings:     ${prog.counts.warnings}${note("(non-fatal; run continues)")}`,
+    `memory errs:  ${prog.counts.memoryErrors}${note("(failed memory_add calls; re-run with --force to retry)")}`,
   ];
   return { ok: true, runId, progress: prog, message: lines.join("\n") };
 }

package/lib/prompt.mjs

@@ -71,6 +71,67 @@ export async function askChoice(questionText, options) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// askMultiChoice
+// ---------------------------------------------------------------------------
+
+/**
+ * Display a numbered list and let the user pick multiple items.
+ *
+ * Input formats accepted (all case-insensitive):
+ *   - `1,3,5` comma-separated indices
+ *   - `1-3` range, or mixed `1,3-5`
+ *   - `all` selects every option, `none` selects none
+ *   - empty input accepts the default set shown in the prompt
+ *
+ * @param {string} questionText
+ * @param {{ label: string, description?: string }[]} options
+ * @param {{ defaults?: string[] }} [opts] - Labels to default-on; shown with
+ *   `[x]` in the list and returned when the user presses Enter.
+ * @returns {Promise<string[]>} Array of selected option `label`s.
+ */
+export async function askMultiChoice(questionText, options, opts = {}) {
+  const defaults = new Set(opts.defaults ?? []);
+  console.log(`\n  ${questionText}`);
+  for (let i = 0; i < options.length; i++) {
+    const o = options[i];
+    const mark = defaults.has(o.label) ? "[x]" : "[ ]";
+    const desc = o.description ? `  - ${o.description}` : "";
+    console.log(`    ${mark} ${i + 1}) ${o.label}${desc}`);
+  }
+  console.log(`  (comma list like "1,3" or "1-3" / "all" / "none" / empty = keep defaults)`);
+
+  while (true) {
+    const raw = (await question(`  Choice: `)).trim().toLowerCase();
+    if (!raw) {
+      return options.filter((o) => defaults.has(o.label)).map((o) => o.label);
+    }
+    if (raw === "all") return options.map((o) => o.label);
+    if (raw === "none") return [];
+
+    const picked = new Set();
+    let bad = false;
+    for (const token of raw.split(",").map((t) => t.trim()).filter(Boolean)) {
+      const rangeMatch = token.match(/^(\d+)-(\d+)$/);
+      if (rangeMatch) {
+        const lo = parseInt(rangeMatch[1], 10);
+        const hi = parseInt(rangeMatch[2], 10);
+        if (lo < 1 || hi > options.length || lo > hi) { bad = true; break; }
+        for (let i = lo; i <= hi; i++) picked.add(i);
+      } else {
+        const n = parseInt(token, 10);
+        if (!Number.isInteger(n) || n < 1 || n > options.length) { bad = true; break; }
+        picked.add(n);
+      }
+    }
+    if (bad || picked.size === 0) {
+      console.log(`  Please enter numbers between 1 and ${options.length}, "all", or "none".`);
+      continue;
+    }
+    return [...picked].sort((a, b) => a - b).map((i) => options[i - 1].label);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // askText
 // ---------------------------------------------------------------------------
@@ -103,6 +164,18 @@ export async function askText(questionText, defaultValue) {
  * @returns {Promise<string>}
  */
 export async function askSecret(questionText) {
+  // Fully close the singleton readline BEFORE printing the prompt or
+  // entering raw mode. pause() alone was insufficient — readline left
+  // stdin in a state where the terminal echo would still leak keystrokes
+  // before our raw-mode handler wrote its `*` mask. close() forcefully
+  // releases stdin back to the OS, which lets setRawMode actually
+  // suppress echo. getRL() will recreate the interface on the next
+  // askText/askYesNo call, so downstream prompts still work.
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+
   // Print the prompt without a trailing newline.
   process.stdout.write(`  ${questionText} `);
 
@@ -131,6 +204,7 @@ export async function askSecret(questionText) {
     function cleanup() {
       stdin.setRawMode(wasRaw);
       stdin.removeListener("data", onData);
+      stdin.pause();
       process.stdout.write("\n");
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugabytedb/meko-mcp",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Single-line installer for Meko MCP Server across Claude and Cursor clients",
   "type": "module",
   "bin": {