open-memex 0.4.0-alpha.7 → 0.4.1

package/dist/export.js

@@ -0,0 +1,157 @@
+/**
+ * Export / import: portable memory archives (§9, D40).
+ *
+ * `export` bundles selected memories (markdown source of truth + manifest)
+ * into a single .tar.gz for moving to another machine or another app.
+ * `import` restores a bundle: personal memories go to the personal dir,
+ * project memories are re-keyed to the current project and land in the
+ * outbox as drafts (submit moves them into the repo).
+ *
+ * D40: export excludes `visibility: private` by default; `--all` / `-a`
+ * includes everything — the full-migration escape hatch.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { db } from "./store/db.js";
+import { readMemoryFile, writeMemoryFile, normalizeFrontmatter, } from "./store/markdown.js";
+import { upsertFromFile } from "./store/sync.js";
+import { contentHash } from "./store/lifecycle.js";
+const EXPORT_FORMAT = "open-memex-export/1";
+function fail(msg) {
+    throw new Error(`[open-memex] ${msg}`);
+}
+function checkTar() {
+    try {
+        execFileSync("tar", ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        fail("the `tar` command is required for export/import but was not found on PATH");
+    }
+}
+export function exportMemories(opts) {
+    checkTar();
+    const includePrivate = opts.includePrivate ?? false;
+    let sql = `SELECT id, scope_key, scope, visibility, type, file_path FROM memories WHERE scope_key IN (${opts.scopeKeys.map(() => "?").join(",")})`;
+    const params = [...opts.scopeKeys];
+    if (!includePrivate)
+        sql += ` AND visibility != 'private'`;
+    if (opts.type) {
+        sql += ` AND type = ?`;
+        params.push(opts.type);
+    }
+    if (opts.tag) {
+        sql += ` AND (',' || tags || ',' LIKE ?)`;
+        params.push(`%,${opts.tag},%`);
+    }
+    sql += ` ORDER BY updated_at DESC`;
+    const rows = db().prepare(sql).all(...params);
+    const skippedPrivate = includePrivate
+        ? 0
+        : db().prepare(`SELECT COUNT(*) AS n FROM memories WHERE scope_key IN (${opts.scopeKeys.map(() => "?").join(",")}) AND visibility = 'private'`).get(...opts.scopeKeys).n;
+    const stage = fs.mkdtempSync(path.join(os.tmpdir(), "open-memex-export-"));
+    try {
+        const memDir = path.join(stage, "memories");
+        fs.mkdirSync(memDir, { recursive: true });
+        const manifestEntries = [];
+        let exported = 0;
+        for (const r of rows) {
+            const mf = readMemoryFile(r.file_path);
+            if (!mf)
+                continue; // stale index row — skip, don't fail the export
+            const rel = path.join(r.scope, `${r.id}.md`);
+            const dest = path.join(memDir, rel);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.copyFileSync(r.file_path, dest);
+            manifestEntries.push({ id: r.id, scope: r.scope, file: path.join("memories", rel) });
+            exported++;
+        }
+        const manifest = {
+            format: EXPORT_FORMAT,
+            exported_at: new Date().toISOString(),
+            open_memex_version: readPackageVersion(),
+            include_private: includePrivate,
+            filters: {
+                scope_keys: opts.scopeKeys,
+                type: opts.type ?? null,
+                tag: opts.tag ?? null,
+            },
+            memories: manifestEntries,
+        };
+        fs.writeFileSync(path.join(stage, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+        const stamp = new Date().toISOString().replace(/[:.]/g, "").slice(0, 15);
+        const outFile = opts.outFile ?? path.resolve(`open-memex-export-${stamp}.tar.gz`);
+        execFileSync("tar", ["-czf", outFile, "-C", stage, "manifest.json", "memories"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { file: outFile, exported, skippedPrivate, includePrivate };
+    }
+    finally {
+        fs.rmSync(stage, { recursive: true, force: true });
+    }
+}
+function readPackageVersion() {
+    try {
+        const here = new URL(import.meta.url);
+        const pkg = path.join(path.dirname(here.pathname), "..", "package.json");
+        return JSON.parse(fs.readFileSync(pkg, "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function importBundle(bundlePath, opts) {
+    checkTar();
+    if (!fs.existsSync(bundlePath))
+        fail(`bundle not found: ${bundlePath}`);
+    const stage = fs.mkdtempSync(path.join(os.tmpdir(), "open-memex-import-"));
+    try {
+        execFileSync("tar", ["-xzf", path.resolve(bundlePath), "-C", stage], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const manifestPath = path.join(stage, "manifest.json");
+        if (!fs.existsSync(manifestPath))
+            fail("not an open-memex export bundle (manifest.json missing)");
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        if (manifest.format !== EXPORT_FORMAT) {
+            fail(`unsupported bundle format: ${manifest.format} (expected ${EXPORT_FORMAT})`);
+        }
+        const result = { imported: 0, skippedIdentical: 0, skippedConflict: [] };
+        const existingStmt = db().prepare(`SELECT content_hash FROM memories WHERE id = ?`);
+        for (const entry of manifest.memories ?? []) {
+            const src = path.join(stage, entry.file);
+            const mf = readMemoryFile(src);
+            if (!mf)
+                continue;
+            const fm = normalizeFrontmatter({ ...mf.fm });
+            // Re-key to this machine: personal stays personal; project memories
+            // adopt the current project's scope key (keys embed a path hash).
+            if (fm.scope === "project")
+                fm.scope_key = opts.projectScopeKey;
+            else if (fm.scope === "personal")
+                fm.scope_key = "personal";
+            const existing = existingStmt.get(fm.id);
+            if (existing) {
+                if (existing.content_hash === contentHash(mf.body))
+                    result.skippedIdentical++;
+                else
+                    result.skippedConflict.push({ id: fm.id, file: entry.file });
+                continue;
+            }
+            if (opts.dryRun) {
+                result.imported++;
+                continue;
+            }
+            const { filePath } = writeMemoryFile(fm, mf.body);
+            const written = readMemoryFile(filePath);
+            if (written)
+                upsertFromFile(written);
+            result.imported++;
+        }
+        return result;
+    }
+    finally {
+        fs.rmSync(stage, { recursive: true, force: true });
+    }
+}

package/dist/mcp.js

@@ -104,6 +104,20 @@ export async function runMcpServer() {
     syncScope(scope.key, "session");
     syncScope(PERSONAL_SCOPE.key, "session");
     console.error(`[open-memex] MCP server up. scope=${scope.key}`);
+    // D12: pulls are explicit by default — session start never touches the
+    // network. With sync.autoPull, one best-effort pull; a failure never
+    // blocks the session, it just logs and continues.
+    if (cfg.sync?.autoPull) {
+        try {
+            const { GitProvider } = await import("./providers/git.js");
+            const r = new GitProvider().pull(process.cwd());
+            syncScope(scope.key, "pull");
+            console.error(`[open-memex] auto-pull: ${r.branch} ${r.fastForwarded ? "fast-forwarded" : "already up to date"}`);
+        }
+        catch (e) {
+            console.error(`[open-memex] auto-pull skipped: ${e.message}`);
+        }
+    }
     // D26: re-sync on every request, not just at startup. The in-repo dir
     // follows the current git branch, so a branch switch mid-session would
     // otherwise leave the index pointing at files that no longer exist.

package/dist/providers/git.js

@@ -0,0 +1,142 @@
+/**
+ * GitProvider — the git transport for repo-synced shared scopes (§9, D12).
+ *
+ * Git is a transport, not the product boundary: this provider moves the
+ * in-repo memory dir (`.ai/open-memex/`) between the local checkout and the
+ * remote. It never touches the appdata outbox, never force-pushes, never
+ * auto-merges a divergence — those are human decisions.
+ *
+ * Hard rules (from §9 / D12 / D36):
+ * - pull is explicit (`open-memex pull`); pull = fetch + fast-forward only.
+ * - push is explicit (`open-memex push`); the tool never pushes on its own.
+ * - a failed pull/push fails with a clear message and leaves no broken state.
+ */
+import { execFileSync } from "node:child_process";
+function fail(msg) {
+    throw new Error(`[open-memex] ${msg}`);
+}
+/** Run git, raising a readable error. `timeoutMs` guards network calls. */
+function git(root, args, timeoutMs = 0) {
+    try {
+        return execFileSync("git", args, {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
+        }).trim();
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ETIMEDOUT")
+            fail(`git ${args.join(" ")} timed out — remote unreachable?`);
+        const detail = (err.stderr ?? err.message ?? "").trim().split("\n")[0];
+        fail(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+    }
+}
+const FETCH_TIMEOUT_MS = 30_000;
+export class GitProvider {
+    name = "git";
+    capabilities = {
+        read: true,
+        write: true,
+        delete: false,
+        history: true,
+        sync: "bidirectional",
+    };
+    /** Current branch + upstream, or a clear failure when git can't answer. */
+    status(root) {
+        git(root, ["rev-parse", "--git-dir"]);
+        const branch = git(root, ["branch", "--show-current"]) ||
+            git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+        let upstream = null;
+        try {
+            upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+        }
+        catch {
+            upstream = null;
+        }
+        let ahead = 0;
+        let behind = 0;
+        if (upstream) {
+            const counts = git(root, ["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+            const [a, b] = counts.split(/\s+/).map((n) => parseInt(n, 10));
+            ahead = Number.isFinite(a) ? a : 0;
+            behind = Number.isFinite(b) ? b : 0;
+        }
+        const remote = upstream ? upstream.split("/")[0] : null;
+        return { branch, upstream, remote, ahead, behind };
+    }
+    /**
+     * Explicit pull: fetch + fast-forward only (§9).
+     * Diverged branches are NOT merged — the user resolves them by hand.
+     */
+    pull(root) {
+        const st = this.status(root);
+        if (!st.upstream || !st.remote) {
+            fail(`branch ${st.branch} has no upstream — set one with ` +
+                `\`git push -u <remote> ${st.branch}\`, then pull again`);
+        }
+        git(root, ["fetch", st.remote], FETCH_TIMEOUT_MS);
+        const before = git(root, ["rev-parse", "HEAD"]);
+        const remoteSha = git(root, ["rev-parse", st.upstream]);
+        if (before === remoteSha) {
+            return {
+                at: new Date().toISOString(),
+                branch: st.branch,
+                remote: st.remote,
+                before,
+                after: before,
+                fastForwarded: false,
+            };
+        }
+        // Fast-forward is possible iff HEAD is an ancestor of the upstream.
+        let ffPossible = false;
+        try {
+            git(root, ["merge-base", "--is-ancestor", "HEAD", st.upstream]);
+            ffPossible = true;
+        }
+        catch {
+            ffPossible = false;
+        }
+        if (!ffPossible) {
+            fail(`branch ${st.branch} has diverged from ${st.upstream} — ` +
+                `open-memex never force-merges; resolve it by hand ` +
+                `(rebase or merge), then pull again`);
+        }
+        git(root, ["merge", "--ff-only", st.upstream]);
+        const after = git(root, ["rev-parse", "HEAD"]);
+        return {
+            at: new Date().toISOString(),
+            branch: st.branch,
+            remote: st.remote,
+            before,
+            after,
+            fastForwarded: true,
+        };
+    }
+    /** Explicit push of the current branch. Never called automatically. */
+    push(root) {
+        const st = this.status(root);
+        if (!st.remote) {
+            // No upstream yet: push explicitly sets it (-u), still user-invoked.
+            const remotes = git(root, ["remote"]);
+            const remote = remotes.split("\n").map((r) => r.trim()).filter(Boolean)[0];
+            if (!remote)
+                fail("no git remote configured — add one before pushing");
+            git(root, ["push", "-u", remote, st.branch], FETCH_TIMEOUT_MS);
+            return {
+                at: new Date().toISOString(),
+                branch: st.branch,
+                remote,
+                head: git(root, ["rev-parse", "HEAD"]),
+            };
+        }
+        git(root, ["push", st.remote, st.branch], FETCH_TIMEOUT_MS);
+        return {
+            at: new Date().toISOString(),
+            branch: st.branch,
+            remote: st.remote,
+            head: git(root, ["rev-parse", "HEAD"]),
+        };
+    }
+}

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/CURATOR.md

@@ -0,0 +1,59 @@
+# Curator Convention
+
+The **curator** is the human who tends a project's shared memory. It is a
+documented convention, not a permission system — anyone on the team can act
+as curator; the tool records *who* did *what* (the audit trail), it doesn't
+decide who is *allowed* to.
+
+## What the curator does
+
+1. **Triage proposals.** `open-memex propose` puts memories up for review.
+   The curator reads them, then `open-memex promote <id>` to approve or
+   `open-memex promote <id> --reject` to send back, with `--note` saying why.
+2. **Resolve conflicts.** `open-memex resolve` lists file-level and semantic
+   conflicts. The curator merges or picks a winner — Core never silently
+   resolves a semantic conflict; both sides stay `active` until a human
+   decides.
+3. **Keep the garden.** Deprecate what's stale (`open-memex status <id>
+   deprecated`), supersede what's been replaced, forget what's noise.
+   Shared memory rots without pruning.
+4. **Watch the pipeline.** `open-memex sync-status` shows the outbox, review
+   states, and uncommitted files; `open-memex pr-status --apply` maps the
+   GitHub PR state back onto `review_state`.
+
+## Admission bar
+
+Approve a memory when it is:
+
+- **True** — you believe it, or it cites something verifiable.
+- **Durable** — it will still matter in a month. Chat logs are not memories.
+- **Scoped right** — project knowledge in project scope; personal stuff stays
+  personal (personal memories are never the curator's business).
+- **Well-typed** — `type` says what it IS (`decision`, `gotcha`, `lesson`…),
+  `tags` say what it's ABOUT.
+
+Send back (don't silently fix) when it's vague, duplicated, or belongs in
+`docs/` as formal documentation instead — memory is the fast-changing long
+tail, `docs/` is the slow-changing core.
+
+## What the curator does NOT do
+
+- **Never rewrite someone else's memory in place.** Propose a superseding
+  memory instead — the chain (`supersedes` / `superseded_by`) is the audit
+  trail.
+- **Never approve their own proposals silently in team mode.** That's what
+  `--local-approve` is for — solo projects only.
+- **Never pull rank with the tool.** If the team disagrees with a call, the
+  disagreement itself is worth a memory.
+
+## Cadence
+
+There is no required cadence. A workable default: triage proposals at the
+end of each work chunk (the same checkpoint where §3.5 distillation runs),
+and do a pruning pass when `sync-status` starts feeling noisy.
+
+## Solo mode
+
+No team, no curator needed. `open-memex propose --local-approve` records
+`approved_by: self` and skips the PR. You are the curator, the proposer,
+and the gardener — the same hygiene rules apply, just faster.

package/docs/TEST-PLAN.md

@@ -0,0 +1,72 @@
+# OpenMemex 测试计划（v0.4.0-alpha.10）
+
+> 自动化部分：`node --experimental-strip-types scripts/test-full.ts`
+> 62 项全过（26 个 CLI 命令 + 11 个 MCP tool），隔离环境运行，不碰真实数据。
+> 下面是机器/账号相关的部分，需要 Stone 在真机上过一遍。
+
+## A. Windows 真机 + VS Code Copilot
+
+- [ ] `npm i -g open-memex@alpha` 全局安装，`open-memex --version` 显示正确版本
+- [ ] 在一个真实项目目录跑 `open-memex init`（不加 `--yes`，走一遍交互）
+  - 确认 `.vscode/mcp.json` 生成，`~/.copilot/copilot-instructions.md` 合并写入（不覆盖已有内容）
+- [ ] 重启 VS Code，Copilot Chat 里问 "what do you remember about this project?"
+  - 预期：MCP 连接成功，能调用 memory_search
+- [ ] `open-memex add "windows 真机测试" --type fact`，再让 Copilot 搜出来
+- [ ] 中文路径项目、中文记忆内容各试一条（CJK 索引）
+
+## B. 真实 GitHub PR 全流程（review 工作流）
+
+在一个真实 repo 里：
+
+- [ ] `open-memex add "PR流程测试" --scope personal` → `propose --to project` → `sync-status` 看到 outbox draft
+- [ ] `open-memex submit <id>`（留在当前分支，本地 commit）
+- [ ] 手动 `git push` + 开 PR
+- [ ] 在 PR 里点 Approve → 回来跑 `open-memex pr-status`（先看 report），再 `pr-status --apply`
+  - 预期：memory 变成 approved，`approved_by` 是 reviewer
+- [ ] 找一条让 reviewer 点 "Request changes" → `pr-status --apply`
+  - 预期：只给 suggestion，**不**自动 reject（D32）
+- [ ] Merge PR → `pr-status --apply`
+  - 预期：memory 变成 published
+- [ ] `open-memex resolve` 无冲突时输出 "(no conflicted memory files)"
+
+## C. 其他编辑器 MCP 集成
+
+- [ ] Cursor：`open-memex mcp --print-config cursor` → 贴到 Cursor MCP 配置 → 能连上
+- [ ] opencode：`open-memex init --client opencode` → `opencode.jsonc` 生效
+- [ ] Claude Code：`open-memex mcp --print-config claude` 给出的 `claude mcp add` 命令能跑通
+
+## D. 跨机迁移（export/import 真实场景）
+
+- [ ] 本机：`open-memex export --all -o migration.tar.gz`（含 private 的全量）
+- [ ] 本机：`open-memex export -o share.tar.gz`（默认排除 private）→ 解包检查 manifest，确认没有 visibility:private 的条目
+- [ ] 另一台机器：`open-memex import migration.tar.gz --dry-run` 先看预览，再正式 import
+  - 预期：project memory re-key 到新机器的 project scope，进 outbox 当 draft；personal 进 personal
+- [ ] 同一个 bundle 导两次 → 第二次 "skipped N identical"
+
+## E. Agent 会话行为（D42 / §3.5）
+
+- [ ] 新开一个 agent 会话（MCP 已接），看 initialize 返回的 instructions 里有没有 session-start 同步指引
+- [ ] 对 agent 说 "sync memory" / "同步记忆"
+  - 预期：agent 走 memory_status → 摘要 → 问你要同步哪条（而不是直接翻 appdata）
+- [ ] 长对话中 agent 是否在检查点提议蒸馏（§3.5），提议后是否等你批准才保存（D42）
+
+## F. 冲突解决（3-way merge）
+
+- [ ] 两台机器（或两个 clone）同时改同一条 project memory，各自 submit + push，一边 pull 制造 diverged
+  - 预期：`open-memex pull` 明确报错退出，不自动 merge
+- [ ] 手动 merge 后 `open-memex resolve <id>` 看 3-way 展示（base/outbox/repo），手动解决
+
+## G. 同事 pilot（1–2 人，Stone 私下选）
+
+- [ ] 对方 `npx open-memex@alpha init` 走通
+- [ ] 对方能 propose → 你这边能看到 PR → promote 流程走通
+- [ ] 收集反馈：哪里卡、哪里不符合直觉
+
+## H. 已知问题观察
+
+- [ ] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：注意是否丢数据（预期：不丢，只影响退出码）
+- [ ] `memory_list` 默认只列 project scope 是否符合预期（Stone 已定保持现状）
+
+---
+
+测试中发现的 bug 直接记到 GitHub issue；改完后更新本文档的复选框。

package/docs/V2-DESIGN.md

@@ -534,8 +534,10 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 | atlaso-labs/codex | Codex marketplace | long-term memory plugin for Codex (hooks + MCP + cloud-sync upsell) | **direct comparable** for a future Codex plugin; their cloud upsell vs our local-first |
 
 (Star counts / funding as of Sep 2026 — re-verify before quoting publicly.)
-- **Phase 3 — Org layer.** Org memory repo · curator convention · `examples/remote-server/` ·
-  distill-to-AGENTS.md assist · export/import archive command for user portability.
+- **Phase 3 — Org layer.** Org memory repo · `examples/remote-server/` ·
+  curator convention ✅ `docs/CURATOR.md` (2026-09-29, pulled forward) ·
+  distill-to-AGENTS.md assist ✅ `open-memex distill-agents` (2026-09-29, pulled forward) ·
+  export/import archive command ✅ `open-memex export` / `import` (2026-09-29, pulled forward, D40).
 - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
   sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
   for enterprise knowledge systems.
@@ -858,6 +860,28 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   saved via `memory_add` with the new optional `source` param set to
   `"inference"` (default `"tool"`). *Rationale: closes the 0.4.0 TODO from D41 —
   the design's capture loop now reaches the agent. Implemented 2026-09-29.*
+- **D43** — `distill-agents` output gains a "Memory hygiene (open-memex)"
+  footer carrying the §3.5 checkpoint guidance (propose 1–3 distilled captures
+  at checkpoints; save nothing without approval; prefer `reference` over
+  copying). *Rationale: double insurance for opencode users, who never see the
+  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-alpha.7",
+  "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",