open-memex 0.4.0 → 0.4.1

package/README.md

@@ -1,5 +1,7 @@
 # open-memex
 
+> A shared organizational memory layer that helps people and AI capture, retain, and reuse institutional knowledge.
+
 [![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
 

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # open-memex
 
+> 共享组织记忆层，帮助人与 AI 捕获、沉淀并复用组织知识。
+
 [![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
 

package/dist/cli.js

@@ -223,11 +223,15 @@ Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict
 
 Flags:
   --from / --to   scope keys (default: current project → personal)
-  --dry-run       preview without moving anything
+  --dry-run       preview without moving anything (--to-v2 previews the legacy
+                  files in place, including per-file conversion plans)
   --on-conflict   newer (default), overwrite, or skip
   --to-v2         convert a legacy my-o-memory data dir to the v2 layout
 
 Always preview with --dry-run first; nothing moves without confirmation.
+On Windows, if another program holds the legacy folder open, the backup
+rename fails with an actionable message instead of a stack trace — close
+the program and re-run.
 
 Examples:
   open-memex migrate --dry-run
@@ -376,14 +380,21 @@ function parseFlags(argv) {
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a.startsWith("--")) {
-            const key = a.slice(2);
+            const raw = a.slice(2);
+            const eq = raw.indexOf("=");
+            if (eq >= 0) {
+                // D44: accept --key=value as well as --key value (issue #7 — the
+                // = form was silently misparsed before, dropping the flag).
+                out[raw.slice(0, eq)] = raw.slice(eq + 1);
+                continue;
+            }
             const val = argv[i + 1];
             if (val !== undefined && !val.startsWith("--")) {
-                out[key] = val;
+                out[raw] = val;
                 i++;
             }
             else {
-                out[key] = "true";
+                out[raw] = "true";
             }
         }
     }
@@ -486,7 +497,15 @@ async function main() {
     if (cmd === "migrate" && rest.includes("--to-v2")) {
         const flags = parseFlags(rest);
         const dryRun = flags["dry-run"] === "true";
-        const stats = migrateV2({ dryRun });
+        let stats;
+        try {
+            stats = migrateV2({ dryRun });
+        }
+        catch (err) {
+            // D44: actionable message, not a raw syscall stack (issue #7).
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
         console.log(`${dryRun ? "DRY RUN: " : ""}scanned ${stats.scanned} files: ` +
             `${stats.converted} to convert, ${stats.skippedV2} already v2`);
         for (const p of stats.plans) {
@@ -496,7 +515,9 @@ async function main() {
                 console.log(`  - ${c}`);
         }
         if (stats.legacyBackup) {
-            console.log(`\nlegacy my-o-memory data dir merged; backup kept at:\n  ${stats.legacyBackup}`);
+            console.log(dryRun
+                ? `\nDRY RUN: legacy my-o-memory data dir found — it would be merged and backed up at:\n  ${stats.legacyBackup}`
+                : `\nlegacy my-o-memory data dir merged; backup kept at:\n  ${stats.legacyBackup}`);
         }
         if (!dryRun && stats.converted > 0) {
             console.log(`\nindex schema will rebuild automatically on next run; ` +

package/dist/store/v2migrate.js

@@ -83,23 +83,45 @@ export function planConversion(filePath, memoriesRoot) {
     return { fm, body, fromPath: filePath, toPath, changes };
 }
 /**
- * Merge a legacy `my-o-memory` data root into the current `open-memex` root.
- * The old dir is renamed to a dated backup — never deleted. Returns the
- * backup path, or null when no legacy dir exists.
+ * Locate a legacy `my-o-memory` data root next to the current root.
+ * Pure lookup — no disk writes.
  */
-function migrateLegacyDataRoot(dryRun) {
+export function findLegacyDataRoot() {
     const { root } = paths();
     const legacy = path.join(path.dirname(root), "my-o-memory");
     if (!fs.existsSync(legacy) || !fs.statSync(legacy).isDirectory())
         return null;
+    return legacy;
+}
+/** Dated backup path for a legacy data root. Pure — no disk writes. */
+export function legacyBackupPath(legacy) {
     const stamp = new Date().toISOString().slice(0, 10);
-    const backup = `${legacy}.backup-${stamp}`;
-    if (!dryRun) {
-        const legacyMem = path.join(legacy, "memories");
-        if (fs.existsSync(legacyMem)) {
-            for (const entry of fs.readdirSync(legacyMem)) {
-                const src = path.join(legacyMem, entry);
-                const dst = path.join(root, "memories", entry);
+    return `${legacy}.backup-${stamp}`;
+}
+/**
+ * Merge a legacy `my-o-memory` data root into the current `open-memex` root.
+ * The old dir is renamed to a dated backup — never deleted.
+ * Failures throw an actionable Error (no raw syscall dump): on Windows the
+ * backup rename typically fails with EPERM when another program holds the
+ * folder open.
+ */
+function mergeLegacyDataRoot(legacy, backup) {
+    const { memories } = paths();
+    const fail = (where, err) => {
+        const code = err?.code;
+        throw new Error(`could not ${where} (${legacy})` +
+            (code ? ` [${code}]` : "") +
+            `. Another program may be holding the folder open (e.g. a running MCP server, editor, or antivirus). ` +
+            `Your memories are safe — nothing was deleted. Close the program and re-run ` +
+            `\`open-memex migrate --to-v2\`, or rename the folder to ${backup} yourself and re-run.`);
+    };
+    const legacyMem = path.join(legacy, "memories");
+    if (fs.existsSync(legacyMem)) {
+        fs.mkdirSync(memories, { recursive: true });
+        for (const entry of fs.readdirSync(legacyMem)) {
+            const src = path.join(legacyMem, entry);
+            const dst = path.join(memories, entry);
+            try {
                 if (!fs.existsSync(dst)) {
                     fs.renameSync(src, dst);
                 }
@@ -113,46 +135,73 @@ function migrateLegacyDataRoot(dryRun) {
                     }
                 }
             }
+            catch (err) {
+                fail(`move memories from the legacy data dir`, err);
+            }
         }
+    }
+    try {
         fs.renameSync(legacy, backup);
     }
-    return backup;
+    catch (err) {
+        fail(`back up the legacy data dir`, err);
+    }
 }
-export function migrateV2(opts) {
-    const { memories: memoriesRoot } = paths();
-    const result = {
-        scanned: 0,
-        converted: 0,
-        skippedV2: 0,
-        plans: [],
-        legacyBackup: null,
-    };
-    result.legacyBackup = migrateLegacyDataRoot(opts.dryRun);
-    if (!fs.existsSync(memoriesRoot))
-        return result;
-    for (const entry of fs.readdirSync(memoriesRoot, { withFileTypes: true })) {
+/** Plan v1 → v2 conversion for every `.md` file under `dir`. Read-only. */
+function planDir(dir, memoriesRoot, result) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         if (!entry.isDirectory())
             continue;
-        const dir = path.join(memoriesRoot, entry.name);
-        for (const name of fs.readdirSync(dir)) {
+        const sub = path.join(dir, entry.name);
+        for (const name of fs.readdirSync(sub)) {
             if (!name.endsWith(".md"))
                 continue;
-            const filePath = path.join(dir, name);
+            const filePath = path.join(sub, name);
             result.scanned++;
             const plan = planConversion(filePath, memoriesRoot);
             if (!plan) {
                 result.skippedV2++;
                 continue;
             }
-            if (!opts.dryRun) {
-                fs.mkdirSync(path.dirname(plan.toPath), { recursive: true });
-                fs.writeFileSync(plan.toPath, serialize(plan.fm, plan.body), "utf8");
-                if (plan.toPath !== plan.fromPath)
-                    fs.unlinkSync(plan.fromPath);
-            }
             result.converted++;
             result.plans.push(plan);
         }
     }
+}
+/** Apply conversion plans to disk (real run only — never in dry-run). */
+function applyPlans(result) {
+    for (const plan of result.plans) {
+        fs.mkdirSync(path.dirname(plan.toPath), { recursive: true });
+        fs.writeFileSync(plan.toPath, serialize(plan.fm, plan.body), "utf8");
+        if (plan.toPath !== plan.fromPath)
+            fs.unlinkSync(plan.fromPath);
+    }
+}
+export function migrateV2(opts) {
+    const { memories: memoriesRoot } = paths();
+    const result = {
+        scanned: 0,
+        converted: 0,
+        skippedV2: 0,
+        plans: [],
+        legacyBackup: null,
+    };
+    const legacy = findLegacyDataRoot();
+    if (legacy) {
+        result.legacyBackup = legacyBackupPath(legacy);
+        if (opts.dryRun) {
+            // D44: dry-run previews the legacy files in place — nothing is moved,
+            // so the preview actually shows what would convert (issue #7).
+            planDir(path.join(legacy, "memories"), memoriesRoot, result);
+        }
+        else {
+            mergeLegacyDataRoot(legacy, result.legacyBackup);
+        }
+    }
+    planDir(memoriesRoot, memoriesRoot, result);
+    if (!opts.dryRun)
+        applyPlans(result);
     return result;
 }

package/docs/V2-DESIGN.md

@@ -867,6 +867,21 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   MCP handshake instructions or the `init`-written instruction files — but
   opencode reads AGENTS.md natively, so the distilled snippet teaches the
   checkpoint habit wherever it lands. Approved 2026-09-29.*
+- **D44** — `migrate --to-v2` hotfix (issue #7, 0.4.1): (1) `--dry-run` now
+  previews the legacy `my-o-memory` files in place — per-file conversion plans
+  without moving anything (previously it scanned only the new, still-empty
+  root and always reported "0 files", making the preview useless); (2) dry-run
+  no longer prints the false "legacy data dir merged" line; (3) the Windows
+  EPERM on the legacy-dir backup rename is caught and rethrown as an actionable
+  message (close the program holding the folder — e.g. a running MCP server —
+  and re-run; nothing was deleted), and the CLI prints it as `Error: …` with
+  exit 1 instead of a raw syscall stack; (4) `parseFlags` accepts `--key=value`
+  in addition to `--key value` (the `=` form was silently misparsed before,
+  dropping the flag — which can turn a `--dry-run` into a real run).
+  *Rationale: a preview that shows nothing is worse than no preview — the user
+  cannot confirm what the real run will do; and a destructive-path failure must
+  speak in user terms. Shipped as 0.4.1 hotfix on the stable line. Approved
+  2026-09-29.*
 - **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
   (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
   `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/smoke-pure.ts

@@ -1,7 +1,7 @@
 // Quick smoke test — runs the pure-logic modules (no bun:sqlite dependency).
 // Usage:  node --experimental-strip-types scripts\smoke-pure.ts
 import { parse, serialize, ulid, normalizeFrontmatter, msToRfc3339, timeToMs, parseRawFrontmatter, type Frontmatter } from "../src/store/markdown.ts";
-import { planConversion, isV2File } from "../src/store/v2migrate.ts";
+import { planConversion, isV2File, migrateV2 } from "../src/store/v2migrate.ts";
 import { redact, findSecret } from "../src/redact.ts";
 import { detectKeywords } from "../src/capture/keywords.ts";
 import { DEFAULT_CONFIG } from "../src/config.ts";
@@ -314,6 +314,54 @@ const plan2 = planConversion(v1path, memRoot);
 ok("v2 on disk → null plan", plan2 === null);
 fs.rmSync(tmpRoot, { recursive: true, force: true });
 
+console.log("== migrateV2 dry-run previews legacy files (issue #7) ==");
+// legacy dir sits next to the new root (sibling), as on a real v1 upgrade
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "v2hotfix-"));
+const newRoot = path.join(tmpHome, "open-memex");
+const legacyRoot = path.join(tmpHome, "my-o-memory");
+const legacyMem = path.join(legacyRoot, "memories", "user");
+fs.mkdirSync(legacyMem, { recursive: true });
+const v1legacy = `---\nid: 01HOTFIX1\nscope_key: user\nscope_kind: user\nproject_name: user\ntype: fact\npriority: 1\ncreated_at: 1758854400000\nupdated_at: 1758854400000\n---\n\nlegacy content\n`;
+fs.writeFileSync(path.join(legacyMem, "01HOTFIX1.md"), v1legacy, "utf8");
+process.env.MY_O_MEMORY_HOME = newRoot;
+
+const dry = migrateV2({ dryRun: true });
+ok("dry-run scans the legacy file", dry.scanned === 1 && dry.plans.length === 1, `scanned=${dry.scanned}`);
+ok("dry-run yields a conversion plan", dry.plans.length === 1 && dry.plans[0].toPath.startsWith(newRoot), dry.plans[0]?.toPath);
+ok("dry-run reports legacy backup target", typeof dry.legacyBackup === "string" && dry.legacyBackup.includes("backup-"), dry.legacyBackup);
+ok("dry-run moves nothing", fs.existsSync(path.join(legacyMem, "01HOTFIX1.md")) && !fs.existsSync(path.join(newRoot, "memories", "personal", "01HOTFIX1.md")));
+ok("dry-run does not rename legacy dir", fs.existsSync(legacyRoot) && !fs.existsSync(dry.legacyBackup!));
+
+const real = migrateV2({ dryRun: false });
+ok("real run converts", real.converted === 1, `converted=${real.converted}`);
+ok("real run writes v2 file to new root", fs.existsSync(path.join(newRoot, "memories", "personal", "01HOTFIX1.md")));
+ok("real run backs up legacy dir", !fs.existsSync(legacyRoot) && fs.existsSync(real.legacyBackup!));
+const backContent = fs.readFileSync(path.join(newRoot, "memories", "personal", "01HOTFIX1.md"), "utf8");
+ok("converted file has schema_version 2", backContent.includes("schema_version: 2"));
+
+// backup rename failure → actionable Error, exit-1-worthy, no raw stack
+// (same process/root: paths() is cached per process)
+const legacyRoot2 = path.join(tmpHome, "my-o-memory");
+const legacyMem2 = path.join(legacyRoot2, "memories", "user");
+fs.mkdirSync(legacyMem2, { recursive: true });
+fs.writeFileSync(path.join(legacyMem2, "01HOTFIX2.md"), v1legacy, "utf8");
+// block the rename: pre-create today's dated backup as a non-empty dir
+const blocked = path.join(tmpHome, "my-o-memory.backup-" + new Date().toISOString().slice(0, 10));
+fs.mkdirSync(blocked, { recursive: true });
+fs.writeFileSync(path.join(blocked, "sentinel"), "x", "utf8");
+let boom: unknown = null;
+try {
+  migrateV2({ dryRun: false });
+} catch (e) {
+  boom = e;
+}
+ok("backup failure throws", boom instanceof Error, String(boom));
+ok("backup failure message is actionable", boom instanceof Error && boom.message.includes("could not back up") && boom.message.includes("Your memories are safe"), boom instanceof Error ? boom.message.slice(0, 60) : "");
+ok("failed backup keeps moved files safe in new root", fs.existsSync(path.join(newRoot, "memories", "user", "01HOTFIX2.md")));
+ok("failed backup leaves legacy dir for retry", fs.existsSync(legacyRoot2));
+delete process.env.MY_O_MEMORY_HOME;
+fs.rmSync(tmpHome, { recursive: true, force: true });
+
 console.log("== lifecycle pure: contentHash / similarity ==");
 ok("hash deterministic + whitespace-insensitive", contentHash("hello   world\n") === contentHash("hello world"));
 ok("hash differs on content", contentHash("hello world") !== contentHash("hello mars"));

package/src/cli.ts

@@ -250,11 +250,15 @@ Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict
 
 Flags:
   --from / --to   scope keys (default: current project → personal)
-  --dry-run       preview without moving anything
+  --dry-run       preview without moving anything (--to-v2 previews the legacy
+                  files in place, including per-file conversion plans)
   --on-conflict   newer (default), overwrite, or skip
   --to-v2         convert a legacy my-o-memory data dir to the v2 layout
 
 Always preview with --dry-run first; nothing moves without confirmation.
+On Windows, if another program holds the legacy folder open, the backup
+rename fails with an actionable message instead of a stack trace — close
+the program and re-run.
 
 Examples:
   open-memex migrate --dry-run
@@ -412,13 +416,20 @@ function parseFlags(argv: string[]): Record<string, string> {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
     if (a.startsWith("--")) {
-      const key = a.slice(2);
+      const raw = a.slice(2);
+      const eq = raw.indexOf("=");
+      if (eq >= 0) {
+        // D44: accept --key=value as well as --key value (issue #7 — the
+        // = form was silently misparsed before, dropping the flag).
+        out[raw.slice(0, eq)] = raw.slice(eq + 1);
+        continue;
+      }
       const val = argv[i + 1];
       if (val !== undefined && !val.startsWith("--")) {
-        out[key] = val;
+        out[raw] = val;
         i++;
       } else {
-        out[key] = "true";
+        out[raw] = "true";
       }
     }
   }
@@ -548,7 +559,14 @@ async function main() {
   if (cmd === "migrate" && rest.includes("--to-v2")) {
     const flags = parseFlags(rest);
     const dryRun = flags["dry-run"] === "true";
-    const stats = migrateV2({ dryRun });
+    let stats;
+    try {
+      stats = migrateV2({ dryRun });
+    } catch (err) {
+      // D44: actionable message, not a raw syscall stack (issue #7).
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
     console.log(
       `${dryRun ? "DRY RUN: " : ""}scanned ${stats.scanned} files: ` +
         `${stats.converted} to convert, ${stats.skippedV2} already v2`,
@@ -562,7 +580,9 @@ async function main() {
     }
     if (stats.legacyBackup) {
       console.log(
-        `\nlegacy my-o-memory data dir merged; backup kept at:\n  ${stats.legacyBackup}`,
+        dryRun
+          ? `\nDRY RUN: legacy my-o-memory data dir found — it would be merged and backed up at:\n  ${stats.legacyBackup}`
+          : `\nlegacy my-o-memory data dir merged; backup kept at:\n  ${stats.legacyBackup}`,
       );
     }
     if (!dryRun && stats.converted > 0) {

package/src/store/v2migrate.ts

@@ -118,23 +118,48 @@ export interface MigrateV2Result {
 }
 
 /**
- * Merge a legacy `my-o-memory` data root into the current `open-memex` root.
- * The old dir is renamed to a dated backup — never deleted. Returns the
- * backup path, or null when no legacy dir exists.
+ * Locate a legacy `my-o-memory` data root next to the current root.
+ * Pure lookup — no disk writes.
  */
-function migrateLegacyDataRoot(dryRun: boolean): string | null {
+export function findLegacyDataRoot(): string | null {
   const { root } = paths();
   const legacy = path.join(path.dirname(root), "my-o-memory");
   if (!fs.existsSync(legacy) || !fs.statSync(legacy).isDirectory()) return null;
+  return legacy;
+}
 
+/** Dated backup path for a legacy data root. Pure — no disk writes. */
+export function legacyBackupPath(legacy: string): string {
   const stamp = new Date().toISOString().slice(0, 10);
-  const backup = `${legacy}.backup-${stamp}`;
-  if (!dryRun) {
-    const legacyMem = path.join(legacy, "memories");
-    if (fs.existsSync(legacyMem)) {
-      for (const entry of fs.readdirSync(legacyMem)) {
-        const src = path.join(legacyMem, entry);
-        const dst = path.join(root, "memories", entry);
+  return `${legacy}.backup-${stamp}`;
+}
+
+/**
+ * Merge a legacy `my-o-memory` data root into the current `open-memex` root.
+ * The old dir is renamed to a dated backup — never deleted.
+ * Failures throw an actionable Error (no raw syscall dump): on Windows the
+ * backup rename typically fails with EPERM when another program holds the
+ * folder open.
+ */
+function mergeLegacyDataRoot(legacy: string, backup: string): void {
+  const { memories } = paths();
+  const fail = (where: string, err: unknown): never => {
+    const code = (err as NodeJS.ErrnoException)?.code;
+    throw new Error(
+      `could not ${where} (${legacy})` +
+        (code ? ` [${code}]` : "") +
+        `. Another program may be holding the folder open (e.g. a running MCP server, editor, or antivirus). ` +
+        `Your memories are safe — nothing was deleted. Close the program and re-run ` +
+        `\`open-memex migrate --to-v2\`, or rename the folder to ${backup} yourself and re-run.`,
+    );
+  };
+  const legacyMem = path.join(legacy, "memories");
+  if (fs.existsSync(legacyMem)) {
+    fs.mkdirSync(memories, { recursive: true });
+    for (const entry of fs.readdirSync(legacyMem)) {
+      const src = path.join(legacyMem, entry);
+      const dst = path.join(memories, entry);
+      try {
         if (!fs.existsSync(dst)) {
           fs.renameSync(src, dst);
         } else {
@@ -145,46 +170,75 @@ function migrateLegacyDataRoot(dryRun: boolean): string | null {
             if (!fs.existsSync(d)) fs.renameSync(s, d);
           }
         }
+      } catch (err) {
+        fail(`move memories from the legacy data dir`, err);
       }
     }
+  }
+  try {
     fs.renameSync(legacy, backup);
+  } catch (err) {
+    fail(`back up the legacy data dir`, err);
   }
-  return backup;
 }
 
-export function migrateV2(opts: { dryRun: boolean }): MigrateV2Result {
-  const { memories: memoriesRoot } = paths();
-  const result: MigrateV2Result = {
-    scanned: 0,
-    converted: 0,
-    skippedV2: 0,
-    plans: [],
-    legacyBackup: null,
-  };
-
-  result.legacyBackup = migrateLegacyDataRoot(opts.dryRun);
-
-  if (!fs.existsSync(memoriesRoot)) return result;
-  for (const entry of fs.readdirSync(memoriesRoot, { withFileTypes: true })) {
+/** Plan v1 → v2 conversion for every `.md` file under `dir`. Read-only. */
+function planDir(
+  dir: string,
+  memoriesRoot: string,
+  result: MigrateV2Result,
+): void {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
-    const dir = path.join(memoriesRoot, entry.name);
-    for (const name of fs.readdirSync(dir)) {
+    const sub = path.join(dir, entry.name);
+    for (const name of fs.readdirSync(sub)) {
       if (!name.endsWith(".md")) continue;
-      const filePath = path.join(dir, name);
+      const filePath = path.join(sub, name);
       result.scanned++;
       const plan = planConversion(filePath, memoriesRoot);
       if (!plan) {
         result.skippedV2++;
         continue;
       }
-      if (!opts.dryRun) {
-        fs.mkdirSync(path.dirname(plan.toPath), { recursive: true });
-        fs.writeFileSync(plan.toPath, serialize(plan.fm, plan.body), "utf8");
-        if (plan.toPath !== plan.fromPath) fs.unlinkSync(plan.fromPath);
-      }
       result.converted++;
       result.plans.push(plan);
     }
   }
+}
+
+/** Apply conversion plans to disk (real run only — never in dry-run). */
+function applyPlans(result: MigrateV2Result): void {
+  for (const plan of result.plans) {
+    fs.mkdirSync(path.dirname(plan.toPath), { recursive: true });
+    fs.writeFileSync(plan.toPath, serialize(plan.fm, plan.body), "utf8");
+    if (plan.toPath !== plan.fromPath) fs.unlinkSync(plan.fromPath);
+  }
+}
+
+export function migrateV2(opts: { dryRun: boolean }): MigrateV2Result {
+  const { memories: memoriesRoot } = paths();
+  const result: MigrateV2Result = {
+    scanned: 0,
+    converted: 0,
+    skippedV2: 0,
+    plans: [],
+    legacyBackup: null,
+  };
+
+  const legacy = findLegacyDataRoot();
+  if (legacy) {
+    result.legacyBackup = legacyBackupPath(legacy);
+    if (opts.dryRun) {
+      // D44: dry-run previews the legacy files in place — nothing is moved,
+      // so the preview actually shows what would convert (issue #7).
+      planDir(path.join(legacy, "memories"), memoriesRoot, result);
+    } else {
+      mergeLegacyDataRoot(legacy, result.legacyBackup);
+    }
+  }
+
+  planDir(memoriesRoot, memoriesRoot, result);
+  if (!opts.dryRun) applyPlans(result);
   return result;
 }