open-memex 0.3.0-alpha.1 → 0.3.0

package/AGENTS.md

@@ -34,12 +34,14 @@ node --experimental-strip-types scripts\smoke-pure.ts   # runs pure-logic checks
 node --experimental-strip-types scripts\smoke-mcp.ts    # MCP handshake + tool round-trip (temp dirs, no real data)
 ```
 
-After `npm i -g open-memex@alpha` (or `npm link` from source), the `open-memex` bin is on
+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] [--force] [--yes]`
-one-command project setup (editor MCP config + .github/copilot-instructions.md;
-resolves the server command at init time — npx fallback when no durable bin is on PATH, D17),
+`open-memex init [--client vscode|cursor|opencode|visualstudio] [--instructions personal|project] [--force] [--yes]`
+one-command project setup (editor MCP config + Copilot memory instructions;
+instructions default to user-level ~/.copilot/copilot-instructions.md so the repo
+stays clean for teammates without open-memex — D22; 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).

package/README.md

@@ -21,16 +21,15 @@ plus a generic MCP server (VS Code Copilot, Cursor, Claude Code, Visual Studio,
 **npm (recommended):**
 
 ```sh
-npm install -g open-memex@alpha
+npm install -g open-memex
 ```
 
-This installs the `0.3.0-alpha` prerelease channel. (`latest` still points at the older
-`0.1.0` stable.)
+This installs the `0.3.0` stable release.
 
 **No install — run via npx:**
 
 ```sh
-npx -y open-memex@alpha <command>   # e.g. npx -y open-memex@alpha init --client vscode
+npx -y open-memex <command>   # e.g. npx -y open-memex init --client vscode
 ```
 
 **From source** (bleeding edge, `V2-dev-p2` branch):
@@ -42,9 +41,6 @@ npm install
 node --experimental-strip-types src/cli.ts <command>
 ```
 
-> The `0.3.0-alpha` npm publish is cut from this branch — if `npx` still resolves an
-> older alpha, install from source until the publish lands.
-
 #### "`open-memex` is not recognized" — PATH setup
 
 A global `npm install -g` puts the `open-memex` launcher in npm's global bin folder.
@@ -65,6 +61,15 @@ If your terminal can't find it, that folder isn't on your `PATH`:
 3. No admin rights / don't want to touch `PATH`? Use the npx form above — npx
    resolves the package itself and needs no `PATH` changes.
 
+#### "`EBUSY` / `EPERM` on `better_sqlite3.node`" — Windows reinstall
+
+On Windows a loaded DLL is locked: if the open-memex MCP server is running
+(VS Code MCP panel, Cursor, etc.), `npm install -g open-memex` cannot
+replace `better_sqlite3.node` and fails with `EBUSY` / `EPERM`. Stop the MCP
+server first (or quit the editor), then re-run the install. If it still fails,
+delete `node_modules/open-memex` and any `node_modules/.open-memex-*` temp
+folders under your global npm root and install again.
+
 ### Step 2 — One-command setup for your editor
 
 Run from your **project root** (so the project scope resolves to this repo):
@@ -74,10 +79,10 @@ Run from your **project root** (so the project scope resolves to this repo):
 ```sh
 open-memex init --client vscode
 # …or without a global install:
-npx -y open-memex@alpha init --client vscode
+npx -y open-memex init --client vscode
 ```
 
-Writes `.vscode/mcp.json` and `.github/copilot-instructions.md`, then reload the
+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.
 
 **Cursor:**
@@ -86,7 +91,7 @@ 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 `.github/copilot-instructions.md`.
+Writes `.cursor/mcp.json` and user-level Copilot instructions.
 
 **opencode** (as a plain MCP consumer):
 
@@ -112,7 +117,7 @@ claude mcp add open-memex -- open-memex mcp
 open-memex init --client visualstudio
 ```
 
-Writes solution-level `.mcp.json` and `.github/copilot-instructions.md`. Requires
+Writes solution-level `.mcp.json` and user-level Copilot instructions. Requires
 Visual Studio 2022 17.14+ or Visual Studio 2026 (**Windows-only**). Visual Studio
 also auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`, so the VS Code setup
 above works too.
@@ -123,6 +128,12 @@ above works too.
 
 `init` notes:
 
+- 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
@@ -130,8 +141,8 @@ above works too.
 - 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
-  `npx -y open-memex@alpha mcp` server command into the config so the setup keeps
-  working. `npm i -g open-memex@alpha` + `open-memex init --force` switches to the
+  `npx -y open-memex mcp` server command into the config so the setup keeps
+  working. `npm i -g open-memex` + `open-memex init --force` switches to the
   faster direct command later.
 
 ### Step 3 — Verify it works
@@ -237,6 +248,8 @@ open-memex config set <key> <value>                # change a setting
 open-memex doctor                                  # environment health check
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # preview keyword capture
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
+open-memex --help      # this reference
+open-memex --version   # installed version
 ```
 
 Memory operations:
@@ -272,7 +285,7 @@ no host-specific plugin needed. Any MCP client can use open-memex.
 
 ```sh
 open-memex mcp               # after a global install
-npx -y open-memex@alpha mcp  # no install needed
+npx -y open-memex mcp  # no install needed
 ```
 
 The project scope is resolved from the process working directory, so configure the
@@ -280,16 +293,16 @@ server with cwd set to your project root (`init` handles this for you).
 
 > **Note:** MCP is request/response — it gives the agent tools, not the opencode
 > plugin's automatic keyword capture or first-turn context injection. Proactive
-> memory use depends on the agent's instructions (the `.github/copilot-instructions.md`
+> memory use depends on the agent's instructions (the Copilot instructions
 > that `init` writes).
 
 ## Roadmap
 
-**`0.3.0-alpha` (this release):** generic MCP server, `open-memex` bin/CLI, one-command
+**`0.3.0` (this release):** generic MCP server, `open-memex` bin/CLI, one-command
 `init` setup, Chinese keyword capture with personal/project routing, `config` /
 `capture --dry-run` / `doctor` helpers, Visual Studio support.
 
-**Coming — `0.3.0-beta`:** team sync — shared memory via git (`propose` / `promote` /
+**Coming — `0.4.0`:** team sync — shared memory via git (`propose` / `promote` /
 `resolve` workflow, in-repo memory dir), 1–2 colleague pilot.
 
 **Coming — `0.3.0` (stable):** org layer — org memory repo, curator convention,

package/README.zh-CN.md

@@ -21,15 +21,15 @@
 **npm（推荐）：**
 
 ```sh
-npm install -g open-memex@alpha
+npm install -g open-memex
 ```
 
-安装的是 `0.3.0-alpha` 预览通道。（`latest` 仍指向旧的 `0.1.0` 稳定版。）
+安装的是 `0.3.0` 正式版。
 
 **免安装——用 npx 直接跑：**
 
 ```sh
-npx -y open-memex@alpha <命令>   # 例如 npx -y open-memex@alpha init --client vscode
+npx -y open-memex <命令>   # 例如 npx -y open-memex init --client vscode
 ```
 
 **从源码安装**（最新开发版，`V2-dev-p2` 分支）：
@@ -41,9 +41,6 @@ npm install
 node --experimental-strip-types src/cli.ts <命令>
 ```
 
-> `0.3.0-alpha` 的 npm 发布从该分支切出——如果 npx 还解析到旧的 alpha 版，
-> 请先用源码安装，等发布落地。
-
 #### 提示 "'open-memex' 不是内部命令"？——PATH 设置
 
 `npm install -g` 会把 `open-memex` 启动器放到 npm 的全局 bin 目录。
@@ -63,6 +60,14 @@ node --experimental-strip-types src/cli.ts <命令>
 3. 没有管理员权限 / 不想动 `PATH`？用上面的 npx 形式——npx 自己解析包，
    不需要改 `PATH`。
 
+#### Windows 重装报 "`EBUSY` / `EPERM`（`better_sqlite3.node`）"
+
+Windows 下被进程加载的 DLL 是锁死的：如果 open-memex MCP server 正在运行
+（VS Code MCP 面板、Cursor 等），`npm install -g open-memex` 替换不了
+`better_sqlite3.node`，就会报 `EBUSY` / `EPERM`。先停掉 MCP server
+（或退出编辑器），再重跑安装。还不行的话，手动删掉全局 npm 目录下的
+`node_modules/open-memex` 和 `node_modules/.open-memex-*` 临时目录，再装。
+
 ### 第二步——给你的编辑器一键配置
 
 在**项目根目录**下运行（这样 project scope 会解析到这个仓库）：
@@ -72,10 +77,10 @@ node --experimental-strip-types src/cli.ts <命令>
 ```sh
 open-memex init --client vscode
 # ……没装全局包的话：
-npx -y open-memex@alpha init --client vscode
+npx -y open-memex init --client vscode
 ```
 
-自动写 `.vscode/mcp.json` 和 `.github/copilot-instructions.md`，然后重新加载窗口，
+自动写 `.vscode/mcp.json` 和用户级 Copilot instructions，然后重新加载窗口，
 在 Copilot Chat 的 MCP 面板里确认 `open-memex` server 已启动。
 
 **Cursor：**
@@ -84,7 +89,7 @@ npx -y open-memex@alpha init --client vscode
 open-memex init --client cursor
 ```
 
-自动写 `.cursor/mcp.json` 和 `.github/copilot-instructions.md`。
+自动写 `.cursor/mcp.json` 和用户级 Copilot instructions。
 
 **opencode**（作为普通 MCP 客户端）：
 
@@ -110,7 +115,7 @@ claude mcp add open-memex -- open-memex mcp
 open-memex init --client visualstudio
 ```
 
-写 solution 级 `.mcp.json` 和 `.github/copilot-instructions.md`。需要
+写 solution 级 `.mcp.json` 和用户级 Copilot instructions。需要
 Visual Studio 2022 17.14+ 或 Visual Studio 2026（**仅 Windows**）。
 Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，
 所以上面的 VS Code 配置同样可用。
@@ -120,14 +125,20 @@ Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，
 
 `init` 说明：
 
+- Copilot 记忆 instructions 默认写到**用户级**
+  （`~/.copilot/copilot-instructions.md`；Visual Studio 是
+  `%USERPROFILE%\copilot-instructions.md`）——所有项目生效，永不 checkin
+  到 repo，没装 open-memex 的同事看不到、也不会出错。团队人人都用
+  open-memex 时可用 `--instructions project` 改写
+  `.github/copilot-instructions.md`。
 - 在终端里会交互式询问：配哪个编辑器、是否开启关键词自动捕获、
   是否在首轮注入记忆。`--yes` 全用默认值；脚本 / 非 TTY 环境不提问
   （编辑器默认 VS Code）。
 - 已有配置文件会被**合并，不会被覆盖**——重复运行是安全的。
   `--force` 强制覆盖。
 - 如果 `PATH` 上没有可用的 `open-memex`（比如一次性 npx），`init` 会把
-  `npx -y open-memex@alpha mcp` 写进配置，配置照样能用。
-  以后 `npm i -g open-memex@alpha` + `open-memex init --force` 可切换到更快
+  `npx -y open-memex mcp` 写进配置，配置照样能用。
+  以后 `npm i -g open-memex` + `open-memex init --force` 可切换到更快
   的直接调用。
 
 ### 第三步——验证
@@ -236,6 +247,8 @@ open-memex config set <key> <value>                # 改设置
 open-memex doctor                                  # 环境健康检查
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # 预览关键词捕获
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
+open-memex --help      # 本帮助
+open-memex --version   # 已安装版本
 ```
 
 记忆操作：
@@ -272,7 +285,7 @@ CLI 跑在 Node 22 下。从源码 checkout 使用时走内置的实验性 TypeS
 
 ```sh
 open-memex mcp               # 全局安装后
-npx -y open-memex@alpha mcp  # 免安装
+npx -y open-memex mcp  # 免安装
 ```
 
 project scope 从进程工作目录解析，所以配置 server 时 cwd 要指向项目根目录
@@ -280,15 +293,15 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 
 > **注意：** MCP 是请求/响应式的——它给 agent 提供 tools，但没有 opencode
 > 插件的关键词自动捕获和首轮上下文注入。想让 agent 主动用记忆，
-> 靠的是 agent 的 instructions（`init` 写的 `.github/copilot-instructions.md`）。
+> 靠的是 agent 的 instructions（`init` 写的 Copilot instructions）。
 
 ## 路线图（Roadmap）
 
-**`0.3.0-alpha`（本版）：** 通用 MCP server、`open-memex` bin/CLI、
+**`0.3.0`（本版）：** 通用 MCP server、`open-memex` bin/CLI、
 一键 `init` 配置、中文关键词捕获（含 personal/project 路由）、
 `config` / `capture --dry-run` / `doctor` 助手命令、Visual Studio 支持。
 
-**Coming —— `0.3.0-beta`：** 团队同步——用 git 做共享记忆
+**Coming —— `0.4.0`：** 团队同步——用 git 做共享记忆
 （`propose` / `promote` / `resolve` 工作流、仓库内记忆目录），
 找 1–2 个同事做 pilot。
 

package/dist/cli.js

@@ -13,32 +13,38 @@ import { paths } from "./paths.js";
 import { redact } from "./redact.js";
 import { resolveMcpCommand } from "./init.js";
 import fs from "node:fs";
-function usage() {
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function usage(exitCode = 1) {
     console.log(`open-memex CLI
 
 Usage:
-  node --experimental-strip-types src/cli.ts where
-  node --experimental-strip-types src/cli.ts list [--scope project|personal] [--type T] [--limit N]
-  node --experimental-strip-types src/cli.ts search "query" [--scope project|personal|both] [--type T] [--limit N]
-  node --experimental-strip-types src/cli.ts add "content" [--scope project|personal] [--type T] [--tag t1,t2]
-  node --experimental-strip-types src/cli.ts supersede <id> "new content" [--type T] [--tag t1,t2]
-  node --experimental-strip-types src/cli.ts status <id> active|deprecated|retracted|archived
-  node --experimental-strip-types src/cli.ts forget <id>
-  node --experimental-strip-types src/cli.ts reindex
-  node --experimental-strip-types src/cli.ts scopes
-  node --experimental-strip-types src/cli.ts migrate [--from <key>] [--to <key>]
+  open-memex where
+  open-memex list [--scope project|personal] [--type T] [--limit N]
+  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+  open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+  open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+  open-memex status <id> active|deprecated|retracted|archived
+  open-memex forget <id>
+  open-memex reindex
+  open-memex scopes
+  open-memex migrate [--from <key>] [--to <key>]
                                           [--dry-run] [--on-conflict newer|overwrite|skip]
-  node --experimental-strip-types src/cli.ts migrate --to-v2 [--dry-run]
-  node --experimental-strip-types src/cli.ts mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
-  node --experimental-strip-types src/cli.ts init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
-  node --experimental-strip-types src/cli.ts config [set <key> <value>]
-  node --experimental-strip-types src/cli.ts capture --dry-run "text"
-  node --experimental-strip-types src/cli.ts doctor
+  open-memex migrate --to-v2 [--dry-run]
+  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 config [set <key> <value>]
+  open-memex capture --dry-run "text"
+  open-memex doctor
 
 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\`) plus
-\`.github/copilot-instructions.md\` — no copy-paste needed.
+\`opencode.jsonc\`, or Visual Studio's solution-level \`.mcp.json\`) — no copy-paste
+needed. 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.
@@ -58,7 +64,7 @@ git remote after memories were already stored under the cwd-based key.
 \`migrate --to-v2\` converts v1 memory files to the v2 format (§19):
 user→personal scope rename, epoch→RFC 3339 times, priority→importance,
 type: instruction→role split. Always preview with --dry-run first.`);
-    process.exit(1);
+    process.exit(exitCode);
 }
 function parseFlags(argv) {
     const out = {};
@@ -147,8 +153,16 @@ function printMcpConfig(client) {
 }
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
-    if (!cmd)
-        usage();
+    if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help")
+        usage(0);
+    if (cmd === "--version" || cmd === "-v") {
+        // package.json sits two levels above this file in both layouts
+        // (src/cli.ts and dist/cli.js).
+        const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        console.log(`open-memex ${pkg.version}`);
+        return;
+    }
     const cfg = loadConfig();
     const project = resolveProjectScope(process.cwd());
     // `migrate --to-v2` is a pure file operation (V2-DESIGN §19) — it runs
@@ -184,6 +198,7 @@ async function main() {
             client: flags["client"],
             force: flags["force"] === "true",
             yes: flags["yes"] === "true",
+            instructions: flags["instructions"],
         });
         return;
     }

package/dist/init.js

@@ -1,6 +1,7 @@
 // `open-memex init` — one-command project setup (§17 adoption path).
 // Pure file operation: no DB, no network. Safe to run in any directory.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
@@ -35,6 +36,9 @@ export function resolveMcpCommand() {
 const INSTRUCTIONS = `${MARKER}
 # OpenMemex memory
 
+> Applies only when the \`open-memex\` MCP server is available in this session
+> (the \`memory_*\` tools exist). Otherwise ignore this section.
+
 You have a local memory MCP server (\`open-memex\`) with five tools:
 \`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`.
 
@@ -174,9 +178,21 @@ function writeVisualStudioMcpJson(root, force) {
     }
     return file;
 }
-function writeInstructions(root) {
-    const dir = path.join(root, ".github");
-    const file = path.join(dir, "copilot-instructions.md");
+function writeInstructions(root, scope, client) {
+    const file = scope === "project"
+        ? path.join(root, ".github", "copilot-instructions.md")
+        : client === "visualstudio"
+            ? path.join(os.homedir(), "copilot-instructions.md")
+            : path.join(os.homedir(), ".copilot", "copilot-instructions.md");
+    if (scope === "personal") {
+        // A previous project-scoped init may have left the section behind — flag it
+        // so the repo can go back to being open-memex-free for teammates.
+        const proj = path.join(root, ".github", "copilot-instructions.md");
+        if (fs.existsSync(proj) && fs.readFileSync(proj, "utf8").includes(MARKER)) {
+            console.log(`  ! project-level instructions still present at ${proj}`);
+            console.log(`    remove the open-memex section there to keep the repo clean.`);
+        }
+    }
     if (fs.existsSync(file)) {
         const cur = fs.readFileSync(file, "utf8");
         if (cur.includes(MARKER)) {
@@ -186,7 +202,7 @@ function writeInstructions(root) {
         fs.writeFileSync(file, cur.replace(/\s+$/, "") + "\n\n" + INSTRUCTIONS);
     }
     else {
-        fs.mkdirSync(dir, { recursive: true });
+        fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.writeFileSync(file, INSTRUCTIONS);
     }
     console.log(`  + ${file}`);
@@ -237,6 +253,21 @@ async function promptClient() {
         rl.close();
     }
 }
+/** D22: where the Copilot memory instructions live. Personal (default) is the
+ * Copilot user-level location — all projects, never checked in. */
+async function promptInstructionsScope() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("Where should the Copilot memory instructions live?");
+        console.log("  1) personal — user-level, all projects, never checked into a repo");
+        console.log("  2) project  — .github/copilot-instructions.md, shared with the repo");
+        const ans = (await rl.question("Choice [1]: ")).trim();
+        return ans === "2" ? "project" : "personal";
+    }
+    finally {
+        rl.close();
+    }
+}
 export async function initProject(opts) {
     const interactive = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
     let client = normalizeClient(opts.client ?? "");
@@ -248,11 +279,22 @@ export async function initProject(opts) {
         client = (await promptClient()) ?? "";
     if (!client && !interactive)
         client = "vscode"; // historical default for scripts / one-shot npx
+    let scope = "personal";
+    if (opts.instructions) {
+        if (opts.instructions !== "personal" && opts.instructions !== "project") {
+            console.error(`unknown --instructions "${opts.instructions}" (personal|project)`);
+            process.exit(1);
+        }
+        scope = opts.instructions;
+    }
+    else if (interactive) {
+        scope = await promptInstructionsScope();
+    }
     if (interactive) {
         // Install-time settings (D19). Non-default answers persist to the JSONC
         // config file; `open-memex config set` changes them later.
         const patch = {};
-        const keywordCaptureEnabled = await askBool("Auto-capture keywords like 记住… / remember… into memory?", DEFAULT_CONFIG.keywordCaptureEnabled);
+        const keywordCaptureEnabled = await askBool("Auto-capture keywords like remember… / note that… into memory?", DEFAULT_CONFIG.keywordCaptureEnabled);
         if (keywordCaptureEnabled !== DEFAULT_CONFIG.keywordCaptureEnabled)
             patch.keywordCaptureEnabled = keywordCaptureEnabled;
         const injectOnFirstTurn = await askBool("Inject relevant memories when a session starts?", DEFAULT_CONFIG.injectOnFirstTurn);
@@ -269,8 +311,10 @@ export async function initProject(opts) {
         writeMcpJson(root, client, opts.force);
         // copilot-instructions.md is VS Code/Cursor-shaped; opencode as a plain MCP
         // consumer already gets the guidance from the tool descriptions (D16).
+        // D22: personal scope (default) writes to the Copilot user-level location
+        // so the repo stays clean for teammates without open-memex.
         if (client !== "opencode")
-            writeInstructions(root);
+            writeInstructions(root, scope, client);
     }
     else {
         console.log("  - editor setup skipped");

package/docs/V2-DESIGN.md

@@ -587,6 +587,16 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   / `npm run mcp` run `src/` directly); `doctor`'s MCP self-check resolves its server
   entry the same way it is running (`dist/mcp.js` vs `src/mcp.ts`). The opencode
   native plugin still loads `src/index.ts` (Bun strips types anywhere). 2026-09-27.*
+- **D22** — `init` writes the Copilot memory instructions to the **user level** by
+  default (`~/.copilot/copilot-instructions.md`; `%USERPROFILE%\copilot-
+  instructions.md` for Visual Studio 2026) instead of the repo-level
+  `.github/copilot-instructions.md`. *Rationale: the repo-level file is checked in,
+  so teammates without open-memex get Copilot errors about missing `memory_*`
+  tools. The user-level location is GitHub's official personal-instructions slot
+  (highest priority, all projects, never in a repo). `--instructions project`
+  keeps the old repo-level behavior for teams where everyone uses open-memex.
+  The instructions carry a guard clause ("ignore this section when the
+  `open-memex` MCP server is not available") as cheap insurance. 2026-09-27.*
 
 ## Open Questions
 

package/package.json

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

@@ -20,33 +20,39 @@ import { paths } from "./paths.ts";
 import { redact } from "./redact.ts";
 import { resolveMcpCommand } from "./init.ts";
 import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-function usage(): never {
+function usage(exitCode = 1): never {
   console.log(`open-memex CLI
 
 Usage:
-  node --experimental-strip-types src/cli.ts where
-  node --experimental-strip-types src/cli.ts list [--scope project|personal] [--type T] [--limit N]
-  node --experimental-strip-types src/cli.ts search "query" [--scope project|personal|both] [--type T] [--limit N]
-  node --experimental-strip-types src/cli.ts add "content" [--scope project|personal] [--type T] [--tag t1,t2]
-  node --experimental-strip-types src/cli.ts supersede <id> "new content" [--type T] [--tag t1,t2]
-  node --experimental-strip-types src/cli.ts status <id> active|deprecated|retracted|archived
-  node --experimental-strip-types src/cli.ts forget <id>
-  node --experimental-strip-types src/cli.ts reindex
-  node --experimental-strip-types src/cli.ts scopes
-  node --experimental-strip-types src/cli.ts migrate [--from <key>] [--to <key>]
+  open-memex where
+  open-memex list [--scope project|personal] [--type T] [--limit N]
+  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+  open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+  open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+  open-memex status <id> active|deprecated|retracted|archived
+  open-memex forget <id>
+  open-memex reindex
+  open-memex scopes
+  open-memex migrate [--from <key>] [--to <key>]
                                           [--dry-run] [--on-conflict newer|overwrite|skip]
-  node --experimental-strip-types src/cli.ts migrate --to-v2 [--dry-run]
-  node --experimental-strip-types src/cli.ts mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
-  node --experimental-strip-types src/cli.ts init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
-  node --experimental-strip-types src/cli.ts config [set <key> <value>]
-  node --experimental-strip-types src/cli.ts capture --dry-run "text"
-  node --experimental-strip-types src/cli.ts doctor
+  open-memex migrate --to-v2 [--dry-run]
+  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 config [set <key> <value>]
+  open-memex capture --dry-run "text"
+  open-memex doctor
 
 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\`) plus
-\`.github/copilot-instructions.md\` — no copy-paste needed.
+\`opencode.jsonc\`, or Visual Studio's solution-level \`.mcp.json\`) — no copy-paste
+needed. 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.
@@ -66,7 +72,7 @@ git remote after memories were already stored under the cwd-based key.
 \`migrate --to-v2\` converts v1 memory files to the v2 format (§19):
 user→personal scope rename, epoch→RFC 3339 times, priority→importance,
 type: instruction→role split. Always preview with --dry-run first.`);
-  process.exit(1);
+  process.exit(exitCode);
 }
 
 function parseFlags(argv: string[]): Record<string, string> {
@@ -179,7 +185,16 @@ function printMcpConfig(client: string): never {
 
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
-  if (!cmd) usage();
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") usage(0);
+
+  if (cmd === "--version" || cmd === "-v") {
+    // package.json sits two levels above this file in both layouts
+    // (src/cli.ts and dist/cli.js).
+    const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    console.log(`open-memex ${pkg.version}`);
+    return;
+  }
 
   const cfg = loadConfig();
   const project = resolveProjectScope(process.cwd());
@@ -225,6 +240,7 @@ async function main() {
       client: flags["client"],
       force: flags["force"] === "true",
       yes: flags["yes"] === "true",
+      instructions: flags["instructions"],
     });
     return;
   }

package/src/init.ts

@@ -1,6 +1,7 @@
 // `open-memex init` — one-command project setup (§17 adoption path).
 // Pure file operation: no DB, no network. Safe to run in any directory.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
@@ -46,6 +47,9 @@ export function resolveMcpCommand(): McpCommand {
 const INSTRUCTIONS = `${MARKER}
 # OpenMemex memory
 
+> Applies only when the \`open-memex\` MCP server is available in this session
+> (the \`memory_*\` tools exist). Otherwise ignore this section.
+
 You have a local memory MCP server (\`open-memex\`) with five tools:
 \`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`.
 
@@ -186,9 +190,26 @@ function writeVisualStudioMcpJson(root: string, force: boolean): string | null {
   return file;
 }
 
-function writeInstructions(root: string): string {
-  const dir = path.join(root, ".github");
-  const file = path.join(dir, "copilot-instructions.md");
+function writeInstructions(
+  root: string,
+  scope: "personal" | "project",
+  client: string,
+): string {
+  const file =
+    scope === "project"
+      ? path.join(root, ".github", "copilot-instructions.md")
+      : client === "visualstudio"
+        ? path.join(os.homedir(), "copilot-instructions.md")
+        : path.join(os.homedir(), ".copilot", "copilot-instructions.md");
+  if (scope === "personal") {
+    // A previous project-scoped init may have left the section behind — flag it
+    // so the repo can go back to being open-memex-free for teammates.
+    const proj = path.join(root, ".github", "copilot-instructions.md");
+    if (fs.existsSync(proj) && fs.readFileSync(proj, "utf8").includes(MARKER)) {
+      console.log(`  ! project-level instructions still present at ${proj}`);
+      console.log(`    remove the open-memex section there to keep the repo clean.`);
+    }
+  }
   if (fs.existsSync(file)) {
     const cur = fs.readFileSync(file, "utf8");
     if (cur.includes(MARKER)) {
@@ -197,7 +218,7 @@ function writeInstructions(root: string): string {
     }
     fs.writeFileSync(file, cur.replace(/\s+$/, "") + "\n\n" + INSTRUCTIONS);
   } else {
-    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, INSTRUCTIONS);
   }
   console.log(`  + ${file}`);
@@ -254,10 +275,26 @@ async function promptClient(): Promise<string | null> {
   }
 }
 
+/** D22: where the Copilot memory instructions live. Personal (default) is the
+ * Copilot user-level location — all projects, never checked in. */
+async function promptInstructionsScope(): Promise<"personal" | "project"> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    console.log("Where should the Copilot memory instructions live?");
+    console.log("  1) personal — user-level, all projects, never checked into a repo");
+    console.log("  2) project  — .github/copilot-instructions.md, shared with the repo");
+    const ans = (await rl.question("Choice [1]: ")).trim();
+    return ans === "2" ? "project" : "personal";
+  } finally {
+    rl.close();
+  }
+}
+
 export async function initProject(opts: {
   client?: string;
   force: boolean;
   yes: boolean;
+  instructions?: string;
 }): Promise<void> {
   const interactive = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
   let client = normalizeClient(opts.client ?? "");
@@ -267,12 +304,22 @@ export async function initProject(opts: {
   }
   if (!client && interactive) client = (await promptClient()) ?? "";
   if (!client && !interactive) client = "vscode"; // historical default for scripts / one-shot npx
+  let scope: "personal" | "project" = "personal";
+  if (opts.instructions) {
+    if (opts.instructions !== "personal" && opts.instructions !== "project") {
+      console.error(`unknown --instructions "${opts.instructions}" (personal|project)`);
+      process.exit(1);
+    }
+    scope = opts.instructions;
+  } else if (interactive) {
+    scope = await promptInstructionsScope();
+  }
   if (interactive) {
     // Install-time settings (D19). Non-default answers persist to the JSONC
     // config file; `open-memex config set` changes them later.
     const patch: Record<string, unknown> = {};
     const keywordCaptureEnabled = await askBool(
-      "Auto-capture keywords like 记住… / remember… into memory?",
+      "Auto-capture keywords like remember… / note that… into memory?",
       DEFAULT_CONFIG.keywordCaptureEnabled,
     );
     if (keywordCaptureEnabled !== DEFAULT_CONFIG.keywordCaptureEnabled)
@@ -296,7 +343,9 @@ export async function initProject(opts: {
     writeMcpJson(root, client, opts.force);
     // copilot-instructions.md is VS Code/Cursor-shaped; opencode as a plain MCP
     // consumer already gets the guidance from the tool descriptions (D16).
-    if (client !== "opencode") writeInstructions(root);
+    // D22: personal scope (default) writes to the Copilot user-level location
+    // so the repo stays clean for teammates without open-memex.
+    if (client !== "opencode") writeInstructions(root, scope, client);
   } else {
     console.log("  - editor setup skipped");
   }