open-memex 0.4.0-alpha.10 → 0.4.0-alpha.11

package/README.md

@@ -1,15 +1,77 @@
 # open-memex
 
+[![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
+
 [中文文档](./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, …).
 
+## Why open-memex?
+
+Engineering knowledge lives in two places: the code, and people's heads.
+Every new AI coding session starts from zero — the same project context gets
+explained again, the same gotchas get rediscovered, the same incident lessons
+fade when the chat ends.
+
+open-memex captures the part worth remembering — the decision, the constraint,
+the lesson — as reviewable Markdown, and injects it back into the next session
+automatically.
+
+> No capture, nothing to inherit.
+
+It also complements agentic development workflows (spec-driven development,
+plan/implement/verify loops): plans produce decisions, verification produces
+rules — open-memex is the memory layer that keeps them across sessions instead
+of re-deriving them on every run.
+
+## How it compares
+
+| | open-memex | Cloud memory services | Wiki / docs portal | Chat history |
+|---|---|---|---|---|
+| Data location | Your machine + your repos | Vendor servers | Central server | Gone when the chat ends |
+| Review before sharing | Yes — outbox + PR | Varies | Yes | No |
+| Agent recall | Session-start injection + search | API calls | Manual lookup | No |
+| Human-readable | Plain Markdown files | Dashboard / API | Yes | No |
+
 - **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 in development (the published npm package ships pre-compiled JS), no Bun install
 
+## Architecture
+
+```text
+                        ┌──────────────────┐
+                        │     AI agent     │
+                        │ Copilot / Cursor │
+                        │ Claude / opencode│
+                        └────────┬─────────┘
+                                 │ MCP (stdio) — 11 tools
+                                 │ session-start injection
+                        ┌────────▼─────────┐
+                        │    open-memex    │
+                        │    MCP server    │
+                        └──┬────────────┬──┘
+                           │            │
+              ┌────────────▼───┐  ┌─────▼──────────┐
+              │ Markdown files │  │ SQLite FTS5    │
+              │ source of truth│  │ rebuildable    │
+              │ local-first    │  │ index (BM25)   │
+              └─────────────┬──┘  └────────────────┘
+                            │ submit (explicit,
+                            │  local commit)
+                    ┌───────▼────────┐
+                    │    Git repo    │
+                    │ .ai/open-memex/│
+                    │  PR-reviewed   │
+                    │  team memory   │
+                    └────────────────┘
+
+personal scope: this machine only — never synced, never enters a repo.
+```
+
 ## Installation
 
 ### Requirements
@@ -18,7 +80,9 @@ plus a generic MCP server (VS Code Copilot, Cursor, Claude Code, Visual Studio,
 
 ### Step 1 — Install the CLI
 
-**npm (recommended):**
+#### Stable vs alpha
+
+**Stable** (recommended for most users) — the `latest` tag:
 
 ```sh
 npm install -g open-memex
@@ -26,10 +90,26 @@ npm install -g open-memex
 
 This installs the `0.3.0` stable release.
 
+**Alpha** (bleeding edge, for testers) — the `alpha` tag:
+
+```sh
+npm install -g open-memex@alpha
+```
+
+See what's published:
+
+```sh
+npm view open-memex version         # latest stable
+npm view open-memex@alpha version   # latest alpha
+```
+
+Alpha builds may have rough edges — bug reports are welcome.
+
 **No install — run via npx:**
 
 ```sh
-npx -y open-memex <command>   # e.g. npx -y open-memex init --client vscode
+npx -y open-memex <command>         # e.g. npx -y open-memex init --client vscode
+npx -y open-memex@alpha <command>  # alpha line, no install
 ```
 
 **From source** (bleeding edge, `V2-dev-p2` branch):
@@ -185,6 +265,62 @@ storage writability, then boots a real MCP server and runs `initialize` +
   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 "…"`.
 
+## Memory types
+
+Eleven types — `type` says what the memory is, `tags` say what it's about:
+
+| Type | Captures |
+|---|---|
+| `fact` | A stable true statement about the project or world |
+| `preference` | How someone likes things done |
+| `decision` | A choice that was made — the why and the trade-off |
+| `constraint` | A rule that must not be violated |
+| `todo` | A commitment to do something later |
+| `knowledge` | Durable domain or architecture knowledge |
+| `howto` | A procedure that worked |
+| `gotcha` | A trap to avoid |
+| `lesson` | What an incident or mistake taught us |
+| `observation` | Something noticed, not yet a conclusion |
+| `reference` | A pointer to the authoritative doc (no copying) |
+
+## Team memory workflow
+
+Personal notes stay private. Project knowledge follows an explicit, reviewable
+pipeline — nothing is shared automatically:
+
+```
+capture → outbox (draft, local) → submit → repo (.ai/open-memex/) → PR review → published → recall
+```
+
+1. **Capture** — save decisions, gotchas, lessons as drafts during normal work.
+2. **Review** — drafts wait in a local outbox; `sync-status` (or saying
+   "sync memory" in chat) shows what's pending.
+3. **Submit** — you name the memories; they move into `<repo>/.ai/open-memex/`
+   with a local commit. open-memex never auto-pushes.
+4. **PR review** — memories are plain Markdown; reviewers approve, request
+   changes, or reject through the normal branch/PR process (`promote`,
+   `pr-status`, `resolve`).
+5. **Recall** — published memories are injected at session start and searchable
+   on demand, for humans and agents alike.
+
+Reviewer convention: [docs/CURATOR.md](./docs/CURATOR.md).
+
+## Security & data
+
+- **Local-first:** everything lives on your machine (`%APPDATA%\open-memex` /
+  `~/.local/share/open-memex`) plus the repos you choose. Zero cloud calls,
+  zero accounts, zero third-party APIs, zero telemetry.
+- **Secrets stay out:** `<private>…</private>` spans are stripped; detected API
+  keys/tokens are masked in place before saving. Preview with
+  `open-memex capture --dry-run "…"`.
+- **Personal never syncs:** the `personal` scope is this machine only — excluded
+  from export by default and can never enter a repo.
+- **Auditable sharing:** team memories move only by explicit `submit`, travel
+  through branch/PR review, and every `promote` transition is appended to the
+  memory's `review_history` (who / when / why).
+- **You own the files:** Markdown is the source of truth — inspect, edit, or
+  delete anything by hand; the SQLite index rebuilds from the files.
+
 ## Scopes
 
 - **project** — scoped to the current repo (keyed off the git origin URL hash, or the cwd if no remote). Default for new memories.
@@ -401,28 +537,27 @@ server with cwd set to your project root (`init` handles this for you).
 
 ## Roadmap
 
-**`0.3.0` (this release):** generic MCP server, `open-memex` bin/CLI, one-command
+**`0.3.0` (stable):** 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.
 
-**In progress — `0.4.0`:** team sync — shared memory via git: appdata draft
+**`0.4.0` (in development):** team sync — shared memory via git: appdata draft
 outbox → `sync-status` → `submit` (local branch+commit, push/PR on your Yes)
-→ `promote` / `resolve` review workflow, in-repo `.ai/open-memex/` dir, 1–2
-colleague pilot; capture — §3.5 checkpoint distillation in MCP handshake +
-init instructions (agent proposes 1–3 captures, human decides).
-
-**Coming — `0.3.0` (stable):** org layer — org memory repo, curator convention,
-distill-to-AGENTS.md assist, `export`/`import` archive for user portability
-(Markdown + manifest, no walled garden; private excluded by default,
-`-a`/`--all` for full migration).
-
-**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.
-
-Design details: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) (append-only decision log D1–D20).
+→ `promote` / `resolve` review workflow, in-repo `.ai/open-memex/` dir;
+`export` / `import` archive for user portability (Markdown + manifest, no walled
+garden; private excluded by default, `-a` / `--all` for full migration);
+distill-to-AGENTS.md assist (`distill-agents`, propose-only — you merge by hand);
+§3.5 checkpoint distillation in the MCP handshake + init instructions (the agent
+proposes 1–3 captures at checkpoints, the human decides); 1–2 colleague pilot.
+
+**Future (signal-gated, no version committed):** org layer — org memory repo,
+curator convention; 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.
+
+Design details: [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) (append-only decision log).
 
 ## License
 

package/README.zh-CN.md

@@ -1,15 +1,74 @@
 # open-memex
 
+[![npm version](https://img.shields.io/npm/v/open-memex.svg)](https://www.npmjs.com/package/open-memex)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
+
 [English](./README.md)
 
 给 AI 编程助手的本地优先持久记忆：一个 [opencode](https://opencode.ai) 插件，
 加上一个通用 MCP server（VS Code Copilot、Cursor、Claude Code、Visual Studio 等）。
 
+## 为什么需要 open-memex？
+
+工程知识只存在于两个地方：代码里，和人的脑子里。
+每个新的 AI 编程会话都从零开始——同样的项目背景要反复讲，同样的坑要反复踩，
+同样的事故教训在聊天结束时就消失了。
+
+open-memex 把值得记住的部分——决策、约束、教训——存成可 review 的 Markdown，
+并在下一次会话开始时自动注入回去。
+
+> No capture, nothing to inherit.（不记录，就无从传承。）
+
+它也补齐了 agentic 开发工作流（spec 驱动开发、plan/implement/verify 循环）缺的那一块：
+plan 产出决策，verify 产出规则——open-memex 是让它们跨会话留存的记忆层，
+而不是每次从头重新推导。
+
+## 和其它方案的对比
+
+| | open-memex | 云端记忆服务 | Wiki / 文档平台 | 聊天记录 |
+|---|---|---|---|---|
+| 数据在哪 | 你的机器 + 你的仓库 | 服务商服务器 | 中心服务器 | 聊天结束就没了 |
+| 分享前 review | 有——outbox + PR | 不一定 | 有 | 没有 |
+| Agent 回忆 | 会话开始注入 + 搜索 | 调 API | 人工去查 | 没有 |
+| 人类可读 | 纯 Markdown 文件 | 后台 / API | 有 | 没有 |
+
 - **Markdown 文件**是 source of truth（人类可读、git 友好）
 - **SQLite FTS5** 做可重建索引（BM25 关键词检索，`better-sqlite3`）
 - **零云端**、零账号、零第三方 API
 - 直接跑在 opencode 内嵌的 Bun 运行时里；CLI 和 MCP server 跑在 Node 下——开发时无需构建（发布的 npm 包带预编译好的 JS）、无需安装 Bun
 
+## 架构
+
+```text
+                        ┌──────────────────┐
+                        │     AI agent     │
+                        │ Copilot / Cursor │
+                        │ Claude / opencode│
+                        └────────┬─────────┘
+                                 │ MCP (stdio) — 11 tools
+                                 │ session-start injection
+                        ┌────────▼─────────┐
+                        │    open-memex    │
+                        │    MCP server    │
+                        └──┬────────────┬──┘
+                           │            │
+              ┌────────────▼───┐  ┌─────▼──────────┐
+              │ Markdown files │  │ SQLite FTS5    │
+              │ source of truth│  │ rebuildable    │
+              │ local-first    │  │ index (BM25)   │
+              └─────────────┬──┘  └────────────────┘
+                            │ submit (explicit,
+                            │  local commit)
+                    ┌───────▼────────┐
+                    │    Git repo    │
+                    │ .ai/open-memex/│
+                    │  PR-reviewed   │
+                    │  team memory   │
+                    └────────────────┘
+
+personal scope：只属于这台机器——永不同步，永远进不了仓库。
+```
+
 ## 安装
 
 ### 前置要求
@@ -18,7 +77,9 @@
 
 ### 第一步——安装 CLI
 
-**npm（推荐）：**
+#### 稳定版 vs Alpha 版
+
+**稳定版**（推荐大多数用户）——`latest` 标签：
 
 ```sh
 npm install -g open-memex
@@ -26,10 +87,26 @@ npm install -g open-memex
 
 安装的是 `0.3.0` 正式版。
 
+**Alpha 版**（最新开发版，给测试者）——`alpha` 标签：
+
+```sh
+npm install -g open-memex@alpha
+```
+
+查看已发布版本：
+
+```sh
+npm view open-memex version         # 最新稳定版
+npm view open-memex@alpha version   # 最新 alpha 版
+```
+
+Alpha 版可能有毛边——欢迎报 bug。
+
 **免安装——用 npx 直接跑：**
 
 ```sh
-npx -y open-memex <命令>   # 例如 npx -y open-memex init --client vscode
+npx -y open-memex <命令>          # 例如 npx -y open-memex init --client vscode
+npx -y open-memex@alpha <命令>   # alpha 线，免安装
 ```
 
 **从源码安装**（最新开发版，`V2-dev-p2` 分支）：
@@ -180,6 +257,48 @@ open-memex doctor
   （API key、token、高熵凭据）就地打码——保留前 4 个字符，其余替换为 `x`——
   然后照常保存。用 `open-memex capture --dry-run "…"` 预览一条消息会被如何捕获。
 
+## 记忆类型（Memory types）
+
+11 种类型——`type` 说明这条记忆是什么，`tags` 说明它和什么有关：
+
+| 类型 | 记录什么 |
+|---|---|
+| `fact` | 关于项目或世界的稳定事实 |
+| `preference` | 某人做事的偏好 |
+| `decision` | 做过的选择——为什么、权衡了什么 |
+| `constraint` | 不能违反的规则 |
+| `todo` | 以后要做的承诺 |
+| `knowledge` | 持久的领域或架构知识 |
+| `howto` | 验证过的做法 |
+| `gotcha` | 要避开的坑 |
+| `lesson` | 事故或错误教会我们的东西 |
+| `observation` | 注意到的现象，还不是结论 |
+| `reference` | 指向权威文档的指针（不复制内容） |
+
+## 团队记忆工作流
+
+个人笔记永远私有。项目知识走一条显式、可 review 的流水线——没有任何东西会自动分享：
+
+```
+capture → outbox（本地草稿）→ submit → 仓库（.ai/open-memex/）→ PR review → published → recall
+```
+
+1. **Capture**——正常工作中把决策、坑、教训存成草稿。
+2. **Review**——草稿在本地 outbox 里等着；`sync-status`（或在聊天里说"同步记忆"）查看待处理项。
+3. **Submit**——你点名要分享的记忆才会进 `<repo>/.ai/open-memex/`，并做本地 commit。open-memex 永远不会自动 push。
+4. **PR review**——记忆就是纯 Markdown；reviewer 走正常的分支/PR 流程批准、要求修改或拒绝（`promote`、`pr-status`、`resolve`）。
+5. **Recall**——已发布的记忆在会话开始时自动注入，也可随时搜索，人和 agent 都能用。
+
+Reviewer 守则：[docs/CURATOR.md](./docs/CURATOR.md)。
+
+## 安全与数据
+
+- **本地优先：** 所有东西都在你的机器上（`%APPDATA%\open-memex` / `~/.local/share/open-memex`），加上你选择的仓库。零云端调用、零账号、零第三方 API、零遥测。
+- **密钥进不来：** `<private>…</private>` 包裹的内容会被剥离；检测到的 API key / token 在保存前就地打码。先用 `open-memex capture --dry-run "…"` 预览。
+- **个人 scope 永不同步：** `personal` 只属于这台机器——export 默认排除，也永远进不了仓库。
+- **分享可审计：** 团队记忆只能靠显式的 `submit` 移动，走分支/PR review，每次 `promote` 状态流转都会追加到记忆的 `review_history`（谁/何时/为什么）。
+- **文件是你的：** Markdown 是 source of truth——随手看、随手改、随手删；SQLite 索引可以从文件重建。
+
 ## Scope
 
 - **project** — 绑定当前仓库（用 git origin URL 哈希做 key，无 remote 则用 cwd）。新记忆默认进这里。
@@ -387,28 +506,26 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 
 ## 路线图（Roadmap）
 
-**`0.3.0`（本版）：** 通用 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 支持。
 
-**进行中 —— `0.4.0`：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
+**`0.4.0`（开发中）：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
 `sync-status` → `submit`（本地分支+commit，push/PR 拿你的 Yes 才做）
-→ `promote` / `resolve` 评审工作流、仓库内 `.ai/open-memex/` 目录，
-找 1–2 个同事做 pilot；捕获——§3.5 检查点蒸馏写进 MCP 握手指令和
-init 指令文件（agent 提议 1–3 条，人来定）。
-
-**Coming —— `0.3.0`（稳定版）：** 组织层——组织记忆仓库、
-curator 约定、distill-to-AGENTS.md 辅助、`export`/`import` 归档
-（Markdown + manifest，不造围墙花园，用户可带走；
-private 默认不导出，`-a`/`--all` 全量迁移）。
-
-**未来（看信号再定，不承诺版本）：** 原生 agent 插件
-（Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；
+→ `promote` / `resolve` 评审工作流、仓库内 `.ai/open-memex/` 目录；
+`export` / `import` 归档做用户可携带（Markdown + manifest，不造围墙花园；
+private 默认不导出，`-a` / `--all` 全量迁移）；
+distill-to-AGENTS.md 辅助（`distill-agents`，只提议不改写——人工合并）；
+§3.5 检查点蒸馏写进 MCP 握手指令和 init 指令文件
+（agent 在检查点提议 1–3 条捕获，人来定）；找 1–2 个同事做 pilot。
+
+**未来（看信号再定，不承诺版本）：** 组织层——组织记忆仓库、curator 约定；
+原生 agent 插件（Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；
 本地 embedding 做基准测试门控的实验（**未经明确 opt-in 绝不下载
 embedding 模型**）；云端 `RemoteProvider` 定制只在多仓库共享、
 ACL 或合规需求出现时才做。
 
-设计细节：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（append-only 决策日志 D1–D20）。
+设计细节：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（append-only 决策日志）。
 
 ## 许可证
 

package/dist/cli.js

@@ -23,7 +23,10 @@ import { fileURLToPath } from "node:url";
 const COMMAND_HELP = {
     where: `Show which project scope the current directory resolves to, and where its data lives.
 
-Usage: open-memex where`,
+Usage: open-memex where
+
+Example:
+  open-memex where`,
     list: `List memories in a scope, newest first.
 
 Usage: open-memex list [--scope project|personal] [--type T] [--limit N]
@@ -60,13 +63,22 @@ Example:
   open-memex add "We deploy on Fridays" --scope project --tag process`,
     supersede: `Replace a memory with a newer version. The old one is kept as history.
 
-Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]`,
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+
+Example:
+  open-memex supersede 01ABC "We deploy on Thursdays now"`,
     status: `Change a memory's lifecycle status.
 
-Usage: open-memex status <id> active|deprecated|retracted|archived`,
+Usage: open-memex status <id> active|deprecated|retracted|archived
+
+Example:
+  open-memex status 01ABC deprecated`,
     forget: `Delete a memory by id.
 
-Usage: open-memex forget <id>`,
+Usage: open-memex forget <id>
+
+Example:
+  open-memex forget 01ABC`,
     propose: `Copy personal memories into the project outbox as review drafts.
 The personal originals stay put. Nothing enters git at this step.
 
@@ -100,21 +112,34 @@ Usage: open-memex resolve [id-or-path]
 
 With no argument, lists conflicts. With an id or file path, shows the
 3-way merge (base / outbox / repo) so you can resolve it by hand.
-Conflicts are never auto-resolved.`,
+Conflicts are never auto-resolved.
+
+Examples:
+  open-memex resolve
+  open-memex resolve 01ABC`,
     "sync-status": `Show the project memory sync pipeline: when the index last synced
 and what triggered it, drafts waiting in the outbox (appdata), memories in the
 repo awaiting review or published, and repo files not yet committed.
 
-Usage: open-memex sync-status`,
+Usage: open-memex sync-status
+
+Example:
+  open-memex sync-status`,
     pull: `Pull shared project memories from the git remote: fetch + fast-forward
 only. Never auto-merges — a diverged branch fails with a clear message and is
 left for you to resolve by hand. On success the local index re-syncs.
 
-Usage: open-memex pull`,
+Usage: open-memex pull
+
+Example:
+  open-memex pull`,
     push: `Push the current branch (with its submitted memories) to the git
 remote. Explicit only — open-memex never pushes on its own.
 
-Usage: open-memex push`,
+Usage: open-memex push
+
+Example:
+  open-memex push`,
     export: `Export memories to a portable .tar.gz bundle (markdown source of
 truth + manifest.json) for moving to another machine or another app.
 Excludes visibility:private memories by default; --all includes everything.
@@ -126,19 +151,31 @@ Flags:
   --type    filter by memory type
   --tag     filter by tag
   --all, -a include private memories (full migration)
-  -o        output file (default: ./open-memex-export-<timestamp>.tar.gz)`,
+  -o        output file (default: ./open-memex-export-<timestamp>.tar.gz)
+
+Examples:
+  open-memex export -o backup.tar.gz
+  open-memex export --scope both --all -o full-migration.tar.gz`,
     import: `Import a bundle created by \`open-memex export\`. Personal memories
 go to the personal dir; project memories are re-keyed to the current project
 and land in the outbox as drafts. Existing identical memories are skipped;
 conflicting ids are reported, never overwritten.
 
-Usage: open-memex import <bundle.tar.gz> [--dry-run]`,
+Usage: open-memex import <bundle.tar.gz> [--dry-run]
+
+Examples:
+  open-memex import backup.tar.gz --dry-run
+  open-memex import backup.tar.gz`,
     "distill-agents": `Propose an AGENTS.md snippet distilled from project
 memories (decisions, constraints, lessons, gotchas, howtos). Prints markdown
 to stdout, or writes it with -o. Review and merge by hand — open-memex never
 rewrites your AGENTS.md on its own.
 
-Usage: open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]`,
+Usage: open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
+
+Examples:
+  open-memex distill-agents
+  open-memex distill-agents --type decision,gotcha -o agents-snippet.md`,
     submit: `Move outbox drafts into the repo for review: copies the drafts into
 the repo memory dir as proposed (a local-approved copy keeps its approval),
 commits locally on the CURRENT branch, and moves the outbox originals out.
@@ -162,13 +199,23 @@ overwritten. Report-only by default.
 Usage: open-memex pr-status [--apply]
 
 Flags:
-  --apply   write the transitions locally (still never pushes)`,
+  --apply   write the transitions locally (still never pushes)
+
+Examples:
+  open-memex pr-status
+  open-memex pr-status --apply`,
     reindex: `Rebuild the SQLite index from the markdown files.
 
-Usage: open-memex reindex`,
+Usage: open-memex reindex
+
+Example:
+  open-memex reindex`,
     scopes: `List the known scopes (personal + project).
 
-Usage: open-memex scopes`,
+Usage: open-memex scopes
+
+Example:
+  open-memex scopes`,
     migrate: `Move memories between scopes, or convert a legacy my-o-memory data dir.
 
 Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict newer|overwrite|skip]
@@ -180,13 +227,21 @@ Flags:
   --on-conflict   newer (default), overwrite, or skip
   --to-v2         convert a legacy my-o-memory data dir to the v2 layout
 
-Always preview with --dry-run first; nothing moves without confirmation.`,
+Always preview with --dry-run first; nothing moves without confirmation.
+
+Examples:
+  open-memex migrate --dry-run
+  open-memex migrate --from personal --to project --dry-run`,
     mcp: `Start the stdio MCP server (the same server editors connect to).
 
 Usage: open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
 
 Flags:
-  --print-config   print the MCP client config instead of starting the server`,
+  --print-config   print the MCP client config instead of starting the server
+
+Examples:
+  open-memex mcp
+  open-memex mcp --print-config vscode`,
     init: `One-command project setup: writes the MCP config for your editor and the
 agent memory instructions. Existing files are merged, never clobbered.
 
@@ -197,21 +252,32 @@ Flags:
   --client        editor to configure (default: auto-detect)
   --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
   --force         overwrite existing config
-  --yes           accept all defaults, never prompt`,
+  --yes           accept all defaults, never prompt
+
+Examples:
+  open-memex init
+  open-memex init --client cursor --yes`,
     config: `Show config, or set a key.
 
 Usage: open-memex config [set <key> <value>]
 
-Example:
+Examples:
+  open-memex config
   open-memex config set sync.autoPull false`,
     capture: `Preview what the keyword-capture watcher would extract from text.
 
-Usage: open-memex capture --dry-run "text"`,
+Usage: open-memex capture --dry-run "text"
+
+Example:
+  open-memex capture --dry-run "remember: we deploy on Fridays"`,
     doctor: `Environment health check: Node version, config source, scope resolution,
 storage writability, then boots a real MCP server and runs initialize +
 tools/list against it — all eleven tools must show up.
 
-Usage: open-memex doctor`,
+Usage: open-memex doctor
+
+Example:
+  open-memex doctor`,
 };
 function usage(exitCode = 1) {
     console.log(`open-memex CLI
@@ -247,6 +313,9 @@ Usage:
   open-memex capture --dry-run "text"
   open-memex doctor
 
+Every command has its own help with description and examples:
+  open-memex <command> --help   (or -h)
+
 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\`) — no copy-paste
@@ -1044,6 +1113,10 @@ async function main() {
             entries.push({ key: name, files, marker });
         }
         entries.sort((a, b) => b.files - a.files);
+        if (entries.length === 0) {
+            console.log("(no scopes with memories yet — add one with `open-memex add`)");
+            return;
+        }
         for (const e of entries) {
             console.log(`  ${e.files.toString().padStart(4)}  ${e.key}${e.marker}`);
         }

package/docs/TEST-PLAN.md

@@ -0,0 +1,72 @@
+# OpenMemex 测试计划（v0.4.0-alpha.10）
+
+> 自动化部分：`node --experimental-strip-types scripts/test-full.ts`
+> 62 项全过（26 个 CLI 命令 + 11 个 MCP tool），隔离环境运行，不碰真实数据。
+> 下面是机器/账号相关的部分，需要 Stone 在真机上过一遍。
+
+## A. Windows 真机 + VS Code Copilot
+
+- [ ] `npm i -g open-memex@alpha` 全局安装，`open-memex --version` 显示正确版本
+- [ ] 在一个真实项目目录跑 `open-memex init`（不加 `--yes`，走一遍交互）
+  - 确认 `.vscode/mcp.json` 生成，`~/.copilot/copilot-instructions.md` 合并写入（不覆盖已有内容）
+- [ ] 重启 VS Code，Copilot Chat 里问 "what do you remember about this project?"
+  - 预期：MCP 连接成功，能调用 memory_search
+- [ ] `open-memex add "windows 真机测试" --type fact`，再让 Copilot 搜出来
+- [ ] 中文路径项目、中文记忆内容各试一条（CJK 索引）
+
+## B. 真实 GitHub PR 全流程（review 工作流）
+
+在一个真实 repo 里：
+
+- [ ] `open-memex add "PR流程测试" --scope personal` → `propose --to project` → `sync-status` 看到 outbox draft
+- [ ] `open-memex submit <id>`（留在当前分支，本地 commit）
+- [ ] 手动 `git push` + 开 PR
+- [ ] 在 PR 里点 Approve → 回来跑 `open-memex pr-status`（先看 report），再 `pr-status --apply`
+  - 预期：memory 变成 approved，`approved_by` 是 reviewer
+- [ ] 找一条让 reviewer 点 "Request changes" → `pr-status --apply`
+  - 预期：只给 suggestion，**不**自动 reject（D32）
+- [ ] Merge PR → `pr-status --apply`
+  - 预期：memory 变成 published
+- [ ] `open-memex resolve` 无冲突时输出 "(no conflicted memory files)"
+
+## C. 其他编辑器 MCP 集成
+
+- [ ] Cursor：`open-memex mcp --print-config cursor` → 贴到 Cursor MCP 配置 → 能连上
+- [ ] opencode：`open-memex init --client opencode` → `opencode.jsonc` 生效
+- [ ] Claude Code：`open-memex mcp --print-config claude` 给出的 `claude mcp add` 命令能跑通
+
+## D. 跨机迁移（export/import 真实场景）
+
+- [ ] 本机：`open-memex export --all -o migration.tar.gz`（含 private 的全量）
+- [ ] 本机：`open-memex export -o share.tar.gz`（默认排除 private）→ 解包检查 manifest，确认没有 visibility:private 的条目
+- [ ] 另一台机器：`open-memex import migration.tar.gz --dry-run` 先看预览，再正式 import
+  - 预期：project memory re-key 到新机器的 project scope，进 outbox 当 draft；personal 进 personal
+- [ ] 同一个 bundle 导两次 → 第二次 "skipped N identical"
+
+## E. Agent 会话行为（D42 / §3.5）
+
+- [ ] 新开一个 agent 会话（MCP 已接），看 initialize 返回的 instructions 里有没有 session-start 同步指引
+- [ ] 对 agent 说 "sync memory" / "同步记忆"
+  - 预期：agent 走 memory_status → 摘要 → 问你要同步哪条（而不是直接翻 appdata）
+- [ ] 长对话中 agent 是否在检查点提议蒸馏（§3.5），提议后是否等你批准才保存（D42）
+
+## F. 冲突解决（3-way merge）
+
+- [ ] 两台机器（或两个 clone）同时改同一条 project memory，各自 submit + push，一边 pull 制造 diverged
+  - 预期：`open-memex pull` 明确报错退出，不自动 merge
+- [ ] 手动 merge 后 `open-memex resolve <id>` 看 3-way 展示（base/outbox/repo），手动解决
+
+## G. 同事 pilot（1–2 人，Stone 私下选）
+
+- [ ] 对方 `npx open-memex@alpha init` 走通
+- [ ] 对方能 propose → 你这边能看到 PR → promote 流程走通
+- [ ] 收集反馈：哪里卡、哪里不符合直觉
+
+## H. 已知问题观察
+
+- [ ] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：注意是否丢数据（预期：不丢，只影响退出码）
+- [ ] `memory_list` 默认只列 project scope 是否符合预期（Stone 已定保持现状）
+
+---
+
+测试中发现的 bug 直接记到 GitHub issue；改完后更新本文档的复选框。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.0-alpha.10",
+  "version": "0.4.0-alpha.11",
   "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/scripts/test-full.ts

@@ -0,0 +1,345 @@
+// Full feature test — exercises every CLI command and every MCP tool.
+// Usage: node --experimental-strip-types scripts/test-full.ts
+// Isolated: uses temp HOME + MY_O_MEMORY_HOME + temp git repos. Touches nothing real.
+//
+// NOTE on flakiness: better-sqlite3 11.x intermittently crashes at process
+// exit on Node 24 (RemoveEnvironmentCleanupHook assertion, exit 134) — a
+// known pre-existing issue. The work itself always completes; only the exit
+// code/output flush is affected. Id-generating calls retry until an id is
+// parsed, and crash-prone commands retry up to 5 times.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const CLI = path.join(REPO, "dist", "cli.js");
+const MCP_TS = path.join(REPO, "src", "mcp.ts");
+
+const T = fs.mkdtempSync(path.join(os.tmpdir(), "om-full-"));
+const TESTENV = {
+  ...process.env,
+  HOME: path.join(T, "home"),
+  MY_O_MEMORY_HOME: path.join(T, "data"),
+};
+fs.mkdirSync(TESTENV.HOME, { recursive: true });
+
+let pass = 0, fail = 0;
+const failures: string[] = [];
+function ok(name: string, cond: boolean, info?: string) {
+  if (cond) { pass++; console.log(`  ok   ${name}`); }
+  else { fail++; failures.push(name); console.log(`  FAIL ${name}${info ? " — " + info : ""}`); }
+}
+function isCrash(err: string): boolean {
+  return /RemoveEnvironmentCleanupHook|Assertion failed/.test(err);
+}
+// Base runner: transparently retries the known better-sqlite3 exit crash
+// (work completes; only exit code/output flush is affected).
+function cliRaw(args: string[], cwd: string, env: NodeJS.ProcessEnv): { out: string; err: string; code: number } {
+  let last = { out: "", err: "", code: 1 };
+  for (let i = 0; i < 5; i++) {
+    try {
+      const out = execFileSync("node", [CLI, ...args], { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+      return { out, err: "", code: 0 };
+    } catch (e: any) {
+      last = { out: e.stdout ?? "", err: e.stderr ?? "", code: e.status ?? 1 };
+      if (!isCrash(last.err)) break; // real error, not the flaky crash
+    }
+  }
+  return last;
+}
+function cli(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cliRaw(args, cwd, TESTENV);
+}
+function git(args: string[], cwd: string) {
+  execFileSync("git", args, { cwd, env: TESTENV, stdio: "ignore" });
+}
+function mkproj(name: string): string {
+  const p = path.join(T, name);
+  fs.mkdirSync(p, { recursive: true });
+  git(["init", "-q"], p);
+  git(["config", "user.email", "test@example.com"], p);
+  git(["config", "user.name", "Test"], p);
+  fs.writeFileSync(path.join(p, "README.md"), "# test\n");
+  git(["add", "."], p);
+  git(["commit", "-qm", "init"], p);
+  return p;
+}
+const grabId = (out: string) => (out.match(/saved ([A-Z0-9]{26})/) || [])[1] ?? "";
+const grabArrowId = (out: string) => (out.match(/→\s*([A-Z0-9]{26})/) || [])[1] ?? "";
+function tarRead(tarfile: string, member: string): string {
+  try {
+    return execFileSync("tar", ["-xzOf", tarfile, member], { env: TESTENV, encoding: "utf8" });
+  } catch { return ""; }
+}
+function cliRetry(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cli(args, cwd); // retry is built into cliRaw
+}
+// add is the id factory — the known better-sqlite3 exit crash can eat the
+// output, so retry until we actually get an id back.
+function addMem(args: string[], cwd: string): string {
+  for (let i = 0; i < 5; i++) {
+    const id = grabId(cli(["add", ...args], cwd).out);
+    if (id) return id;
+  }
+  return "";
+}
+function proposeMem(id: string, cwd: string): string {
+  for (let i = 0; i < 5; i++) {
+    const d = grabArrowId(cli(["propose", id, "--to", "project"], cwd).out);
+    if (d) return d;
+  }
+  return "";
+}
+// Separate data dir = separate machine (the real export/import scenario).
+const TESTENV2 = { ...TESTENV, MY_O_MEMORY_HOME: path.join(T, "data2") };
+function cli2(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cliRaw(args, cwd, TESTENV2);
+}
+
+console.log("== setup ==");
+const PROJ = mkproj("proj");
+const REMOTE = path.join(T, "remote.git");
+execFileSync("git", ["init", "-q", "--bare", REMOTE], { env: TESTENV });
+git(["remote", "add", "origin", REMOTE], PROJ);
+ok("proj + bare remote ready", fs.existsSync(path.join(PROJ, ".git")));
+
+// ---------- 1. where / scopes / config ----------
+console.log("== where / scopes / config ==");
+let r = cli(["where"], PROJ);
+ok("where shows project scope", /project__/.test(r.out), r.out.slice(0, 120));
+r = cli(["scopes"], PROJ);
+ok("scopes empty → graceful message", /no scopes with memories yet/.test(r.out), r.out.slice(0, 120));
+r = cli(["config", "set", "sync.autoPull", "true"], PROJ);
+r = cli(["config"], PROJ);
+ok("config set/get dotted key", /autoPull/.test(r.out) && /true/.test(r.out), r.out.slice(0, 200));
+cli(["config", "set", "sync.autoPull", "false"], PROJ);
+
+// ---------- 2. add / list / search ----------
+console.log("== add / list / search ==");
+const idFact = addMem(["fulltest fact about deploys", "--type", "fact", "--tag", "t1"], PROJ);
+const idDecision = addMem(["fulltest decision to use ff merges", "--type", "decision", "--tag", "t2"], PROJ);
+const idPersonal = addMem(["fulltest personal pref", "--scope", "personal"], PROJ);
+ok("add returns ids", !!idFact && !!idDecision && !!idPersonal);
+r = cli(["list"], PROJ);
+ok("list default = project only", r.out.includes(idFact) && r.out.includes(idDecision) && !r.out.includes(idPersonal));
+r = cli(["list", "--scope", "personal"], PROJ);
+ok("list --scope personal", r.out.includes(idPersonal) && !r.out.includes(idFact));
+r = cli(["scopes"], PROJ);
+ok("scopes lists populated scopes", /personal/.test(r.out) && /project__/.test(r.out), r.out.slice(0, 160));
+r = cli(["list", "--type", "decision"], PROJ);
+ok("list --type filter", r.out.includes(idDecision) && !r.out.includes(idFact));
+r = cli(["search", "ff merges"], PROJ);
+ok("search finds decision", r.out.includes(idDecision), r.out.slice(0, 150));
+
+// ---------- 3. supersede / status / forget ----------
+console.log("== supersede / status / forget ==");
+r = cli(["supersede", idFact, "fulltest fact about deploys v2"], PROJ);
+const idV2 = grabArrowId(r.out);
+ok("supersede creates new version", !!idV2 && idV2 !== idFact, r.out.slice(0, 150));
+const idDep = addMem(["fulltest to deprecate", "--type", "fact"], PROJ);
+r = cli(["status", idDep, "deprecated"], PROJ);
+ok("status deprecated", r.code === 0, (r.err || r.out).slice(0, 150));
+r = cli(["status", idFact, "deprecated"], PROJ);
+ok("status on superseded chain-member is refused", r.code !== 0 && /chain-managed|supersede/i.test(r.err + r.out), (r.err || r.out).slice(0, 120));
+r = cli(["forget", idDecision], PROJ);
+ok("forget deletes", r.code === 0 && /delet/i.test(r.out), r.out.slice(0, 120));
+r = cli(["list"], PROJ);
+ok("forgotten id gone from list", !r.out.includes(idDecision));
+
+// ---------- 4. propose / submit / promote / sync-status ----------
+console.log("== review workflow: propose / submit / promote ==");
+const idProp = addMem(["fulltest proposal candidate", "--scope", "personal"], PROJ);
+const idDraft = proposeMem(idProp, PROJ);
+ok("propose stages outbox draft", !!idDraft);
+r = cli(["sync-status"], PROJ);
+ok("sync-status shows outbox draft", /outbox/.test(r.out) && r.out.includes(idDraft));
+r = cli(["submit", idDraft], PROJ);
+ok("submit commits locally", r.code === 0, (r.err || r.out).slice(0, 150));
+const log = execFileSync("git", ["log", "--oneline", "-1"], { cwd: PROJ, env: TESTENV, encoding: "utf8" });
+ok("submit created a git commit", /submit|mem/i.test(log), log.trim());
+r = cli(["promote", idDraft, "--note", "fulltest approval"], PROJ);
+ok("promote → approved", r.code === 0, (r.err || r.out).slice(0, 150));
+r = cli(["promote", idDraft, "--note", "fulltest publish"], PROJ);
+ok("promote → published", r.code === 0, (r.err || r.out).slice(0, 150));
+const idRej = addMem(["fulltest reject candidate", "--scope", "personal"], PROJ);
+const idRejDraft = proposeMem(idRej, PROJ);
+r = cliRetry(["submit", idRejDraft], PROJ);
+ok("reject-path submit", r.code === 0, (r.err || r.out).slice(0, 120));
+r = cli(["promote", idRejDraft, "--reject", "--note", "fulltest rejection"], PROJ);
+ok("promote --reject with note", r.code === 0, (r.err || r.out).slice(0, 150));
+
+// ---------- 5. export / import ----------
+console.log("== export / import ==");
+const expFile = path.join(T, "bundle.tar.gz");
+r = cliRetry(["export", "-o", expFile], PROJ);
+ok("export creates bundle", r.code === 0 && fs.existsSync(expFile), (r.err || r.out).slice(0, 120));
+const man = JSON.parse(tarRead(expFile, "manifest.json") || "{}");
+ok("manifest format valid", man.format === "open-memex-export/1" && Array.isArray(man.memories) && man.memories.length > 0, JSON.stringify(man).slice(0, 120));
+r = cliRetry(["export", "--scope", "personal", "--all", "-o", path.join(T, "p.tar.gz")], PROJ);
+const manP = JSON.parse(tarRead(path.join(T, "p.tar.gz"), "manifest.json") || "{}");
+ok("export --all includes private", manP.include_private === true && manP.memories.length >= 2);
+const PROJ2 = mkproj("proj2");
+function cli2Retry(args: string[], cwd: string): { out: string; err: string; code: number } {
+  return cli2(args, cwd); // retry is built into cliRaw
+}
+r = cli2Retry(["import", expFile, "--dry-run"], PROJ2);
+ok("import --dry-run", /DRY RUN/.test(r.out), r.out.slice(0, 120));
+r = cli2Retry(["import", expFile], PROJ2);
+ok("import real run", /imported [1-9]/.test(r.out), r.out.slice(0, 120));
+r = cli2(["list"], PROJ2);
+ok("imported memories visible in target project", /fulltest/.test(r.out), r.out.slice(0, 160));
+r = cli2Retry(["import", expFile], PROJ2);
+ok("import identical → skipped", /skipped [1-9]+ identical/.test(r.out), r.out.slice(0, 120));
+// conflict: craft bundle with same id, different content
+const cid = man.memories[0].id;
+const cstage = path.join(T, "cstage");
+fs.mkdirSync(path.join(cstage, "memories", "project"), { recursive: true });
+fs.writeFileSync(path.join(cstage, "memories", "project", cid + ".md"),
+  `---\nid: ${cid}\nscope: project\nscope_key: project__old__x\nvisibility: internal\ntype: fact\nstatus: active\ncreated_at: 2026-01-01T00:00:00Z\nupdated_at: 2026-01-01T00:00:00Z\n---\n\nCONFLICT CONTENT\n`);
+fs.writeFileSync(path.join(cstage, "manifest.json"), JSON.stringify({ format: "open-memex-export/1", exported_at: "2026-01-01T00:00:00Z", open_memex_version: "t", include_private: false, filters: {}, memories: [{ id: cid, scope: "project", file: `memories/project/${cid}.md` }] }));
+const cfile = path.join(T, "conflict.tar.gz");
+execFileSync("tar", ["-czf", cfile, "-C", cstage, "manifest.json", "memories"], { env: TESTENV });
+r = cli2Retry(["import", cfile], PROJ2);
+ok("import conflict reported, never overwritten", /conflict/.test(r.out) && /imported 0/.test(r.out), r.out.slice(0, 160));
+
+// ---------- 6. distill-agents ----------
+console.log("== distill-agents ==");
+addMem(["fulltest distill decision: always fast-forward", "--type", "decision"], PROJ);
+addMem(["fulltest distill gotcha: sqlite crashes on exit", "--type", "gotcha"], PROJ);
+r = cliRetry(["distill-agents"], PROJ);
+ok("distill-agents proposes snippet", /## Learned/.test(r.out), r.out.slice(0, 120));
+r = cliRetry(["distill-agents", "--type", "decision", "-o", path.join(T, "snip.md")], PROJ);
+ok("distill-agents -o writes file", fs.existsSync(path.join(T, "snip.md")));
+
+// ---------- 7. pull / push ----------
+console.log("== pull / push ==");
+r = cliRetry(["push"], PROJ);
+ok("push explicit", r.code === 0, (r.err || r.out).slice(0, 150));
+const PROJ3 = path.join(T, "proj3");
+execFileSync("git", ["clone", "-q", REMOTE, PROJ3], { env: TESTENV });
+git(["config", "user.email", "test@example.com"], PROJ3);
+git(["config", "user.name", "Test"], PROJ3);
+const idRemote = addMem(["fulltest remote memory", "--type", "fact"], PROJ3);
+cliRetry(["submit", idRemote], PROJ3);
+cliRetry(["push"], PROJ3);
+r = cliRetry(["pull"], PROJ);
+ok("pull fast-forward", r.code === 0 && /up.to.date|fast-forward|pulled/i.test(r.out + r.err), (r.out + r.err).slice(0, 150));
+// diverged: commit on both sides
+fs.writeFileSync(path.join(PROJ, "div1.txt"), "a");
+git(["add", "."], PROJ); git(["commit", "-qm", "div1"], PROJ);
+fs.writeFileSync(path.join(PROJ3, "div2.txt"), "b");
+git(["add", "."], PROJ3); git(["commit", "-qm", "div2"], PROJ3);
+cli(["push"], PROJ3);
+r = cli(["pull"], PROJ);
+ok("pull diverged → clear failure", r.code !== 0 && /diverg|behind|ahead/i.test(r.out + r.err), (r.out + r.err).slice(0, 160));
+
+// ---------- 8. migrate / reindex ----------
+console.log("== migrate / reindex ==");
+r = cli(["migrate", "--dry-run"], PROJ);
+ok("migrate bare → graceful no-op message", /no --from given/.test(r.out + r.err), (r.out + r.err).slice(0, 150));
+const idMig = addMem(["fulltest migrate me", "--scope", "personal"], PROJ);
+r = cli(["migrate", "--from", "personal", "--to", "project", "--dry-run"], PROJ);
+ok("migrate personal→project dry-run", r.code === 0, (r.err || r.out).slice(0, 150));
+const dbPath = path.join(TESTENV.MY_O_MEMORY_HOME as string, "index.db");
+fs.rmSync(dbPath);
+const beforeReindex = Date.now();
+cli(["reindex"], PROJ); // exit code unreliable (known sqlite exit crash); verify by artifact
+let dbOk = false;
+try { dbOk = fs.existsSync(dbPath) && fs.statSync(dbPath).mtimeMs >= beforeReindex - 1000; } catch { /* no */ }
+ok("reindex rebuilds", dbOk, `db exists: ${fs.existsSync(dbPath)}`);
+r = cli(["list", "--scope", "personal"], PROJ);
+ok("list works after reindex", r.out.includes(idMig) || r.out.includes(idPersonal));
+
+// ---------- 9. capture / doctor / mcp --print-config / init ----------
+console.log("== capture / doctor / mcp / init ==");
+r = cli(["capture", "--dry-run", "remember: we deploy on Fridays and use ff merges"], PROJ);
+ok("capture --dry-run", r.code === 0 && /deploy|friday/i.test(r.out), r.out.slice(0, 150));
+for (const c of ["vscode", "cursor", "claude", "opencode", "visualstudio"]) {
+  r = cli(["mcp", "--print-config", c], PROJ);
+  ok(`mcp --print-config ${c}`, r.code === 0 && r.out.trim().length > 10, r.err.slice(0, 100));
+}
+r = cli(["init", "--client", "vscode", "--yes"], PROJ);
+ok("init --client vscode --yes", r.code === 0 && fs.existsSync(path.join(PROJ, ".vscode", "mcp.json")), (r.err || r.out).slice(0, 150));
+r = cliRetry(["doctor"], PROJ);
+ok("doctor", r.code === 0 && /All checks passed/.test(r.out), (r.err || r.out).slice(0, 200));
+
+// ---------- 10. MCP: all 11 tools + session-start instructions ----------
+console.log("== MCP tools ==");
+{
+  const child = spawn("node", ["--experimental-strip-types", MCP_TS], {
+    cwd: PROJ, env: TESTENV, stdio: ["pipe", "pipe", "pipe"],
+  });
+  let buf = "";
+  let id = 0;
+  const pending = new Map<number, (v: any) => void>();
+  child.stdout.on("data", (d: Buffer) => {
+    buf += d.toString();
+    let idx: number;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, idx).trim();
+      buf = buf.slice(idx + 1);
+      if (!line) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg.id !== undefined && pending.has(msg.id)) { pending.get(msg.id)!(msg); pending.delete(msg.id); }
+      } catch { /* ignore */ }
+    }
+  });
+  const req = (method: string, params: any) => new Promise<any>((resolve) => {
+    const i = ++id;
+    pending.set(i, resolve);
+    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id: i, method, params }) + "\n");
+    setTimeout(() => { if (pending.has(i)) { pending.delete(i); resolve({ __timeout: true }); } }, 30000);
+  });
+  const call = async (tool: string, args: any) => {
+    const resp = await req("tools/call", { name: tool, arguments: args });
+    const text = (resp.result?.content || []).map((c: any) => c.text || "").join("\n");
+    return { resp, text };
+  };
+
+  const init = await req("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "t", version: "1" } });
+  const instructions: string = init.result?.instructions || "";
+  ok("MCP initialize returns instructions", instructions.length > 200, instructions.slice(0, 100));
+  ok("instructions mention sync/memory_status", /memory_status|sync/i.test(instructions));
+  await req("notifications/initialized", {});
+  const tools = await req("tools/list", {});
+  const names: string[] = (tools.result?.tools || []).map((t: any) => t.name);
+  const expected = ["memory_add","memory_forget","memory_list","memory_pr_status","memory_promote","memory_propose","memory_resolve","memory_search","memory_status","memory_submit","memory_supersede"];
+  ok("11 MCP tools listed", expected.every((n) => names.includes(n)), names.join(","));
+
+  let m = await call("memory_add", { content: "mcptest fact via MCP", type: "fact" });
+  const mid = (m.text.match(/([A-Z0-9]{26})/) || [])[1] || "";
+  ok("memory_add", !!mid, m.text.slice(0, 120));
+  m = await call("memory_search", { query: "mcptest fact" });
+  ok("memory_search", m.text.includes(mid), m.text.slice(0, 120));
+  m = await call("memory_list", { limit: 5 });
+  ok("memory_list", m.text.includes(mid) || /fact/.test(m.text), m.text.slice(0, 120));
+  m = await call("memory_status", {});
+  ok("memory_status", /project|outbox|sync/i.test(m.text), m.text.slice(0, 120));
+  m = await call("memory_supersede", { id: mid, content: "mcptest fact via MCP v2" });
+  const mid2 = (m.text.match(/with ([A-Z0-9]{26})/) || [])[1] || "";
+  ok("memory_supersede", !!mid2 && mid2 !== mid, m.text.slice(0, 120));
+  // propose → submit → promote via MCP
+  const pid = ((await call("memory_add", { content: "mcptest proposal", scope: "personal" })).text.match(/([A-Z0-9]{26})/) || [])[1] || "";
+  m = await call("memory_propose", { ids: [pid] });
+  const pdraft = (m.text.match(/→\s*([A-Z0-9]{26})/) || m.text.match(/([A-Z0-9]{26})/) || [])[1] || "";
+  ok("memory_propose", !!pdraft && pdraft !== pid, m.text.slice(0, 120));
+  m = await call("memory_submit", { ids: [pdraft] });
+  ok("memory_submit", !/error/i.test(m.text) || /commit|submit/i.test(m.text), m.text.slice(0, 120));
+  m = await call("memory_promote", { id: pdraft, note: "mcptest approve" });
+  ok("memory_promote", !/__timeout/.test(JSON.stringify(m.resp)), m.text.slice(0, 120));
+  m = await call("memory_resolve", {});
+  ok("memory_resolve (list)", !/__timeout/.test(JSON.stringify(m.resp)), m.text.slice(0, 120));
+  m = await call("memory_pr_status", {});
+  ok("memory_pr_status (report)", !/__timeout/.test(JSON.stringify(m.resp)), m.text.slice(0, 120));
+  m = await call("memory_forget", { id: mid2 });
+  ok("memory_forget", /delet|forget/i.test(m.text), m.text.slice(0, 120));
+  child.kill();
+}
+
+console.log("\n================ SUMMARY ================");
+console.log(`pass: ${pass}, fail: ${fail}`);
+if (failures.length) { console.log("failed tests:"); for (const f of failures) console.log("  - " + f); }
+process.exit(fail ? 1 : 0);

package/src/cli.ts

@@ -30,7 +30,10 @@ import { fileURLToPath } from "node:url";
 const COMMAND_HELP: Record<string, string> = {
   where: `Show which project scope the current directory resolves to, and where its data lives.
 
-Usage: open-memex where`,
+Usage: open-memex where
+
+Example:
+  open-memex where`,
 
   list: `List memories in a scope, newest first.
 
@@ -71,15 +74,24 @@ Example:
 
   supersede: `Replace a memory with a newer version. The old one is kept as history.
 
-Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]`,
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+
+Example:
+  open-memex supersede 01ABC "We deploy on Thursdays now"`,
 
   status: `Change a memory's lifecycle status.
 
-Usage: open-memex status <id> active|deprecated|retracted|archived`,
+Usage: open-memex status <id> active|deprecated|retracted|archived
+
+Example:
+  open-memex status 01ABC deprecated`,
 
   forget: `Delete a memory by id.
 
-Usage: open-memex forget <id>`,
+Usage: open-memex forget <id>
+
+Example:
+  open-memex forget 01ABC`,
 
   propose: `Copy personal memories into the project outbox as review drafts.
 The personal originals stay put. Nothing enters git at this step.
@@ -116,24 +128,37 @@ Usage: open-memex resolve [id-or-path]
 
 With no argument, lists conflicts. With an id or file path, shows the
 3-way merge (base / outbox / repo) so you can resolve it by hand.
-Conflicts are never auto-resolved.`,
+Conflicts are never auto-resolved.
+
+Examples:
+  open-memex resolve
+  open-memex resolve 01ABC`,
 
   "sync-status": `Show the project memory sync pipeline: when the index last synced
 and what triggered it, drafts waiting in the outbox (appdata), memories in the
 repo awaiting review or published, and repo files not yet committed.
 
-Usage: open-memex sync-status`,
+Usage: open-memex sync-status
+
+Example:
+  open-memex sync-status`,
 
   pull: `Pull shared project memories from the git remote: fetch + fast-forward
 only. Never auto-merges — a diverged branch fails with a clear message and is
 left for you to resolve by hand. On success the local index re-syncs.
 
-Usage: open-memex pull`,
+Usage: open-memex pull
+
+Example:
+  open-memex pull`,
 
   push: `Push the current branch (with its submitted memories) to the git
 remote. Explicit only — open-memex never pushes on its own.
 
-Usage: open-memex push`,
+Usage: open-memex push
+
+Example:
+  open-memex push`,
 
   export: `Export memories to a portable .tar.gz bundle (markdown source of
 truth + manifest.json) for moving to another machine or another app.
@@ -146,21 +171,33 @@ Flags:
   --type    filter by memory type
   --tag     filter by tag
   --all, -a include private memories (full migration)
-  -o        output file (default: ./open-memex-export-<timestamp>.tar.gz)`,
+  -o        output file (default: ./open-memex-export-<timestamp>.tar.gz)
+
+Examples:
+  open-memex export -o backup.tar.gz
+  open-memex export --scope both --all -o full-migration.tar.gz`,
 
   import: `Import a bundle created by \`open-memex export\`. Personal memories
 go to the personal dir; project memories are re-keyed to the current project
 and land in the outbox as drafts. Existing identical memories are skipped;
 conflicting ids are reported, never overwritten.
 
-Usage: open-memex import <bundle.tar.gz> [--dry-run]`,
+Usage: open-memex import <bundle.tar.gz> [--dry-run]
+
+Examples:
+  open-memex import backup.tar.gz --dry-run
+  open-memex import backup.tar.gz`,
 
   "distill-agents": `Propose an AGENTS.md snippet distilled from project
 memories (decisions, constraints, lessons, gotchas, howtos). Prints markdown
 to stdout, or writes it with -o. Review and merge by hand — open-memex never
 rewrites your AGENTS.md on its own.
 
-Usage: open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]`,
+Usage: open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
+
+Examples:
+  open-memex distill-agents
+  open-memex distill-agents --type decision,gotcha -o agents-snippet.md`,
 
   submit: `Move outbox drafts into the repo for review: copies the drafts into
 the repo memory dir as proposed (a local-approved copy keeps its approval),
@@ -186,15 +223,25 @@ overwritten. Report-only by default.
 Usage: open-memex pr-status [--apply]
 
 Flags:
-  --apply   write the transitions locally (still never pushes)`,
+  --apply   write the transitions locally (still never pushes)
+
+Examples:
+  open-memex pr-status
+  open-memex pr-status --apply`,
 
   reindex: `Rebuild the SQLite index from the markdown files.
 
-Usage: open-memex reindex`,
+Usage: open-memex reindex
+
+Example:
+  open-memex reindex`,
 
   scopes: `List the known scopes (personal + project).
 
-Usage: open-memex scopes`,
+Usage: open-memex scopes
+
+Example:
+  open-memex scopes`,
 
   migrate: `Move memories between scopes, or convert a legacy my-o-memory data dir.
 
@@ -207,14 +254,22 @@ Flags:
   --on-conflict   newer (default), overwrite, or skip
   --to-v2         convert a legacy my-o-memory data dir to the v2 layout
 
-Always preview with --dry-run first; nothing moves without confirmation.`,
+Always preview with --dry-run first; nothing moves without confirmation.
+
+Examples:
+  open-memex migrate --dry-run
+  open-memex migrate --from personal --to project --dry-run`,
 
   mcp: `Start the stdio MCP server (the same server editors connect to).
 
 Usage: open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
 
 Flags:
-  --print-config   print the MCP client config instead of starting the server`,
+  --print-config   print the MCP client config instead of starting the server
+
+Examples:
+  open-memex mcp
+  open-memex mcp --print-config vscode`,
 
   init: `One-command project setup: writes the MCP config for your editor and the
 agent memory instructions. Existing files are merged, never clobbered.
@@ -226,24 +281,35 @@ Flags:
   --client        editor to configure (default: auto-detect)
   --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
   --force         overwrite existing config
-  --yes           accept all defaults, never prompt`,
+  --yes           accept all defaults, never prompt
+
+Examples:
+  open-memex init
+  open-memex init --client cursor --yes`,
 
   config: `Show config, or set a key.
 
 Usage: open-memex config [set <key> <value>]
 
-Example:
+Examples:
+  open-memex config
   open-memex config set sync.autoPull false`,
 
   capture: `Preview what the keyword-capture watcher would extract from text.
 
-Usage: open-memex capture --dry-run "text"`,
+Usage: open-memex capture --dry-run "text"
+
+Example:
+  open-memex capture --dry-run "remember: we deploy on Fridays"`,
 
   doctor: `Environment health check: Node version, config source, scope resolution,
 storage writability, then boots a real MCP server and runs initialize +
 tools/list against it — all eleven tools must show up.
 
-Usage: open-memex doctor`,
+Usage: open-memex doctor
+
+Example:
+  open-memex doctor`,
 };
 
 function usage(exitCode = 1): never {
@@ -280,6 +346,9 @@ Usage:
   open-memex capture --dry-run "text"
   open-memex doctor
 
+Every command has its own help with description and examples:
+  open-memex <command> --help   (or -h)
+
 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\`) — no copy-paste
@@ -1128,6 +1197,10 @@ function positionalArgs(argv: string[]): string[] {
       entries.push({ key: name, files, marker });
     }
     entries.sort((a, b) => b.files - a.files);
+    if (entries.length === 0) {
+      console.log("(no scopes with memories yet — add one with `open-memex add`)");
+      return;
+    }
     for (const e of entries) {
       console.log(`  ${e.files.toString().padStart(4)}  ${e.key}${e.marker}`);
     }