@memnexus-ai/cli 1.7.217 → 1.7.219

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.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,12 +45,17 @@ 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.isRetryableCreateError = isRetryableCreateError;
+exports.parseJsonlCreateLine = parseJsonlCreateLine;
+exports.resolveCreateConcurrency = resolveCreateConcurrency;
+exports.batchCreateWithRetry = batchCreateWithRetry;
+exports.runBatchCreate = runBatchCreate;
+exports.buildBatchCreateItems = buildBatchCreateItems;
+exports.readStdinRaw = readStdinRaw;
+exports.handleStreamingCreate = handleStreamingCreate;
 exports.registerMemoriesCommands = registerMemoriesCommands;
 exports.registerMemoryRelationshipCommands = registerMemoryRelationshipCommands;
 exports.registerMemoryTimelineCommand = registerMemoryTimelineCommand;
@@ -64,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");
@@ -260,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}"`);
@@ -382,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`);
@@ -496,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
@@ -546,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++;
@@ -727,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}...`;
@@ -779,6 +794,496 @@ async function handleBatchDelete(rawIds, options, mode) {
         throw error;
     }
 }
+// ── Streaming batch create (PO CLI-latency directive, iteration 2) ────────────
+// Scripted single-creates pay node's cold-start (0.3-0.5s) PLUS one HTTP round
+// trip PER memory: 53 memories ≈ 1-2 min end-to-end. There is deliberately NO
+// batch-create server endpoint yet (deferred — an L-effort item on the triage
+// plan). This is a CLIENT-SIDE fix only: ONE process reads JSONL from stdin and
+// fires N createMemory calls with connection reuse and bounded concurrency,
+// targeting ~20-40s for the same 53 memories. Each item is still one HTTP
+// request against the server; we cut the cold-start tax and serialize latency,
+// not the request count.
+/** Default parallel creates when MX_CREATE_CONCURRENCY is unset. */
+exports.BATCH_CREATE_DEFAULT_CONCURRENCY = 4;
+/** Clamp band for MX_CREATE_CONCURRENCY (mirrors the RECALL_MAX_MS clamp convention). */
+exports.BATCH_CREATE_CONCURRENCY_MIN = 1;
+exports.BATCH_CREATE_CONCURRENCY_MAX = 8;
+/** Max retries per item on 429/503 before giving up (mirrors batch delete). */
+exports.BATCH_CREATE_MAX_RETRIES = 3;
+/**
+ * Hard cap on total stdin bytes read (128 MB) before we abort. A mistaken
+ * multi-GB pipe would otherwise accumulate unbounded and OOM the CLI
+ * (CWE-400, client-side); we fail closed with a clear error instead. Matches
+ * the 64KB-class file-bound precedent from v3.89a — generous enough that any
+ * legitimate JSONL batch fits, small enough that a runaway pipe stops early.
+ */
+exports.BATCH_CREATE_MAX_STDIN_BYTES = 128 * 1024 * 1024;
+/**
+ * Hard cap on a single JSONL line length (1 MB). A line longer than this is
+ * rejected as a per-line parse error BEFORE JSON.parse (bounding parser memory),
+ * preserving the one-result-line-per-input-line contract instead of aborting
+ * the whole stream. A single memory body never legitimately approaches 1 MB.
+ */
+exports.BATCH_CREATE_MAX_LINE_BYTES = 1024 * 1024;
+/**
+ * Fields a JSONL create line may carry. Mirrors the single-create option map
+ * (createMemory body). Any other key is rejected per-line — a typo like
+ * "contnet" fails that line loudly instead of silently dropping the content.
+ * `supersedes` is intentionally excluded: it is a separate relationship call in
+ * single-create, out of scope for the streaming path (noted in the PR).
+ */
+exports.BATCH_CREATE_ALLOWED_KEYS = new Set([
+    'content',
+    'name',
+    'topics',
+    'conversationId',
+    'memoryType',
+    'context',
+    'role',
+    'importance',
+    'codeContext',
+    'taskId',
+    'outcome',
+    'distill',
+]);
+/** True when a create should be retried: 429 (rate limited) or 503 (transient). */
+function isRetryableCreateError(error) {
+    return (0, retry_1.isRateLimitError)(error) || (0, retry_1.isServiceUnavailableError)(error);
+}
+/**
+ * Parse and validate one JSONL line into a createMemory body.
+ *
+ * Returns `{ data }` on success or `{ error }` on failure. Rejects: non-JSON,
+ * non-object lines, unknown keys, and a missing/blank `content`. `conversationId`
+ * defaults to "NEW" (mirrors single-create). `topics` accepts a JSON array or a
+ * comma-separated string; `importance` accepts a number or numeric string.
+ */
+function parseJsonlCreateLine(raw) {
+    // Bound per-line memory BEFORE JSON.parse: reject an oversized line as a
+    // per-line error so the stream keeps going (one result line per input line).
+    const lineBytes = Buffer.byteLength(raw, 'utf8');
+    if (lineBytes > exports.BATCH_CREATE_MAX_LINE_BYTES) {
+        return {
+            error: `line too large (${lineBytes} bytes > ${exports.BATCH_CREATE_MAX_LINE_BYTES} byte limit)`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { error: 'invalid JSON' };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { error: 'line must be a JSON object' };
+    }
+    const obj = parsed;
+    const unknown = Object.keys(obj).filter((k) => !exports.BATCH_CREATE_ALLOWED_KEYS.has(k));
+    if (unknown.length > 0) {
+        return { error: `unknown field(s): ${unknown.join(', ')}` };
+    }
+    if (typeof obj.content !== 'string' || obj.content.trim().length === 0) {
+        return { error: 'content is required and must be a non-empty string' };
+    }
+    if ('codeContext' in obj && obj.codeContext !== undefined) {
+        const cc = obj.codeContext;
+        if (cc === null || typeof cc !== 'object' || Array.isArray(cc)) {
+            return { error: 'codeContext must be a JSON object' };
+        }
+    }
+    let topics;
+    if ('topics' in obj && obj.topics !== undefined) {
+        if (Array.isArray(obj.topics)) {
+            topics = obj.topics.map((t) => String(t));
+        }
+        else if (typeof obj.topics === 'string') {
+            topics = obj.topics
+                .split(',')
+                .map((t) => t.trim())
+                .filter((t) => t.length > 0);
+        }
+        else {
+            return { error: 'topics must be an array or comma-separated string' };
+        }
+    }
+    let importance;
+    if ('importance' in obj && obj.importance !== undefined) {
+        const n = typeof obj.importance === 'string' ? parseFloat(obj.importance) : obj.importance;
+        if (typeof n !== 'number' || !Number.isFinite(n)) {
+            return { error: 'importance must be a number between 0 and 1' };
+        }
+        importance = n;
+    }
+    const conversationId = typeof obj.conversationId === 'string' && obj.conversationId.trim().length > 0
+        ? obj.conversationId
+        : 'NEW';
+    const data = {
+        conversationId,
+        content: obj.content,
+    };
+    if (obj.name !== undefined)
+        data.name = obj.name;
+    if (topics !== undefined)
+        data.topics = topics;
+    // Defaults parity with single-create (memories.ts create action): role
+    // defaults to 'user'; memoryType defaults by name-presence (named memories are
+    // 'procedural', otherwise 'episodic'). Applying them here means batch and
+    // single create produce identical memories for identical input fields.
+    data.role = obj.role !== undefined ? obj.role : 'user';
+    data.memoryType =
+        obj.memoryType !== undefined
+            ? obj.memoryType
+            : obj.name !== undefined
+                ? 'procedural'
+                : 'episodic';
+    if (obj.context !== undefined)
+        data.context = obj.context;
+    if (importance !== undefined)
+        data.importance = importance;
+    if (obj.codeContext !== undefined)
+        data.codeContext = obj.codeContext;
+    if (obj.taskId !== undefined)
+        data.taskId = obj.taskId;
+    if (obj.outcome !== undefined)
+        data.outcome = obj.outcome;
+    if (obj.distill !== undefined)
+        data.distill = obj.distill;
+    return { data };
+}
+/**
+ * Resolve the create concurrency from MX_CREATE_CONCURRENCY, clamped to
+ * [MIN, MAX]. Out-of-band values are clamped to the nearest bound (non-numeric →
+ * default) and warn once on stderr — mirrors the RECALL_MAX_MS clamp convention
+ * (import-time band + single WARN).
+ */
+function resolveCreateConcurrency(raw, warn = (m) => console.warn(chalk_1.default.yellow(m))) {
+    if (raw === undefined || raw === '')
+        return exports.BATCH_CREATE_DEFAULT_CONCURRENCY;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n)) {
+        warn(`MX_CREATE_CONCURRENCY=${raw} is not a number, using default ${exports.BATCH_CREATE_DEFAULT_CONCURRENCY}`);
+        return exports.BATCH_CREATE_DEFAULT_CONCURRENCY;
+    }
+    if (n < exports.BATCH_CREATE_CONCURRENCY_MIN || n > exports.BATCH_CREATE_CONCURRENCY_MAX) {
+        const clamped = Math.max(exports.BATCH_CREATE_CONCURRENCY_MIN, Math.min(exports.BATCH_CREATE_CONCURRENCY_MAX, n));
+        warn(`MX_CREATE_CONCURRENCY=${raw} out of range [${exports.BATCH_CREATE_CONCURRENCY_MIN},${exports.BATCH_CREATE_CONCURRENCY_MAX}], clamped to ${clamped}`);
+        return clamped;
+    }
+    return n;
+}
+/**
+ * Create one memory, retrying on 429/503 up to `maxRetries` times, honoring the
+ * server's Retry-After hint (falls back to linear backoff). A 402 (quota) is
+ * NOT retried — it rethrows immediately so the pool can stop the stream early.
+ */
+async function batchCreateWithRetry(data, deps) {
+    const maxRetries = deps.maxRetries ?? exports.BATCH_CREATE_MAX_RETRIES;
+    const defaultRetryMs = deps.defaultRetryMs ?? 1000;
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await deps.createFn(data);
+        }
+        catch (error) {
+            if ((0, retry_1.isQuotaError)(error))
+                throw error;
+            if (isRetryableCreateError(error) && attempt < maxRetries) {
+                const waitMs = (0, retry_1.getRetryAfterMs)(error) ?? defaultRetryMs * (attempt + 1);
+                deps.onRateLimited?.(waitMs);
+                await deps.sleep(waitMs);
+                attempt++;
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Run `items` through a bounded-concurrency worker pool. Each valid line becomes
+ * one createMemory call with per-item 429/503 retry; each parse-error line
+ * resolves immediately as a failure. Results are emitted via `onResult` in
+ * COMPLETION order, with the input line number attached.
+ *
+ * A 402 (quota exhausted) STOPS the stream early: the offending line is reported
+ * as failed, no new lines are pulled, in-flight creates drain, and every
+ * not-yet-pulled line is emitted as a not-attempted failure in line order. This
+ * mirrors the batch-delete early-abort contract — the caller always gets one
+ * result line per input line, never a dropped report (the v3.90 lesson).
+ *
+ * If the sink (`onResult`, i.e. stdout) THROWS — the classic `... | head`
+ * EPIPE — that is a distinct terminal condition, NOT a create failure. The
+ * create for that line already succeeded and is counted; we stop pulling new
+ * work, emit nothing further to the dead sink, and set `outputClosed` so the
+ * caller can print an accounting to stderr (which is still open). `emit` is
+ * guarded so a sink throw can never be misread as a create failure (which would
+ * duplicate the line) nor propagate uncaught.
+ */
+async function runBatchCreate(items, deps) {
+    const concurrency = Math.max(1, deps.concurrency);
+    const summary = {
+        total: items.length,
+        ok: 0,
+        failed: 0,
+        notAttempted: 0,
+        quotaStopped: false,
+        rateLimitedCount: 0,
+        delivered: 0,
+        outputClosed: false,
+    };
+    const attempted = new Array(items.length).fill(false);
+    let next = 0;
+    let stopped = false;
+    let sinkClosed = false;
+    // Guarded sink write: never throws. A sink failure (EPIPE) becomes a terminal
+    // stop condition instead of an exception that the create catch would misread.
+    const emit = (r) => {
+        if (sinkClosed)
+            return;
+        try {
+            deps.onResult?.(r);
+            summary.delivered++;
+        }
+        catch {
+            sinkClosed = true;
+            stopped = true;
+            summary.outputClosed = true;
+        }
+    };
+    async function worker() {
+        for (;;) {
+            if (stopped)
+                return;
+            const i = next++;
+            if (i >= items.length)
+                return;
+            attempted[i] = true;
+            const item = items[i];
+            // Compute the result BEFORE emitting. The success emit lives OUTSIDE the
+            // create try/catch so a sink throw on a successful line is handled by the
+            // guarded emit — never caught here as a bogus create failure.
+            let result;
+            if (item.parseError) {
+                summary.failed++;
+                result = { line: item.line, ok: false, error: item.parseError, code: 'PARSE_ERROR' };
+            }
+            else {
+                try {
+                    const res = await batchCreateWithRetry(item.data, {
+                        createFn: deps.createFn,
+                        sleep: deps.sleep,
+                        maxRetries: deps.maxRetries,
+                        defaultRetryMs: deps.defaultRetryMs,
+                        onRateLimited: () => {
+                            summary.rateLimitedCount++;
+                        },
+                    });
+                    summary.ok++;
+                    result = { line: item.line, ok: true, id: res?.id };
+                }
+                catch (error) {
+                    summary.failed++;
+                    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;
+                        summary.quotaStopped = true;
+                        emit({ line: item.line, ok: false, error: errorMessage(error), code: 'QUOTA_STOPPED' });
+                        return;
+                    }
+                    result = {
+                        line: item.line,
+                        ok: false,
+                        error: errorMessage(error),
+                        code: 'CREATE_FAILED',
+                    };
+                }
+            }
+            emit(result);
+            // If the sink died on that write, stop cleanly (no further stdout writes).
+            if (stopped)
+                return;
+        }
+    }
+    const workerCount = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    // Lines the pool never pulled (only possible after an early stop — quota or
+    // sink close) are reported as not-attempted in line order — one result line
+    // per input line. Under a sink close these emits are no-ops (sink is dead) but
+    // are still COUNTED so the stderr accounting is complete.
+    if (stopped) {
+        const closed = summary.outputClosed;
+        const code = closed ? 'OUTPUT_CLOSED' : 'NOT_ATTEMPTED';
+        const reason = closed
+            ? 'not attempted (output pipe closed early)'
+            : 'not attempted (stream stopped after quota exhaustion)';
+        for (let i = 0; i < items.length; i++) {
+            if (!attempted[i]) {
+                summary.notAttempted++;
+                emit({ line: items[i].line, ok: false, error: reason, code });
+            }
+        }
+    }
+    return summary;
+}
+/**
+ * Split raw stdin into non-blank lines, each paired with its 1-based input line
+ * number and parse result. Blank/whitespace-only lines are skipped silently (a
+ * trailing newline is normal in JSONL and is not an error).
+ */
+function buildBatchCreateItems(raw) {
+    const items = [];
+    const lines = raw.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim().length === 0)
+            continue;
+        const parsed = parseJsonlCreateLine(line);
+        items.push({ line: i + 1, data: parsed.data, parseError: parsed.error });
+    }
+    return items;
+}
+/** Thrown by readStdinRaw when accumulated stdin exceeds the byte cap. */
+class StdinTooLargeError extends Error {
+    bytes;
+    limit;
+    code = 'STDIN_TOO_LARGE';
+    constructor(bytes, limit) {
+        super(`stdin exceeded the ${limit}-byte limit (read > ${bytes} bytes)`);
+        this.bytes = bytes;
+        this.limit = limit;
+        this.name = 'StdinTooLargeError';
+    }
+}
+exports.StdinTooLargeError = StdinTooLargeError;
+/**
+ * Read all of stdin as a single string (no whitespace splitting), aborting once
+ * accumulated bytes exceed `maxBytes`. Without the cap a mistaken multi-GB pipe
+ * would grow `data` unbounded and OOM the CLI (CWE-400); we fail closed with a
+ * StdinTooLargeError instead. `maxBytes` is injectable for tests; production
+ * uses BATCH_CREATE_MAX_STDIN_BYTES.
+ */
+async function readStdinRaw(maxBytes = exports.BATCH_CREATE_MAX_STDIN_BYTES) {
+    if (process.stdin.isTTY)
+        return '';
+    return new Promise((resolve, reject) => {
+        let data = '';
+        let bytes = 0;
+        let aborted = false;
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('readable', () => {
+            if (aborted)
+                return;
+            let chunk;
+            while ((chunk = process.stdin.read()) !== null) {
+                bytes += Buffer.byteLength(chunk, 'utf8');
+                if (bytes > maxBytes) {
+                    aborted = true;
+                    // Stop draining and tear down the stream rather than keep buffering.
+                    if (typeof process.stdin.destroy === 'function') {
+                        process.stdin.destroy();
+                    }
+                    reject(new StdinTooLargeError(bytes, maxBytes));
+                    return;
+                }
+                data += chunk;
+            }
+        });
+        process.stdin.on('end', () => {
+            if (!aborted)
+                resolve(data);
+        });
+        process.stdin.on('error', () => {
+            if (!aborted)
+                resolve(data);
+        });
+    });
+}
+/** Issue one createMemory via the SDK and normalize the id out of the response. */
+async function createOneViaSdk(data) {
+    // The global fetch wrapper in index.ts attaches X-MX-Client AND the v3.89a
+    // per-project attribution headers, so batch-created memories carry attribution
+    // automatically — no per-item work here. codeContext supplied on a line still
+    // rides in the request body untouched.
+    const response = await (0, api_client_1.getSdk)().memories.createMemory(data);
+    const memory = response?.data?.data ?? response?.data;
+    return { id: memory?.id };
+}
+/**
+ * `mx memories create --stdin-jsonl`: streaming batch create. Reads JSONL from
+ * stdin (one createMemory body per line), fires bounded-concurrency creates, and
+ * writes one JSONL result line per input line to stdout in completion order.
+ *
+ * stdout is PURE JSONL: the ONLY writes are the per-line result objects below.
+ * Every status/warning/summary goes to stderr. There is no session-preamble
+ * printer on this command path, so the #4176-class stdout-pollution bug cannot
+ * occur here — but the split is enforced deliberately so a future preamble can
+ * never leak into the machine-readable stream.
+ */
+async function handleStreamingCreate(maxStdinBytes = exports.BATCH_CREATE_MAX_STDIN_BYTES) {
+    const concurrency = resolveCreateConcurrency(process.env.MX_CREATE_CONCURRENCY);
+    let raw;
+    try {
+        raw = await readStdinRaw(maxStdinBytes);
+    }
+    catch (error) {
+        if (error?.code === 'STDIN_TOO_LARGE') {
+            // Fail closed: nothing was attempted, so nothing is emitted on stdout.
+            console.error(chalk_1.default.red(`Error: stdin exceeded the ${maxStdinBytes}-byte limit; aborted before creating anything. ` +
+                'Split the input into smaller batches.'));
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+    const items = buildBatchCreateItems(raw);
+    if (items.length === 0) {
+        console.error(chalk_1.default.red('Error: --stdin-jsonl expects one JSON object per line on stdin; got none.'));
+        process.exitCode = 1;
+        return;
+    }
+    // Auto-attach the Claude Code session id to every line, exactly as single
+    // create does (create action: readSessionContext() when in AI-agent context),
+    // so batch-created memories group into the same conversation/session.
+    const claudeSession = config_1.config.isAIAgentContext() ? (0, session_reader_1.readSessionContext)() : undefined;
+    const claudeSessionId = claudeSession?.sessionId || undefined;
+    const summary = await runBatchCreate(items, {
+        createFn: (data) => createOneViaSdk(claudeSessionId ? { ...data, claudeSessionId } : data),
+        sleep: retry_1.sleep,
+        concurrency,
+        onResult: (r) => {
+            // Pure JSONL on stdout — the ONLY stdout write on this path. A broken pipe
+            // (reader closed early) throws EPIPE here; runBatchCreate's guarded emit
+            // catches it and stops cleanly (summary.outputClosed), handled below.
+            process.stdout.write(JSON.stringify(r) + '\n');
+        },
+    });
+    // Terminal: the reader closed stdout early (EPIPE). stdout is dead but stderr
+    // is still open — write a distinct accounting so the caller knows exactly how
+    // many results were delivered vs. created vs. never attempted. Creates are not
+    // idempotent, so this reconciliation matters.
+    if (summary.outputClosed) {
+        console.error(chalk_1.default.red(`Error: output pipe closed early — ${summary.delivered} result line(s) delivered, ` +
+            `${summary.ok} created, ${summary.notAttempted} not attempted. ` +
+            'Reconcile against the delivered result lines before re-running (creates are not idempotent).'));
+        process.exitCode = 1;
+        return;
+    }
+    // Summary + any early-stop notice go to stderr so stdout stays pure JSONL.
+    if (summary.quotaStopped) {
+        console.error(chalk_1.default.red(`Stopped early on quota (402): ${summary.ok} created, ${summary.failed} failed, ${summary.notAttempted} not attempted.`));
+    }
+    else {
+        const rl = summary.rateLimitedCount > 0
+            ? `, ${summary.rateLimitedCount} rate-limited retr${summary.rateLimitedCount === 1 ? 'y' : 'ies'}`
+            : '';
+        console.error(`Batch create: ${summary.ok} created, ${summary.failed} failed of ${summary.total}${rl} (concurrency ${concurrency}).`);
+    }
+    // Non-zero exit when anything failed or was not attempted, so scripts detect
+    // partial failure — partial results are still fully emitted above.
+    if (summary.failed > 0 || summary.notAttempted > 0) {
+        process.exitCode = 1;
+    }
+}
 /**
  * Register memory management commands
  * @param program - Commander program instance
@@ -809,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) {
@@ -910,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
@@ -969,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}'`);
@@ -1011,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}'`);
@@ -1042,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}`);
@@ -1087,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,
@@ -1132,9 +1637,27 @@ function registerMemoriesCommands(program) {
         .option('--outcome <outcome>', 'Task outcome: resolved | unresolved')
         .option('--distill', 'Request LLM distillation into structured 5-section notebook (Pro/Enterprise only)')
         .option('--interactive', 'Interactive mode')
+        .option('--stdin-jsonl', 'Streaming batch create: read JSONL from stdin (one createMemory object per line), ' +
+        'create with bounded concurrency (MX_CREATE_CONCURRENCY, default 4), and emit one ' +
+        'JSONL result line per input line on stdout ({line, ok, id?, error?, code?}). On ' +
+        'failure, code is one of PARSE_ERROR | CREATE_FAILED | QUOTA_STOPPED | NOT_ATTEMPTED | ' +
+        'OUTPUT_CLOSED. Exits non-zero if any line failed.')
         .option('--format <format>', 'Output format (json|table|yaml)')
         .action(async (options) => {
         try {
+            // Streaming batch create path. Mutually exclusive with the single-create
+            // content/interactive flags — the input is stdin JSONL, not CLI flags.
+            if (options.stdinJsonl) {
+                const conflicting = ['content', 'interactive', 'supersedes'].filter((k) => options[k]);
+                if (conflicting.length > 0) {
+                    console.error(chalk_1.default.red(`Error: --stdin-jsonl cannot be combined with --${conflicting.join(', --')}. ` +
+                        'Pass all fields as JSON per line on stdin instead.'));
+                    process.exitCode = 1;
+                    return;
+                }
+                await handleStreamingCreate();
+                return;
+            }
             // Build codeContext from --code-context JSON and/or convenience flags
             let codeContext;
             if (options.codeContext) {
@@ -1261,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
@@ -1283,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 }),
@@ -1297,7 +1833,7 @@ function registerMemoriesCommands(program) {
                             options.conversationId.toUpperCase() !== 'NEW' && {
                             conversationId: options.conversationId,
                         }),
-                    });
+                    }));
                     upserted = true;
                 }
                 else {
@@ -1330,12 +1866,12 @@ 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) {
@@ -1400,7 +1936,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);
@@ -1411,15 +1947,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);
@@ -1428,7 +1964,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);
@@ -1444,7 +1980,13 @@ 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}`);
@@ -1455,7 +1997,7 @@ function registerMemoriesCommands(program) {
                 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);
@@ -1476,7 +2018,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}'`);
@@ -1677,7 +2219,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) {
@@ -1898,7 +2442,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.
@@ -2316,19 +2860,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 {
@@ -2429,9 +2973,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) {
@@ -2537,7 +3081,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);
@@ -2580,7 +3124,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) {
@@ -2608,7 +3152,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) {
@@ -2671,12 +3215,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`);
@@ -2816,7 +3362,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)
@@ -2905,7 +3451,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)
@@ -3051,7 +3597,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 });
             }
@@ -3067,7 +3613,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 }));
             }
@@ -3305,7 +3851,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');