open-memex 0.5.0-alpha.5 → 0.5.1

package/AGENTS.md

@@ -12,7 +12,7 @@ via `prepublishOnly` — Node refuses `--experimental-strip-types` for files und
 
 - **opencode host** loads `src/index.ts` under embedded **Bun**. SQLite here is `bun:sqlite` (built-in).
 - **CLI** (`src/cli.ts`) and smoke tests run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
-- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same ten memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
+- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same eleven memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
 
 `src/store/db.ts` picks the backend at runtime by sniffing `globalThis.Bun`. Both backends share the same surface (`new Database(path)`, `.exec`, `.prepare().run/all/get`, `.close`). Any DB code you write must stay on that common subset — do not import `better-sqlite3` or `bun:sqlite` directly outside `db.ts`.
 
@@ -61,7 +61,7 @@ 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).
+(node version, config, scope resolution, storage writability, VS Code MCP enablement, MCP handshake).
 `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.
 `open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]`
@@ -125,7 +125,7 @@ Context injection happens exactly once per session in `experimental.chat.system.
 
 `docs/V2-DESIGN.md` is the frozen protocol v0.2 (zero open questions). Per its §12:
 AGENTS.md answers "how should AI work here"; the design doc answers "why is it
-built this way" (principles, iron rules, D1–D13 decision log). Before changing
+built this way" (principles, iron rules, D1–D49 decision log). Before changing
 architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
 schema, MCP tools, CLI contract), read the relevant design section — the decision
 log records what was already considered and rejected.
@@ -138,7 +138,7 @@ build roadmap; the design doc tracks the *why*.
 
 ## Branch workflow
 
-`dev/<topic>` → PR → `main` (the v2 line; alpha versions published with
+`dev/<topic>` → PR → `main` (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`.

package/CONTRIBUTING.md

@@ -2,10 +2,13 @@
 
 ## Branch workflow
 
-- `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.
+- `main` — the only line (the `V2` integration branch was retired 2026-09-29).
+  Land work via pull request from a `dev/<topic>` branch. Exception: tiny
+  text-only doc tweaks may go directly to `main`, but only after the owner
+  has previewed and approved the exact change. 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.
 
@@ -25,7 +28,7 @@ branches are cheap.)
 ## Design authority
 
 Protocol decisions live in `docs/V2-DESIGN.md` (frozen v0.2, decision log
-D1–D13). Changing architecture, scope semantics, lifecycle, or the protocol
+D1–D49). Changing architecture, scope semantics, lifecycle, or the protocol
 surface (frontmatter schema, MCP tools, CLI contract) requires updating the
 design doc first. `AGENTS.md` has the working notes for AI agents; this file
 has the contributor workflow.

package/README.md

@@ -23,6 +23,20 @@ automatically.
 
 > No capture, nothing to inherit.
 
+### One memory, every agent
+
+Most developers don't use one AI tool — they use several on the same machine:
+Copilot in VS Code, Cursor, opencode, Claude Code. Each tool keeps
+its own silo: a decision made in one is invisible to the others.
+
+open-memex is tool-agnostic by design. Memory lives as Markdown + SQLite next
+to your project, and every editor talks to it through the same MCP interface.
+Wire up two, three, five clients with `open-memex init` — they all read and
+write the same memory on that machine. A constraint captured in VS Code is respected in
+opencode; a lesson learned in Cursor shows up in Claude Code.
+
+> Your memory belongs to you — not to your tools.
+
 It also complements agentic development workflows (spec-driven development,
 plan/implement/verify loops): plans produce decisions, verification produces
 rules — open-memex is the memory layer that keeps them across sessions instead
@@ -36,6 +50,7 @@ of re-deriving them on every run.
 | Review before sharing | Yes — outbox + PR | Varies | Yes | No |
 | Agent recall | Session-start injection + search | API calls | Manual lookup | No |
 | Human-readable | Plain Markdown files | Dashboard / API | Yes | No |
+| Works across AI tools | Yes — any MCP client (same machine) | Per-integration | No | No |
 
 - **Markdown files** as the source of truth (human-editable, git-friendly)
 - **SQLite FTS5** as a rebuildable index (BM25 keyword search, via `better-sqlite3`)
@@ -90,7 +105,7 @@ personal scope: this machine only — never synced, never enters a repo.
 npm install -g open-memex
 ```
 
-This installs the `0.4.1` stable release.
+This installs the `0.5.1` stable release.
 
 **Alpha** (bleeding edge, for testers) — the `alpha` tag:
 
@@ -219,7 +234,8 @@ 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
+user-level `~/.config/opencode/opencode.json` (or `opencode.jsonc` if that is
+the file you already have) — 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.)
@@ -623,6 +639,18 @@ distill-to-AGENTS.md assist (`distill-agents`, propose-only — you merge by han
 §3.5 checkpoint distillation in the MCP handshake + init instructions (the agent
 proposes 1–3 captures at checkpoints, the human decides); 1–2 colleague pilot.
 
+**`0.5.0` (stable):** init UX pass — `init --global` writes the editor wiring
+once at user level (D45); bare `init` auto-detects installed editors and wires
+them all (D46); non-JSON configs are left untouched with a paste-ready snippet
+instead of an error (D47); `uninstall` reverses `init` without touching memory
+data (D48); empty config files are treated as blank, not corrupt (D49).
+"One memory, every agent": every editor on the same machine reads and writes
+the same memory through one MCP interface.
+
+**`0.5.1` (stable):** `--help` accuracy fixes — the `mcp` help text now states the
+server exposes 11 tools (a superset of the opencode plugin's five memory tools),
+and install hints point at the stable line instead of `@alpha` (F27).
+
 **Future (signal-gated, no version committed):** org layer — org memory repo,
 curator convention; native agent plugins (Claude Code / Codex hooks as
 enhancement paths over the same MCP tools); local embeddings as a
@@ -669,7 +697,7 @@ project. A per-project `.vscode/mcp.json` still wins when present, and the
 entry keeps `cwd=${workspaceFolder}` so project-scope resolution keeps
 working per window. If your user-level `mcp.json` has comments (VS Code
 accepts JSONC), `init` leaves it alone and prints the exact snippet to add
-by hand.
+by hand. An empty file is treated as blank and written to directly.
 
 **How do I remove the editor wiring?**
 `open-memex uninstall` reverses `init`: it removes the MCP server entry,

package/README.zh-CN.md

@@ -21,6 +21,18 @@ open-memex 把值得记住的部分——决策、约束、教训——存成可
 
 > No capture, nothing to inherit.（不记录，就无从传承。）
 
+### 一份记忆，所有 Agent 通用
+
+大多数开发者并不是只用一个 AI 工具——同一台电脑上可能装着 VS Code Copilot、
+Cursor、opencode、Claude Code。但每个工具的记忆都是孤岛：在 A 里定好的决策，B 一无所知。
+
+open-memex 天生与工具无关。记忆以 Markdown + SQLite 的形式存在项目旁边，
+所有编辑器都通过同一个 MCP 接口读写。用 `open-memex init` 接上两三个客户端，
+它们读写的是这台机器上的同一份记忆：在 VS Code 里记下的约束，opencode 会遵守；
+在 Cursor 里学到的教训，Claude Code 也看得到。
+
+> 记忆属于你，不属于工具。
+
 它也补齐了 agentic 开发工作流（spec 驱动开发、plan/implement/verify 循环）缺的那一块：
 plan 产出决策，verify 产出规则——open-memex 是让它们跨会话留存的记忆层，
 而不是每次从头重新推导。
@@ -33,6 +45,7 @@ plan 产出决策，verify 产出规则——open-memex 是让它们跨会话留
 | 分享前 review | 有——outbox + PR | 不一定 | 有 | 没有 |
 | Agent 回忆 | 会话开始注入 + 搜索 | 调 API | 人工去查 | 没有 |
 | 人类可读 | 纯 Markdown 文件 | 后台 / API | 有 | 没有 |
+| 跨 AI 工具通用 | 可以——同一台机器上的任何 MCP 客户端 | 按集成逐个对接 | 不可以 | 不可以 |
 
 - **Markdown 文件**是 source of truth（人类可读、git 友好）
 - **SQLite FTS5** 做可重建索引（BM25 关键词检索，`better-sqlite3`）
@@ -87,7 +100,7 @@ personal scope：只属于这台机器——永不同步，永远进不了仓库
 npm install -g open-memex
 ```
 
-安装的是 `0.4.1` 正式版。
+安装的是 `0.5.1` 正式版。
 
 **Alpha 版**（最新开发版，给测试者）——`alpha` 标签：
 
@@ -213,7 +226,8 @@ open-memex init --client opencode --global --yes
 ```
 
 把 `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` 合并进用户级
-`~/.config/opencode/opencode.json`——一次配置，每个项目自动生效，不用逐个项目
+`~/.config/opencode/opencode.json`（如果你用的是 `opencode.jsonc`，就合并进那个）
+——一次配置，每个项目自动生效，不用逐个项目
 init。在 tools 之外还能获得关键词自动捕获和首轮上下文注入。（带注释的配置文件
 不会被改动——那种情况请手动加 `plugin` 这一行。）
 
@@ -587,6 +601,10 @@ distill-to-AGENTS.md 辅助（`distill-agents`，只提议不改写——人工
 §3.5 检查点蒸馏写进 MCP 握手指令和 init 指令文件
 （agent 在检查点提议 1–3 条捕获，人来定）；找 1–2 个同事做 pilot。
 
+**`0.5.0`（稳定版）：** init 体验整修——`init --global` 一次写好用户级编辑器接线（D45）；裸 `init` 自动检测已装编辑器并一次全接上（D46）；非标准 JSON 配置不再报错，而是原样保留并打印手贴片段（D47）；`uninstall` 逆转 `init` 且永不碰记忆数据（D48）；空配置文件按空白处理、不再误判为损坏（D49）。"一份记忆，所有 Agent 通用"：同一台机器上的每个编辑器，经由同一个 MCP 接口读写同一份记忆。
+
+**`0.5.1`（稳定版）：** `--help` 文案准确性修正——`mcp` 帮助写明 server 暴露 11 个工具（含 opencode 插件的 5 个 memory 工具），安装提示改指稳定版而非 `@alpha`（F27）。
+
 **未来（看信号再定，不承诺版本）：** 组织层——组织记忆仓库、curator 约定；
 原生 agent 插件（Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；
 本地 embedding 做基准测试门控的实验（**未经明确 opt-in 绝不下载
@@ -625,7 +643,7 @@ Linux：`~/.config/Code/User/mcp.json`），每个项目打开 server 都在。
 项目里如果有 `.vscode/mcp.json` 仍然优先；entry 里保留了
 `cwd=${workspaceFolder}`，project scope 按窗口照常工作。
 如果你的用户级 `mcp.json` 带注释（VS Code 接受 JSONC），`init` 不会碰它，
-只打印可直接手贴的配置片段。
+只打印可直接手贴的配置片段。空文件会被当作空白直接写入。
 
 **怎么拆掉编辑器接线？**
 `open-memex uninstall` 就是 `init` 的逆操作：删掉 MCP server 条目、opencode

package/dist/cli.js

@@ -296,8 +296,9 @@ 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.
+storage writability, VS Code MCP enablement (settings.json + system policy),
+then boots a real MCP server and runs initialize + tools/list against it —
+all eleven tools must show up.
 
 Usage: open-memex doctor
 
@@ -343,7 +344,7 @@ 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\`) detects
+One-command project setup: \`open-memex init\` (or \`npx -y open-memex 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\`
@@ -358,9 +359,9 @@ 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
-available directly: \`open-memex mcp\` starts the stdio MCP server (same five
-memory_* tools as the opencode plugin); \`open-memex mcp --print-config <client>\`
+Once installed globally (\`npm i -g open-memex\`) the \`open-memex\` command is
+available directly: \`open-memex mcp\` starts the stdio MCP server (11 tools, a superset of
+the opencode plugin's five memory_* tools); \`open-memex mcp --print-config <client>\`
 prints a copy-paste MCP client config snippet.
 
 Scope defaults to \`project\` (derived from cwd's git remote or path).
@@ -433,7 +434,7 @@ function resolveCliScope(flags, project) {
         : project;
 }
 /** Print a copy-paste MCP client config snippet. Requires a global install
- * (`npm i -g open-memex@alpha`) so the `open-memex` command is on PATH. */
+ * (`npm i -g open-memex`) so the `open-memex` command is on PATH. */
 function printMcpConfig(client) {
     const c = client.toLowerCase();
     // D17: resolve the server command the same way `init` does.
@@ -489,7 +490,7 @@ function printMcpConfig(client) {
         process.exit(1);
     }
     if (!mc.durable) {
-        console.error(`\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex@alpha\` for faster startup.`);
+        console.error(`\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex\` for faster startup.`);
     }
     process.exit(0);
 }
@@ -648,7 +649,7 @@ async function main() {
         }
         return;
     }
-    // `mcp` starts the stdio MCP server (same tools as the opencode plugin).
+    // `mcp` starts the stdio MCP server (11 tools; the opencode plugin exposes 5).
     // Branched before db() — runMcpServer() does its own init, and stdout must
     // stay clean for the MCP protocol.
     if (cmd === "mcp") {

package/dist/doctor.js

@@ -3,8 +3,9 @@
 // Read-only except that paths() and the MCP handshake may create the (empty)
 // data directories, exactly like a normal `open-memex mcp` start would.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.js";
 import { paths } from "./paths.js";
@@ -136,9 +137,146 @@ function mcpCheck() {
         });
     });
 }
+/** Parse JSON tolerating line/block comments plus trailing commas
+ * (VS Code's settings.json is JSONC). Health-check grade, not a full parser. */
+function parseLenientJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        /* fall through to comment stripping */
+    }
+    let out = "";
+    let i = 0;
+    let inStr = false;
+    let esc = false;
+    while (i < raw.length) {
+        const c = raw[i];
+        const n = raw[i + 1];
+        if (inStr) {
+            out += c;
+            if (esc)
+                esc = false;
+            else if (c === "\\")
+                esc = true;
+            else if (c === '"')
+                inStr = false;
+            i++;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === "/" && n === "/") {
+            while (i < raw.length && raw[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c === "/" && n === "*") {
+            i += 2;
+            while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i++;
+            i += 2;
+            continue;
+        }
+        out += c;
+        i++;
+    }
+    out = out.replace(/,\s*([}\]])/g, "$1");
+    return JSON.parse(out);
+}
+function vscodeSettingsPath() {
+    const home = os.homedir();
+    if (process.platform === "win32") {
+        const appdata = process.env.APPDATA;
+        return appdata ? path.join(appdata, "Code", "User", "settings.json") : null;
+    }
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "Code", "User", "settings.json");
+    }
+    return path.join(home, ".config", "Code", "User", "settings.json");
+}
+/** True when a Windows system policy disables MCP (value name contains "mcp",
+ * data is 0/0x0/false). Checks HKLM and HKCU policy keys. */
+function windowsMcpPolicyDisabled() {
+    if (process.platform !== "win32")
+        return null;
+    for (const hive of ["HKLM", "HKCU"]) {
+        try {
+            const stdout = execFileSync("reg", ["query", `${hive}\\SOFTWARE\\Policies\\Microsoft\\VSCode`], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
+            for (const line of stdout.split("\n")) {
+                const m = line.match(/^\s{2,}(\S+)\s+REG_\w+\s+(\S+)/);
+                if (m && /mcp/i.test(m[1]) && /^(0x0|0|false)$/i.test(m[2])) {
+                    return `${hive}\\SOFTWARE\\Policies\\Microsoft\\VSCode!${m[1]}`;
+                }
+            }
+        }
+        catch {
+            /* policy key absent — no policy */
+        }
+    }
+    return null;
+}
+function settingsMcpDisabled(file) {
+    try {
+        const parsed = parseLenientJson(fs.readFileSync(file, "utf8"));
+        return parsed["chat.mcp.enabled"] === false;
+    }
+    catch {
+        return false; // unreadable file: don't claim anything
+    }
+}
+/** VS Code ignores MCP server entries entirely when MCP is switched off —
+ * either in settings.json or, on managed machines, by system policy. */
+function vscodeMcpCheck() {
+    const name = "vscode-mcp";
+    const policyHit = windowsMcpPolicyDisabled();
+    if (policyHit) {
+        return {
+            name,
+            ok: false,
+            detail: `MCP is disabled by system policy (${policyHit}) — managed by your organization. ` +
+                `VS Code will ignore open-memex's MCP entry on this machine.`,
+        };
+    }
+    const files = [];
+    const user = vscodeSettingsPath();
+    if (user)
+        files.push(user);
+    const ws = path.join(process.cwd(), ".vscode", "settings.json");
+    if (!files.includes(ws))
+        files.push(ws);
+    const found = [];
+    const disabled = [];
+    for (const f of files) {
+        if (!fs.existsSync(f))
+            continue;
+        found.push(f);
+        if (settingsMcpDisabled(f))
+            disabled.push(f);
+    }
+    if (disabled.length > 0) {
+        return {
+            name,
+            ok: false,
+            detail: `chat.mcp.enabled is false in ${disabled.join(", ")} — VS Code will not load ` +
+                `MCP servers. Set it to true (or ask IT if the setting shows as managed).`,
+        };
+    }
+    return {
+        name,
+        ok: true,
+        detail: found.length > 0
+            ? `MCP enabled (checked ${found.join(", ")})`
+            : "VS Code settings not found on this machine — nothing to check",
+    };
+}
 export async function runDoctor() {
     console.log("open-memex doctor");
-    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck()];
+    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
     checks.push(await mcpCheck());
     let allOk = true;
     for (const c of checks) {

package/docs/SCOPES.md

@@ -64,14 +64,15 @@ moves `memories/user/` → `memories/personal/` and rewrites the frontmatter
 tree is kept. Reads remain backward compatible: a v1 file with `scope: user`
 is interpreted as `personal`.
 
-## Visibility (planned, not yet enforced)
+## Visibility
 
 v2 frontmatter carries a separate `visibility` field (`private` | `internal` |
-`shared`). The intended rule: `visibility: private` inside a shared scope is
-**physically isolated** — written to a local-only cache directory, never
-under `.open-memex/` — rather than relying on `.gitignore`. This is not
-implemented yet; today, treat `personal` as the only confidentiality
-boundary and review anything you place under `.open-memex/` before pushing.
+`shared`), defaulting to `private` for the personal scope and `internal` for
+the project scope. `open-memex export` excludes `visibility: private` memories
+by default (`--all` / `-a` includes them, D40). Physical isolation of private
+memories into a local-only cache directory is still planned; today, treat
+`personal` as the only hard confidentiality boundary and review anything you
+place under `.ai/open-memex/` before pushing.
 
 ## Reserved names
 

package/docs/TEST-PLAN.md

@@ -1,4 +1,4 @@
-# OpenMemex 测试计划（v0.4.0-alpha.10）
+# OpenMemex 测试计划（v0.5.1）
 
 > 自动化部分：`node --experimental-strip-types scripts/test-full.ts`
 > 62 项全过（26 个 CLI 命令 + 11 个 MCP tool），隔离环境运行，不碰真实数据。
@@ -6,7 +6,7 @@
 
 ## A. Windows 真机 + VS Code Copilot
 
-- [ ] `npm i -g open-memex@alpha` 全局安装，`open-memex --version` 显示正确版本
+- [ ] `npm i -g open-memex` 全局安装（稳定版），`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?"
@@ -60,10 +60,17 @@
 
 ## G. 同事 pilot（1–2 人，Stone 私下选）
 
-- [ ] 对方 `npx open-memex@alpha init` 走通
+- [ ] 对方 `npx -y open-memex init` 走通
 - [ ] 对方能 propose → 你这边能看到 PR → promote 流程走通
 - [ ] 收集反馈：哪里卡、哪里不符合直觉
 
+## I. init/uninstall 行为（D47–D49）
+
+- [ ] 空的 `mcp.json`：`open-memex init --client vscode` 直接写入，不再报 "not valid JSON"（D49）
+- [ ] 带注释的 `mcp.json`：`init` 不动文件，只打印手贴片段（D47）
+- [ ] `open-memex uninstall --client vscode` 移除接线条目，记忆数据不动；再跑 `init` 可恢复（D48）
+- [ ] 裸 `open-memex uninstall`（交互终端）会先确认再清所有编辑器；`--yes` 跳过确认
+
 ## H. 已知问题观察
 
 - [ ] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：注意是否丢数据（预期：不丢，只影响退出码）

package/docs/USER-GUIDE.md

@@ -2,9 +2,8 @@
 
 > This document describes open-memex's **mental model**: where your memories live,
 > how they flow, and who can see them. The in-repo directory (§2, §6 write path)
-> and the propose → promote → resolve workflow (§5) are implemented on the
-> `V2-dev-p2b` branch; features marked **2B** are still to be built;
-> everything else is 0.3.0 behavior.
+> and the propose → promote → resolve workflow (§5) shipped in 0.4.0
+> (Phase 2B); everything described here is current as of 0.5.0.
 
 ## In one sentence
 
@@ -172,7 +171,7 @@ personal idea ──propose──▶ outbox draft ──submit──▶ proposed
 - **Submit** (explicit, your call): `open-memex submit <id...>` → local branch
   + local commit into `.ai/open-memex/`; push/PR are printed for you (or done
   by your agent on your Yes).
-- **Pull** **2B**: `open-memex pull` (always explicit, never automatic) → git fetch +
+- **Pull**: `open-memex pull` (always explicit, never automatic) → git fetch +
   fast-forward → scans `.ai/open-memex/*.md` → merges into the local `index.db` by
   file mtime. Retrieval always goes through SQLite, never walks git.
 - **personal scope**: never syncs (§1 iron rule).
@@ -194,4 +193,4 @@ personal idea ──propose──▶ outbox draft ──submit──▶ proposed
 
 ---
 
-*Companion design record: `docs/V2-DESIGN.md` (decisions D1–D24).*
+*Companion design record: `docs/V2-DESIGN.md` (decisions D1–D49).*

package/docs/USER-GUIDE.zh-CN.md

@@ -2,8 +2,7 @@
 
 > 本文档讲的是 open-memex 的**心智模型**：你的记忆住在哪里、怎么流动、谁能看到。
 > in-repo 目录（§2、§6 的写路径）和 propose → promote → resolve 工作流（§5）
-> 已在 `V2-dev-p2b` 分支实现；标有 **2B** 的功能属于 Phase 2B 待实现部分，
-> 其余为 0.3.0 已有行为。
+> 已随 0.4.0（Phase 2B）发布；本文描述的均为 0.5.0 现行行为。
 
 ## 一句话
 
@@ -143,7 +142,7 @@ server 不能主动推送，调不调 `memory_search` 全看 model 的判断。
   **不碰 repo、不自动 commit、不自动 push**。
 - **交**（显式，你说了算）：`open-memex submit <id...>` → 本地分支 + 本地 commit
   进 `.ai/open-memex/`；push/PR 命令打印给你（或你的 agent 拿着你的 Yes 自己做）。
-- **拉** **2B**：`open-memex pull`（必须显式，没有自动）→ git fetch + fast-forward →
+- **拉**：`open-memex pull`（必须显式，没有自动）→ git fetch + fast-forward →
   扫描 `.ai/open-memex/*.md` → 按文件 mtime 合进本地 `index.db`。检索永远走 SQLite，不 walk git。
 - **personal scope**：永远不同步（§1 铁律）。
 - **没 git 的项目**：照常用，project scope 降级为纯本地并明确提示，不会坏掉。
@@ -158,4 +157,4 @@ server 不能主动推送，调不调 `memory_search` 全看 model 的判断。
 
 ---
 
-*配套设计文档：`docs/V2-DESIGN.md`（D1–D24 决策记录）。*
+*配套设计文档：`docs/V2-DESIGN.md`（D1–D49 决策记录）。*

package/docs/V2-DESIGN.md

@@ -494,7 +494,7 @@ Zero-config is survival for an open-source project. The opencode plugin remains
 - **Phase 1 — Local hardening (1–2 wks).** CJK default (bigram+FTS5) · v1→v2 migration · dedup +
   lifecycle · redaction hardening · scope docs. No external dependencies.
 - **Phase 2A — MCP server (shipped 2026-09-27, D15).** Core/adapters split
-  (`src/tools/ops.ts`) · MCP server (`src/mcp.ts`, stdio) exposing all five memory tools —
+  (`src/tools/ops.ts`) · MCP server (`src/mcp.ts`, stdio) exposing all eleven memory tools —
   read-only-first phasing dropped per D15 · query-aware injection stays host-side.
   Ships in **`0.3.0-alpha`** (with bin/npx user-friendliness polish per §17 adoption path).
 - **Phase 2B — Team sync.** GitProvider · `propose/promote/resolve` · in-repo dir · 1–2 colleague pilot
@@ -538,6 +538,14 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   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).
+- **0.5.0 (stable, 2026-09-29).** Init UX pass: `init --global` user-level editor
+  wiring (D45) · bare-init auto-detect wires all installed editors (D46) · JSONC
+  configs left untouched with a paste-ready snippet (D47) · `uninstall` reverses
+  `init` without touching memory data (D48) · empty config files treated as
+  blank, not corrupt (D49).
+- **0.5.1 (stable).** `--help` accuracy: `mcp` help states the server exposes 11
+  tools (a superset of the opencode plugin's five memory tools); install hints point
+  at the stable line instead of `@alpha` (F27).
 - **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.5.0-alpha.5",
+  "version": "0.5.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",

package/src/cli.ts

@@ -329,8 +329,9 @@ 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.
+storage writability, VS Code MCP enablement (settings.json + system policy),
+then boots a real MCP server and runs initialize + tools/list against it —
+all eleven tools must show up.
 
 Usage: open-memex doctor
 
@@ -377,7 +378,7 @@ 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\`) detects
+One-command project setup: \`open-memex init\` (or \`npx -y open-memex 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\`
@@ -392,9 +393,9 @@ 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
-available directly: \`open-memex mcp\` starts the stdio MCP server (same five
-memory_* tools as the opencode plugin); \`open-memex mcp --print-config <client>\`
+Once installed globally (\`npm i -g open-memex\`) the \`open-memex\` command is
+available directly: \`open-memex mcp\` starts the stdio MCP server (11 tools, a superset of
+the opencode plugin's five memory_* tools); \`open-memex mcp --print-config <client>\`
 prints a copy-paste MCP client config snippet.
 
 Scope defaults to \`project\` (derived from cwd's git remote or path).
@@ -471,7 +472,7 @@ function resolveCliScope(flags: Record<string, string>, project: Scope): Scope {
 }
 
 /** Print a copy-paste MCP client config snippet. Requires a global install
- * (`npm i -g open-memex@alpha`) so the `open-memex` command is on PATH. */
+ * (`npm i -g open-memex`) so the `open-memex` command is on PATH. */
 function printMcpConfig(client: string): never {
   const c = client.toLowerCase();
   // D17: resolve the server command the same way `init` does.
@@ -547,7 +548,7 @@ function printMcpConfig(client: string): never {
   }
   if (!mc.durable) {
     console.error(
-      `\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex@alpha\` for faster startup.`,
+      `\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex\` for faster startup.`,
     );
   }
   process.exit(0);
@@ -724,7 +725,7 @@ async function main() {
     return;
   }
 
-  // `mcp` starts the stdio MCP server (same tools as the opencode plugin).
+  // `mcp` starts the stdio MCP server (11 tools; the opencode plugin exposes 5).
   // Branched before db() — runMcpServer() does its own init, and stdout must
   // stay clean for the MCP protocol.
   if (cmd === "mcp") {

package/src/doctor.ts

@@ -3,8 +3,9 @@
 // Read-only except that paths() and the MCP handshake may create the (empty)
 // data directories, exactly like a normal `open-memex mcp` start would.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.ts";
 import { paths } from "./paths.ts";
@@ -158,9 +159,145 @@ function mcpCheck(): Promise<Check> {
   });
 }
 
+/** Parse JSON tolerating line/block comments plus trailing commas
+ * (VS Code's settings.json is JSONC). Health-check grade, not a full parser. */
+function parseLenientJson(raw: string): Record<string, unknown> {
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    /* fall through to comment stripping */
+  }
+  let out = "";
+  let i = 0;
+  let inStr = false;
+  let esc = false;
+  while (i < raw.length) {
+    const c = raw[i];
+    const n = raw[i + 1];
+    if (inStr) {
+      out += c;
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      inStr = true;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && n === "/") {
+      while (i < raw.length && raw[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && n === "*") {
+      i += 2;
+      while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  out = out.replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(out) as Record<string, unknown>;
+}
+
+function vscodeSettingsPath(): string | null {
+  const home = os.homedir();
+  if (process.platform === "win32") {
+    const appdata = process.env.APPDATA;
+    return appdata ? path.join(appdata, "Code", "User", "settings.json") : null;
+  }
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", "Code", "User", "settings.json");
+  }
+  return path.join(home, ".config", "Code", "User", "settings.json");
+}
+
+/** True when a Windows system policy disables MCP (value name contains "mcp",
+ * data is 0/0x0/false). Checks HKLM and HKCU policy keys. */
+function windowsMcpPolicyDisabled(): string | null {
+  if (process.platform !== "win32") return null;
+  for (const hive of ["HKLM", "HKCU"]) {
+    try {
+      const stdout = execFileSync(
+        "reg",
+        ["query", `${hive}\\SOFTWARE\\Policies\\Microsoft\\VSCode`],
+        { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] },
+      ) as string;
+      for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s{2,}(\S+)\s+REG_\w+\s+(\S+)/);
+        if (m && /mcp/i.test(m[1]) && /^(0x0|0|false)$/i.test(m[2])) {
+          return `${hive}\\SOFTWARE\\Policies\\Microsoft\\VSCode!${m[1]}`;
+        }
+      }
+    } catch {
+      /* policy key absent — no policy */
+    }
+  }
+  return null;
+}
+
+function settingsMcpDisabled(file: string): boolean {
+  try {
+    const parsed = parseLenientJson(fs.readFileSync(file, "utf8"));
+    return parsed["chat.mcp.enabled"] === false;
+  } catch {
+    return false; // unreadable file: don't claim anything
+  }
+}
+
+/** VS Code ignores MCP server entries entirely when MCP is switched off —
+ * either in settings.json or, on managed machines, by system policy. */
+function vscodeMcpCheck(): Check {
+  const name = "vscode-mcp";
+  const policyHit = windowsMcpPolicyDisabled();
+  if (policyHit) {
+    return {
+      name,
+      ok: false,
+      detail:
+        `MCP is disabled by system policy (${policyHit}) — managed by your organization. ` +
+        `VS Code will ignore open-memex's MCP entry on this machine.`,
+    };
+  }
+  const files: string[] = [];
+  const user = vscodeSettingsPath();
+  if (user) files.push(user);
+  const ws = path.join(process.cwd(), ".vscode", "settings.json");
+  if (!files.includes(ws)) files.push(ws);
+  const found: string[] = [];
+  const disabled: string[] = [];
+  for (const f of files) {
+    if (!fs.existsSync(f)) continue;
+    found.push(f);
+    if (settingsMcpDisabled(f)) disabled.push(f);
+  }
+  if (disabled.length > 0) {
+    return {
+      name,
+      ok: false,
+      detail:
+        `chat.mcp.enabled is false in ${disabled.join(", ")} — VS Code will not load ` +
+        `MCP servers. Set it to true (or ask IT if the setting shows as managed).`,
+    };
+  }
+  return {
+    name,
+    ok: true,
+    detail:
+      found.length > 0
+        ? `MCP enabled (checked ${found.join(", ")})`
+        : "VS Code settings not found on this machine — nothing to check",
+  };
+}
+
 export async function runDoctor(): Promise<boolean> {
   console.log("open-memex doctor");
-  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck()];
+  const checks: Check[] = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
   checks.push(await mcpCheck());
   let allOk = true;
   for (const c of checks) {