open-memex 0.4.0-alpha.7 → 0.4.1

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]
@@ -143,17 +223,29 @@ 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.`,
+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
+  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 +256,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 +298,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 +317,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,19 +350,51 @@ 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++) {
         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";
             }
         }
     }
@@ -354,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) {
@@ -364,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; ` +
@@ -418,7 +571,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 +936,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 +1134,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");
+}