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

package/AGENTS.md

@@ -1,16 +1,23 @@
 # AGENTS.md
 
-Local-first memory plugin for opencode. See `README.md` and `PLAN.md` for user-facing docs and the roadmap. This file lists only the non-obvious things an agent needs to work in this repo.
+Local-first memory plugin for opencode. See `README.md` (English) and `README.zh-CN.md` (Chinese)
+for user-facing docs; `docs/V2-DESIGN.md` §18 for the roadmap. This file lists only the non-obvious things an agent needs to work in this repo.
 
 ## Runtime model — read before touching anything
 
-Two runtimes 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 test run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
+- **CLI** (`src/cli.ts`) and smoke tests run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
+- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same five memory tools to any MCP client (VS Code Copilot, Cursor, Claude Code). **stdout is the protocol channel — never log to stdout in `mcp.ts`; diagnostics go to stderr.**
 
 `src/store/db.ts` picks the backend at runtime by sniffing `globalThis.Bun`. Both backends share the same surface (`new Database(path)`, `.exec`, `.prepare().run/all/get`, `.close`). Any DB code you write must stay on that common subset — do not import `better-sqlite3` or `bun:sqlite` directly outside `db.ts`.
 
+Tool logic is host-agnostic and lives in `src/tools/ops.ts` (plain functions + shared zod arg shapes + `TOOL_DESCRIPTIONS`). `src/tools/memory.ts` (opencode) and `src/mcp.ts` are thin adapters — when adding or changing a tool, change `ops.ts` once and both hosts pick it up.
+
 Consequences:
 - Imports **must** use explicit `.ts` extensions (`allowImportingTsExtensions: true`, `moduleResolution: "Bundler"`).
 - No transpile / bundle output. Do not add one; opencode loads the `.ts` file directly.
@@ -22,9 +29,26 @@ Consequences:
 npm install                                          # once
 npm run typecheck                                    # tsc --noEmit — the only lint/type gate
 npm run cli -- where | list | search "q" | add ... | forget <id> | reindex
+npm run mcp                                          # start the stdio MCP server
 node --experimental-strip-types scripts\smoke-pure.ts   # runs pure-logic checks (no sqlite)
+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
+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 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 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`.
 
 To load the plugin in opencode locally, `~/.config/opencode/opencode.jsonc` must have:
@@ -56,7 +80,7 @@ Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (S
 
 Every write path (tool, keyword hook, CLI `add`) must:
 1. Call `redact(content, cfg.redactPatterns)`. Built-in provider patterns live in `src/redact.ts` (always on); config `redactPatterns` is for user extras only.
-2. If `hadSecret` → refuse the write (do not save `[REDACTED]` unless the user wrapped it in `<private>…</private>`).
+2. If `hadSecret` → the matched secret is **masked in place** (first 4 characters kept, the rest replaced with `x`) and the write proceeds; never save the unmasked original. `<private>…</private>` spans are stripped to `[REDACTED]` instead (design D14).
 3. Check `findDuplicates` (design §3.4): identical content is idempotent (return existing id); near-duplicates (similarity ≥ 0.8) warn but save — suggest `supersede` when the new content replaces the old.
 4. `writeMemoryFile` first, then `readMemoryFile` + `upsertFromFile` to keep FTS in sync.
 
@@ -67,7 +91,7 @@ Every write path (tool, keyword hook, CLI `add`) must:
 - Chain integrity is self-healing: on read, a missing counterpart is auto-completed with a warning; a dangling pointer warns but is never fabricated. Don't "fix" chains by editing frontmatter directly — let the read path do it.
 - Frontmatter is `schema_version: 2`. The SQLite index schema is versioned separately and rebuilds automatically on version change — never hand-edit `index.db`.
 
-Keyword capture fires from `chat.message` on the assistant's `output.parts` text. Patterns live in `src/capture/keywords.ts` / config `keywordPatterns`; regex group 1 is the memory body.
+Keyword capture fires from `chat.message` on the user's message parts (`UserMessage`). Patterns live in `src/capture/keywords.ts` / config `keywordPatterns`; regex group 1 is the memory body. Scope routing: personal patterns (`cfg.keywordPersonalPatterns`) force the personal scope — the rule is 我 → personal (记住我/替我记/我觉得/我喜欢/remember for me), 我们 → current scope (我们认为/我们决定/帮我们记住); personal patterns run first and claim their line so a generic trigger can't double-fire.
 
 Context injection happens exactly once per session in `experimental.chat.system.transform`, guarded by an in-memory `Set<sessionID>` in `src/index.ts`. It is not persisted — restarting opencode re-injects on the next first turn.
 
@@ -83,7 +107,7 @@ log records what was already considered and rejected.
 Still hard: no cloud, no silent sync (explicit pull only), Markdown is the source
 of truth, `personal` scope never leaves the machine. Embeddings are an *optional
 capability* per the design — do not add them (or LLM-driven extraction, or a
-knowledge graph) without updating the design doc first. `PLAN.md` tracks the
+knowledge graph) without updating the design doc first. `docs/V2-DESIGN.md` §18 tracks the
 build roadmap; the design doc tracks the *why*.
 
 ## Branch workflow
@@ -97,3 +121,9 @@ hold `V2` and `V2/…` simultaneously. Full rules: `CONTRIBUTING.md`.
 - `strict: true`, `verbatimModuleSyntax: false`. Prefer `import type` for types anyway.
 - Log prefix is `[open-memex]`. Gate verbose logs behind `cfg.logLevel === "debug"`.
 - Windows is a first-class target (this workspace is Windows). Use `node:path` and never hardcode `/`.
+- **Docs ship with code.** Every code change updates the docs it affects in the same commit:
+  new/changed tools → `README.md` + `README.zh-CN.md` tool tables + MCP section (keep both
+  languages in sync); behavior changes → both READMEs
+  and the frozen `docs/V2-DESIGN.md` (append a `D<n>` decision entry, never rewrite history);
+  new commands → README CLI sections + this file's Commands. A change without its docs
+  is not done.

package/README.md

@@ -1,45 +1,172 @@
 # open-memex
 
-Local-first persistent memory plugin for [opencode](https://opencode.ai).
+[中文文档](./README.zh-CN.md)
+
+Local-first persistent memory for AI coding agents: an [opencode](https://opencode.ai) plugin
+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 runs 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
+
+### Requirements
+
+- **Node.js ≥ 22.6** (`open-memex doctor` verifies this for you)
+
+### Step 1 — Install the CLI
+
+**npm (recommended):**
+
+```sh
+npm install -g open-memex@alpha
+```
+
+This installs the `0.3.0-alpha` prerelease channel. (`latest` still points at the older
+`0.1.0` stable.)
 
-## Install (dev)
+**No install — run via npx:**
 
+```sh
+npx -y open-memex@alpha <command>   # e.g. npx -y open-memex@alpha init --client vscode
 ```
-cd c:\github\open-memex
+
+**From source** (bleeding edge, `V2-dev-p2` branch):
+
+```sh
+git clone -b V2-dev-p2 https://github.com/stoneskin/open-memex.git
+cd open-memex
 npm install
+node --experimental-strip-types src/cli.ts <command>
 ```
 
-Then add to `~/.config/opencode/opencode.jsonc`:
+> 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.
 
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["file:///c:/github/open-memex/src/index.ts"]
-}
+#### "`open-memex` is not recognized" — PATH setup
+
+A global `npm install -g` puts the `open-memex` launcher in npm's global bin folder.
+If your terminal can't find it, that folder isn't on your `PATH`:
+
+1. Find the folder: `npm config get prefix`
+   - **Windows:** the launcher (`open-memex.cmd`) sits directly in that folder, e.g.
+     `C:\Users\<you>\AppData\Roaming\npm`
+   - **macOS / Linux:** it's in `<prefix>/bin`, e.g. `/usr/local/bin` or
+     `~/.nvm/versions/node/v22.x.x/bin`
+2. Add it to `PATH`:
+   - **Windows:** Settings → System → About → Advanced system settings →
+     Environment Variables → add the folder to the *User* `Path` → **restart the
+     terminal**. Verify with `where open-memex`.
+   - **macOS / Linux:** add `export PATH="$(npm prefix -g)/bin:$PATH"` to
+     `~/.zshrc` (or `~/.bashrc`), restart the shell, verify with
+     `command -v open-memex`.
+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.
+
+### Step 2 — One-command setup for your editor
+
+Run from your **project root** (so the project scope resolves to this repo):
+
+**VS Code** (Copilot):
+
+```sh
+open-memex init --client vscode
+# …or without a global install:
+npx -y open-memex@alpha init --client vscode
 ```
 
-Restart opencode.
+Writes `.vscode/mcp.json` and `.github/copilot-instructions.md`, then reload the
+window and confirm the `open-memex` server is started in Copilot Chat's MCP panel.
+
+**Cursor:**
+
+```sh
+open-memex init --client cursor
+```
+
+Writes `.cursor/mcp.json` and `.github/copilot-instructions.md`.
+
+**opencode** (as a plain MCP consumer):
+
+```sh
+open-memex init --client opencode
+```
+
+Writes project-level `opencode.jsonc` (`type: "local"`). Prefer the native plugin
+instead? Add `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` to
+`~/.config/opencode/opencode.jsonc` — you get keyword auto-capture and first-turn
+context injection on top of the tools.
+
+**Claude Code** (from your project root):
+
+```sh
+claude mcp add open-memex -- open-memex mcp
+# …or print the config snippet: open-memex mcp --print-config claude
+```
+
+**Visual Studio** (from your solution directory):
+
+```sh
+open-memex init --client visualstudio
+```
 
-## Tools the plugin exposes to the agent
+Writes solution-level `.mcp.json` and `.github/copilot-instructions.md`. 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.
+
+**Codex:** no `init` client yet — add the server manually via
+`open-memex mcp --print-config` as a starting point (`[mcp_servers]` in
+`config.toml`, or `codex mcp add`).
+
+`init` notes:
+
+- 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
+  VS Code).
+- 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
+  faster direct command later.
+
+### Step 3 — Verify it works
+
+```sh
+open-memex doctor
+```
+
+Checks: Node version, config source, scope resolution for the current directory,
+storage writability, then boots a real MCP server and runs `initialize` +
+`tools/list` against it — all five tools must show up.
+
+## Tools the agent gets
 
 | Tool | What it does |
 |---|---|
-| `memory_add`     | Save a fact, preference, decision, note |
-| `memory_search`  | Keyword search (BM25) across project + personal memories |
-| `memory_list`    | List memories in a scope, newest first |
+| `memory_add`       | Save a fact, preference, decision, note |
+| `memory_search`    | Keyword search (BM25) across project + personal memories |
+| `memory_list`      | List memories in a scope, newest first |
 | `memory_supersede` | Replace a memory with a newer version (keeps a supersede chain) |
-| `memory_forget`  | Delete a memory by id |
+| `memory_forget`    | Delete a memory by id |
 
 ## Capture
 
-- **Keyword triggers** in user messages: `remember ...`, `note that ...`, `TIL ...`, `save this: ...`
+- **Keyword triggers** in user messages (opencode native plugin): `remember …`,
+  `note that …`, `don't forget …`, `TIL …`, `save this …`, plus Chinese
+  `记住…` / `记一下` / `记录一下` / `别忘了…`.
+  Scope routing: first-person singular goes **personal** (`remember for me`,
+  `记住我…`, `替我记…`, `我觉得…`, `我喜欢…`); first-person plural goes to the
+  current **project** scope (`我们认为…`, `我们决定…`, `帮我们记住…`).
 - **Explicit tool calls** by the agent (via `memory_add`)
-- **Redaction**: content inside `<private>...</private>` tags is stripped; content matching secret patterns (API keys, tokens) is refused
+- **Redaction**: content inside `<private>…</private>` tags is stripped; detected
+  secrets (API keys, tokens, high-entropy credentials) are masked in place — first
+  4 characters kept, the rest replaced with `x` — and the memory is saved.
+  Preview what a message would capture with `open-memex capture --dry-run "…"`.
 
 ## Scopes
 
@@ -66,39 +193,115 @@ $XDG_DATA_HOME/open-memex/          (Linux/macOS)
 ```
 
 Each `.md` file has v2 YAML frontmatter (`id, scope, scope_key, visibility, role, type,
-importance, status, tags, created_at, updated_at, schema_version`, ...) followed by the
+importance, status, tags, created_at, updated_at, schema_version`, …) followed by the
 memory content. You can edit them by hand — the plugin re-syncs on startup by comparing
 file mtimes. Markdown is the source of truth; the SQLite index is derived and rebuildable
 (`open-memex reindex`).
 
 ## Config
 
-Optional file at `~/.config/opencode/open-memex.jsonc`. See `PLAN.md` for defaults.
+Optional file at `~/.config/opencode/open-memex.jsonc` (override path with
+`MY_O_MEMORY_CONFIG`; override storage root with `MY_O_MEMORY_HOME`).
 
-## CLI
+Defaults:
 
-Runs under Node 22 with the built-in experimental TypeScript loader (no build step).
+```jsonc
+{
+  "maxProjectMemories": 8,    // top-N project memories injected on first turn
+  "maxProfileItems": 5,       // top-N personal items injected on first turn
+  "injectOnFirstTurn": true,  // [OPEN-MEMEX] system-prompt block
+  "keywordCaptureEnabled": true,
+  "logLevel": "info"          // info | debug
+}
+```
+
+`open-memex config` prints the effective config (defaults + file).
+Change a setting after install:
 
+```sh
+open-memex config set keywordCaptureEnabled false
+open-memex config set maxProjectMemories 12
 ```
-node --experimental-strip-types src/cli.ts where
-node --experimental-strip-types src/cli.ts list --scope project
-node --experimental-strip-types src/cli.ts search "auth flow"
-node --experimental-strip-types src/cli.ts add "This repo uses better-sqlite3" --type project-config
-node --experimental-strip-types src/cli.ts supersede <id> "Updated content"
-node --experimental-strip-types src/cli.ts status <id> deprecated
-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 <old-scope-key> [--dry-run]
-node --experimental-strip-types src/cli.ts migrate --to-v2 [--dry-run]
+
+Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
+`keywordCaptureEnabled`, `logLevel`. Full design: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
+
+## CLI reference
+
+Setup & health:
+
+```sh
+open-memex init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
+open-memex config                                  # print effective config
+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
 ```
 
-Or via the npm script: `npm run cli -- list --scope project`.
-**Note:** flag arguments beyond the first must be passed via direct `node` invocation, not `npm run cli --`, because npm swallows unknown `--flag` args.
+Memory operations:
+
+```sh
+open-memex add "This repo uses better-sqlite3" --type project-config
+open-memex search "auth flow"
+open-memex list --scope project
+open-memex supersede <id> "Updated content"
+open-memex status <id> deprecated
+open-memex forget <id>
+```
+
+Maintenance:
+
+```sh
+open-memex where        # show storage + config paths
+open-memex scopes       # list project scopes with memory counts
+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. 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`).
+
+## MCP server
+
+The same five memory tools over the Model Context Protocol via a stdio server —
+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
+```
+
+The project scope is resolved from the process working directory, so configure the
+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`
+> that `init` writes).
+
+## Roadmap
+
+**`0.3.0-alpha` (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` /
+`resolve` workflow, in-repo memory dir), 1–2 colleague pilot.
+
+**Coming — `0.3.0` (stable):** org layer — org memory repo, curator convention,
+distill-to-AGENTS.md assist.
 
-## Status
+**Future (signal-gated, no version committed):** native agent plugins (Claude Code /
+Codex hooks as enhancement paths over the same MCP tools); local embeddings as a
+benchmark-gated experiment (no embedding model is ever downloaded without explicit
+opt-in); cloud `RemoteProvider` customization only if multi-repo sharing, ACL, or
+compliance needs demand it.
 
-v2 alpha (`0.2.0-alpha`): v2 data model + migration, dedup + lifecycle (supersede/status), redaction hardening, CJK bigram retrieval. See `PLAN.md` for the roadmap (local embeddings, auto-capture, compaction hook, etc).
+Design details: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) (append-only decision log D1–D20).
 
 ## License