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

package/AGENTS.md

@@ -5,7 +5,10 @@ for user-facing docs; `docs/V2-DESIGN.md` §18 for the roadmap. This file lists
 
 ## Runtime model — read before touching anything
 
-Three entry points execute the same TypeScript source, with **no build step**:
+Three entry points execute the same TypeScript source. **Development is build-free**;
+the published npm package ships pre-compiled JS (`npm run build` → `dist/`,
+via `prepublishOnly` — Node refuses `--experimental-strip-types` for files under
+`node_modules`, so a global install cannot run `src/` directly):
 
 - **opencode host** loads `src/index.ts` under embedded **Bun**. SQLite here is `bun:sqlite` (built-in).
 - **CLI** (`src/cli.ts`) and smoke tests run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
@@ -34,16 +37,19 @@ 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).
 `open-memex init` asks editor + two settings on a TTY (`--yes` skips, scripts never
 prompt); `open-memex config set <key> <value>` edits settings after install.
-The bin is a tiny JS launcher (`bin/open-memex.js`) that
-re-execs `src/cli.ts` with type-stripping — no build step, works on Node 22.6+.
+The published `open-memex` bin points at `dist/cli.js` (compiled at publish time).
+From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
+with type-stripping — no build step needed for development.
 
 There is **no `npm test`** and no CI. Verification loop is: `npm run typecheck` + `smoke-pure.ts` + (if touching sqlite) `npm run cli -- reindex` against a scratch `MY_O_MEMORY_HOME`.
 

package/README.md

@@ -8,7 +8,7 @@ plus a generic MCP server (VS Code Copilot, Cursor, Claude Code, Visual Studio,
 - **Markdown files** as the source of truth (human-editable, git-friendly)
 - **SQLite FTS5** as a rebuildable index (BM25 keyword search, via `better-sqlite3`)
 - **Zero cloud**, zero account, zero third-party API
-- Loads directly under opencode's embedded Bun runtime; CLI and MCP server run under Node — no build step, no Bun install
+- Loads directly under opencode's embedded Bun runtime; CLI and MCP server run under Node — no build step in development (the published npm package ships pre-compiled JS), no Bun install
 
 ## Installation
 
@@ -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:
@@ -259,8 +267,9 @@ open-memex reindex      # rebuild the SQLite index from markdown
 open-memex migrate --to-v2 [--dry-run]   # v1 data → v2
 ```
 
-The CLI runs under Node 22 with the built-in experimental TypeScript loader (no build
-step). From a source checkout, prefix every command with
+The CLI runs under Node 22. From a source checkout it uses the built-in experimental
+TypeScript loader (no build step); the published npm package ships pre-compiled JS
+(`npm run build` at publish time). From a source checkout, prefix every command with
 `node --experimental-strip-types src/cli.ts` (or `npm run cli -- <command>` for
 simple cases — npm swallows unknown `--flag` args, so prefer direct `node`).
 
@@ -279,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

@@ -8,7 +8,7 @@
 - **Markdown 文件**是 source of truth（人类可读、git 友好）
 - **SQLite FTS5** 做可重建索引（BM25 关键词检索，`better-sqlite3`）
 - **零云端**、零账号、零第三方 API
-- 直接跑在 opencode 内嵌的 Bun 运行时里；CLI 和 MCP server 跑在 Node 下——无需构建、无需安装 Bun
+- 直接跑在 opencode 内嵌的 Bun 运行时里；CLI 和 MCP server 跑在 Node 下——开发时无需构建（发布的 npm 包带预编译好的 JS）、无需安装 Bun
 
 ## 安装
 
@@ -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   # 已安装版本
 ```
 
 记忆操作：
@@ -258,7 +266,8 @@ open-memex reindex      # 从 markdown 重建 SQLite 索引
 open-memex migrate --to-v2 [--dry-run]   # v1 数据 → v2
 ```
 
-CLI 跑在 Node 22 内置的实验性 TypeScript loader 下（无需构建）。
+CLI 跑在 Node 22 下。从源码 checkout 使用时走内置的实验性 TypeScript loader（无需构建）；
+发布的 npm 包带预编译好的 JS（发布时间执行 `npm run build`）。
 从源码 checkout 使用时，每条命令前加
 `node --experimental-strip-types src/cli.ts`（简单场景也可用
 `npm run cli -- <命令>`——但 npm 会吞掉未知的 `--flag` 参数，
@@ -279,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/capture/keywords.js

@@ -0,0 +1,43 @@
+/**
+ * Scan user text for memory-capture keyword triggers.
+ * Each pattern must have a single capture group whose value becomes the memory body.
+ * Personal patterns (cfg.keywordPersonalPatterns) force the personal scope.
+ *
+ * Personal patterns run first and claim their line: an explicit scope signal
+ * (e.g. "记住我对花粉过敏") must not also fire the generic 记住 into the project scope.
+ */
+export function detectKeywords(userText, cfg) {
+    if (!cfg.keywordCaptureEnabled)
+        return [];
+    const hits = [];
+    const lines = userText.split(/\r?\n/);
+    const claimed = new Set();
+    const scan = (patterns, personal, skipClaimed) => {
+        for (const src of patterns) {
+            let re;
+            try {
+                re = new RegExp(src, "i");
+            }
+            catch {
+                continue;
+            }
+            for (let i = 0; i < lines.length; i++) {
+                if (skipClaimed && claimed.has(i))
+                    continue;
+                const m = lines[i].match(re);
+                if (!m || !m[1])
+                    continue;
+                const content = m[1].trim().replace(/[.!?]$/, "").trim();
+                if (content.length >= 3 && content.length <= 2000) {
+                    hits.push({ content, pattern: src, personal });
+                    if (personal)
+                        claimed.add(i);
+                    break; // one hit per pattern per message
+                }
+            }
+        }
+    };
+    scan(cfg.keywordPersonalPatterns, true, false);
+    scan(cfg.keywordPatterns, false, true);
+    return hits;
+}