open-memex 0.5.0-alpha.2 → 0.5.0-alpha.4

package/README.md

@@ -90,7 +90,7 @@ personal scope: this machine only — never synced, never enters a repo.
 npm install -g open-memex
 ```
 
-This installs the `0.4.0` stable release.
+This installs the `0.4.1` stable release.
 
 **Alpha** (bleeding edge, for testers) — the `alpha` tag:
 
@@ -114,10 +114,10 @@ npx -y open-memex <command>         # e.g. npx -y open-memex init --client vscod
 npx -y open-memex@alpha <command>  # alpha line, no install
 ```
 
-**From source** (bleeding edge, `V2-dev-p2` branch):
+**From source** (bleeding edge, `main` branch):
 
 ```sh
-git clone -b V2-dev-p2 https://github.com/stoneskin/open-memex.git
+git clone -b main https://github.com/stoneskin/open-memex.git
 cd open-memex
 npm install
 node --experimental-strip-types src/cli.ts <command>
@@ -158,7 +158,7 @@ Run from your **project root** (so the project scope resolves to this repo):
 
 ```sh
 open-memex init --yes
-# …or without a global install:
+# …or without installing the package first:
 npx -y open-memex init --yes
 ```
 
@@ -167,16 +167,25 @@ With no `--client`, `init` **detects your installed editors and wires them all**
 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`:
 
+> **Two different "globals" — don't mix them up.**
+> - `npm install -g open-memex` installs the *package* globally: it puts the
+>   `open-memex` command on your PATH.
+> - `init --global` writes the *editor config* at user level instead of the
+>   project: init once, the wiring works in every project. It works the same
+>   whether the package was installed globally or run via npx.
+
 **VS Code** (Copilot):
 
 ```sh
 open-memex init --client vscode
-# …or without a global install:
+# …or without installing the package first:
 npx -y open-memex init --client vscode
 ```
 
-Writes `.vscode/mcp.json` and user-level Copilot instructions, then reload the
-window and confirm the `open-memex` server is started in Copilot Chat's MCP panel.
+Wires the project-level `.vscode/mcp.json` and user-level Copilot instructions,
+then reload the window and confirm the `open-memex` server is started in Copilot
+Chat's MCP panel. On a TTY, `init` asks whether the MCP config should be
+per-project or user-level instead of guessing; `--global` forces user-level.
 
 **Cursor:**
 
@@ -184,7 +193,9 @@ window and confirm the `open-memex` server is started in Copilot Chat's MCP pane
 open-memex init --client cursor
 ```
 
-Writes `.cursor/mcp.json` and user-level Copilot instructions.
+Same shape as VS Code: project-level `.cursor/mcp.json` by default, user-level
+with `--global` (or when `init` asks on a TTY), plus user-level Copilot
+instructions.
 
 **One-time setup for all projects (VS Code / Cursor):**
 
@@ -198,7 +209,8 @@ Writes the server entry to the editor's *user-level* MCP config
 `~/.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.)
+If the user-level file has comments in it (VS Code accepts JSONC), `init` leaves
+the file untouched and prints the exact snippet to paste in by hand.
 
 **opencode** (native plugin — recommended):
 
@@ -243,6 +255,17 @@ above works too.
 `open-memex mcp --print-config` as a starting point (`[mcp_servers]` in
 `config.toml`, or `codex mcp add`).
 
+**Remove the wiring:**
+
+```sh
+open-memex uninstall --yes
+```
+
+Reverses `init` — removes the MCP server entry, the opencode plugin line, and
+the open-memex section of the Copilot instructions. With no `--client` it cleans
+up every detected editor (project-level and user-level wiring); `--global`
+limits the cleanup to user-level. Your memories are never touched.
+
 `init` notes:
 
 - With no `--client`, `init` auto-detects installed editors (VS Code via `code`
@@ -437,7 +460,9 @@ Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
 Setup & health:
 
 ```sh
-open-memex init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
+open-memex init [--client vscode|cursor|opencode|visualstudio]
+              [--instructions personal|project] [--global] [--force] [--yes]
+open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]
 open-memex config                                  # print effective config
 open-memex config set <key> <value>                # change a setting
 open-memex doctor                                  # environment health check
@@ -607,6 +632,52 @@ sharing, ACL, or compliance needs demand it.
 
 Design details: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) (append-only decision log).
 
+## FAQ
+
+**Do I need to initialize open-memex for each project after installing?**
+Two layers. The data layer needs nothing — there is no per-project init:
+the data dir is created on demand and the project scope is derived
+automatically from your cwd's git remote or path, so memories are
+namespaced per project with zero setup. The editor wiring takes one step:
+run `open-memex init` with no arguments and it auto-detects every editor
+you have installed (VS Code, Cursor, opencode — plus Visual Studio when the
+project has a `.sln`) and wires them all, user-level wherever the editor
+supports it, so one init covers every project. Prefer a single editor?
+`open-memex init --client <vscode|cursor|opencode|visualstudio>`. Prefer to
+force user-level for VS Code / Cursor? Add `--global`. The Copilot memory
+instructions default to user-level (`~/.copilot/`), which is global.
+
+**Does opencode need `init`?**
+Two paths. Recommended: `open-memex init --client opencode --global` —
+it merges the native open-memex plugin into
+`~/.config/opencode/opencode.json` for you. One-time setup, applies to all
+projects, and additionally enables keyword auto-capture and first-turn
+memory injection. Prefer to do it by hand? Add
+`"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]`
+(the installed package's path) to that file instead. As a plain MCP
+consumer: `open-memex init --client opencode` writes a project-level
+`opencode.jsonc` (no hooks). If your user-level config has comments, `init`
+leaves it untouched and prints the manual step.
+
+**VS Code — run `init` once, or per project?**
+Once. Plain `open-memex init` auto-detects VS Code and writes the MCP server
+entry to VS Code's user-level `mcp.json`
+(`%APPDATA%/Code/User/mcp.json` on Windows,
+`~/Library/Application Support/Code/User/mcp.json` on macOS,
+`~/.config/Code/User/mcp.json` on Linux), so the server starts in every
+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.
+
+**How do I remove the editor wiring?**
+`open-memex uninstall` reverses `init`: it removes the MCP server entry,
+the opencode plugin line, and the open-memex section of the Copilot
+instructions. With no `--client` it cleans up every detected editor;
+`--global` limits the cleanup to user-level wiring. Your memories are
+never touched.
+
 ## License
 
 [Apache-2.0](./LICENSE)

package/README.zh-CN.md

@@ -87,7 +87,7 @@ personal scope：只属于这台机器——永不同步，永远进不了仓库
 npm install -g open-memex
 ```
 
-安装的是 `0.4.0` 正式版。
+安装的是 `0.4.1` 正式版。
 
 **Alpha 版**（最新开发版，给测试者）——`alpha` 标签：
 
@@ -111,10 +111,10 @@ npx -y open-memex <命令>          # 例如 npx -y open-memex init --client vsc
 npx -y open-memex@alpha <命令>   # alpha 线，免安装
 ```
 
-**从源码安装**（最新开发版，`V2-dev-p2` 分支）：
+**从源码安装**（最新开发版，`main` 分支）：
 
 ```sh
-git clone -b V2-dev-p2 https://github.com/stoneskin/open-memex.git
+git clone -b main https://github.com/stoneskin/open-memex.git
 cd open-memex
 npm install
 node --experimental-strip-types src/cli.ts <命令>
@@ -153,7 +153,7 @@ Windows 下被进程加载的 DLL 是锁死的：如果 open-memex MCP server
 
 ```sh
 open-memex init --yes
-# ……没装全局包的话：
+# ……没先装包的话：
 npx -y open-memex init --yes
 ```
 
@@ -162,16 +162,24 @@ npx -y open-memex init --yes
 一次 init，所有项目通用；项目里有 solution 文件时 Visual Studio 也会一起配。
 想只配某一个编辑器？加 `--client`：
 
+> **两个"全局"不是一回事，别搞混。**
+> - `npm install -g open-memex` 是把*包*装到全局：让 `open-memex` 命令出现在
+>   你的 PATH 里。
+> - `init --global` 是把*编辑器配置*写到用户级而不是项目里：init 一次，
+>   每个项目都生效。不管包是全局安装的还是用 npx 临时跑的，效果一样。
+
 **VS Code**（Copilot）：
 
 ```sh
 open-memex init --client vscode
-# ……没装全局包的话：
+# ……没先装包的话：
 npx -y open-memex init --client vscode
 ```
 
-自动写 `.vscode/mcp.json` 和用户级 Copilot instructions，然后重新加载窗口，
-在 Copilot Chat 的 MCP 面板里确认 `open-memex` server 已启动。
+配项目级 `.vscode/mcp.json` 和用户级 Copilot instructions，然后重新加载窗口，
+在 Copilot Chat 的 MCP 面板里确认 `open-memex` server 已启动。终端交互模式下
+`init` 会问你要配到项目级还是用户级，而不是替你猜；`--global` 直接强制
+用户级。
 
 **Cursor：**
 
@@ -179,7 +187,9 @@ npx -y open-memex init --client vscode
 open-memex init --client cursor
 ```
 
-自动写 `.cursor/mcp.json` 和用户级 Copilot instructions。
+和 VS Code 一个套路：默认写项目级 `.cursor/mcp.json`，`--global`
+（或终端里 `init` 问你时选用户级）就写用户级，外加用户级 Copilot
+instructions。
 
 **一次配置、所有项目通用（VS Code / Cursor）：**
 
@@ -193,7 +203,8 @@ open-memex init --client vscode --global --yes
 `~/.config/Code/User/mcp.json`；Cursor 是 `~/.cursor/mcp.json`），
 而不是写到项目里——init 一次，每个项目打开自动启动 server。
 如果某个项目自己定义了 `.vscode/mcp.json`，项目级的优先。
-（终端交互模式下，`init` 会问你配到项目级还是用户级。）
+如果用户级文件里带注释（VS Code 接受 JSONC），`init` 不会碰这个文件，
+只打印可直接手贴的配置片段。
 
 **opencode**（原生插件——推荐）：
 
@@ -236,6 +247,16 @@ Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，
 **Codex：** 暂无 `init` 客户端——以 `open-memex mcp --print-config` 为起点手动添加
 （`config.toml` 的 `[mcp_servers]`，或 `codex mcp add`）。
 
+**拆掉接线：**
+
+```sh
+open-memex uninstall --yes
+```
+
+`init` 的逆操作——删掉 MCP server 条目、opencode 插件行和 Copilot
+instructions 里的 open-memex 段。不带 `--client` 时把检测到的编辑器全清掉
+（项目级和用户级都清）；`--global` 只清用户级。你的记忆数据永远不会被碰。
+
 `init` 说明：
 
 - Copilot 记忆 instructions 默认写到**用户级**
@@ -416,7 +437,9 @@ open-memex config set maxProjectMemories 12
 安装与健康检查：
 
 ```sh
-open-memex init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
+open-memex init [--client vscode|cursor|opencode|visualstudio]
+              [--instructions personal|project] [--global] [--force] [--yes]
+open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]
 open-memex config                                  # 打印生效配置
 open-memex config set <key> <value>                # 改设置
 open-memex doctor                                  # 环境健康检查
@@ -572,6 +595,43 @@ ACL 或合规需求出现时才做。
 
 设计细节：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（append-only 决策日志）。
 
+## 常见问题（FAQ）
+
+**装完之后，每个项目都要初始化 open-memex 吗（像其他 app 那样）？**
+分两层。数据层不需要——没有 per-project 初始化的概念：数据目录按需自动创建，
+project scope 从当前目录的 git remote 或路径自动推导，记忆天然按项目隔离，
+零配置。编辑器接线只需要一步：直接跑 `open-memex init`（不带参数），它会自动
+检测你装好的编辑器（VS Code、Cursor、opencode；项目里有 `.sln` 时还有 Visual
+Studio）并一次全接上——支持用户级配置的编辑器就写用户级，一次 init 所有项目
+通用。只想接某一个编辑器？用
+`open-memex init --client <vscode|cursor|opencode|visualstudio>`。
+想给 VS Code / Cursor 强制写用户级？加 `--global`。
+Copilot 记忆指令默认写用户级（`~/.copilot/`），那个是全局的。
+
+**opencode 需要跑 `init` 吗？**
+两条路。推荐：`open-memex init --client opencode --global`——自动把原生插件
+合并进 `~/.config/opencode/opencode.json`。一次配置，所有项目生效，还多拿
+关键词自动捕获和首轮记忆注入。想手写？往那个文件里加
+`"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]`
+（填 open-memex 的实际安装路径）就行。当纯 MCP 用：
+`open-memex init --client opencode` 写项目级 `opencode.jsonc`（无 hooks）。
+如果你的用户级配置里带注释，`init` 不会碰它，只打印手动步骤。
+
+**VS Code 呢——跑一次就行，还是每个项目都要跑？**
+跑一次就行。直接 `open-memex init` 会自动检测到 VS Code，把 MCP server 写进
+VS Code 的用户级 `mcp.json`（Windows：`%APPDATA%/Code/User/mcp.json`；
+macOS：`~/Library/Application Support/Code/User/mcp.json`；
+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
+插件行和 Copilot instructions 里的 open-memex 段。不带 `--client` 时把检测
+到的编辑器全清掉；`--global` 只清用户级。你的记忆数据永远不会被碰。
+
 ## 许可证
 
 [Apache-2.0](./LICENSE)

package/dist/cli.js

@@ -266,6 +266,22 @@ Examples:
   open-memex init
   open-memex init --client vscode --global --yes
   open-memex init --client cursor --yes`,
+    uninstall: `Remove the editor wiring that \`init\` wrote: the MCP server entry,
+the opencode native plugin line, and the Copilot instructions section.
+Your memories are never touched.
+
+Usage: open-memex uninstall [--client vscode|cursor|opencode|visualstudio]
+              [--global] [--yes]
+
+Flags:
+  --client   editor to unwire (default: auto-detect all installed editors)
+  --global   only the user-level config; without it, both project-level and
+             user-level wiring are removed (init may have written either)
+  --yes      accept all defaults, never prompt
+
+Examples:
+  open-memex uninstall
+  open-memex uninstall --client vscode --yes`,
     config: `Show config, or set a key.
 
 Usage: open-memex config [set <key> <value>]
@@ -318,6 +334,8 @@ Usage:
   open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
   open-memex init [--client vscode|cursor|opencode|visualstudio]
               [--instructions personal|project] [--force] [--yes]
+  open-memex uninstall [--client vscode|cursor|opencode|visualstudio]
+              [--global] [--yes]
   open-memex config [set <key> <value>]
   open-memex capture --dry-run "text"
   open-memex doctor
@@ -547,6 +565,18 @@ async function main() {
         });
         return;
     }
+    // `uninstall` reverses `init` — removes the editor wiring; never touches data.
+    // No DB needed (pure file operation, like init).
+    if (cmd === "uninstall") {
+        const flags = parseFlags(rest);
+        const { uninstallProject } = await import("./init.js");
+        await uninstallProject({
+            client: flags["client"],
+            global: flags["global"] === "true",
+            yes: flags["yes"] === "true",
+        });
+        return;
+    }
     // `doctor` runs environment health checks — no DB needed (it self-contains).
     if (cmd === "doctor") {
         const { runDoctor } = await import("./doctor.js");

package/dist/init.js

@@ -160,6 +160,16 @@ export function mergeServerEntry(doc, sectionKey, entry, force) {
     section["open-memex"] = entry;
     return "added";
 }
+/**
+ * D46-followup: when a config file isn't valid JSON we leave it untouched —
+ * but "fix it manually" alone isn't helpful. Print the exact snippet the
+ * user needs to add by hand (same idea as the opencode --global hint).
+ */
+export function printManualEntryHint(sectionKey, entry) {
+    console.error(`    Add this under "${sectionKey}":`);
+    const pretty = JSON.stringify({ "open-memex": entry }, null, 2).replace(/\n/g, "\n    ");
+    console.error(`    ${pretty}`);
+}
 /**
  * Read (or create) a JSON config file, merge the open-memex server entry, write
  * it back. Existing files are merged, never clobbered; invalid JSON is left
@@ -174,6 +184,7 @@ function writeServerEntryFile(file, sectionKey, entry, force, mkdir) {
         }
         catch {
             console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+            printManualEntryHint(sectionKey, entry);
             return null;
         }
     }
@@ -276,6 +287,12 @@ function writeOpencodeMcpJson(root, force) {
         }
         catch {
             console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+            const mc = resolveMcpCommand();
+            printManualEntryHint("mcp", {
+                type: "local",
+                command: [mc.command, ...mc.args],
+                enabled: true,
+            });
             return null;
         }
     }
@@ -311,6 +328,12 @@ function writeVisualStudioMcpJson(root, force) {
         }
         catch {
             console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+            const mc = resolveMcpCommand();
+            printManualEntryHint("servers", {
+                type: "stdio",
+                command: mc.command,
+                args: mc.args,
+            });
             return null;
         }
     }
@@ -615,3 +638,197 @@ export async function initProject(opts) {
     }
     console.log(`\nDone. Reload your editor window to start the open-memex MCP server.`);
 }
+// ---------------------------------------------------------------------------
+// uninstall — the reverse of init (D48). Removes the editor wiring init wrote:
+// the MCP server entry, the opencode native plugin line, and the Copilot
+// instructions section. Memory data is never touched.
+// ---------------------------------------------------------------------------
+/**
+ * Pure removal of the open-memex server entry from a parsed config doc.
+ * Prunes the section when it becomes empty. Mutates `doc`.
+ */
+export function removeServerEntry(doc, sectionKey) {
+    const section = doc[sectionKey];
+    if (!section || typeof section !== "object" || !("open-memex" in section))
+        return "absent";
+    delete section["open-memex"];
+    if (Object.keys(section).length === 0)
+        delete doc[sectionKey];
+    return "removed";
+}
+/**
+ * Pure removal of open-memex plugin entries from a parsed opencode config doc.
+ * Matches any plugin URL containing `match` (robust against the package moving
+ * between installs). Prunes the `plugin` array when it becomes empty.
+ * Mutates `doc`.
+ */
+export function removePluginEntry(doc, match) {
+    const plugins = doc["plugin"];
+    if (!Array.isArray(plugins))
+        return "absent";
+    const kept = plugins.filter((p) => !(typeof p === "string" && p.includes(match)));
+    if (kept.length === plugins.length)
+        return "absent";
+    if (kept.length === 0)
+        delete doc["plugin"];
+    else
+        doc["plugin"] = kept;
+    return "removed";
+}
+/**
+ * Pure removal of the open-memex instructions section from a
+ * copilot-instructions.md body. init always appends it last (MARKER..end),
+ * so cutting from the marker to the end is exact; returns "" when nothing
+ * but the section remains so the caller can delete the file.
+ */
+export function removeInstructionsSection(text) {
+    const idx = text.lastIndexOf(MARKER);
+    if (idx < 0)
+        return text;
+    const rest = text.slice(0, idx).replace(/\s+$/, "");
+    return rest ? rest + "\n" : "";
+}
+/**
+ * Remove the server entry from one JSON config file. Existing files are
+ * merged, never clobbered; invalid JSON is left untouched with the manual
+ * step (same D47 treatment as the init write path).
+ */
+function removeServerEntryFile(file, sectionKey) {
+    if (!fs.existsSync(file))
+        return "absent";
+    let doc;
+    try {
+        doc = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+        console.error(`    Delete the "open-memex" key under "${sectionKey}".`);
+        return null;
+    }
+    const res = removeServerEntry(doc, sectionKey);
+    if (res === "removed") {
+        fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+        console.log(`  - ${file} (open-memex entry removed)`);
+    }
+    return res;
+}
+/** Remove the open-memex plugin URL from one opencode user-level config file. */
+function removeOpencodePluginFile(file) {
+    if (!fs.existsSync(file))
+        return "absent";
+    let doc;
+    try {
+        doc = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+        console.error(`    Delete the open-memex URL from the "plugin" array.`);
+        return null;
+    }
+    const res = removePluginEntry(doc, "open-memex");
+    if (res === "removed") {
+        fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+        console.log(`  - ${file} (open-memex plugin removed)`);
+    }
+    return res;
+}
+/** Remove the open-memex section from one copilot-instructions.md file. */
+function removeInstructionsFile(file) {
+    if (!fs.existsSync(file))
+        return "absent";
+    const cur = fs.readFileSync(file, "utf8");
+    if (!cur.includes(MARKER))
+        return "absent";
+    const next = removeInstructionsSection(cur);
+    if (next === "") {
+        fs.unlinkSync(file);
+        console.log(`  - ${file} (deleted — it only held open-memex instructions)`);
+    }
+    else {
+        fs.writeFileSync(file, next);
+        console.log(`  - ${file} (open-memex instructions removed)`);
+    }
+    return "removed";
+}
+export async function uninstallProject(opts) {
+    const interactive = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    const explicit = normalizeClient(opts.client ?? "");
+    if (explicit && !INIT_CLIENTS.includes(explicit)) {
+        console.error(`unknown client "${opts.client}" (${INIT_CLIENTS.join("|")})`);
+        process.exit(1);
+    }
+    // Mirror init's client resolution: explicit --client, else auto-detect.
+    let clients;
+    if (explicit) {
+        clients = [explicit];
+    }
+    else if (interactive) {
+        const detected = detectInstalledClients();
+        if (detected.length === 0) {
+            console.log("  - no supported editors detected — nothing to remove");
+            return;
+        }
+        console.log(`Detected editors: ${detected.join(", ")}`);
+        const all = await askBool("Remove open-memex wiring from all of them?", true);
+        if (all) {
+            clients = detected;
+        }
+        else {
+            const one = await promptClient();
+            clients = one ? [one] : [];
+        }
+    }
+    else {
+        clients = detectInstalledClients();
+        if (clients.length > 0) {
+            console.log(`Detected editors: ${clients.join(", ")} — removing from all (use --client to pick one)`);
+        }
+    }
+    if (clients.length === 0) {
+        console.log("  - nothing to remove");
+        return;
+    }
+    // Without --global, clean both levels: init may have written either one,
+    // and a leftover entry at the other level would be a surprise.
+    const levels = opts.global ? ["user"] : ["project", "user"];
+    const root = projectRoot();
+    console.log(`open-memex uninstall — project root: ${root}`);
+    let changed = 0;
+    const bump = (r) => {
+        if (r === "removed")
+            changed++;
+    };
+    for (const client of clients) {
+        if (client === "vscode" || client === "cursor") {
+            const sectionKey = client === "cursor" ? "mcpServers" : "servers";
+            for (const level of levels) {
+                const file = level === "user"
+                    ? userMcpConfigPath(client)
+                    : path.join(root, client === "cursor" ? ".cursor/mcp.json" : ".vscode/mcp.json");
+                bump(removeServerEntryFile(file, sectionKey));
+            }
+        }
+        else if (client === "opencode") {
+            for (const level of levels) {
+                if (level === "user")
+                    bump(removeOpencodePluginFile(opencodeGlobalConfigPath()));
+                else
+                    bump(removeServerEntryFile(path.join(root, "opencode.jsonc"), "mcp"));
+            }
+        }
+        else if (client === "visualstudio") {
+            // Solution-level only — --global is meaningless, same as init.
+            bump(removeServerEntryFile(path.join(root, ".mcp.json"), "servers"));
+        }
+    }
+    // Copilot instructions: init may have written personal (default) or project.
+    if (clients.some((c) => c !== "opencode")) {
+        bump(removeInstructionsFile(path.join(os.homedir(), ".copilot", "copilot-instructions.md")));
+        bump(removeInstructionsFile(path.join(os.homedir(), "copilot-instructions.md")));
+        bump(removeInstructionsFile(path.join(root, ".github", "copilot-instructions.md")));
+    }
+    console.log(changed > 0
+        ? `\nDone. Removed open-memex wiring from ${changed} file(s).`
+        : "\nDone. Nothing to remove — no open-memex wiring found.");
+    console.log("Your memories are untouched (uninstall never deletes data).");
+}

package/docs/V2-DESIGN.md

@@ -930,6 +930,30 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   should not have to learn `--client` to get started. The help text already
   promised "default: auto-detect"; D46 makes the code keep that promise.
   Approved 2026-09-29.*
+- **D47** — when `init` refuses to touch a config file that isn't valid JSON
+  (usually JSONC with comments — VS Code / Cursor / opencode all accept them),
+  it now prints the exact snippet to add by hand: the section key plus the
+  `"open-memex"` entry, pretty-printed. Covers all three MCP-writing paths —
+  vscode/cursor (user + project level), opencode project-level `opencode.jsonc`,
+  and Visual Studio `.mcp.json` — matching the manual hint the opencode
+  `--global` plugin path already printed (D46). The file is still never
+  rewritten; the hint just makes "fix it manually" actionable. Triggered by
+  Stone's real Windows run: his user-level `mcp.json` had comments, init
+  correctly left it alone, but the old message gave him nothing to paste.
+  *Rationale: a refusal without a remedy is a dead end; the entry shape is
+  already computed, so printing it costs nothing. Approved 2026-09-29.*
+- **D48** — new `open-memex uninstall` command, the reverse of `init`
+  (0.5.0-alpha.4). Removes the MCP server entry / opencode native plugin line /
+  Copilot instructions section that `init` wrote; memory data is never touched.
+  Client resolution mirrors `init` (explicit `--client`, else auto-detect with
+  an interactive confirm). Without `--global` it cleans both project-level and
+  user-level files — init may have written either, and a leftover entry at the
+  other level would be a surprise; `--global` restricts to user-level. Empty
+  sections/arrays are pruned; an instructions file that only held the
+  open-memex section is deleted. Non-JSON (JSONC) configs are left untouched
+  with the manual step, same D47 treatment as the init write path.
+  *Rationale: Stone asked "有 uninstall 吗" while testing init on Windows —
+  every write deserves an undo. Approved 2026-09-29.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.5.0-alpha.2",
+  "version": "0.5.0-alpha.4",
   "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/scripts/smoke-pure.ts

@@ -8,7 +8,7 @@ import { DEFAULT_CONFIG } from "../src/config.ts";
 import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE } from "../src/scope.ts";
 import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
-import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, opencodeGlobalConfigPath } from "../src/init.ts";
+import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, opencodeGlobalConfigPath, printManualEntryHint, removeServerEntry, removePluginEntry, removeInstructionsSection } from "../src/init.ts";
 
 let fails = 0;
 function ok(name: string, cond: boolean, info?: unknown) {
@@ -422,6 +422,40 @@ ok("plugin merge force on dup adds nothing twice", mergePluginEntry(pdoc, "file:
 const pdoc2: Record<string, unknown> = { plugin: ["file:///other"], theme: "dark" };
 ok("plugin merge preserves siblings", mergePluginEntry(pdoc2, "file:///x", false) === "added"
   && (pdoc2["plugin"] as unknown[]).length === 2 && pdoc2["theme"] === "dark");
+// printManualEntryHint: the invalid-JSON bail-out must show the exact snippet to add by hand.
+const hintLines: string[] = [];
+const origErr = console.error;
+console.error = (msg?: unknown) => { hintLines.push(String(msg)); };
+printManualEntryHint("servers", { type: "stdio", command: "open-memex", args: ["mcp"] });
+console.error = origErr;
+const hintText = hintLines.join("\n");
+ok("manual hint names the section", hintText.includes('"servers"'));
+ok("manual hint contains the entry", hintText.includes('"open-memex"') && hintText.includes("stdio"));
+// removeServerEntry: pure removal semantics.
+const rdoc: Record<string, unknown> = { servers: { "open-memex": { command: "x" }, other: { command: "y" } }, untouched: 1 };
+ok("remove deletes the entry", removeServerEntry(rdoc, "servers") === "removed"
+  && !("open-memex" in (rdoc["servers"] as Record<string, unknown>))
+  && "other" in (rdoc["servers"] as Record<string, unknown>));
+ok("remove absent when entry already gone", removeServerEntry(rdoc, "servers") === "absent"
+  && "servers" in rdoc); // sibling kept, section kept
+const rdoc2: Record<string, unknown> = { servers: { "open-memex": { command: "x" } } };
+ok("remove prunes empty section", removeServerEntry(rdoc2, "servers") === "removed" && !("servers" in rdoc2));
+ok("remove absent when no entry", removeServerEntry({ servers: {} }, "servers") === "absent");
+ok("remove absent when no section", removeServerEntry({}, "servers") === "absent");
+// removePluginEntry: removes any open-memex URL, prunes empty array.
+const rpdoc: Record<string, unknown> = { plugin: ["file:///x/open-memex/src/index.ts", "other-plugin"], theme: "dark" };
+ok("plugin remove by substring", removePluginEntry(rpdoc, "open-memex") === "removed"
+  && JSON.stringify(rpdoc["plugin"]) === JSON.stringify(["other-plugin"]));
+const rpdoc3: Record<string, unknown> = { plugin: ["file:///open-memex/y"] };
+ok("plugin remove prunes empty array", removePluginEntry(rpdoc3, "open-memex") === "removed" && !("plugin" in rpdoc3));
+ok("plugin remove absent", removePluginEntry({ plugin: ["other"] }, "open-memex") === "absent");
+// removeInstructionsSection: cuts MARKER..end, "" when nothing remains.
+ok("instructions remove keeps prior content",
+  removeInstructionsSection("# mine\n\n<!-- open-memex -->\n# OpenMemex memory\n") === "# mine\n");
+ok("instructions remove returns empty when wholesale",
+  removeInstructionsSection("<!-- open-memex -->\n# OpenMemex memory\n") === "");
+ok("instructions remove no-op without marker",
+  removeInstructionsSection("# mine\n") === "# mine\n");
 // detectInstalledClients with a fully fake env.
 const binDir = fs.mkdtempSync(path.join(os.tmpdir(), "memex-bin-"));
 fs.writeFileSync(path.join(binDir, "code"), "#!/bin/sh\n");

package/src/cli.ts

@@ -296,6 +296,23 @@ Examples:
   open-memex init --client vscode --global --yes
   open-memex init --client cursor --yes`,
 
+  uninstall: `Remove the editor wiring that \`init\` wrote: the MCP server entry,
+the opencode native plugin line, and the Copilot instructions section.
+Your memories are never touched.
+
+Usage: open-memex uninstall [--client vscode|cursor|opencode|visualstudio]
+              [--global] [--yes]
+
+Flags:
+  --client   editor to unwire (default: auto-detect all installed editors)
+  --global   only the user-level config; without it, both project-level and
+             user-level wiring are removed (init may have written either)
+  --yes      accept all defaults, never prompt
+
+Examples:
+  open-memex uninstall
+  open-memex uninstall --client vscode --yes`,
+
   config: `Show config, or set a key.
 
 Usage: open-memex config [set <key> <value>]
@@ -351,6 +368,8 @@ Usage:
   open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
   open-memex init [--client vscode|cursor|opencode|visualstudio]
               [--instructions personal|project] [--force] [--yes]
+  open-memex uninstall [--client vscode|cursor|opencode|visualstudio]
+              [--global] [--yes]
   open-memex config [set <key> <value>]
   open-memex capture --dry-run "text"
   open-memex doctor
@@ -617,6 +636,19 @@ async function main() {
     return;
   }
 
+  // `uninstall` reverses `init` — removes the editor wiring; never touches data.
+  // No DB needed (pure file operation, like init).
+  if (cmd === "uninstall") {
+    const flags = parseFlags(rest);
+    const { uninstallProject } = await import("./init.ts");
+    await uninstallProject({
+      client: flags["client"],
+      global: flags["global"] === "true",
+      yes: flags["yes"] === "true",
+    });
+    return;
+  }
+
   // `doctor` runs environment health checks — no DB needed (it self-contains).
   if (cmd === "doctor") {
     const { runDoctor } = await import("./doctor.ts");

package/src/init.ts

@@ -181,6 +181,17 @@ export function mergeServerEntry(
   return "added";
 }
 
+/**
+ * D46-followup: when a config file isn't valid JSON we leave it untouched —
+ * but "fix it manually" alone isn't helpful. Print the exact snippet the
+ * user needs to add by hand (same idea as the opencode --global hint).
+ */
+export function printManualEntryHint(sectionKey: string, entry: Record<string, unknown>): void {
+  console.error(`    Add this under "${sectionKey}":`);
+  const pretty = JSON.stringify({ "open-memex": entry }, null, 2).replace(/\n/g, "\n    ");
+  console.error(`    ${pretty}`);
+}
+
 /**
  * Read (or create) a JSON config file, merge the open-memex server entry, write
  * it back. Existing files are merged, never clobbered; invalid JSON is left
@@ -200,6 +211,7 @@ function writeServerEntryFile(
       doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
     } catch {
       console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      printManualEntryHint(sectionKey, entry);
       return null;
     }
   }
@@ -308,6 +320,12 @@ function writeOpencodeMcpJson(root: string, force: boolean): string | null {
       doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
     } catch {
       console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      const mc = resolveMcpCommand();
+      printManualEntryHint("mcp", {
+        type: "local",
+        command: [mc.command, ...mc.args],
+        enabled: true,
+      });
       return null;
     }
   }
@@ -343,6 +361,12 @@ function writeVisualStudioMcpJson(root: string, force: boolean): string | null {
       doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
     } catch {
       console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+      const mc = resolveMcpCommand();
+      printManualEntryHint("servers", {
+        type: "stdio",
+        command: mc.command,
+        args: mc.args,
+      });
       return null;
     }
   }
@@ -677,3 +701,196 @@ export async function initProject(opts: {
   }
   console.log(`\nDone. Reload your editor window to start the open-memex MCP server.`);
 }
+
+// ---------------------------------------------------------------------------
+// uninstall — the reverse of init (D48). Removes the editor wiring init wrote:
+// the MCP server entry, the opencode native plugin line, and the Copilot
+// instructions section. Memory data is never touched.
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure removal of the open-memex server entry from a parsed config doc.
+ * Prunes the section when it becomes empty. Mutates `doc`.
+ */
+export function removeServerEntry(
+  doc: Record<string, unknown>,
+  sectionKey: string,
+): "removed" | "absent" {
+  const section = doc[sectionKey];
+  if (!section || typeof section !== "object" || !("open-memex" in section)) return "absent";
+  delete (section as Record<string, unknown>)["open-memex"];
+  if (Object.keys(section as Record<string, unknown>).length === 0) delete doc[sectionKey];
+  return "removed";
+}
+
+/**
+ * Pure removal of open-memex plugin entries from a parsed opencode config doc.
+ * Matches any plugin URL containing `match` (robust against the package moving
+ * between installs). Prunes the `plugin` array when it becomes empty.
+ * Mutates `doc`.
+ */
+export function removePluginEntry(doc: Record<string, unknown>, match: string): "removed" | "absent" {
+  const plugins = doc["plugin"];
+  if (!Array.isArray(plugins)) return "absent";
+  const kept = (plugins as unknown[]).filter(
+    (p) => !(typeof p === "string" && p.includes(match)),
+  );
+  if (kept.length === plugins.length) return "absent";
+  if (kept.length === 0) delete doc["plugin"];
+  else doc["plugin"] = kept;
+  return "removed";
+}
+
+/**
+ * Pure removal of the open-memex instructions section from a
+ * copilot-instructions.md body. init always appends it last (MARKER..end),
+ * so cutting from the marker to the end is exact; returns "" when nothing
+ * but the section remains so the caller can delete the file.
+ */
+export function removeInstructionsSection(text: string): string {
+  const idx = text.lastIndexOf(MARKER);
+  if (idx < 0) return text;
+  const rest = text.slice(0, idx).replace(/\s+$/, "");
+  return rest ? rest + "\n" : "";
+}
+
+/**
+ * Remove the server entry from one JSON config file. Existing files are
+ * merged, never clobbered; invalid JSON is left untouched with the manual
+ * step (same D47 treatment as the init write path).
+ */
+function removeServerEntryFile(file: string, sectionKey: string): "removed" | "absent" | null {
+  if (!fs.existsSync(file)) return "absent";
+  let doc: Record<string, unknown>;
+  try {
+    doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+  } catch {
+    console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+    console.error(`    Delete the "open-memex" key under "${sectionKey}".`);
+    return null;
+  }
+  const res = removeServerEntry(doc, sectionKey);
+  if (res === "removed") {
+    fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+    console.log(`  - ${file} (open-memex entry removed)`);
+  }
+  return res;
+}
+
+/** Remove the open-memex plugin URL from one opencode user-level config file. */
+function removeOpencodePluginFile(file: string): "removed" | "absent" | null {
+  if (!fs.existsSync(file)) return "absent";
+  let doc: Record<string, unknown>;
+  try {
+    doc = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+  } catch {
+    console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
+    console.error(`    Delete the open-memex URL from the "plugin" array.`);
+    return null;
+  }
+  const res = removePluginEntry(doc, "open-memex");
+  if (res === "removed") {
+    fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
+    console.log(`  - ${file} (open-memex plugin removed)`);
+  }
+  return res;
+}
+
+/** Remove the open-memex section from one copilot-instructions.md file. */
+function removeInstructionsFile(file: string): "removed" | "absent" {
+  if (!fs.existsSync(file)) return "absent";
+  const cur = fs.readFileSync(file, "utf8");
+  if (!cur.includes(MARKER)) return "absent";
+  const next = removeInstructionsSection(cur);
+  if (next === "") {
+    fs.unlinkSync(file);
+    console.log(`  - ${file} (deleted — it only held open-memex instructions)`);
+  } else {
+    fs.writeFileSync(file, next);
+    console.log(`  - ${file} (open-memex instructions removed)`);
+  }
+  return "removed";
+}
+
+export async function uninstallProject(opts: {
+  client?: string;
+  /** D48: only the user-level config; without it, both levels are cleaned. */
+  global?: boolean;
+  yes: boolean;
+}): Promise<void> {
+  const interactive = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+  const explicit = normalizeClient(opts.client ?? "");
+  if (explicit && !(INIT_CLIENTS as readonly string[]).includes(explicit)) {
+    console.error(`unknown client "${opts.client}" (${INIT_CLIENTS.join("|")})`);
+    process.exit(1);
+  }
+  // Mirror init's client resolution: explicit --client, else auto-detect.
+  let clients: InitClient[];
+  if (explicit) {
+    clients = [explicit as InitClient];
+  } else if (interactive) {
+    const detected = detectInstalledClients();
+    if (detected.length === 0) {
+      console.log("  - no supported editors detected — nothing to remove");
+      return;
+    }
+    console.log(`Detected editors: ${detected.join(", ")}`);
+    const all = await askBool("Remove open-memex wiring from all of them?", true);
+    if (all) {
+      clients = detected;
+    } else {
+      const one = await promptClient();
+      clients = one ? [one as InitClient] : [];
+    }
+  } else {
+    clients = detectInstalledClients();
+    if (clients.length > 0) {
+      console.log(`Detected editors: ${clients.join(", ")} — removing from all (use --client to pick one)`);
+    }
+  }
+  if (clients.length === 0) {
+    console.log("  - nothing to remove");
+    return;
+  }
+  // Without --global, clean both levels: init may have written either one,
+  // and a leftover entry at the other level would be a surprise.
+  const levels = opts.global ? ["user"] : ["project", "user"];
+  const root = projectRoot();
+  console.log(`open-memex uninstall — project root: ${root}`);
+  let changed = 0;
+  const bump = (r: "removed" | "absent" | null) => {
+    if (r === "removed") changed++;
+  };
+  for (const client of clients) {
+    if (client === "vscode" || client === "cursor") {
+      const sectionKey = client === "cursor" ? "mcpServers" : "servers";
+      for (const level of levels) {
+        const file =
+          level === "user"
+            ? userMcpConfigPath(client)
+            : path.join(root, client === "cursor" ? ".cursor/mcp.json" : ".vscode/mcp.json");
+        bump(removeServerEntryFile(file, sectionKey));
+      }
+    } else if (client === "opencode") {
+      for (const level of levels) {
+        if (level === "user") bump(removeOpencodePluginFile(opencodeGlobalConfigPath()));
+        else bump(removeServerEntryFile(path.join(root, "opencode.jsonc"), "mcp"));
+      }
+    } else if (client === "visualstudio") {
+      // Solution-level only — --global is meaningless, same as init.
+      bump(removeServerEntryFile(path.join(root, ".mcp.json"), "servers"));
+    }
+  }
+  // Copilot instructions: init may have written personal (default) or project.
+  if (clients.some((c) => c !== "opencode")) {
+    bump(removeInstructionsFile(path.join(os.homedir(), ".copilot", "copilot-instructions.md")));
+    bump(removeInstructionsFile(path.join(os.homedir(), "copilot-instructions.md")));
+    bump(removeInstructionsFile(path.join(root, ".github", "copilot-instructions.md")));
+  }
+  console.log(
+    changed > 0
+      ? `\nDone. Removed open-memex wiring from ${changed} file(s).`
+      : "\nDone. Nothing to remove — no open-memex wiring found.",
+  );
+  console.log("Your memories are untouched (uninstall never deletes data).");
+}