open-memex 0.4.0 → 0.5.0-alpha.2

package/AGENTS.md

@@ -49,16 +49,21 @@ node --experimental-strip-types scripts\smoke-mcp.ts    # MCP handshake + tool r
 After `npm i -g open-memex` (or `npm link` from source), the `open-memex` bin is on
 PATH: `open-memex mcp` starts the MCP server, `open-memex mcp --print-config <client>`
 prints a client config snippet (client: vscode|cursor|claude|opencode|visualstudio),
-`open-memex init [--client vscode|cursor|opencode|visualstudio] [--instructions personal|project] [--force] [--yes]`
+`open-memex init [--client vscode|cursor|opencode|visualstudio] [--instructions personal|project] [--global] [--force] [--yes]`
 one-command project setup (editor MCP config + Copilot memory instructions;
+no --client → auto-detects installed editors and wires them all, user-level
+where supported — init once, every editor, every project (D46);
 instructions default to user-level ~/.copilot/copilot-instructions.md so the repo
-stays clean for teammates without open-memex — D22; resolves the server command
+stays clean for teammates without open-memex — D22; `--global` writes the MCP
+server entry to the editor's user-level config instead (VS Code / Cursor; D45)
+or the opencode native plugin entry into ~/.config/opencode/opencode.json (D46);
+resolves the server command
 at init time — npx fallback when no durable bin is on PATH, D17),
 `open-memex config` prints the effective config, `open-memex capture --dry-run "text"`
 previews keyword capture without writing, `open-memex doctor` runs health checks
 (node version, config, scope resolution, storage writability, MCP handshake).
-`open-memex init` asks editor + two settings on a TTY (`--yes` skips, scripts never
-prompt); `open-memex config set <key> <value>` edits settings after install.
+`open-memex init` with no --client auto-detects and wires every installed editor
+(`--yes` skips, scripts never prompt); `open-memex config set <key> <value>` edits settings after install.
 The published `open-memex` bin points at `dist/cli.js` (compiled at publish time).
 From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
 with type-stripping — no build step needed for development.
@@ -126,9 +131,10 @@ build roadmap; the design doc tracks the *why*.
 
 ## Branch workflow
 
-`main` (stable, mirrors npm) ← `V2` (v2 integration) ← `V2-dev-p<n>`
-(phase work; draft PRs into `V2`). Never create `V2/<anything>` — git can't
-hold `V2` and `V2/…` simultaneously. Full rules: `CONTRIBUTING.md`.
+`dev/<topic>` → PR → `main` (the v2 line; alpha versions published with
+`npm publish --tag alpha`, npm `latest` moves only on stable releases).
+The `V2` integration branch was retired 2026-09-29 — its job (isolating the
+breaking v1→v2 transition) shipped with 0.3.0. Full rules: `CONTRIBUTING.md`.
 
 ## Style notes
 

package/CONTRIBUTING.md

@@ -2,17 +2,17 @@
 
 ## Branch workflow
 
-- `main` — stable. Mirrors the npm release line. Never commit directly;
-  only merge from `V2` when a milestone is tested and ready to release.
-- `V2` — integration branch for the v2 line. Phase work lands here via
-  pull request. Merges to `main` only after the milestone is dogfooded
-  (plugin tested in opencode, `migrate --to-v2 --dry-run` clean on real data).
-- `V2-dev-p<n>` — phase dev branches (e.g. `V2-dev-p1`). Open as **draft**
-  PRs against `V2`; mark ready and merge after local testing passes.
+- `main` — the v2 line. Never commit directly; land work via pull request
+  from a dev branch. Alpha versions (e.g. `0.5.0-alpha.x`) live on `main`;
+  publish them with `npm publish --tag alpha` so the npm `latest` tag only
+  moves on stable releases.
+- `dev/<topic>` — feature/fix branches (e.g. `dev/init-ux`). Open as **draft**
+  PRs against `main`; mark ready and merge after local testing passes.
 
-**Naming rule:** never create `V2/<anything>` — git cannot hold a branch
-named `V2` and a branch named `V2/…` at the same time (ref file vs.
-directory conflict). Use the flat `V2-dev-*` form instead.
+(The `V2` integration branch was retired 2026-09-29 — it existed only to
+isolate the breaking v1→v2 transition, which shipped with 0.3.0. If a future
+breaking change ever needs isolation, create an integration branch then;
+branches are cheap.)
 
 ## Before opening a PR
 

package/README.md

@@ -1,5 +1,7 @@
 # open-memex
 
+> A shared organizational memory layer that helps people and AI capture, retain, and reuse institutional knowledge.
+
 [![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
 
@@ -154,6 +156,17 @@ folders under your global npm root and install again.
 
 Run from your **project root** (so the project scope resolves to this repo):
 
+```sh
+open-memex init --yes
+# …or without a global install:
+npx -y open-memex init --yes
+```
+
+With no `--client`, `init` **detects your installed editors and wires them all**
+— user-level where the editor supports it (VS Code / Cursor MCP config, opencode
+native plugin), so one init covers every project. Visual Studio joins in when the
+project has a solution file. Prefer to pick a single editor? Pass `--client`:
+
 **VS Code** (Copilot):
 
 ```sh
@@ -173,16 +186,40 @@ open-memex init --client cursor
 
 Writes `.cursor/mcp.json` and user-level Copilot instructions.
 
+**One-time setup for all projects (VS Code / Cursor):**
+
+```sh
+open-memex init --client vscode --global --yes
+```
+
+Writes the server entry to the editor's *user-level* MCP config
+(`%APPDATA%\Code\User\mcp.json` on Windows,
+`~/Library/Application Support/Code/User/mcp.json` on macOS,
+`~/.config/Code/User/mcp.json` on Linux; `~/.cursor/mcp.json` for Cursor)
+instead of the project — init once, the server starts in every project.
+A per-project `.vscode/mcp.json` still wins if a project defines its own.
+(On a TTY, `init` asks whether the config should be per-project or user-level.)
+
+**opencode** (native plugin — recommended):
+
+```sh
+open-memex init --client opencode --global --yes
+```
+
+Merges `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` into your
+user-level `~/.config/opencode/opencode.json` — one-time, every project picks it
+up, no per-project init. You get keyword auto-capture and first-turn context
+injection on top of the tools. (A config file with comments is left untouched —
+add the `plugin` line by hand in that case.)
+
 **opencode** (as a plain MCP consumer):
 
 ```sh
 open-memex init --client opencode
 ```
 
-Writes project-level `opencode.jsonc` (`type: "local"`). Prefer the native plugin
-instead? Add `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` to
-`~/.config/opencode/opencode.jsonc` — you get keyword auto-capture and first-turn
-context injection on top of the tools.
+Writes project-level `opencode.jsonc` (`type: "local"`). Needed only if you
+prefer plain MCP over the native plugin.
 
 **Claude Code** (from your project root):
 
@@ -208,16 +245,25 @@ above works too.
 
 `init` notes:
 
+- With no `--client`, `init` auto-detects installed editors (VS Code via `code`
+  on `PATH` / install location / existing user config; Cursor via `cursor` on
+  `PATH` or `~/.cursor`; opencode via `opencode` on `PATH` or its config dir;
+  Visual Studio when the project has a `.sln`) and wires them all — user-level
+  where supported, so one init covers every project.
+- `--global` writes the MCP server entry to the editor's user-level config
+  (VS Code / Cursor) — one init for all projects. For opencode, `--global`
+  wires the native plugin at user level (no per-project init needed);
+  Visual Studio stays solution-level by design.
 - The Copilot memory instructions default to **user-level**
   (`~/.copilot/copilot-instructions.md`; `%USERPROFILE%\copilot-instructions.md`
   for Visual Studio) — they apply to all your projects and are never checked
   into a repo, so teammates without open-memex see nothing and nothing breaks
   for them. `--instructions project` writes `.github/copilot-instructions.md`
   instead, for teams where everyone uses open-memex.
-- On a terminal it interactively asks which editor to set up, whether to enable
-  keyword auto-capture, and whether to inject memories on the first turn.
-  `--yes` accepts the defaults; scripts / non-TTY never prompt (editor defaults to
-  VS Code).
+- On a terminal it shows the detected editors, asks you to confirm wiring them
+  all (or pick one), and asks whether to enable keyword auto-capture and
+  first-turn memory injection. `--yes` accepts the defaults; scripts /
+  non-TTY never prompt and wire every detected editor.
 - Existing config files are **merged, never clobbered** — re-running is safe.
   `--force` overwrites.
 - With no durable `open-memex` on `PATH` (e.g. one-shot npx), `init` writes an

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # open-memex
 
+> 共享组织记忆层，帮助人与 AI 捕获、沉淀并复用组织知识。
+
 [![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
 
@@ -149,6 +151,17 @@ Windows 下被进程加载的 DLL 是锁死的：如果 open-memex MCP server
 
 在**项目根目录**下运行（这样 project scope 会解析到这个仓库）：
 
+```sh
+open-memex init --yes
+# ……没装全局包的话：
+npx -y open-memex init --yes
+```
+
+不带 `--client` 时，`init` 会**自动检测本机装了哪些编辑器，一次全接上**——
+支持用户级的编辑器走用户级（VS Code / Cursor 的 MCP 配置、opencode 原生插件），
+一次 init，所有项目通用；项目里有 solution 文件时 Visual Studio 也会一起配。
+想只配某一个编辑器？加 `--client`：
+
 **VS Code**（Copilot）：
 
 ```sh
@@ -168,16 +181,39 @@ open-memex init --client cursor
 
 自动写 `.cursor/mcp.json` 和用户级 Copilot instructions。
 
+**一次配置、所有项目通用（VS Code / Cursor）：**
+
+```sh
+open-memex init --client vscode --global --yes
+```
+
+把 server 条目写到编辑器的*用户级* MCP 配置（Windows 下是
+`%APPDATA%\Code\User\mcp.json`，macOS 是
+`~/Library/Application Support/Code/User/mcp.json`，Linux 是
+`~/.config/Code/User/mcp.json`；Cursor 是 `~/.cursor/mcp.json`），
+而不是写到项目里——init 一次，每个项目打开自动启动 server。
+如果某个项目自己定义了 `.vscode/mcp.json`，项目级的优先。
+（终端交互模式下，`init` 会问你配到项目级还是用户级。）
+
+**opencode**（原生插件——推荐）：
+
+```sh
+open-memex init --client opencode --global --yes
+```
+
+把 `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` 合并进用户级
+`~/.config/opencode/opencode.json`——一次配置，每个项目自动生效，不用逐个项目
+init。在 tools 之外还能获得关键词自动捕获和首轮上下文注入。（带注释的配置文件
+不会被改动——那种情况请手动加 `plugin` 这一行。）
+
 **opencode**（作为普通 MCP 客户端）：
 
 ```sh
 open-memex init --client opencode
 ```
 
-写项目级 `opencode.jsonc`（`type: "local"`）。想用原生插件？
-在 `~/.config/opencode/opencode.jsonc` 里加
-`"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]`——
-在 tools 之外还能获得关键词自动捕获和首轮上下文注入。
+写项目级 `opencode.jsonc`（`type: "local"`）。只有当你更想要纯 MCP 而不是原生
+插件时才需要。
 
 **Claude Code**（在项目根目录运行）：
 
@@ -208,11 +244,19 @@ Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，
   到 repo，没装 open-memex 的同事看不到、也不会出错。团队人人都用
   open-memex 时可用 `--instructions project` 改写
   `.github/copilot-instructions.md`。
-- 在终端里会交互式询问：配哪个编辑器、是否开启关键词自动捕获、
-  是否在首轮注入记忆。`--yes` 全用默认值；脚本 / 非 TTY 环境不提问
-  （编辑器默认 VS Code）。
+- 不带 `--client` 时，`init` 自动检测已安装的编辑器（VS Code 看 `PATH` 有没有
+  `code` / 安装位置 / 已有的用户级配置；Cursor 看 `PATH` 有没有 `cursor` 或
+  `~/.cursor`；opencode 看 `PATH` 有没有 `opencode` 或其配置目录；项目里有
+  `.sln` 时算上 Visual Studio），一次全接上——支持用户级的走用户级，
+  一次 init，所有项目通用。
+- 在终端里会列出检测到的编辑器，请你确认是一次全配还是只配一个，
+  再问是否开启关键词自动捕获、是否在首轮注入记忆。`--yes` 全用默认值；
+  脚本 / 非 TTY 环境不提问，直接配所有检测到的编辑器。
 - 已有配置文件会被**合并，不会被覆盖**——重复运行是安全的。
   `--force` 强制覆盖。
+- `--global` 把 MCP server 条目写到编辑器的用户级配置（VS Code / Cursor）——
+  一次配置，所有项目通用。opencode 的 `--global` 走用户级原生插件，
+  不用逐个项目 init；Visual Studio 按设计保持 solution 级。
 - 如果 `PATH` 上没有可用的 `open-memex`（比如一次性 npx），`init` 会把
   `npx -y open-memex mcp` 写进配置，配置照样能用。
   以后 `npm i -g open-memex` + `open-memex init --force` 可切换到更快

package/dist/cli.js

@@ -223,11 +223,15 @@ Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict
 
 Flags:
   --from / --to   scope keys (default: current project → personal)
-  --dry-run       preview without moving anything
+  --dry-run       preview without moving anything (--to-v2 previews the legacy
+                  files in place, including per-file conversion plans)
   --on-conflict   newer (default), overwrite, or skip
   --to-v2         convert a legacy my-o-memory data dir to the v2 layout
 
 Always preview with --dry-run first; nothing moves without confirmation.
+On Windows, if another program holds the legacy folder open, the backup
+rename fails with an actionable message instead of a stack trace — close
+the program and re-run.
 
 Examples:
   open-memex migrate --dry-run
@@ -246,16 +250,21 @@ Examples:
 agent memory instructions. Existing files are merged, never clobbered.
 
 Usage: open-memex init [--client vscode|cursor|opencode|visualstudio]
-              [--instructions personal|project] [--force] [--yes]
+              [--instructions personal|project] [--global] [--force] [--yes]
 
 Flags:
-  --client        editor to configure (default: auto-detect)
+  --client        editor to configure (default: auto-detect all installed editors)
   --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
+  --global        write the MCP server entry to the editor's user-level config
+                  (VS Code / Cursor) — init once, works in every project.
+                  For opencode, --global wires the native plugin at user level
+                  (~/.config/opencode/opencode.json) — no per-project init needed.
   --force         overwrite existing config
   --yes           accept all defaults, never prompt
 
 Examples:
   open-memex init
+  open-memex init --client vscode --global --yes
   open-memex init --client cursor --yes`,
     config: `Show config, or set a key.
 
@@ -316,16 +325,19 @@ Usage:
 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
-needed. The Copilot memory instructions default to your user-level
+One-command project setup: \`open-memex init\` (or \`npx open-memex@alpha init\`) detects
+your installed editors and wires them all — user-level where the editor supports it
+(VS Code / Cursor MCP config, opencode native plugin), so one init covers every project;
+Visual Studio is included when the project has a solution file (its \`.mcp.json\`
+stays solution-level by design). \`--client\` picks a single editor instead, and a
+single-editor opencode init writes the per-project plain-MCP \`opencode.jsonc\`.
+The Copilot memory instructions default to your user-level
 \`~/.copilot/copilot-instructions.md\` (all projects, never checked into a repo);
 \`--instructions project\` writes \`.github/copilot-instructions.md\` instead for
 teams where everyone uses open-memex.
 Existing files are merged, never clobbered; re-running is safe. On a terminal it
-asks which editor to set up and a couple of settings (keyword capture, first-turn
-injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
+confirms the detected editors and asks a couple of settings (keyword capture,
+first-turn injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
 \`open-memex config set <key> <value>\` changes those settings after install.
 
 Once installed globally (\`npm i -g open-memex@alpha\`) the \`open-memex\` command is
@@ -376,14 +388,21 @@ function parseFlags(argv) {
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a.startsWith("--")) {
-            const key = a.slice(2);
+            const raw = a.slice(2);
+            const eq = raw.indexOf("=");
+            if (eq >= 0) {
+                // D44: accept --key=value as well as --key value (issue #7 — the
+                // = form was silently misparsed before, dropping the flag).
+                out[raw.slice(0, eq)] = raw.slice(eq + 1);
+                continue;
+            }
             const val = argv[i + 1];
             if (val !== undefined && !val.startsWith("--")) {
-                out[key] = val;
+                out[raw] = val;
                 i++;
             }
             else {
-                out[key] = "true";
+                out[raw] = "true";
             }
         }
     }
@@ -486,7 +505,15 @@ async function main() {
     if (cmd === "migrate" && rest.includes("--to-v2")) {
         const flags = parseFlags(rest);
         const dryRun = flags["dry-run"] === "true";
-        const stats = migrateV2({ dryRun });
+        let stats;
+        try {
+            stats = migrateV2({ dryRun });
+        }
+        catch (err) {
+            // D44: actionable message, not a raw syscall stack (issue #7).
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
         console.log(`${dryRun ? "DRY RUN: " : ""}scanned ${stats.scanned} files: ` +
             `${stats.converted} to convert, ${stats.skippedV2} already v2`);
         for (const p of stats.plans) {
@@ -496,7 +523,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; ` +
@@ -505,7 +534,7 @@ async function main() {
         return;
     }
     // `init` is a pure file operation (§17 adoption path) — no DB needed.
-    // Interactive when on a TTY (asks editor + settings); --yes skips prompts.
+    // Interactive when on a TTY (confirms detected editors + settings); --yes skips prompts.
     if (cmd === "init") {
         const flags = parseFlags(rest);
         const { initProject } = await import("./init.js");
@@ -514,6 +543,7 @@ async function main() {
             force: flags["force"] === "true",
             yes: flags["yes"] === "true",
             instructions: flags["instructions"],
+            global: flags["global"] === "true",
         });
         return;
     }