mlx-bun 0.0.5 → 0.0.7

package/src/cli.ts

@@ -17,6 +17,7 @@ import pkg from "../package.json" with { type: "json" };
 import { renderHelp } from "./tui";
 import { isSupportedModelRecord } from "./model/support";
 import { perfKernelEnabled } from "./model/fused-decode-kernel";
+import type { JobEvent } from "./jobs/types";
 
 const argv = process.argv.slice(2);
 // The appliance path: naked `mlx-bun` (or only options, e.g.
@@ -39,6 +40,8 @@ Commands:
   fit        Will a model fit this machine? Memory + speed assessment
   scan       Re-index the Hugging Face cache
   harness    Connect your own pi install to the local mlx-bun server
+  train      Fine-tune a LoRA adapter (SFT / DPO / ORPO) on your data
+  memory     Set up + manage your local AI's personal wiki memory
   benchmark  Measure decode/prefill speed of OUR stack on this machine
   evals      Show recent benchmark runs (all stacks)
   help       Show help for a command (also: mlx-bun <command> --help)
@@ -51,6 +54,7 @@ Examples:
   mlx-bun                          # download (first run) + serve + open the chat UI
   mlx-bun pi                       # start (download if needed) and chat with an agent
   mlx-bun serve 12B                # serve the 12B; status page at http://localhost:8090/
+  mlx-bun train e4b --data ./prefs # ORPO LoRA fine-tune on {prompt,chosen,rejected} data
   mlx-bun get mlx-community/gemma-4-12B-it-OptiQ-4bit`;
 
 const SERVER_FLAGS = `Server options:
@@ -235,9 +239,84 @@ Options:
 
 Table view: when, model, bench kind, KV mode, decode tok/s, TTFT,
 peak memory, commit. Runs are written by ./benchmark.sh.`,
+
+  train: `mlx-bun train — fine-tune a LoRA adapter on your data
+
+Usage: mlx-bun train <model> --data <dir> [options]
+
+  <model>              Model to fine-tune (query or snapshot path; auto-picks
+                       the default model if omitted)
+
+Data: <dir> must contain train.jsonl (+ optional valid.jsonl). Rows are
+  {prompt, chosen, rejected} for dpo/orpo, or {messages|text} for sft.
+
+Options:
+  --data <dir>         Dataset dir with train.jsonl  (required)
+  --method <m>         sft | dpo | orpo  [default: orpo]
+  --adapter <dir>      Output adapter dir
+                       [default: ~/.cache/mlx-bun/mlx-bun-finetunes/<method>-<model>]
+  --iters <n>          Training iterations  [default: 100]
+  --lr <f>             Learning rate  [default: orpo 1e-5 · dpo 5e-5 · sft 2e-4]
+  --rank <n>           LoRA rank  [default: orpo 16 · else 8]
+  --scale <f>          LoRA scale  [default: orpo 2.0 · else 1.0]
+  --seq <n>            Max sequence length  [default: gemma 8192 · else 4096]
+  --batch <n>          Batch size  [default: 1]
+  --lambda <f>         ORPO odds-ratio weight  [default: 0.1]
+  --seg <n>            Layers per segment (segmented backward; orpo default 2)
+  --save-every <n>     Crash-safe mountable checkpoint every n steps
+  --resume <dir>       Warm-start LoRA weights from a checkpoint/adapter dir
+  --no-flash           Disable the flash-CCE Metal head (use the MLX fused head)
+  --no-prefix          Disable prefix-sharing (two-forward branches)
+  --no-segment         Disable the segmented backward (hold all activations)
+  --dry-run            Inspect the dataset + print the resolved plan, don't train
+
+ORPO defaults run the full stack: the [M,vocab]-free flash-CCE head +
+prefix-sharing + segmented backward (each falls back + logs if a row's
+preconditions aren't met). Gemma/e4b sets its required training env flags
+automatically. Adapters are mountable directly (mlx-bun serve --adapter).
+Run long jobs detached from your own shell:  nohup mlx-bun train … &`,
+  memory: `mlx-bun memory — your local AI's personal wiki
+
+Usage: mlx-bun memory <subcommand>
+
+A local, durable memory for the assistant: a wiki of Markdown articles
+(~/.mlx-bun/wiki) it reads to remember your projects, people, and history
+across sessions. It's yours — git-tracked, editable in any tool (Obsidian
+opens it as a vault), and it never leaves the machine. A read-only Reference/
+folder symlinks mlx-bun's own docs into memory on day one. Once set up, it
+loads automatically into every \`mlx-bun pi\` and \`mlx-bun serve\` session.
+
+Subcommands:
+  init, setup        Create the wiki + walk through setup (idempotent);
+                     offers to import an existing vault and install the
+                     nightly synthesis job
+  status             Path, article count, git + schedule state
+  open, browse [article]
+                     Open the wiki, or a specific article, in Obsidian
+                     (falls back to Finder / the default Markdown app)
+  list               List article titles + read-only Reference docs
+  search <query>     Search articles from the terminal
+  toc <article>      Print an article's headings + anchors
+  section <article> <anchor>
+                     Print one article section
+  links <article>    Show resolved outbound + inbound wikilinks
+  read <article>     Print an article (stem, e.g. Archie_Project)
+  synthesize         Run the synthesis pipeline now (--since, --model,
+                     --dry-run). STUBBED — a no-op until M1 lands.
+  schedule           Install the nightly launchd job (--at HH:MM [03:00])
+  unschedule         Remove the nightly launchd job
+
+The read path is live: the assistant reads a wiki you set up by hand or
+import during \`memory init\`. Ask the assistant to "open my memory" or run
+\`mlx-bun memory open\` to browse it in Obsidian/Finder, or
+\`mlx-bun memory open <article>\` to jump to a specific page. Synthesis
+(conversations → articles) is stubbed; scheduling is real, so the nightly
+job is wired and ready and starts producing articles the moment synthesis
+lands.`,
 };
 
 HELP.bench = HELP.benchmark!;
+HELP.setup = HELP.memory!;
 
 function printHelp(topic?: string): never {
   if (topic && HELP[topic]) console.log(renderHelp(HELP[topic]));
@@ -368,6 +447,63 @@ function openChatUi(url: string, hostPort: string): void {
 /** Server/runtime flags shared by every mode that loads a model
  *  (serve, pi). Env levers are set here so they're in place before the
  *  generate/compiled-decode modules read them. */
+/** Resolve the decode ROUTE: a tier alias (--l1/--l2/--l3) sets the whole route,
+ *  and an explicit per-fork flag (--perf-kernel/--kv-quant/…) overrides the alias.
+ *  The tier IS the intent; the forks are the escape hatch. Sets the decode env
+ *  levers and returns the kv-quant mode. See docs/design/parity-tier-dag.md.
+ *  Each tier is a GUARANTEE about which reference you reproduce bit-for-bit:
+ *    --l1  bit-for-bit IDENTICAL to mlx-lm    — drop-in replacement for mlx-lm
+ *    --l2  bit-for-bit IDENTICAL to mlx-optiq — drop-in replacement for mlx-optiq.
+ *          optiq SHIPS the fused quantized decode (the quant-KV goldens track
+ *          perf-kernel ON), so L2 turns it ON — not the unfused reference.
+ *    --l3  best performance, NO bit-exact guarantee — correct, but gated by KL +
+ *          tests, because mlx-optiq has no analogy for what L3 does.
+ *  L2 ⊂ L3 (L3 = L2 + compiled). L1 is a separate target (bf16, unfused). */
+function applyDecodeRoute(): { kvQuant?: "off" | "config" | number } {
+  const onOff = (name: string): boolean | null => {
+    const v = opt(name); if (v == null) return null;
+    if (v === "on" || v === "1" || v === "true") return true;
+    if (v === "off" || v === "0" || v === "false") return false;
+    console.error(`--${name} expects on|off (got "${v}")`); process.exit(1);
+  };
+  type Preset = { kv: "off" | "config"; perf: boolean; fusedSdpa: boolean; compiled: boolean; fusedDecode: boolean };
+  const TIERS: Record<string, Preset> = {
+    // A tier is the GUARANTEE; within it we default to the FAST kernel that still
+    // holds it, and expose the slow one as an opt-in. compiled-decode is BIT-EXACT
+    // with uncompiled (compiled-decode.test: on==off) → free speed, so it's ON in
+    // EVERY tier (--compiled-decode off is the slow, same-tier opt-in). perf-kernel
+    // + fused-sdpa match OPTIQ (not the unfused reference; fused-sdpa.test) and are
+    // quantized-KV only → they're the L2 bridge, no-ops on L1's bf16. NOTE: for the
+    // DECODE path L2 == L3 — every decode kernel matches mlx-lm OR optiq. L3's real
+    // territory is the no-oracle FEATURES (HLG sampler, expert offload, batched
+    // mixed-precision) gated by KL+tests, which live off this decode axis.
+    l1: { kv: "off",    perf: false, fusedSdpa: false, compiled: true, fusedDecode: false }, // = mlx-lm bit-for-bit (bf16)
+    l2: { kv: "config", perf: true,  fusedSdpa: true,  compiled: true, fusedDecode: false }, // = mlx-optiq bit-for-bit
+    l3: { kv: "config", perf: true,  fusedSdpa: true,  compiled: true, fusedDecode: false }, // best perf (decode == L2 today)
+  };
+  const tier = flag("l1") ? "l1" : flag("l2") ? "l2" : flag("l3") ? "l3" : null;
+  const p = tier ? TIERS[tier]! : null;
+  const pick = (name: string, base: boolean | undefined): boolean | null => {
+    const ex = onOff(name); return ex !== null ? ex : (base ?? null); // explicit flag wins, else tier preset
+  };
+  const set = (env: string, val: boolean | null, invert = false) => {
+    if (val !== null) process.env[env] = (invert ? !val : val) ? "1" : "0";
+  };
+  set("MLX_BUN_COMPILED_DECODE", pick("compiled-decode", p?.compiled));
+  set("MLX_BUN_PERF_KERNEL", pick("perf-kernel", p?.perf));
+  set("MLX_BUN_FUSED_DECODE", pick("fused-decode", p?.fusedDecode));
+  set("MLX_BUN_NO_FUSED_SDPA", pick("fused-sdpa", p?.fusedSdpa), true); // inverted env
+  const kv = opt("kv-quant"); // explicit --kv-quant overrides the tier
+  if (kv === "off") return { kvQuant: "off" };
+  if (kv === "config") return { kvQuant: "config" };
+  if (kv) {
+    const bits = Number(kv);
+    if (![4, 8].includes(bits)) { console.error(`--kv-quant expects config|off|4|8 (got "${kv}")`); process.exit(1); }
+    return { kvQuant: bits };
+  }
+  return p ? { kvQuant: p.kv } : {};
+}
+
 function serverRuntimeFlags(): { port: number; serverOptions: import("./server").ServerOptions } {
   const onOff = (name: string): boolean | null => {
     const v = opt(name);
@@ -377,21 +513,14 @@ function serverRuntimeFlags(): { port: number; serverOptions: import("./server")
     console.error(`--${name} expects on|off (got "${v}")`);
     process.exit(1);
   };
-  const cd = onOff("compiled-decode");
-  if (cd !== null) process.env.MLX_BUN_COMPILED_DECODE = cd ? "1" : "0";
-  const pk = onOff("perf-kernel");
-  if (pk !== null) process.env.MLX_BUN_PERF_KERNEL = pk ? "1" : "0";
-  const fd = onOff("fused-decode");
-  if (fd !== null) process.env.MLX_BUN_FUSED_DECODE = fd ? "1" : "0";
-  const fs = onOff("fused-sdpa");
-  if (fs !== null) process.env.MLX_BUN_NO_FUSED_SDPA = fs ? "0" : "1"; // inverted env
+  const route = applyDecodeRoute(); // --l1/--l2/--l3 tier alias, with per-fork flags overriding
   if (flag("force-wire")) process.env.MLX_BUN_FORCE_WIRE = "1";
 
   const serverOptions: import("./server").ServerOptions = {};
   const budgetGB = Number(opt("memory-budget", "0"));
   if (budgetGB > 0) serverOptions.memoryBudgetBytes = budgetGB * 1e9;
-  const pcGB = Number(opt("prompt-cache", "0"));
-  if (pcGB > 0) serverOptions.promptCacheBytes = pcGB * 2 ** 30;
+  const pcRaw = opt("prompt-cache"); // null if absent; an explicit value (incl. 0) wins → `--prompt-cache 0` DISABLES the cache
+  if (pcRaw !== null) serverOptions.promptCacheBytes = Math.max(0, Number(pcRaw)) * 2 ** 30;
   // --batch N: max concurrent requests batched through the mlx-lm-parity
   // engine (N=1 = today's serial path). --decode-concurrency is accepted as
   // an mlx_lm.server-compatible alias (drop-in).
@@ -404,14 +533,7 @@ function serverRuntimeFlags(): { port: number; serverOptions: import("./server")
     }
     serverOptions.batch = n;
   }
-  const kv = opt("kv-quant");
-  if (kv === "off") serverOptions.kvQuant = "off";
-  else if (kv === "config") serverOptions.kvQuant = "config";
-  else if (kv) {
-    const bits = Number(kv);
-    if (![4, 8].includes(bits)) { console.error(`--kv-quant expects config|off|4|8 (got "${kv}")`); process.exit(1); }
-    serverOptions.kvQuant = bits;
-  }
+  if (route.kvQuant !== undefined) serverOptions.kvQuant = route.kvQuant;
   const host = opt("host");
   if (host) serverOptions.hostname = host;
   // Server-wide default for the chat template's enable_thinking variable
@@ -733,6 +855,34 @@ switch (cmd) {
     break;
   }
 
+  case "gen":
+  case "generate": {
+    // RAW generate — a direct one-shot entry point (no server, no chat UI). The
+    // three entry points (raw / OpenAI API / chat UI) differ only in how params
+    // are POPULATED; here every param is explicit. Decode-path levers mirror
+    // serve so you can pin the route (mlx-lm compat = --perf-kernel off
+    // --fused-sdpa off --compiled-decode off). KV uses the bf16 bit-exact path.
+    applyDecodeRoute(); // --l1/--l2/--l3 + per-fork overrides set the decode env levers (KV stays bf16 via generateText)
+
+    const prompt = opt("prompt") ?? positional(1);
+    if (!prompt) {
+      console.error('usage: mlx-bun generate [query] --prompt "…" [--raw] [--max-tokens N]');
+      console.error('       sampling:  --temperature N --top-p N --top-k N --seed N');
+      console.error('       decode path: --perf-kernel off --fused-sdpa off --compiled-decode off  (= mlx-lm compat)');
+      process.exit(1);
+    }
+    const { loadTaskModel, generateText } = await import("./eval/runner");
+    const tm = await loadTaskModel(positional(0) ?? opt("query") ?? "");
+    const num = (n: string): number | undefined => { const v = opt(n); return v == null ? undefined : Number(v); };
+    const text = await generateText(tm, prompt, {
+      maxTokens: Number(opt("max-tokens", "256")),
+      useChat: !flag("raw"),
+      sampler: { temperature: num("temperature"), topP: num("top-p"), topK: num("top-k"), seed: num("seed") },
+    });
+    process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+    break;
+  }
+
   case "bench":
   case "benchmark": {
     const { banner, step, box, style } = await import("./tui");
@@ -1070,6 +1220,489 @@ switch (cmd) {
     break;
   }
 
+  case "train": {
+    const { banner, step, box, style } = await import("./tui");
+    const query = positional(0) ?? opt("query");
+    const dataDir = opt("data");
+    if (!dataDir) {
+      console.error("usage: mlx-bun train <model> --data <dir>   (see: mlx-bun help train)");
+      process.exit(1);
+    }
+    if (!(await Bun.file(`${dataDir}/train.jsonl`).exists())) {
+      console.error(`no train.jsonl in ${dataDir}`);
+      process.exit(1);
+    }
+    const method = opt("method", "orpo")!;
+    if (method !== "sft" && method !== "dpo" && method !== "orpo") {
+      console.error(`--method must be sft | dpo | orpo (got "${method}")`);
+      process.exit(1);
+    }
+    const isOrpo = method === "orpo";
+    // Validated numeric flag: default if absent, hard-exit on a non-number.
+    const numFlag = (name: string, dflt: number): number => {
+      const v = opt(name);
+      if (v == null) return dflt;
+      const n = Number(v);
+      if (!Number.isFinite(n)) { console.error(`--${name} expects a number (got "${v}")`); process.exit(1); }
+      return n;
+    };
+
+    banner(pkg.version);
+    const sNative = step("native runtime");
+    await ensureNative(sNative);
+    sNative.done("native runtime ready");
+
+    const { m, picked } = await resolveModelAuto(query);
+
+    // Detect Gemma/e4b and set its required training env flags BEFORE the
+    // trainer is imported (perfKernelEnabled / fused-gelu read them lazily at
+    // forward time, so setting them here — like the launcher — takes effect).
+    const isGemma = (await Bun.file(`${m.path}/config.json`).text()).toLowerCase().includes("gemma");
+    if (isGemma) {
+      process.env.MLX_BUN_PERF_KERNEL ??= "0";
+      process.env.MLX_BUN_FUSED_GELU ??= "0";
+    }
+
+    const modelTag = isGemma ? "e4b" : "cpm5";
+    const adapter = opt("adapter") ?? `${process.env.HOME}/.cache/mlx-bun/mlx-bun-finetunes/${method}-${modelTag}`;
+    const iters = numFlag("iters", 100);
+    const seq = numFlag("seq", isGemma ? 8192 : 4096);
+    const seg = flag("no-segment") ? 0 : numFlag("seg", isOrpo ? 2 : 0);
+    const saveEvery = numFlag("save-every", 0);
+    const flashOn = !flag("no-flash");
+    const prefixOn = !flag("no-prefix");
+    const resume = opt("resume") ?? "";
+
+    // Build the snake_case submit record — the exact shape the server hands to
+    // the finetune job runner (src/train/job.ts parseConfig).
+    const cfg: Record<string, unknown> = {
+      model_dir: m.path,
+      data_dir: dataDir,
+      adapter_path: adapter,
+      method,
+      rank: numFlag("rank", isOrpo ? 16 : 8),
+      scale: numFlag("scale", isOrpo ? 2.0 : 1.0),
+      rank_scaling: "by_bits",
+      num_layers: -1,
+      iters,
+      learning_rate: numFlag("lr", isOrpo ? 1e-5 : method === "dpo" ? 5e-5 : 2e-4),
+      max_seq_length: seq,
+      batch_size: numFlag("batch", 1),
+      grad_accumulation_steps: numFlag("grad-accum", 1),
+      seed: numFlag("seed", 0),
+      steps_per_report: 1,
+      steps_per_eval: saveEvery > 0 ? saveEvery : 1_000_000,
+      save_checkpoints: saveEvery > 0,
+      segment_size: seg,
+      grad_clip_norm: numFlag("grad-clip", 1.0),
+      val_max_examples: numFlag("val-size", 256),
+      warm_start_adapter: resume,
+      ...(isOrpo ? {
+        orpo_lambda: numFlag("lambda", 0.1),
+        orpo_lr_schedule: "cosine",
+        orpo_warmup_iters: Math.min(10, Math.floor(iters / 10)),
+        orpo_chunk_size: 512,
+        orpo_flash_ce: flashOn,
+        orpo_fused_ce: !flashOn,
+        orpo_prefix_shared: prefixOn,
+      } : {}),
+    };
+
+    // Pre-flight: dataset counts + detected format (bail before loading the model).
+    const { inspectDataset } = await import("./train/job");
+    const ds = await inspectDataset(dataDir);
+    if (!ds.ok) { console.error(`dataset: ${ds.error}`); process.exit(1); }
+
+    const planLines = [
+      `${style.green("●")} ${style.bold(`train ${method}`)} ${style.dim(`· ${m.repoId}${picked ? " (auto-picked)" : ""}${isGemma ? " · e4b env set" : ""}`)}`,
+      "",
+      `data       ${style.bold(`${ds.n_train} train`)}${ds.n_valid ? ` · ${ds.n_valid} valid` : ""} ${style.dim(`· format ${ds.format}`)}`,
+      `loop       ${style.dim(`iters ${iters} · lr ${cfg.learning_rate} · rank ${cfg.rank} · scale ${cfg.scale} · seq ${seq} · batch ${cfg.batch_size}`)}`,
+    ];
+    if (isOrpo)
+      planLines.push(
+        `head       ${style.dim(flashOn ? "flash-CCE Metal ([M,vocab]-free)" : "MLX fused linear-CE")}`,
+        `stack      ${style.dim(`prefix-share ${prefixOn ? "on" : "off"} · segmented ${seg > 0 ? `${seg}/seg` : "off"} · λ ${cfg.orpo_lambda}`)}`,
+        `stability  ${style.dim(`grad-clip ${cfg.grad_clip_norm || "off"} · val-size ${cfg.val_max_examples}${(cfg.grad_accumulation_steps as number) > 1 ? ` · grad-accum ${cfg.grad_accumulation_steps} (eff batch ${(cfg.batch_size as number) * (cfg.grad_accumulation_steps as number)})` : ""}`)}`,
+      );
+    else planLines.push(`stack      ${style.dim(`segmented ${seg > 0 ? `${seg}/seg` : "off"}`)}`);
+    if (resume) planLines.push(`warm-start ${style.dim(`from ${resume} (weights only)`)}`);
+    if (saveEvery > 0) planLines.push(`checkpoint ${style.dim(`every ${saveEvery} steps`)}`);
+    planLines.push("", `adapter    ${style.dim(adapter)}`);
+    console.log();
+    box(planLines);
+    console.log();
+    console.log(`  ${style.dim("watch live (other tab):")} ${style.accent(`mlx-bun train-watch ${adapter}`)}`);
+    console.log();
+
+    if (flag("dry-run")) { console.log(`  ${style.dim("dry run — not training.")}`); break; }
+
+    // Run the finetune job runner IN-PROCESS (foreground), streaming metrics to
+    // the terminal — the same runner the server drives via submitSubprocess.
+    // Run long jobs detached from your own shell:  nohup mlx-bun train … &
+    const { finetuneRunner } = await import("./train/job");
+    const { peakMemory, resetPeakMemory } = await import("./mlx/ffi");
+    const losses: number[] = [];
+    const stepMs: number[] = [];
+    let lastStepT = Date.now();
+    resetPeakMemory();
+    const emit = (e: JobEvent) => {
+      if (e.type === "stage" && e.message) console.log(`  ${style.dim("·")} ${e.message}`);
+      else if (e.type === "metric" && e.kind === "train") {
+        const now = Date.now(); stepMs.push(now - lastStepT); lastStepT = now;
+        losses.push(e.loss);
+        const n = losses.length;
+        if (n <= 3 || n % 10 === 0)
+          console.log(`  step ${n}/${iters}: loss ${style.bold(e.loss.toFixed(4))} ${style.dim(`(${(stepMs[stepMs.length - 1]! / 1000).toFixed(1)}s/step · peak ${gb(peakMemory())})`)}`);
+      }
+    };
+    try {
+      await finetuneRunner(emit, cfg);
+    } catch (err) {
+      console.error(`\n  training failed: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    }
+    const finite = losses.every((l) => Number.isFinite(l));
+    const sorted = stepMs.slice(1).sort((a, b) => a - b);
+    const med = sorted[Math.floor(sorted.length / 2)] ?? stepMs[0] ?? 0;
+    console.log();
+    box([
+      `${style.green("●")} ${style.bold("training complete")} ${style.dim(`· ${losses.length} steps`)}`,
+      "",
+      `loss       ${style.bold(`${losses[0]?.toFixed(4) ?? "—"} → ${losses[losses.length - 1]?.toFixed(4) ?? "—"}`)}${finite ? "" : "  (NON-FINITE!)"}`,
+      `speed      ${style.dim(`${(med / 1000).toFixed(1)}s/step median · peak ${gb(peakMemory())}`)}`,
+      "",
+      `adapter    ${style.bold(adapter)}`,
+      `serve it   ${style.accent(`mlx-bun serve ${m.repoId} --adapter ${adapter}`)}`,
+    ]);
+    break;
+  }
+
+  case "train-watch": {
+    // Live mactop-style dashboard for a training run: tails <adapter>/metrics.jsonl.
+    const dir = positional(0) ?? opt("adapter")
+      ?? `${process.env.HOME}/.cache/mlx-bun/mlx-bun-finetunes/orpo-cpm5`;
+    const { runWatch } = await import("./train/watch");
+    await runWatch(dir);
+    break;
+  }
+
+  case "memory": {
+    const { style, box, step, banner } = await import("./tui");
+    const {
+      vaultRoot, vaultStatus, setupVault, importArticlesFrom, commitVault,
+      listMemoryDocuments, readArticle, resolveArticlePath, searchArticles,
+      parseToc, extractSection, getArticleLinks,
+    } = await import("./memory/vault");
+    const { installSchedule, removeSchedule, scheduleStatus, parseAt } = await import("./memory/schedule");
+    const root = vaultRoot();
+    const fmtAt = (a: { hour: number; minute: number }) => `${String(a.hour).padStart(2, "0")}:${String(a.minute).padStart(2, "0")}`;
+    const openMemoryTarget = async (targetPath = root): Promise<"obsidian" | "fallback"> => {
+      // For articles, Obsidian's URL handler opens the exact file inside the
+      // vault. For the vault root, `open -a Obsidian <folder>` opens the folder
+      // as a vault. Both fall back to macOS `open` if Obsidian is unavailable.
+      if (targetPath !== root) {
+        const uri = `obsidian://open?path=${encodeURIComponent(targetPath)}`;
+        const byUri = Bun.spawn(["open", uri], { stdout: "ignore", stderr: "ignore" });
+        if ((await byUri.exited) === 0) return "obsidian";
+      } else {
+        const byApp = Bun.spawn(["open", "-a", "Obsidian", root], { stdout: "ignore", stderr: "ignore" });
+        if ((await byApp.exited) === 0) return "obsidian";
+      }
+      const fallback = Bun.spawn(["open", targetPath], { stdout: "ignore", stderr: "ignore" });
+      await fallback.exited;
+      return "fallback";
+    };
+
+    // Words after `memory`, minus flags: [subcommand, ...query].
+    const words = argv.slice(1).filter((a) => !a.startsWith("-"));
+    const sub = (words[0] ?? "status").toLowerCase();
+    const rest = words.slice(1).join(" ").trim();
+
+    // TTY-only line prompt; in a non-interactive shell returns the default so
+    // the wizard degrades to a non-destructive no-op rather than hanging.
+    const ask = async (q: string, dflt = ""): Promise<string> => {
+      if (!process.stdin.isTTY) return dflt;
+      const { createInterface } = await import("node:readline/promises");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      try {
+        return ((await rl.question(q)).trim() || dflt);
+      } finally {
+        rl.close();
+      }
+    };
+    const confirmYN = async (q: string, defaultYes: boolean): Promise<boolean> => {
+      const a = (await ask(`${q} ${defaultYes ? "[Y/n]" : "[y/N]"} `)).toLowerCase();
+      if (!a) return defaultYes;
+      return a === "y" || a === "yes";
+    };
+
+    if (sub === "init" || sub === "setup") {
+      banner(pkg.version);
+      box([
+        `${style.accent("●")} ${style.bold("Personal memory for your local AI")}`,
+        "",
+        "A wiki of Markdown articles your local assistant reads to remember",
+        "your projects, people, and history across sessions. It's yours —",
+        `git-tracked at ${style.dim(root)}, editable in any tool, and it`,
+        "never leaves this machine.",
+      ]);
+      const sSetup = step("creating your wiki");
+      const res = await setupVault(root);
+      sSetup.done(res.alreadySetUp ? `already set up ${style.dim(`· ${root}`)}` : `wiki ready ${style.dim(`· ${root}`)}`);
+
+      // Offer to seed from an existing vault (e.g. a lucien ~/Dreaming) so the
+      // assistant has real content to read on day one, before synthesis exists.
+      const { homedir } = await import("node:os");
+      const { join } = await import("node:path");
+      const { readdir } = await import("node:fs/promises");
+      const seedRoot = await ask(
+        `\n  Seed from an existing wiki? Enter its path, or blank to skip ${style.dim(`[${join(homedir(), "Dreaming")}]`)}: `,
+        "",
+      );
+      if (seedRoot) {
+        const srcArticles = join(seedRoot.replace(/^~(?=$|[/\\])/, homedir()), "articles");
+        let count = 0;
+        try { count = (await readdir(srcArticles)).filter((n) => n.endsWith(".md")).length; } catch { count = 0; }
+        if (count === 0) {
+          console.log(style.dim(`  no articles found under ${srcArticles} — skipping import`));
+        } else if (await confirmYN(`  Import ${count} article(s) from ${srcArticles}?`, true)) {
+          const sImp = step(`importing ${count} article(s)`);
+          const imported = await importArticlesFrom(srcArticles, root);
+          await commitVault(root, `Import ${imported.length} article(s) from ${seedRoot}`);
+          sImp.done(`imported ${imported.length} article(s)`);
+        }
+      }
+
+      // Offer to install the nightly synthesis job (a launchd agent). The job
+      // itself is a no-op today (synthesis is stubbed), but installing the
+      // schedule now means it starts producing articles the moment M1 lands —
+      // no reconfiguration. Persistent action → TTY-only, defaults to no.
+      let scheduled: string | null = null;
+      console.log(style.dim(
+        "\n  Synthesis (turning your conversations into articles) isn't implemented yet,\n" +
+        "  but you can install the nightly job now so it runs automatically once it is.",
+      ));
+      if (await confirmYN("  Install the nightly synthesis job (runs in the background)?", false)) {
+        const atRaw = await ask(`    At what time? 24h HH:MM ${style.dim("[03:00]")}: `, "03:00");
+        const sSched = step(`installing nightly job at ${fmtAt(parseAt(atRaw))}`);
+        const r = await installSchedule({ at: atRaw });
+        scheduled = fmtAt(r.at);
+        sSched.done(
+          r.loaded
+            ? `nightly job installed ${style.dim(`· ${scheduled} · ${r.plistPath}`)}`
+            : `plist written ${style.dim(`· ${r.plistPath} · launchctl load failed (load it manually)`)}`,
+        );
+      }
+
+      const st = await vaultStatus(root);
+      console.log();
+      box([
+        `${style.green("●")} ${style.bold("memory is set up")} ${style.dim(`· ${st.articleCount} article(s) · ${st.referenceCount} reference doc(s)`)}`,
+        "",
+        `chat now   ${style.accent("mlx-bun pi")} ${style.dim("— the assistant now reads your memory automatically")}`,
+        `inspect    ${style.accent("mlx-bun memory status")} ${style.dim("·")} ${style.accent("mlx-bun memory search <q>")}`,
+        `browse     ${style.dim(`open ${root} in Obsidian, or any editor`)}`,
+        scheduled
+          ? `nightly    ${style.green("scheduled")} ${style.dim(`· ${scheduled} daily · mlx-bun memory unschedule to undo`)}`
+          : `nightly    ${style.dim("not scheduled · mlx-bun memory schedule to set it up")}`,
+        "",
+        style.dim("Synthesis (conversations → articles) is stubbed for now; the scheduled"),
+        style.dim("job no-ops until it lands. Add or import articles to read meanwhile."),
+      ]);
+      break;
+    }
+
+    if (sub === "status") {
+      const st = await vaultStatus(root);
+      if (!st.exists) {
+        console.log(`no memory wiki yet at ${style.dim(root)}`);
+        console.log(`set one up:  ${style.accent("mlx-bun memory init")}`);
+        break;
+      }
+      const sched = await scheduleStatus();
+      console.log();
+      box([
+        `${style.bold("memory")} ${style.dim(`· ${root}`)}`,
+        "",
+        `articles   ${style.bold(String(st.articleCount))}`,
+        `reference  ${style.bold(String(st.referenceCount))} ${style.dim("read-only docs")}`,
+        `git        ${st.isGitRepo ? style.green("tracked") : style.dim("not a git repo")}`,
+        `synthesis  ${style.dim("stubbed (M1) — not implemented yet")}`,
+        `last run   ${style.dim("not available yet")}`,
+        `nightly    ${
+          sched.installed
+            ? `${sched.loaded ? style.green("scheduled") : style.accent("installed (not loaded)")} ${style.dim(`· ${sched.plistPath}`)}`
+            : style.dim("not scheduled · mlx-bun memory schedule")
+        }`,
+        st.recentArticles.length
+          ? `recent    ${st.recentArticles.slice(0, 5).map((r) => r.article).join(", ")}`
+          : `recent    ${style.dim("none")}`,
+      ]);
+      break;
+    }
+
+    if (sub === "open" || sub === "browse") {
+      const st = await vaultStatus(root);
+      if (!st.exists) {
+        console.log(`no memory wiki yet at ${style.dim(root)}`);
+        console.log(`set one up:  ${style.accent("mlx-bun memory init")}`);
+        break;
+      }
+      let targetPath = root;
+      let label = "memory";
+      if (rest) {
+        try {
+          targetPath = await resolveArticlePath(root, rest);
+          label = rest.endsWith(".md") ? rest.slice(0, -3) : rest;
+        } catch (err) {
+          console.error(err instanceof Error ? err.message : String(err));
+          console.error(`try:  ${style.accent(`mlx-bun memory search ${rest}`)}`);
+          process.exit(1);
+        }
+      }
+      const where = await openMemoryTarget(targetPath);
+      console.log(
+        where === "obsidian"
+          ? `opened ${label} in Obsidian: ${targetPath}`
+          : `opened ${label}: ${targetPath}`,
+      );
+      break;
+    }
+
+    if (sub === "synthesize") {
+      const { runSynthesis } = await import("./memory/pipeline");
+      const dryRun = flag("dry-run");
+      console.log();
+      const summary = await runSynthesis(
+        { since: opt("since") ?? undefined, model: opt("model") ?? undefined, dryRun },
+        (e) => {
+          if (e.type === "stage") console.log(`  ${style.dim("·")} ${e.message}`);
+          else console.log(`  ${e.message}`);
+        },
+      );
+      console.log(style.dim(`\n  ${summary.note}`));
+      break;
+    }
+
+    if (sub === "schedule") {
+      const atRaw = opt("at") ?? "03:00";
+      const r = await installSchedule({ at: atRaw });
+      console.log();
+      box([
+        r.loaded
+          ? `${style.green("●")} ${style.bold("nightly synthesis scheduled")} ${style.dim(`· ${fmtAt(r.at)} daily`)}`
+          : `${style.accent("●")} ${style.bold("plist written, but launchctl load failed")}`,
+        "",
+        `plist      ${style.dim(r.plistPath)}`,
+        `runs       ${style.dim("mlx-bun memory synthesize (a no-op until synthesis lands)")}`,
+        `undo       ${style.accent("mlx-bun memory unschedule")}`,
+      ]);
+      break;
+    }
+
+    if (sub === "unschedule") {
+      const removed = await removeSchedule();
+      console.log(removed ? "nightly synthesis job removed" : "no nightly job was installed");
+      break;
+    }
+
+    if (sub === "list") {
+      const docs = await listMemoryDocuments(root);
+      if (docs.length === 0) { console.log("no articles or reference docs yet"); break; }
+      for (const s of docs) console.log(`  ${s}`);
+      const refs = docs.filter((s) => s.startsWith("Reference/")).length;
+      console.log(style.dim(`\n  ${docs.length - refs} article(s), ${refs} read-only reference doc(s)`));
+      break;
+    }
+
+    if (sub === "search") {
+      if (!rest) { console.error("usage: mlx-bun memory search <query>"); process.exit(1); }
+      const { summaries, hits } = await searchArticles(root, rest, { limit: 12 });
+      if (summaries.length === 0) { console.log(`no articles match "${rest}"`); break; }
+      console.log();
+      for (const s of summaries.slice(0, 15)) {
+        const terms = s.matched_terms?.length ? style.dim(` [${s.matched_terms.join(", ")}]`) : "";
+        console.log(`  ${style.bold(s.article)} ${style.dim(`· ${s.occurrences} hit(s)`)}${terms}`);
+      }
+      if (hits.length) {
+        console.log(style.dim("\n  sample lines:"));
+        for (const h of hits.slice(0, 6)) {
+          const where = h.anchor ? `${h.article}#${h.anchor}` : h.article;
+          console.log(`  ${style.dim(`${where}:${h.line}`)}  ${h.excerpt}`);
+        }
+      }
+      console.log(style.dim(`\n  read one:  mlx-bun memory read ${summaries[0]!.article}`));
+      break;
+    }
+
+    if (sub === "toc") {
+      if (!rest) { console.error("usage: mlx-bun memory toc <article>"); process.exit(1); }
+      try {
+        const { content } = await readArticle(root, rest);
+        const toc = parseToc(content);
+        if (toc.length === 0) { console.log("no headings"); break; }
+        for (const h of toc) console.log(`${"  ".repeat(Math.max(0, h.depth - 1))}- ${h.title}  ${style.dim(`#${h.anchor}`)}`);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        console.error(`try:  ${style.accent(`mlx-bun memory search ${rest}`)}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    if (sub === "section") {
+      const [article, anchorRaw] = words.slice(1);
+      const anchor = anchorRaw?.replace(/^#/, "");
+      if (!article || !anchor) { console.error("usage: mlx-bun memory section <article> <anchor>"); process.exit(1); }
+      try {
+        const { content } = await readArticle(root, article);
+        const section = extractSection(content, anchor);
+        if (!section) { console.error(`no section #${anchor} in ${article}`); console.error(`try:  ${style.accent(`mlx-bun memory toc ${article}`)}`); process.exit(1); }
+        console.log(section);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        console.error(`try:  ${style.accent(`mlx-bun memory search ${article}`)}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    if (sub === "links") {
+      if (!rest) { console.error("usage: mlx-bun memory links <article>"); process.exit(1); }
+      try {
+        const { outbound, inbound } = await getArticleLinks(root, rest);
+        console.log(`${style.bold("outbound")}:`);
+        console.log(outbound.length ? outbound.map((s) => `  ${s}`).join("\n") : "  (none)");
+        console.log(`\n${style.bold("inbound")}:`);
+        console.log(inbound.length ? inbound.map((s) => `  ${s}`).join("\n") : "  (none)");
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        console.error(`try:  ${style.accent(`mlx-bun memory search ${rest}`)}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    if (sub === "read") {
+      if (!rest) { console.error("usage: mlx-bun memory read <article>"); process.exit(1); }
+      try {
+        const { content } = await readArticle(root, rest);
+        console.log(content);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        console.error(`try:  ${style.accent(`mlx-bun memory search ${rest}`)}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+
+    console.error(`unknown: mlx-bun memory ${sub}`);
+    printHelp("memory");
+    break;
+  }
+
   default:
     printHelp(cmd);
 }