open-memex 0.4.0-alpha.7 → 0.4.0

package/dist/cli.js

@@ -12,7 +12,7 @@ import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.js";
 import { search, list, hitStateLabel } from "./retrieve/search.js";
 import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
 import { loadConfig } from "./config.js";
-import { paths } from "./paths.js";
+import { paths, projectRoot } from "./paths.js";
 import { redact } from "./redact.js";
 import { resolveMcpCommand } from "./init.js";
 import fs from "node:fs";
@@ -23,7 +23,10 @@ import { fileURLToPath } from "node:url";
 const COMMAND_HELP = {
     where: `Show which project scope the current directory resolves to, and where its data lives.
 
-Usage: open-memex where`,
+Usage: open-memex where
+
+Example:
+  open-memex where`,
     list: `List memories in a scope, newest first.
 
 Usage: open-memex list [--scope project|personal] [--type T] [--limit N]
@@ -60,13 +63,22 @@ Example:
   open-memex add "We deploy on Fridays" --scope project --tag process`,
     supersede: `Replace a memory with a newer version. The old one is kept as history.
 
-Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]`,
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+
+Example:
+  open-memex supersede 01ABC "We deploy on Thursdays now"`,
     status: `Change a memory's lifecycle status.
 
-Usage: open-memex status <id> active|deprecated|retracted|archived`,
+Usage: open-memex status <id> active|deprecated|retracted|archived
+
+Example:
+  open-memex status 01ABC deprecated`,
     forget: `Delete a memory by id.
 
-Usage: open-memex forget <id>`,
+Usage: open-memex forget <id>
+
+Example:
+  open-memex forget 01ABC`,
     propose: `Copy personal memories into the project outbox as review drafts.
 The personal originals stay put. Nothing enters git at this step.
 
@@ -100,12 +112,70 @@ Usage: open-memex resolve [id-or-path]
 
 With no argument, lists conflicts. With an id or file path, shows the
 3-way merge (base / outbox / repo) so you can resolve it by hand.
-Conflicts are never auto-resolved.`,
+Conflicts are never auto-resolved.
+
+Examples:
+  open-memex resolve
+  open-memex resolve 01ABC`,
     "sync-status": `Show the project memory sync pipeline: when the index last synced
 and what triggered it, drafts waiting in the outbox (appdata), memories in the
 repo awaiting review or published, and repo files not yet committed.
 
-Usage: open-memex sync-status`,
+Usage: open-memex sync-status
+
+Example:
+  open-memex sync-status`,
+    pull: `Pull shared project memories from the git remote: fetch + fast-forward
+only. Never auto-merges — a diverged branch fails with a clear message and is
+left for you to resolve by hand. On success the local index re-syncs.
+
+Usage: open-memex pull
+
+Example:
+  open-memex pull`,
+    push: `Push the current branch (with its submitted memories) to the git
+remote. Explicit only — open-memex never pushes on its own.
+
+Usage: open-memex push
+
+Example:
+  open-memex push`,
+    export: `Export memories to a portable .tar.gz bundle (markdown source of
+truth + manifest.json) for moving to another machine or another app.
+Excludes visibility:private memories by default; --all includes everything.
+
+Usage: open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
+
+Flags:
+  --scope   project (default), personal, or both
+  --type    filter by memory type
+  --tag     filter by tag
+  --all, -a include private memories (full migration)
+  -o        output file (default: ./open-memex-export-<timestamp>.tar.gz)
+
+Examples:
+  open-memex export -o backup.tar.gz
+  open-memex export --scope both --all -o full-migration.tar.gz`,
+    import: `Import a bundle created by \`open-memex export\`. Personal memories
+go to the personal dir; project memories are re-keyed to the current project
+and land in the outbox as drafts. Existing identical memories are skipped;
+conflicting ids are reported, never overwritten.
+
+Usage: open-memex import <bundle.tar.gz> [--dry-run]
+
+Examples:
+  open-memex import backup.tar.gz --dry-run
+  open-memex import backup.tar.gz`,
+    "distill-agents": `Propose an AGENTS.md snippet distilled from project
+memories (decisions, constraints, lessons, gotchas, howtos). Prints markdown
+to stdout, or writes it with -o. Review and merge by hand — open-memex never
+rewrites your AGENTS.md on its own.
+
+Usage: open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
+
+Examples:
+  open-memex distill-agents
+  open-memex distill-agents --type decision,gotcha -o agents-snippet.md`,
     submit: `Move outbox drafts into the repo for review: copies the drafts into
 the repo memory dir as proposed (a local-approved copy keeps its approval),
 commits locally on the CURRENT branch, and moves the outbox originals out.
@@ -129,13 +199,23 @@ overwritten. Report-only by default.
 Usage: open-memex pr-status [--apply]
 
 Flags:
-  --apply   write the transitions locally (still never pushes)`,
+  --apply   write the transitions locally (still never pushes)
+
+Examples:
+  open-memex pr-status
+  open-memex pr-status --apply`,
     reindex: `Rebuild the SQLite index from the markdown files.
 
-Usage: open-memex reindex`,
+Usage: open-memex reindex
+
+Example:
+  open-memex reindex`,
     scopes: `List the known scopes (personal + project).
 
-Usage: open-memex scopes`,
+Usage: open-memex scopes
+
+Example:
+  open-memex scopes`,
     migrate: `Move memories between scopes, or convert a legacy my-o-memory data dir.
 
 Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict newer|overwrite|skip]
@@ -147,13 +227,21 @@ Flags:
   --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.`,
+Always preview with --dry-run first; nothing moves without confirmation.
+
+Examples:
+  open-memex migrate --dry-run
+  open-memex migrate --from personal --to project --dry-run`,
     mcp: `Start the stdio MCP server (the same server editors connect to).
 
 Usage: open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
 
 Flags:
-  --print-config   print the MCP client config instead of starting the server`,
+  --print-config   print the MCP client config instead of starting the server
+
+Examples:
+  open-memex mcp
+  open-memex mcp --print-config vscode`,
     init: `One-command project setup: writes the MCP config for your editor and the
 agent memory instructions. Existing files are merged, never clobbered.
 
@@ -164,21 +252,32 @@ Flags:
   --client        editor to configure (default: auto-detect)
   --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
   --force         overwrite existing config
-  --yes           accept all defaults, never prompt`,
+  --yes           accept all defaults, never prompt
+
+Examples:
+  open-memex init
+  open-memex init --client cursor --yes`,
     config: `Show config, or set a key.
 
 Usage: open-memex config [set <key> <value>]
 
-Example:
+Examples:
+  open-memex config
   open-memex config set sync.autoPull false`,
     capture: `Preview what the keyword-capture watcher would extract from text.
 
-Usage: open-memex capture --dry-run "text"`,
+Usage: open-memex capture --dry-run "text"
+
+Example:
+  open-memex capture --dry-run "remember: we deploy on Fridays"`,
     doctor: `Environment health check: Node version, config source, scope resolution,
 storage writability, then boots a real MCP server and runs initialize +
 tools/list against it — all eleven tools must show up.
 
-Usage: open-memex doctor`,
+Usage: open-memex doctor
+
+Example:
+  open-memex doctor`,
 };
 function usage(exitCode = 1) {
     console.log(`open-memex CLI
@@ -195,6 +294,11 @@ Usage:
   open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
   open-memex resolve [id-or-path]
   open-memex sync-status
+  open-memex pull
+  open-memex push
+  open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
+  open-memex import <bundle.tar.gz> [--dry-run]
+  open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
   open-memex submit <id...> [--branch <name>] [--base <branch>]
   open-memex pr-status [--apply]
   open-memex reindex
@@ -209,6 +313,9 @@ Usage:
   open-memex capture --dry-run "text"
   open-memex doctor
 
+Every command has its own help with description and examples:
+  open-memex <command> --help   (or -h)
+
 One-command project setup: \`open-memex init\` (or \`npx open-memex@alpha init\`) writes
 the MCP config for your editor (\`.vscode/mcp.json\`, \`.cursor/mcp.json\`,
 \`opencode.jsonc\`, or Visual Studio's solution-level \`.mcp.json\`) — no copy-paste
@@ -239,6 +346,31 @@ type: instruction→role split. Always preview with --dry-run first.
 Run \`open-memex <command> --help\` for details on a single command.`);
     process.exit(exitCode);
 }
+/**
+ * Build a saveConfig patch for a (possibly dotted) config key, preserving
+ * sibling keys already present in the nested object.
+ */
+function setConfigPath(key, value) {
+    const parts = key.split(".");
+    if (parts.length === 1)
+        return { [key]: value };
+    const cfg = loadConfig();
+    const top = parts[0];
+    const cur = cfg[top] && typeof cfg[top] === "object"
+        ? { ...cfg[top] }
+        : {};
+    let node = cur;
+    for (let i = 1; i < parts.length - 1; i++) {
+        const seg = parts[i];
+        const nxt = node[seg] && typeof node[seg] === "object"
+            ? { ...node[seg] }
+            : {};
+        node[seg] = nxt;
+        node = nxt;
+    }
+    node[parts[parts.length - 1]] = value;
+    return { [top]: cur };
+}
 function parseFlags(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -418,7 +550,9 @@ async function main() {
             }
             try {
                 const saved = validate(value);
-                const file = saveConfig({ [key]: saved });
+                // Dotted keys (e.g. sync.autoPull) write into the nested config
+                // object, preserving sibling keys already on disk.
+                const file = saveConfig(setConfigPath(key, saved));
                 console.log(`set ${key} = ${JSON.stringify(saved)} (${file})`);
             }
             catch (err) {
@@ -781,6 +915,133 @@ async function main() {
         }
         return;
     }
+    // §9 / D12: explicit pull — fetch + fast-forward only, never auto-merge.
+    if (cmd === "pull") {
+        const { GitProvider } = await import("./providers/git.js");
+        const root = projectRoot();
+        try {
+            const r = new GitProvider().pull(root);
+            const stats = syncScope(project.key, "pull");
+            if (r.fastForwarded) {
+                console.log(`pulled ${r.branch} from ${r.remote}: ${r.before.slice(0, 8)} → ${r.after.slice(0, 8)} (fast-forward)`);
+            }
+            else {
+                console.log(`already up to date: ${r.branch} @ ${r.after.slice(0, 8)}`);
+            }
+            console.log(`index: +${stats.added} ~${stats.updated} -${stats.removed} (scanned ${stats.scanned})`);
+        }
+        catch (e) {
+            console.error(`pull failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    // Explicit push — open-memex never pushes on its own (D36).
+    if (cmd === "push") {
+        const { GitProvider } = await import("./providers/git.js");
+        const root = projectRoot();
+        try {
+            const r = new GitProvider().push(root);
+            syncScope(project.key, "push");
+            console.log(`pushed ${r.branch} to ${r.remote} @ ${r.head.slice(0, 8)}`);
+        }
+        catch (e) {
+            console.error(`push failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    // §9 / D40: portable export bundle (markdown + manifest).
+    if (cmd === "export") {
+        const { exportMemories } = await import("./export.js");
+        const flags = parseFlags(rest);
+        const all = flags["all"] === "true" || flags["a"] === "true" || rest.includes("--all") || rest.includes("-a");
+        const scopeFlag = flags["scope"] ?? "project";
+        // parseFlags only handles `--` flags; `-o <file>` is picked up here.
+        const oIdx = rest.findIndex((a) => a === "-o");
+        const outFile = flags["o"] ?? flags["output"] ?? (oIdx >= 0 ? rest[oIdx + 1] : undefined);
+        const scopeKeys = scopeFlag === "both"
+            ? [project.key, PERSONAL_SCOPE.key]
+            : scopeFlag === "personal"
+                ? [PERSONAL_SCOPE.key]
+                : [project.key];
+        try {
+            const r = exportMemories({
+                scopeKeys,
+                type: flags["type"],
+                tag: flags["tag"],
+                includePrivate: all,
+                outFile,
+            });
+            console.log(`exported ${r.exported} memories → ${r.file}`);
+            if (!r.includePrivate && r.skippedPrivate > 0) {
+                console.log(`skipped ${r.skippedPrivate} private memories (use --all to include them)`);
+            }
+        }
+        catch (e) {
+            console.error(`export failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === "import") {
+        const { importBundle } = await import("./export.js");
+        const flags = parseFlags(rest);
+        const bundle = positionalArgs(rest)[0];
+        if (!bundle) {
+            console.error(`usage: open-memex import <bundle.tar.gz> [--dry-run]`);
+            process.exit(2);
+        }
+        const dryRun = flags["dry-run"] === "true";
+        try {
+            const r = importBundle(bundle, { projectScopeKey: project.key, dryRun });
+            if (!dryRun) {
+                syncScope(project.key, "cli");
+                syncScope(PERSONAL_SCOPE.key, "cli");
+            }
+            console.log(`${dryRun ? "DRY RUN: " : ""}imported ${r.imported}, skipped ${r.skippedIdentical} identical`);
+            for (const c of r.skippedConflict) {
+                console.log(`  conflict (kept existing): ${c.id} from ${c.file}`);
+            }
+        }
+        catch (e) {
+            console.error(`import failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    // Phase 3: distill project memories into a proposed AGENTS.md snippet.
+    if (cmd === "distill-agents") {
+        const { distillAgentsMarkdown } = await import("./distill-agents.js");
+        const flags = parseFlags(rest);
+        const scopeFlag = flags["scope"] ?? "project";
+        const scopeKeys = scopeFlag === "personal" ? [PERSONAL_SCOPE.key] : [project.key];
+        const types = flags["type"]
+            ? flags["type"].split(",").map((t) => t.trim()).filter(Boolean)
+            : undefined;
+        const limit = flags["limit"] ? parseInt(flags["limit"], 10) : undefined;
+        const oIdx = rest.findIndex((a) => a === "-o");
+        const outFile = oIdx >= 0 ? rest[oIdx + 1] : undefined;
+        try {
+            const md = distillAgentsMarkdown({ scopeKeys, types, limit });
+            if (!md) {
+                console.log("no distillable memories found (decisions, constraints, lessons, gotchas, howtos)");
+                return;
+            }
+            if (outFile) {
+                fs.writeFileSync(outFile, md, "utf8");
+                console.log(`wrote proposed AGENTS.md snippet → ${outFile} (review and merge by hand)`);
+            }
+            else {
+                console.log(md);
+            }
+        }
+        catch (e) {
+            console.error(`distill-agents failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
     if (cmd === "pr-status") {
         const flags = parseFlags(rest);
         try {
@@ -852,6 +1113,10 @@ async function main() {
             entries.push({ key: name, files, marker });
         }
         entries.sort((a, b) => b.files - a.files);
+        if (entries.length === 0) {
+            console.log("(no scopes with memories yet — add one with `open-memex add`)");
+            return;
+        }
         for (const e of entries) {
             console.log(`  ${e.files.toString().padStart(4)}  ${e.key}${e.marker}`);
         }

package/dist/config.js

@@ -34,6 +34,7 @@ export const DEFAULT_CONFIG = {
     redactPatterns: [],
     logLevel: "info",
     memoryDir: ".ai/open-memex",
+    sync: { autoPull: false },
 };
 function stripJsonComments(raw) {
     // Line comments
@@ -79,6 +80,7 @@ export const SETTABLE_KEYS = {
     injectOnFirstTurn: toBool,
     keywordCaptureEnabled: toBool,
     memoryDir: toRelativeDir,
+    "sync.autoPull": toBool,
     logLevel: (v) => {
         if (v !== "info" && v !== "debug")
             throw new Error('must be "info" or "debug"');

package/dist/distill-agents.js

@@ -0,0 +1,62 @@
+/**
+ * distill-to-AGENTS.md assist (Phase 3).
+ *
+ * Turns distilled project memories (decisions, lessons, gotchas, howtos,
+ * constraints) into a proposed AGENTS.md snippet. ASSIST only: it prints
+ * (or writes with -o) a markdown section for the human to review and merge
+ * by hand — open-memex never rewrites your AGENTS.md on its own.
+ */
+import { db } from "./store/db.js";
+const DEFAULT_TYPES = ["decision", "constraint", "lesson", "gotcha", "howto"];
+export function distillAgentsMarkdown(opts) {
+    const types = opts.types?.length ? opts.types : DEFAULT_TYPES;
+    const limit = Math.max(1, Math.min(opts.limit ?? 30, 200));
+    const sql = `
+    SELECT id, type, tags, content, updated_at FROM memories
+    WHERE scope_key IN (${opts.scopeKeys.map(() => "?").join(",")})
+      AND type IN (${types.map(() => "?").join(",")})
+      AND status = 'active'
+    ORDER BY updated_at DESC
+    LIMIT ?`;
+    const rows = db()
+        .prepare(sql)
+        .all(...opts.scopeKeys, ...types, limit);
+    if (rows.length === 0)
+        return "";
+    const date = new Date().toISOString().slice(0, 10);
+    const lines = [
+        `## Learned (distilled from open-memex, ${date})`,
+        ``,
+        `<!-- Proposed by \`open-memex distill-agents\`. Review each line, keep`,
+        `what's true, delete the rest, then merge into this file by hand. -->`,
+        ``,
+    ];
+    // Group by type, preserving recency within each group.
+    const byType = new Map();
+    for (const r of rows) {
+        const g = byType.get(r.type) ?? [];
+        g.push(r);
+        byType.set(r.type, g);
+    }
+    for (const t of types) {
+        const g = byType.get(t);
+        if (!g?.length)
+            continue;
+        lines.push(`### ${t}`);
+        lines.push(``);
+        for (const r of g) {
+            const first = r.content.split("\n").map((l) => l.trim()).find((l) => l) ?? "";
+            const snippet = first.length > 160 ? first.slice(0, 160) + "…" : first;
+            lines.push(`- ${snippet} \`[${r.id.slice(0, 8)}]\``);
+        }
+        lines.push(``);
+    }
+    // D43 — §3.5 memory-hygiene footer (double insurance for opencode users,
+    // who never see the MCP handshake / init instructions): teach the agent
+    // reading this AGENTS.md to propose distilled captures at checkpoints.
+    lines.push(`### Memory hygiene (open-memex)`);
+    lines.push(``);
+    lines.push(`- At checkpoints (session start, end of a work chunk, after the user commits),`, `  distill the session: propose 1–3 short memories capturing the useful`, `  conclusion — what was learned or decided, how an issue was resolved, what`, `  to avoid, where the authoritative doc lives — not the raw transcript.`, `  Save nothing without user approval.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`);
+    lines.push(``);
+    return lines.join("\n");
+}

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.