open-memex 0.4.0-alpha.7 → 0.4.1

package/src/cli.ts

@@ -18,7 +18,7 @@ import {
   type Frontmatter,
 } from "./store/markdown.ts";
 import { loadConfig } from "./config.ts";
-import { paths } from "./paths.ts";
+import { paths, projectRoot } from "./paths.ts";
 import { redact } from "./redact.ts";
 import { resolveMcpCommand } from "./init.ts";
 import fs from "node:fs";
@@ -30,7 +30,10 @@ import { fileURLToPath } from "node:url";
 const COMMAND_HELP: Record<string, string> = {
   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.
 
@@ -71,15 +74,24 @@ Example:
 
   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.
@@ -116,13 +128,76 @@ 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),
@@ -148,15 +223,25 @@ 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.
 
@@ -165,18 +250,30 @@ 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.
@@ -188,24 +285,35 @@ 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): never {
@@ -223,6 +331,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
@@ -237,6 +350,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
@@ -268,18 +384,52 @@ 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: string, value: unknown): Record<string, unknown> {
+  const parts = key.split(".");
+  if (parts.length === 1) return { [key]: value };
+  const cfg = loadConfig() as unknown as Record<string, unknown>;
+  const top = parts[0]!;
+  const cur =
+    cfg[top] && typeof cfg[top] === "object"
+      ? { ...(cfg[top] as Record<string, unknown>) }
+      : {};
+  let node: Record<string, unknown> = cur;
+  for (let i = 1; i < parts.length - 1; i++) {
+    const seg = parts[i]!;
+    const nxt =
+      node[seg] && typeof node[seg] === "object"
+        ? { ...(node[seg] as Record<string, unknown>) }
+        : {};
+    node[seg] = nxt;
+    node = nxt;
+  }
+  node[parts[parts.length - 1]!] = value;
+  return { [top]: cur };
+}
+
 function parseFlags(argv: string[]): Record<string, string> {
   const out: 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";
       }
     }
   }
@@ -409,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`,
@@ -423,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) {
@@ -483,7 +642,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) {
         console.error(`invalid value for ${key}: ${(err as Error).message}`);
@@ -855,6 +1016,139 @@ function positionalArgs(argv: string[]): string[] {
     return;
   }
 
+  // §9 / D12: explicit pull — fetch + fast-forward only, never auto-merge.
+  if (cmd === "pull") {
+    const { GitProvider } = await import("./providers/git.ts");
+    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 as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  // Explicit push — open-memex never pushes on its own (D36).
+  if (cmd === "push") {
+    const { GitProvider } = await import("./providers/git.ts");
+    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 as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  // §9 / D40: portable export bundle (markdown + manifest).
+  if (cmd === "export") {
+    const { exportMemories } = await import("./export.ts");
+    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 as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (cmd === "import") {
+    const { importBundle } = await import("./export.ts");
+    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 as Error).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.ts");
+    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 as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
   if (cmd === "pr-status") {
     const flags = parseFlags(rest);
     try {
@@ -923,6 +1217,10 @@ function positionalArgs(argv: string[]): string[] {
       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/src/config.ts

@@ -19,6 +19,14 @@ export interface MyOMemoryConfig {
    * memories can never escape the repo.
    */
   memoryDir: string;
+  /**
+   * Sync behavior (§9, D12). Pulls are explicit by default; session start
+   * never touches the network unless autoPull is true — and even then a
+   * failed pull never blocks the session.
+   */
+  sync: {
+    autoPull: boolean;
+  };
 }
 
 export const DEFAULT_CONFIG: MyOMemoryConfig = {
@@ -54,6 +62,7 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
   redactPatterns: [],
   logLevel: "info",
   memoryDir: ".ai/open-memex",
+  sync: { autoPull: false },
 };
 
 function stripJsonComments(raw: string): string {
@@ -102,6 +111,7 @@ export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
   injectOnFirstTurn: toBool,
   keywordCaptureEnabled: toBool,
   memoryDir: toRelativeDir,
+  "sync.autoPull": toBool,
   logLevel: (v) => {
     if (v !== "info" && v !== "debug") throw new Error('must be "info" or "debug"');
     return v;

package/src/distill-agents.ts

@@ -0,0 +1,85 @@
+/**
+ * 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.ts";
+
+const DEFAULT_TYPES = ["decision", "constraint", "lesson", "gotcha", "howto"];
+
+export interface DistillAgentsOptions {
+  scopeKeys: string[];
+  types?: string[];
+  limit?: number;
+}
+
+interface Row {
+  id: string;
+  type: string;
+  tags: string;
+  content: string;
+  updated_at: number;
+}
+
+export function distillAgentsMarkdown(opts: DistillAgentsOptions): string {
+  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 as any[]), ...(types as any[]), limit) as Row[];
+
+  if (rows.length === 0) return "";
+  const date = new Date().toISOString().slice(0, 10);
+  const lines: string[] = [
+    `## 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<string, Row[]>();
+  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");
+}