@memnexus-ai/cli 1.7.218 → 1.7.220

package/dist/commands/memories.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StdinTooLargeError = exports.BATCH_CREATE_ALLOWED_KEYS = exports.BATCH_CREATE_MAX_LINE_BYTES = exports.BATCH_CREATE_MAX_STDIN_BYTES = exports.BATCH_CREATE_MAX_RETRIES = exports.BATCH_CREATE_CONCURRENCY_MAX = exports.BATCH_CREATE_CONCURRENCY_MIN = exports.BATCH_CREATE_DEFAULT_CONCURRENCY = exports.BULK_DELETE_LIST_PAGE_SIZE = exports.BULK_DELETE_MAX_RETRIES = exports.BULK_DELETE_PAGE_PAUSE_MS = exports.BULK_DELETE_MAX_IDS = exports.BULK_DELETE_GUARD_WINDOW_MS = exports.BULK_DELETE_GUARD_THRESHOLD = void 0;
+exports.StdinTooLargeError = exports.BATCH_CREATE_ALLOWED_KEYS = exports.BATCH_CREATE_MAX_LINE_BYTES = exports.BATCH_CREATE_MAX_STDIN_BYTES = exports.BATCH_CREATE_MAX_RETRIES = exports.BATCH_CREATE_CONCURRENCY_MAX = exports.BATCH_CREATE_CONCURRENCY_MIN = exports.BATCH_CREATE_DEFAULT_CONCURRENCY = exports.sleep = exports.getRetryAfterMs = exports.isQuotaError = exports.isServiceUnavailableError = exports.isRateLimitError = exports.BULK_DELETE_LIST_PAGE_SIZE = exports.BULK_DELETE_MAX_RETRIES = exports.BULK_DELETE_PAGE_PAUSE_MS = exports.BULK_DELETE_MAX_IDS = exports.BULK_DELETE_GUARD_WINDOW_MS = exports.BULK_DELETE_GUARD_THRESHOLD = void 0;
 exports.getBulkDeleteGuardPath = getBulkDeleteGuardPath;
 exports.readDeleteGuardTimestamps = readDeleteGuardTimestamps;
 exports.recordDeletion = recordDeletion;
@@ -45,15 +45,10 @@ exports.parseCodeContextFlag = parseCodeContextFlag;
 exports.parseBatchIds = parseBatchIds;
 exports.isValidIsoDate = isValidIsoDate;
 exports.chunkIds = chunkIds;
-exports.isRateLimitError = isRateLimitError;
-exports.getRetryAfterMs = getRetryAfterMs;
-exports.sleep = sleep;
 exports.bulkDeleteWithRetry = bulkDeleteWithRetry;
 exports.runBulkDeletePaged = runBulkDeletePaged;
 exports.collectAllMemoryIds = collectAllMemoryIds;
-exports.isServiceUnavailableError = isServiceUnavailableError;
 exports.isRetryableCreateError = isRetryableCreateError;
-exports.isQuotaError = isQuotaError;
 exports.parseJsonlCreateLine = parseJsonlCreateLine;
 exports.resolveCreateConcurrency = resolveCreateConcurrency;
 exports.batchCreateWithRetry = batchCreateWithRetry;
@@ -74,6 +69,12 @@ const chalk_1 = __importDefault(require("chalk"));
 const api_client_1 = require("../lib/api-client");
 const config_1 = require("../lib/config");
 const errors_1 = require("../lib/errors");
+const retry_1 = require("../lib/retry");
+Object.defineProperty(exports, "isRateLimitError", { enumerable: true, get: function () { return retry_1.isRateLimitError; } });
+Object.defineProperty(exports, "isServiceUnavailableError", { enumerable: true, get: function () { return retry_1.isServiceUnavailableError; } });
+Object.defineProperty(exports, "isQuotaError", { enumerable: true, get: function () { return retry_1.isQuotaError; } });
+Object.defineProperty(exports, "getRetryAfterMs", { enumerable: true, get: function () { return retry_1.getRetryAfterMs; } });
+Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return retry_1.sleep; } });
 const formatters_1 = require("../lib/formatters");
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const spinner_1 = require("../lib/spinner");
@@ -270,11 +271,11 @@ async function resolveShortIds(ids, opts = {}) {
         }
         else {
             // Resolve short ID
-            const listResponse = await (0, api_client_1.getSdk)().memories.listMemories({
+            const listResponse = await retryRead(() => (0, api_client_1.getSdk)().memories.listMemories({
                 limit: 10,
                 offset: 0,
                 idPrefix: id,
-            });
+            }));
             const matches = listResponse.data?.data || [];
             if (matches.length === 0) {
                 warn(`Warning: No memory found with prefix "${id}"`);
@@ -392,10 +393,10 @@ async function handleBatchMemoryGet(ids, options) {
         }
         spinner.text = `Fetching ${resolvedIds.length} memories...`;
         const batchDetail = options.detail || 'minimal';
-        const response = await (0, api_client_1.getSdk)().memories.getMemoriesBatch({
+        const response = await retryRead(() => (0, api_client_1.getSdk)().memories.getMemoriesBatch({
             ids: resolvedIds,
             detail: batchDetail,
-        });
+        }));
         const result = response.data;
         if (result && result.meta && result.meta.missing && result.meta.missing.length > 0) {
             spinner.warn(`Found ${result.meta.found} of ${result.meta.requested} memories`);
@@ -506,42 +507,46 @@ function chunkIds(ids, size = exports.BULK_DELETE_MAX_IDS) {
     }
     return chunks;
 }
-/** True when an error is an HTTP 429 (rate limited). */
-function isRateLimitError(error) {
-    const status = error?.status ?? error?.statusCode ?? error?.response?.status;
-    return status === 429;
+// ── Single-shot retry wiring (PO CLI-latency directive, item 3) ──────────────
+// These thin wrappers apply the shared withSingleShotRetry helper at the plain
+// single-request SDK call sites. The idempotency flag is passed PER CALL SITE —
+// that is the crux of the retry matrix, and it cannot be inferred centrally
+// because the same SDK method (createMemory) serves BOTH single create (retry)
+// and the batch --stdin-jsonl path (already retries via batchCreateWithRetry).
+// Wrapping per single-shot site is therefore the correct, non-double-wrapping
+// chokepoint; the batch helpers are left untouched.
+/** STDERR-only retry notice. Never touches stdout, so `--format json` stays pure. */
+function emitRetryNotice(info) {
+    const reason = info.status === 429 ? 'rate limited' : `transient error ${info.status ?? ''}`.trim();
+    console.error(chalk_1.default.dim(`⏳ ${reason}; retry ${info.attempt}/${info.maxRetries} in ${(info.waitMs / 1000).toFixed(1)}s`));
 }
 /**
- * Extract the server's Retry-After hint in milliseconds, or null if absent.
- * The API surfaces it as a body field (`retryAfter`, seconds) on 429s
- * (see lib/errors.ts) and may also send a Retry-After header; we honor both.
+ * Wrap an idempotent single-shot read (GET search/get/list/recall) or a
+ * naturally idempotent write (DELETE — deleting an already-deleted id is a
+ * no-op). Retries 429 and transient 5xx (502/503/504/408). Do NOT use this for
+ * named-memory PUT: it is a version bump that is only idempotent when
+ * expectedHeadId is supplied, and the CLI/SDK never supply it — use retryWrite.
  */
-function getRetryAfterMs(error) {
-    const data = error?.data ?? error?.response?.data ?? {};
-    const secs = data?.retryAfter ?? data?.retry_after;
-    if (typeof secs === 'number' && Number.isFinite(secs) && secs >= 0) {
-        return Math.round(secs * 1000);
-    }
-    const headers = error?.headers;
-    let headerVal;
-    if (headers) {
-        if (typeof headers.get === 'function') {
-            headerVal = headers.get('retry-after') ?? headers.get('Retry-After');
-        }
-        else {
-            headerVal = headers['retry-after'] ?? headers['Retry-After'];
-        }
-    }
-    if (headerVal) {
-        const n = parseInt(String(headerVal), 10);
-        if (Number.isFinite(n) && n >= 0)
-            return n * 1000;
-    }
-    return null;
+function retryRead(fn) {
+    return (0, retry_1.withSingleShotRetry)(fn, {
+        idempotent: true,
+        sleep: retry_1.sleep,
+        maxRetries: retry_1.SINGLE_SHOT_MAX_RETRIES,
+        onRetry: emitRetryNotice,
+    });
 }
-/** Promise-based sleep. Extracted so tests can inject a no-op/spy. */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Wrap a non-idempotent single-shot write (plain POST create, non-CAS update).
+ * Retries ONLY 429 (server rejected before processing — no duplicate risk);
+ * a transient 5xx is NOT auto-retried because the write may already have landed.
+ */
+function retryWrite(fn) {
+    return (0, retry_1.withSingleShotRetry)(fn, {
+        idempotent: false,
+        sleep: retry_1.sleep,
+        maxRetries: retry_1.SINGLE_SHOT_MAX_RETRIES,
+        onRetry: emitRetryNotice,
+    });
 }
 /**
  * Delete a single page, retrying on 429 up to `maxRetries` times. Honors the
@@ -556,8 +561,8 @@ async function bulkDeleteWithRetry(ids, deps) {
             return await deps.deleteFn(ids);
         }
         catch (error) {
-            if (isRateLimitError(error) && attempt < maxRetries) {
-                const waitMs = getRetryAfterMs(error) ?? defaultRetryMs * (attempt + 1);
+            if ((0, retry_1.isRateLimitError)(error) && attempt < maxRetries) {
+                const waitMs = (0, retry_1.getRetryAfterMs)(error) ?? defaultRetryMs * (attempt + 1);
                 deps.onRateLimited?.(waitMs);
                 await deps.sleep(waitMs);
                 attempt++;
@@ -737,7 +742,7 @@ async function handleBatchDelete(rawIds, options, mode) {
     try {
         const result = await runBulkDeletePaged(resolvedIds, {
             deleteFn: bulkDeleteViaSdk,
-            sleep,
+            sleep: retry_1.sleep,
             onPage: (i, total) => {
                 if (total > 1 && !jsonMode) {
                     spinner.text = `Deleting page ${i + 1} of ${total}...`;
@@ -841,19 +846,9 @@ exports.BATCH_CREATE_ALLOWED_KEYS = new Set([
     'outcome',
     'distill',
 ]);
-/** True when an error is an HTTP 503 (service unavailable — transient). */
-function isServiceUnavailableError(error) {
-    const status = error?.status ?? error?.statusCode ?? error?.response?.status;
-    return status === 503;
-}
 /** True when a create should be retried: 429 (rate limited) or 503 (transient). */
 function isRetryableCreateError(error) {
-    return isRateLimitError(error) || isServiceUnavailableError(error);
-}
-/** True when an error is an HTTP 402 (quota / payment required). */
-function isQuotaError(error) {
-    const status = error?.status ?? error?.statusCode ?? error?.response?.status;
-    return status === 402;
+    return (0, retry_1.isRateLimitError)(error) || (0, retry_1.isServiceUnavailableError)(error);
 }
 /**
  * Parse and validate one JSONL line into a createMemory body.
@@ -990,10 +985,10 @@ async function batchCreateWithRetry(data, deps) {
             return await deps.createFn(data);
         }
         catch (error) {
-            if (isQuotaError(error))
+            if ((0, retry_1.isQuotaError)(error))
                 throw error;
             if (isRetryableCreateError(error) && attempt < maxRetries) {
-                const waitMs = getRetryAfterMs(error) ?? defaultRetryMs * (attempt + 1);
+                const waitMs = (0, retry_1.getRetryAfterMs)(error) ?? defaultRetryMs * (attempt + 1);
                 deps.onRateLimited?.(waitMs);
                 await deps.sleep(waitMs);
                 attempt++;
@@ -1087,7 +1082,7 @@ async function runBatchCreate(items, deps) {
                 }
                 catch (error) {
                     summary.failed++;
-                    if (isQuotaError(error)) {
+                    if ((0, retry_1.isQuotaError)(error)) {
                         // Quota exhausted — pointless to keep hammering. Stop pulling new
                         // lines; in-flight workers finish, remaining lines are not-attempted.
                         stopped = true;
@@ -1253,7 +1248,7 @@ async function handleStreamingCreate(maxStdinBytes = exports.BATCH_CREATE_MAX_ST
     const claudeSessionId = claudeSession?.sessionId || undefined;
     const summary = await runBatchCreate(items, {
         createFn: (data) => createOneViaSdk(claudeSessionId ? { ...data, claudeSessionId } : data),
-        sleep,
+        sleep: retry_1.sleep,
         concurrency,
         onResult: (r) => {
             // Pure JSONL on stdout — the ONLY stdout write on this path. A broken pipe
@@ -1319,7 +1314,7 @@ function registerMemoriesCommands(program) {
             // Named memories filter — fetch and filter client-side
             if (options.named) {
                 const spinner = (0, spinner_1.createSpinner)('Fetching named memories...', options.format).start();
-                const namedResponse = await (0, api_client_1.getSdk)().memories.listMemories({ limit: 100, offset: 0 });
+                const namedResponse = await retryRead(() => (0, api_client_1.getSdk)().memories.listMemories({ limit: 100, offset: 0 }));
                 const namedMemories = (namedResponse.data?.data || []).filter((m) => m.name);
                 spinner.succeed(`Found ${namedMemories.length} named memories`);
                 if (options.format === 'table' || !options.format) {
@@ -1420,7 +1415,7 @@ function registerMemoriesCommands(program) {
                     .filter((t) => t.length > 0)
                     .join(',');
             }
-            const response = await (0, api_client_1.getSdk)().memories.listMemories(listParams);
+            const response = await retryRead(() => (0, api_client_1.getSdk)().memories.listMemories(listParams));
             const result = response.data;
             spinner.succeed(`Found ${result?.data?.length || 0} memories`);
             // Format for table display
@@ -1479,9 +1474,9 @@ function registerMemoriesCommands(program) {
             // Named memory lookup — short-circuits the entire ID-based flow
             if (options.name) {
                 const spinner = (0, spinner_1.createSpinner)('Fetching named memory...', options.format).start();
-                const response = await (0, api_client_1.getSdk)().memories.getMemoryByName(options.name, {
+                const response = await retryRead(() => (0, api_client_1.getSdk)().memories.getMemoryByName(options.name, {
                     detail: options.detail || 'standard',
-                });
+                }));
                 const memory = response.data?.data;
                 if (!memory) {
                     spinner.fail(`No memory found with name '${options.name}'`);
@@ -1521,9 +1516,9 @@ function registerMemoriesCommands(program) {
                 if (isNamedKey) {
                     const spinner = (0, spinner_1.createSpinner)('Fetching named memory...', options.format).start();
                     try {
-                        const response = await (0, api_client_1.getSdk)().memories.getMemoryByName(singleId, {
+                        const response = await retryRead(() => (0, api_client_1.getSdk)().memories.getMemoryByName(singleId, {
                             detail: options.detail || 'standard',
-                        });
+                        }));
                         const memory = response.data?.data;
                         if (!memory) {
                             spinner.fail(`No memory found with name '${singleId}'`);
@@ -1552,11 +1547,11 @@ function registerMemoriesCommands(program) {
                 let resolvedMemory = null;
                 if (isShortId) {
                     const spinner = (0, spinner_1.createSpinner)('Searching for matching memory...', options.format).start();
-                    const listResponse = await (0, api_client_1.getSdk)().memories.listMemories({
+                    const listResponse = await retryRead(() => (0, api_client_1.getSdk)().memories.listMemories({
                         limit: 10,
                         offset: 0,
                         idPrefix: singleId,
-                    });
+                    }));
                     const matches = listResponse.data?.data || [];
                     if (matches.length === 0) {
                         spinner.fail(`No memory found with ID prefix: ${singleId}`);
@@ -1597,9 +1592,9 @@ function registerMemoriesCommands(program) {
                         });
                     }
                     else {
-                        const response = await (0, api_client_1.getSdk)().memories.getMemoryById(memoryId, {
+                        const response = await retryRead(() => (0, api_client_1.getSdk)().memories.getMemoryById(memoryId, {
                             detail,
-                        });
+                        }));
                         const memory = response.data?.data;
                         printMemoryWithDetail(memory, options.format, {
                             includeVectors: !!options.includeVectors,
@@ -1789,7 +1784,12 @@ function registerMemoriesCommands(program) {
             let response;
             let upserted = false;
             try {
-                response = await (0, api_client_1.getSdk)().memories.createMemory(memoryData);
+                // Single create is non-idempotent → retryWrite (429-only: a rejected
+                // 429 never reached processing, so a retry cannot duplicate the create;
+                // a transient 5xx is NOT retried here to avoid a duplicate). A 409
+                // (named already exists) is not retryable and falls through to the
+                // auto-upsert branch below unchanged.
+                response = await retryWrite(() => (0, api_client_1.getSdk)().memories.createMemory(memoryData));
             }
             catch (createError) {
                 // 409 = named memory already exists → auto-upsert via updateNamedMemory
@@ -1811,7 +1811,15 @@ function registerMemoriesCommands(program) {
                     // intentionally NOT forwarded here: it is applied uniformly for both the
                     // create and upsert paths by the createMemoryRelationship call below, so
                     // forwarding it in the body too would create a duplicate SUPERSEDES edge.
-                    response = await (0, api_client_1.getSdk)().memories.updateNamedMemory(memoryData.name, {
+                    // Named update is NOT idempotent on this path: the CLI/SDK never
+                    // supply expectedHeadId, so PUT /named/:name does an UNCONDITIONAL
+                    // version bump (buildNamedVersionBumpCypher). retryWrite → 429-only:
+                    // the named-write gate acquires the permit BEFORE this.write, so a
+                    // 429 is pre-write and safe to retry; a 5xx is ambiguous (the bump
+                    // may already have committed — e.g. Kong 504 after Neo4j commits)
+                    // and MUST NOT be retried, or it silently creates a second identical
+                    // version (memory-history corruption).
+                    response = await retryWrite(() => (0, api_client_1.getSdk)().memories.updateNamedMemory(memoryData.name, {
                         content: memoryData.content,
                         ...(options.memoryType && { memoryType: options.memoryType }),
                         ...(memoryData.topics && { topics: memoryData.topics }),
@@ -1825,7 +1833,7 @@ function registerMemoriesCommands(program) {
                             options.conversationId.toUpperCase() !== 'NEW' && {
                             conversationId: options.conversationId,
                         }),
-                    });
+                    }));
                     upserted = true;
                 }
                 else {
@@ -1839,7 +1847,9 @@ function registerMemoriesCommands(program) {
                 const version = meta?.version || 'new';
                 spinner.succeed(`Named memory '${memoryData.name}' updated (v${version}) via auto-upsert. ID: ${memory?.id}`);
                 if (meta?.previousVersionId) {
-                    console.log(chalk_1.default.gray(`Previous version: ${meta.previousVersionId}`));
+                    if (options.format !== 'json' && options.format !== 'yaml') {
+                        console.log(chalk_1.default.gray(`Previous version: ${meta.previousVersionId}`));
+                    }
                 }
             }
             else {
@@ -1848,7 +1858,9 @@ function registerMemoriesCommands(program) {
                     : 'Memory created with';
                 if (isNewConversation && meta?.conversationCreated) {
                     spinner.succeed(`New conversation created: ${meta.conversationId}\n${nameLabel} ID: ${memory?.id}`);
-                    console.log(chalk_1.default.gray(`\nSession ID: ${meta.sessionId}`));
+                    if (options.format !== 'json' && options.format !== 'yaml') {
+                        console.log(chalk_1.default.gray(`\nSession ID: ${meta.sessionId}`));
+                    }
                 }
                 else {
                     spinner.succeed(`${nameLabel} ID: ${memory?.id}`);
@@ -1858,18 +1870,20 @@ function registerMemoriesCommands(program) {
             if (options.supersedes && memory?.id) {
                 const relSpinner = (0, spinner_1.createSpinner)('Creating SUPERSEDES relationship...', options.format).start();
                 try {
-                    await (0, api_client_1.getSdk)().memories.createMemoryRelationship(memory.id, {
+                    await retryWrite(() => (0, api_client_1.getSdk)().memories.createMemoryRelationship(memory.id, {
                         targetMemoryId: options.supersedes,
                         type: 'SUPERSEDES',
                         confidence: 1.0,
                         reason: 'Created via --supersedes flag',
-                    });
+                    }));
                     relSpinner.succeed(`Relationship created: ${memory.id.substring(0, 8)}... SUPERSEDES ${options.supersedes.substring(0, 8)}...`);
                 }
                 catch (relError) {
                     relSpinner.fail(`Failed to create relationship: ${relError.message || 'Unknown error'}`);
-                    console.log(chalk_1.default.yellow('Memory was created successfully. You can manually create the relationship with:'));
-                    console.log(chalk_1.default.cyan(`  mx memories relationships create ${memory.id} --target ${options.supersedes} --type SUPERSEDES`));
+                    if (options.format !== 'json' && options.format !== 'yaml') {
+                        console.log(chalk_1.default.yellow('Memory was created successfully. You can manually create the relationship with:'));
+                        console.log(chalk_1.default.cyan(`  mx memories relationships create ${memory.id} --target ${options.supersedes} --type SUPERSEDES`));
+                    }
                 }
             }
             (0, formatters_1.printOutput)(memory, options.format);
@@ -1928,7 +1942,7 @@ function registerMemoriesCommands(program) {
                 }
                 updates.name = options.assignName;
                 const spinner = (0, spinner_1.createSpinner)('Assigning name...', options.format).start();
-                const response = await (0, api_client_1.getSdk)().memories.updateMemory(id, updates);
+                const response = await retryWrite(() => (0, api_client_1.getSdk)().memories.updateMemory(id, updates));
                 const memory = response.data?.data;
                 spinner.succeed(`Memory ${id} named '${options.assignName}'`);
                 (0, formatters_1.printOutput)(memory, options.format);
@@ -1939,15 +1953,15 @@ function registerMemoriesCommands(program) {
                 if (options.name) {
                     // Look up current memory by name, then update its name
                     const spinner = (0, spinner_1.createSpinner)('Renaming...', options.format).start();
-                    const getResponse = await (0, api_client_1.getSdk)().memories.getMemoryByName(options.name);
+                    const getResponse = await retryRead(() => (0, api_client_1.getSdk)().memories.getMemoryByName(options.name));
                     const currentMemory = getResponse.data?.data;
                     if (!currentMemory?.id) {
                         spinner.fail(`Named memory '${options.name}' not found`);
                         return;
                     }
-                    const response = await (0, api_client_1.getSdk)().memories.updateMemory(currentMemory.id, {
+                    const response = await retryWrite(() => (0, api_client_1.getSdk)().memories.updateMemory(currentMemory.id, {
                         name: options.rename,
-                    });
+                    }));
                     const memory = response.data?.data;
                     spinner.succeed(`Named memory '${options.name}' renamed to '${options.rename}'`);
                     (0, formatters_1.printOutput)(memory, options.format);
@@ -1956,7 +1970,7 @@ function registerMemoriesCommands(program) {
                 if (id) {
                     updates.name = options.rename;
                     const spinner = (0, spinner_1.createSpinner)('Renaming...', options.format).start();
-                    const response = await (0, api_client_1.getSdk)().memories.updateMemory(id, updates);
+                    const response = await retryWrite(() => (0, api_client_1.getSdk)().memories.updateMemory(id, updates));
                     const memory = response.data?.data;
                     spinner.succeed(`Memory ${id} renamed to '${options.rename}'`);
                     (0, formatters_1.printOutput)(memory, options.format);
@@ -1972,18 +1986,26 @@ function registerMemoriesCommands(program) {
             // Named memory update — creates new version
             if (options.name) {
                 const spinner = (0, spinner_1.createSpinner)('Creating new version...', options.format).start();
-                const response = await (0, api_client_1.getSdk)().memories.updateNamedMemory(options.name, updates);
+                // Named update is NOT idempotent without expectedHeadId (which the
+                // CLI/SDK never supply): PUT /named/:name unconditionally bumps the
+                // version. retryWrite → 429-only: the gate takes the permit before the
+                // write, so a 429 is pre-write and safe to retry; a 5xx is ambiguous
+                // (the bump may already have committed) and MUST NOT be retried, or it
+                // creates a second identical version (silent history corruption).
+                const response = await retryWrite(() => (0, api_client_1.getSdk)().memories.updateNamedMemory(options.name, updates));
                 const memory = response.data?.data;
                 const meta = response.data?.meta;
                 spinner.succeed(`Named memory '${options.name}' updated to v${meta?.version}`);
                 if (meta?.previousVersionId) {
-                    console.log(chalk_1.default.gray(`Previous version: ${meta.previousVersionId}`));
+                    if (options.format !== 'json' && options.format !== 'yaml') {
+                        console.log(chalk_1.default.gray(`Previous version: ${meta.previousVersionId}`));
+                    }
                 }
                 (0, formatters_1.printOutput)(memory, options.format);
                 return;
             }
             const spinner = (0, spinner_1.createSpinner)('Updating memory...', options.format).start();
-            const response = await (0, api_client_1.getSdk)().memories.updateMemory(id, updates);
+            const response = await retryWrite(() => (0, api_client_1.getSdk)().memories.updateMemory(id, updates));
             const memory = response.data?.data;
             spinner.succeed(`Memory ${id} updated successfully`);
             (0, formatters_1.printOutput)(memory, options.format);
@@ -2004,7 +2026,7 @@ function registerMemoriesCommands(program) {
         .action(async (name, options) => {
         try {
             const spinner = (0, spinner_1.createSpinner)('Fetching version history...', options.format).start();
-            const response = await (0, api_client_1.getSdk)().memories.getNamedMemoryHistory(name);
+            const response = await retryRead(() => (0, api_client_1.getSdk)().memories.getNamedMemoryHistory(name));
             const data = response.data;
             if (!data?.versions?.length) {
                 spinner.fail(`No memory found with name '${name}'`);
@@ -2205,7 +2227,9 @@ function registerMemoriesCommands(program) {
                 }
             }
             const spinner = (0, spinner_1.createSpinner)('Deleting memory...', 'table').start();
-            await (0, api_client_1.getSdk)().memories.deleteMemory(id);
+            // DELETE is idempotent (deleting an already-deleted id is a no-op), so a
+            // transient 5xx is retry-safe as well as a 429.
+            await retryRead(() => (0, api_client_1.getSdk)().memories.deleteMemory(id));
             // Record this deletion in the cross-process guard file so the next
             // invocation's threshold check reflects it.
             if (isNonInteractive) {
@@ -2426,7 +2450,7 @@ function registerMemoriesCommands(program) {
                 searchRequest.order = options.order;
             }
             // Use GET endpoint for better performance (Issue #79)
-            const response = await (0, api_client_1.getSdk)().memories.searchMemoriesGet(searchRequest);
+            const response = await retryRead(() => (0, api_client_1.getSdk)().memories.searchMemoriesGet(searchRequest));
             const searchData = response.data;
             // Normalize: API may return flat objects or {memory, score} wrappers.
             // Ensure consistent {memory, score, matchedVia} shape for display code.
@@ -2844,19 +2868,19 @@ async function handleMemoryDiscovery(memoryId, options) {
         const sdk = (0, api_client_1.getSdk)();
         if (options.similar) {
             discoveryType = 'similar';
-            const response = await sdk.memories.getSimilarMemories(memoryId, { limit: options.limit });
+            const response = await retryRead(() => sdk.memories.getSimilarMemories(memoryId, { limit: options.limit }));
             result = response.data;
         }
         else if (options.conversation) {
             discoveryType = 'conversation';
-            const response = await sdk.memories.getConversationMemories(memoryId, {
+            const response = await retryRead(() => sdk.memories.getConversationMemories(memoryId, {
                 limit: options.limit,
-            });
+            }));
             result = response.data;
         }
         else if (options.related) {
             discoveryType = 'related';
-            const response = await sdk.memories.getRelatedMemories(memoryId, { limit: options.limit });
+            const response = await retryRead(() => sdk.memories.getRelatedMemories(memoryId, { limit: options.limit }));
             result = response.data;
         }
         else {
@@ -2957,9 +2981,9 @@ function registerMemoryRelationshipCommands(memories) {
                 return;
             }
             const spinner = (0, spinner_1.createSpinner)('Fetching relationships...', options.format).start();
-            const response = await (0, api_client_1.getSdk)().memories.getMemoryRelationships(id, {
+            const response = await retryRead(() => (0, api_client_1.getSdk)().memories.getMemoryRelationships(id, {
                 direction: options.direction,
-            });
+            }));
             const result = response.data;
             spinner.succeed(`Found ${result?.data?.length || 0} relationships`);
             if (options.format === 'table' || !options.format) {
@@ -3065,7 +3089,7 @@ function registerMemoryRelationshipCommands(memories) {
                 };
             }
             const spinner = (0, spinner_1.createSpinner)('Creating relationship...', options.format).start();
-            const response = await (0, api_client_1.getSdk)().memories.createMemoryRelationship(id, relationshipData);
+            const response = await retryWrite(() => (0, api_client_1.getSdk)().memories.createMemoryRelationship(id, relationshipData));
             const relationship = response.data?.data;
             spinner.succeed(`Relationship created: ${id} ${relationship?.type} ${relationshipData.targetMemoryId}`);
             (0, formatters_1.printOutput)(relationship, options.format);
@@ -3108,7 +3132,7 @@ function registerMemoryRelationshipCommands(memories) {
             }
             // Non-interactive without --force: auto-confirm single delete
             const spinner = (0, spinner_1.createSpinner)('Deleting relationship...', 'table').start();
-            await (0, api_client_1.getSdk)().memories.deleteMemoryRelationship(id, relationshipId);
+            await retryRead(() => (0, api_client_1.getSdk)().memories.deleteMemoryRelationship(id, relationshipId));
             spinner.succeed(`Relationship ${relationshipId} deleted successfully`);
         }
         catch (error) {
@@ -3136,7 +3160,7 @@ function registerMemoryTimelineCommand(memories) {
             const before = parseInt(options.before, 10);
             const after = parseInt(options.after, 10);
             const spinner = (0, spinner_1.createSpinner)('Fetching timeline context...', options.format).start();
-            const response = await (0, api_client_1.getSdk)().memories.getMemoryTimeline(id, { before, after });
+            const response = await retryRead(() => (0, api_client_1.getSdk)().memories.getMemoryTimeline(id, { before, after }));
             const result = response.data;
             spinner.succeed('Timeline context retrieved');
             if (options.format === 'table' || !options.format) {
@@ -3199,12 +3223,14 @@ function registerDetectRelationshipsCommand(memories) {
             const spinner = (0, spinner_1.createSpinner)(options.autoCreate
                 ? 'Detecting and creating relationships...'
                 : 'Detecting relationships...', options.format).start();
-            const response = await (0, api_client_1.getSdk)().memories.detectMemoryRelationships(id, {
+            // detect with --auto-create writes relationship edges, so it is
+            // non-idempotent → retryWrite (429-only) to avoid duplicate edges on 5xx.
+            const response = await retryWrite(() => (0, api_client_1.getSdk)().memories.detectMemoryRelationships(id, {
                 body: {
                     autoCreate: options.autoCreate || false,
                     minConfidence,
                 },
-            });
+            }));
             const result = response.data;
             const suggestions = result?.data || [];
             spinner.succeed(`Found ${suggestions.length} potential relationships`);
@@ -3344,7 +3370,7 @@ function registerDigestCommand(memories) {
                 sdk.config.timeoutMs = RECALL_MAX_MS;
             let response;
             try {
-                response = await sdk.memories.generateMemoryDigest(body);
+                response = await retryRead(() => sdk.memories.generateMemoryDigest(body));
             }
             finally {
                 if (sdk.config)
@@ -3433,7 +3459,7 @@ function registerStatusCommand(memories) {
                 sdk.config.timeoutMs = 180000;
             let response;
             try {
-                response = await sdk.memories.generateMemoryDigest(body);
+                response = await retryRead(() => sdk.memories.generateMemoryDigest(body));
             }
             finally {
                 if (sdk.config)
@@ -3579,7 +3605,7 @@ function registerRecapCommand(memories) {
                 };
                 if (excludeTopicsParam)
                     searchRequest.excludeTopics = excludeTopicsParam;
-                const response = await (0, api_client_1.getSdk)().memories.searchMemoriesGet(searchRequest);
+                const response = await retryRead(() => (0, api_client_1.getSdk)().memories.searchMemoriesGet(searchRequest));
                 // Normalize: API may return flat objects or {memory, score} wrappers.
                 results = (response.data?.data || []).map((r) => r.memory ? r : { memory: r, score: r.score, matchedVia: r.matchedVia });
             }
@@ -3595,7 +3621,7 @@ function registerRecapCommand(memories) {
                 };
                 if (excludeTopicsParam)
                     listRequest.excludeTopics = excludeTopicsParam;
-                const response = await (0, api_client_1.getSdk)().memories.listMemories(listRequest);
+                const response = await retryRead(() => (0, api_client_1.getSdk)().memories.listMemories(listRequest));
                 // Wrap in search-result shape expected by groupByConversation / displayRecap
                 results = (response.data?.data || []).map((m) => ({ memory: m }));
             }
@@ -3833,7 +3859,7 @@ function registerBuildContextCommand(memories) {
                 body.files = options.files;
             }
             const sdk = (0, api_client_1.getSdk)();
-            const response = await sdk.memories.buildContext(body);
+            const response = await retryRead(() => sdk.memories.buildContext(body));
             const data = response?.data || response;
             if (!data) {
                 spinner.fail('No response data received');