open-memex 0.3.0-alpha.1 → 0.3.0-alpha.3

package/AGENTS.md

@@ -37,9 +37,11 @@ node --experimental-strip-types scripts\smoke-mcp.ts    # MCP handshake + tool r
 After `npm i -g open-memex@alpha` (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

@@ -77,7 +77,7 @@ open-memex init --client vscode
 npx -y open-memex@alpha 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 +86,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 +112,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 +123,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
@@ -237,6 +243,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:
@@ -280,7 +288,7 @@ 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

package/README.zh-CN.md

@@ -75,7 +75,7 @@ open-memex init --client vscode
 npx -y open-memex@alpha init --client vscode
 ```
 
-自动写 `.vscode/mcp.json` 和 `.github/copilot-instructions.md`，然后重新加载窗口，
+自动写 `.vscode/mcp.json` 和用户级 Copilot instructions，然后重新加载窗口，
 在 Copilot Chat 的 MCP 面板里确认 `open-memex` server 已启动。
 
 **Cursor：**
@@ -84,7 +84,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 +110,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,6 +120,12 @@ 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）。
@@ -236,6 +242,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   # 已安装版本
 ```
 
 记忆操作：
@@ -280,7 +288,7 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 
 > **注意：** MCP 是请求/响应式的——它给 agent 提供 tools，但没有 opencode
 > 插件的关键词自动捕获和首轮上下文注入。想让 agent 主动用记忆，
-> 靠的是 agent 的 instructions（`init` 写的 `.github/copilot-instructions.md`）。
+> 靠的是 agent 的 instructions（`init` 写的 Copilot instructions）。
 
 ## 路线图（Roadmap）
 

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-alpha.3",
   "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");
   }