open-memex 0.1.0 → 0.3.0-alpha

package/AGENTS.md

@@ -1,16 +1,20 @@
 # 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, with **no build step**:
 
 - **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 +26,25 @@ 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 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+.
+
 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:
@@ -46,28 +66,60 @@ Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (S
 
 ## Scope keys
 
-- `user` scope key is literal `"user"`.
+- `personal` scope key is literal `"personal"` (v1 called this `user`; renamed in v2, design §19).
 - `project` scope key: `project__<sanitized-name>__<12-hex-sha256>`, seeded from normalized git origin URL, else lowercased cwd. See `src/scope.ts`. Same repo across machines → same key (intentional; enables future git-commit of memories).
+- `org`, `team`, `public` are reserved — the schema rejects writes. See `docs/SCOPES.md`.
 - The scope key **changes** when a repo gains/loses a git origin. `src/index.ts` logs a one-shot warning on load if it finds files under the legacy cwd-only key (`resolveCwdScope`). Use `cli scopes` to enumerate all scope dirs and `cli migrate --from <old>` to reconcile — see `src/store/migrate.ts`. No auto-migration; two unrelated repos at the same cwd would silently merge.
 - Read-only callers must use `memoriesDirPath` (in `src/paths.ts`), never `memoriesDirFor`. The latter `mkdir -p`s the directory as a side effect and will pollute storage with empty scope dirs.
 
 ## Capture / write path invariants
 
 Every write path (tool, keyword hook, CLI `add`) must:
-1. Call `redact(content, cfg.redactPatterns)`.
-2. If `hadSecret` → refuse the write (do not save `[REDACTED]` unless the user wrapped it in `<private>…</private>`).
-3. `writeMemoryFile` first, then `readMemoryFile` + `upsertFromFile` to keep FTS in sync.
+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` → 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.
+
+## Lifecycle invariants (design §3.3)
+
+- Statuses: `active → superseded | deprecated | retracted | archived`. Retrieval excludes `retracted`/`archived`, ranks `active` above `deprecated`.
+- Never hand-write `status: superseded` or half a chain. Use the `supersede` code path (`src/store/lifecycle.ts`): the old record keeps its file, flips to `superseded`, and both sides get `supersedes`/`superseded_by`. Only `active` memories can be superseded.
+- 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.
 
-## Design constraints from PLAN.md worth honoring
+## Design constraints — read the frozen design first
+
+`docs/V2-DESIGN.md` is the frozen protocol v0.2 (zero open questions). Per its §12:
+AGENTS.md answers "how should AI work here"; the design doc answers "why is it
+built this way" (principles, iron rules, D1–D13 decision log). Before changing
+architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
+schema, MCP tools, CLI contract), read the relevant design section — the decision
+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. `docs/V2-DESIGN.md` §18 tracks the
+build roadmap; the design doc tracks the *why*.
+
+## Branch workflow
 
-MVP is intentionally: no cloud, no embeddings/vector search, no LLM-driven extraction, no knowledge graph. Do not add these without updating `PLAN.md`. Items 1–8 in the v2 roadmap have a rough priority order; prefer extending existing modules over new top-level concepts.
+`main` (stable, mirrors npm) ← `V2` (v2 integration) ← `V2-dev-p<n>`
+(phase work; draft PRs into `V2`). Never create `V2/<anything>` — git can't
+hold `V2` and `V2/…` simultaneously. Full rules: `CONTRIBUTING.md`.
 
 ## Style notes
 
 - `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/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to open-memex
+
+## Branch workflow
+
+- `main` — stable. Mirrors the npm release line. Never commit directly;
+  only merge from `V2` when a milestone is tested and ready to release.
+- `V2` — integration branch for the v2 line. Phase work lands here via
+  pull request. Merges to `main` only after the milestone is dogfooded
+  (plugin tested in opencode, `migrate --to-v2 --dry-run` clean on real data).
+- `V2-dev-p<n>` — phase dev branches (e.g. `V2-dev-p1`). Open as **draft**
+  PRs against `V2`; mark ready and merge after local testing passes.
+
+**Naming rule:** never create `V2/<anything>` — git cannot hold a branch
+named `V2` and a branch named `V2/…` at the same time (ref file vs.
+directory conflict). Use the flat `V2-dev-*` form instead.
+
+## Before opening a PR
+
+- `npm run typecheck` is clean
+- `node --experimental-strip-types scripts/smoke-pure.ts` passes
+- If you touched SQLite/FTS: `open-memex reindex` works against a scratch
+  `MY_O_MEMORY_HOME`
+- No secrets in fixtures (redaction tests are the exception)
+
+## Design authority
+
+Protocol decisions live in `docs/V2-DESIGN.md` (frozen v0.2, decision log
+D1–D13). Changing architecture, scope semantics, lifecycle, or the protocol
+surface (frontmatter schema, MCP tools, CLI contract) requires updating the
+design doc first. `AGENTS.md` has the working notes for AI agents; this file
+has the contributor workflow.

package/README.md

@@ -1,53 +1,183 @@
 # 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, 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
+```
+
+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
 ```
 
-Restart opencode.
+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:
 
-## Tools the plugin exposes to the agent
+- 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 + user memories |
-| `memory_list`    | List memories in a scope, newest first |
-| `memory_forget`  | Delete a memory by id |
+| `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 |
 
 ## 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
 
 - **project** — scoped to the current repo (keyed off the git origin URL hash, or the cwd if no remote). Default for new memories.
-- **user** — global across all your projects; use for personal preferences.
+- **personal** — global across all your projects, this machine only, never synced. Use for personal preferences. (v1 called this `user`; `migrate --to-v2` renames it.)
+
+See [docs/SCOPES.md](./docs/SCOPES.md) for the full scope model: key derivation, migration, visibility, reserved names.
 
 ## Retrieval
 
-On the first turn of every session, `open-memex` injects a `[OPEN-MEMEX]` block into the system prompt containing top-N recent project memories + top-N user preferences. The agent can also call `memory_search` on demand.
+On the first turn of every session, `open-memex` injects a `[OPEN-MEMEX]` block into the system prompt containing top-N recent project memories + top-N personal preferences. The agent can also call `memory_search` on demand.
 
 ## Storage layout
 
@@ -56,40 +186,122 @@ On the first turn of every session, `open-memex` injects a `[OPEN-MEMEX]` block
 $XDG_DATA_HOME/open-memex/          (Linux/macOS)
 ├── index.db                         # SQLite FTS5 index (rebuildable)
 └── memories/
-    ├── user/
+    ├── personal/
     │   └── <id>.md
     └── project__<name>__<hash12>/
         └── <id>.md
 ```
 
-Each `.md` file has YAML frontmatter (`id, scope_key, type, tags, created_at, ...`) followed by the memory content. You can edit them by hand — the plugin re-syncs on startup by comparing file mtimes.
+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
+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`).
+
+Defaults:
+
+```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
+```
+
+Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
+`keywordCaptureEnabled`, `logLevel`. Full design: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
 
-## CLI
+## CLI reference
 
-Runs under Node 22 with the built-in experimental TypeScript loader (no build step).
+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
 ```
-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 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]
+
+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>
 ```
 
-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.
+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 with the built-in experimental TypeScript loader (no build
+step). 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.
 
-MVP. See `PLAN.md` for the v2 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
 
-[MIT](./LICENSE)
+[Apache-2.0](./LICENSE)