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

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.
@@ -339,7 +475,9 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 # propose an AGENTS.md snippet distilled from project memories
 # (decisions, constraints, lessons, gotchas, howtos). Prints markdown;
 # -o writes it to a file. You review and merge by hand — open-memex
-# never rewrites your AGENTS.md on its own.
+# never rewrites your AGENTS.md on its own. The snippet ends with a
+# "memory hygiene" section (§3.5 checkpoint guidance) so agents reading
+# AGENTS.md learn to propose distilled captures at checkpoints.
 
 open-memex propose <id...> --to project [--local-approve]
 # propose one or several personal memories at once (one branch, one PR);
@@ -401,28 +539,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）。新记忆默认进这里。
@@ -329,7 +448,8 @@ open-memex import <bundle.tar.gz> [--dry-run]
 open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
 # 把项目记忆（decision/constraint/lesson/gotcha/howto）提炼成
 # AGENTS.md 片段。默认打印到 stdout；-o 写文件。人工审阅后手工合并——
-# open-memex 永不自动改写你的 AGENTS.md。
+# open-memex 永不自动改写你的 AGENTS.md。片段末尾带一段"记忆卫生"
+# （§3.5 检查点指引），让读 AGENTS.md 的 agent 学会在检查点提议蒸馏捕获。
 
 open-memex propose <id...> --to project [--local-approve]
 # 一次 propose 一条或多条（一个分支、一个 PR），每条独立新 id。
@@ -387,28 +507,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}`);
         }