@memnexus-ai/cli 1.7.217 → 1.7.218

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.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;
@@ -51,6 +51,16 @@ 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;
+exports.runBatchCreate = runBatchCreate;
+exports.buildBatchCreateItems = buildBatchCreateItems;
+exports.readStdinRaw = readStdinRaw;
+exports.handleStreamingCreate = handleStreamingCreate;
 exports.registerMemoriesCommands = registerMemoriesCommands;
 exports.registerMemoryRelationshipCommands = registerMemoryRelationshipCommands;
 exports.registerMemoryTimelineCommand = registerMemoryTimelineCommand;
@@ -779,6 +789,506 @@ 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 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;
+}
+/**
+ * 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 (isQuotaError(error))
+                throw error;
+            if (isRetryableCreateError(error) && attempt < maxRetries) {
+                const waitMs = 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 (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,
+        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
@@ -1132,9 +1642,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) {