open-memex 0.5.0 → 0.6.0-alpha.10

package/AGENTS.md

@@ -12,7 +12,7 @@ via `prepublishOnly` — Node refuses `--experimental-strip-types` for files und
 
 - **opencode host** loads `src/index.ts` under embedded **Bun**. SQLite here is `bun:sqlite` (built-in).
 - **CLI** (`src/cli.ts`) and smoke tests run under **Node 22+** with `--experimental-strip-types`. SQLite here is `better-sqlite3` (native module).
-- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same ten 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.**
+- **MCP server** (`src/mcp.ts`, stdio) runs under **Node 22+** with `--experimental-strip-types`. It exposes the same eleven 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`.
 
@@ -61,16 +61,37 @@ 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).
+(node version, config, scope resolution, storage writability, VS Code MCP enablement, MCP handshake).
 `open-memex init` with no --client auto-detects and wires every installed editor
 (`--yes` skips, scripts never prompt); `open-memex config set <key> <value>` edits settings after install.
+`npm install -g` prints a pointer to `open-memex init` via a postinstall script
+(print-only — postinstall must never prompt, it runs in CI/Docker; D50).
+Note: npm swallows lifecycle-script stdout (background run unless
+`--foreground-scripts`), so the postinstall pointer is best-effort only —
+every CLI entry point also prints a one-line stderr nudge until init has run
+or been declined (F28; stderr keeps the MCP stdio protocol intact).
+Bare `open-memex` on a machine where init never completed offers to run it on a
+TTY (usage as before when non-interactive); init/uninstall maintain a
+`.init.json` first-run marker at the data root so the offer is asked once (D50);
+init ends with a one-line next-step hint (`open-memex add` + ask the agent to
+recall it) so a first-time user sees what "it works" looks like (D51).
+init also installs the bundled `open-memex` Agent Skill (skills/open-memex/SKILL.md,
+teaches skill-aware agents the CLI: save/search/scope rules/outbox flow) into each
+wired editor's user-level skills dir — ~/.copilot/skills/ (VS Code),
+~/.cursor/skills/ (Cursor), ~/.config/opencode/skills/ (opencode, per-project MCP
+mode only — with the native plugin the skill is skipped and any previously installed
+one is removed, D55); Visual Studio
+has no skills concept and is skipped. Copy, not symlink (Windows needs no
+Developer Mode); existing skill kept unless --force (D54).
 `open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]`
 reverses init — removes the MCP server entry / opencode plugin line / Copilot
-instructions section; memory data never touched (D48); no --client → auto-detect
+instructions section / Agent Skill directory; memory data never touched (D48); no --client → auto-detect
 with an interactive confirm, explicit --client never prompts; `--yes` only skips
 that confirm; `--global` limits cleanup to user-level. Empty/whitespace-only
 config files parse as `{}` and are safely populated (D49); non-JSON (JSONC)
-files are left untouched with a printed manual snippet (D47).
+files are left untouched with a printed manual snippet (D47). init/uninstall also sweep
+pre-rename `my-o-memory` plugin entries and MCP server keys wherever they touch a
+config, and `open-memex doctor` reports any remaining pre-rename leftovers (F30).
 The published `open-memex` bin points at `dist/cli.js` (compiled at publish time).
 From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
 with type-stripping — no build step needed for development.
@@ -125,7 +146,7 @@ Context injection happens exactly once per session in `experimental.chat.system.
 
 `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
+built this way" (principles, iron rules, D1–D49 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.
@@ -138,7 +159,7 @@ build roadmap; the design doc tracks the *why*.
 
 ## Branch workflow
 
-`dev/<topic>` → PR → `main` (the v2 line; alpha versions published with
+`dev/<topic>` → PR → `main` (alpha versions published with
 `npm publish --tag alpha`, npm `latest` moves only on stable releases).
 The `V2` integration branch was retired 2026-09-29 — its job (isolating the
 breaking v1→v2 transition) shipped with 0.3.0. Full rules: `CONTRIBUTING.md`.

package/CONTRIBUTING.md

@@ -2,10 +2,13 @@
 
 ## Branch workflow
 
-- `main` — the v2 line. Never commit directly; land work via pull request
-  from a dev branch. Alpha versions (e.g. `0.5.0-alpha.x`) live on `main`;
-  publish them with `npm publish --tag alpha` so the npm `latest` tag only
-  moves on stable releases.
+- `main` — the only line (the `V2` integration branch was retired 2026-09-29).
+  Land work via pull request from a `dev/<topic>` branch. Exception: tiny
+  text-only doc tweaks may go directly to `main`, but only after the owner
+  has previewed and approved the exact change. Alpha versions
+  (e.g. `0.5.0-alpha.x`) live on `main`; publish them with
+  `npm publish --tag alpha` so the npm `latest` tag only moves on stable
+  releases.
 - `dev/<topic>` — feature/fix branches (e.g. `dev/init-ux`). Open as **draft**
   PRs against `main`; mark ready and merge after local testing passes.
 
@@ -25,7 +28,7 @@ branches are cheap.)
 ## 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
+D1–D49). 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

@@ -23,6 +23,20 @@ automatically.
 
 > No capture, nothing to inherit.
 
+### One memory, every agent
+
+Most developers don't use one AI tool — they use several on the same machine:
+Copilot in VS Code, Cursor, opencode, Claude Code. Each tool keeps
+its own silo: a decision made in one is invisible to the others.
+
+open-memex is tool-agnostic by design. Memory lives as Markdown + SQLite next
+to your project, and every editor talks to it through the same MCP interface.
+Wire up two, three, five clients with `open-memex init` — they all read and
+write the same memory on that machine. A constraint captured in VS Code is respected in
+opencode; a lesson learned in Cursor shows up in Claude Code.
+
+> Your memory belongs to you — not to your tools.
+
 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
@@ -36,6 +50,7 @@ of re-deriving them on every run.
 | 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 |
+| Works across AI tools | Yes — any MCP client (same machine) | Per-integration | No | No |
 
 - **Markdown files** as the source of truth (human-editable, git-friendly)
 - **SQLite FTS5** as a rebuildable index (BM25 keyword search, via `better-sqlite3`)
@@ -90,7 +105,7 @@ personal scope: this machine only — never synced, never enters a repo.
 npm install -g open-memex
 ```
 
-This installs the `0.4.1` stable release.
+This installs the `0.5.1` stable release.
 
 **Alpha** (bleeding edge, for testers) — the `alpha` tag:
 
@@ -98,6 +113,12 @@ This installs the `0.4.1` stable release.
 npm install -g open-memex@alpha
 ```
 
+```sh
+open-memex init
+```
+
+The install isn't complete until you run `open-memex init` — it wires up your editors (VS Code, Cursor, opencode, and Visual Studio for solution projects).
+
 See what's published:
 
 ```sh
@@ -165,7 +186,10 @@ npx -y open-memex init --yes
 With no `--client`, `init` **detects your installed editors and wires them all**
 — user-level where the editor supports it (VS Code / Cursor MCP config, opencode
 native plugin), so one init covers every project. Visual Studio joins in when the
-project has a solution file. Prefer to pick a single editor? Pass `--client`:
+project has a solution file. It also installs an **Agent Skill** (`open-memex`)
+into each editor's skills folder (not opencode when the native plugin is wired —
+the plugin already provides memory tools), so skill-aware agents can use your memory via
+the CLI with no MCP configuration. Prefer to pick a single editor? Pass `--client`:
 
 > **Two different "globals" — don't mix them up.**
 > - `npm install -g open-memex` installs the *package* globally: it puts the
@@ -174,6 +198,14 @@ project has a solution file. Prefer to pick a single editor? Pass `--client`:
 >   project: init once, the wiring works in every project. It works the same
 >   whether the package was installed globally or run via npx.
 
+Installing the package also prints a reminder to run `open-memex init` — the
+wiring is a separate step. And if you run bare `open-memex` on a machine where
+init never completed, it offers to run it for you (only on an interactive
+terminal; scripts and CI just see the usual usage text). When init finishes,
+it prints one concrete next step — save a memory with `open-memex add`, then
+ask your agent to recall it — so a first-time user sees what "it works" looks
+like.
+
 **VS Code** (Copilot):
 
 ```sh
@@ -219,7 +251,8 @@ open-memex init --client opencode --global --yes
 ```
 
 Merges `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` into your
-user-level `~/.config/opencode/opencode.json` — one-time, every project picks it
+user-level `~/.config/opencode/opencode.json` (or `opencode.jsonc` if that is
+the file you already have) — one-time, every project picks it
 up, no per-project init. You get keyword auto-capture and first-turn context
 injection on top of the tools. (A config file with comments is left untouched —
 add the `plugin` line by hand in that case.)
@@ -492,8 +525,9 @@ branches and PRs. Nothing moves without you naming it.
 
 In an AI chat with the MCP server connected, just say **"sync memory"**
 (or "同步记忆") — the agent runs the status check, summarizes the outbox drafts,
-and asks which ones to sync. The agent also proposes this on its own at session
-start and at work checkpoints.
+and asks which ones to sync. The server also tells the agent on its own: at
+session start the handshake reports how many drafts are waiting, and every
+memory-changing tool result carries the current count when it is non-zero.
 
 ```sh
 open-memex sync-status
@@ -547,8 +581,8 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 # (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. The snippet ends with a
-# "memory hygiene" section (§3.5 checkpoint guidance) so agents reading
-# AGENTS.md learn to propose distilled captures at checkpoints.
+# "memory hygiene" section (§3.5 distillation guidance) so agents reading
+# AGENTS.md learn to propose distilled captures when a task ends.
 
 open-memex propose <id...> --to project [--local-approve]
 # propose one or several personal memories at once (one branch, one PR);
@@ -603,8 +637,9 @@ 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 server sends session-start
-> guidance (call `memory_status` at session start and at checkpoints) in the MCP
-> handshake `instructions`, and `init` writes the fuller version into the
+> guidance in the MCP handshake `instructions` (including the live outbox draft
+> count at session start, plus the pending count appended to memory-changing
+> tool results when non-zero), and `init` writes the fuller version into the
 > editor's instruction files. Both are advisory — no MCP consumer offers a hard
 > session-start hook.
 
@@ -620,8 +655,20 @@ outbox → `sync-status` → `submit` (local branch+commit, push/PR on your Yes)
 `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.
+§3.5 distillation in the MCP handshake + init instructions (the agent proposes
+1–3 captures when a task ends, the human decides); 1–2 colleague pilot.
+
+**`0.5.0` (stable):** init UX pass — `init --global` writes the editor wiring
+once at user level (D45); bare `init` auto-detects installed editors and wires
+them all (D46); non-JSON configs are left untouched with a paste-ready snippet
+instead of an error (D47); `uninstall` reverses `init` without touching memory
+data (D48); empty config files are treated as blank, not corrupt (D49).
+"One memory, every agent": every editor on the same machine reads and writes
+the same memory through one MCP interface.
+
+**`0.5.1` (stable):** `--help` accuracy fixes — the `mcp` help text now states the
+server exposes 11 tools (a superset of the opencode plugin's five memory tools),
+and install hints point at the stable line instead of `@alpha` (F27).
 
 **Future (signal-gated, no version committed):** org layer — org memory repo,
 curator convention; native agent plugins (Claude Code / Codex hooks as
@@ -669,7 +716,7 @@ project. A per-project `.vscode/mcp.json` still wins when present, and the
 entry keeps `cwd=${workspaceFolder}` so project-scope resolution keeps
 working per window. If your user-level `mcp.json` has comments (VS Code
 accepts JSONC), `init` leaves it alone and prints the exact snippet to add
-by hand.
+by hand. An empty file is treated as blank and written to directly.
 
 **How do I remove the editor wiring?**
 `open-memex uninstall` reverses `init`: it removes the MCP server entry,

package/README.zh-CN.md

@@ -21,6 +21,18 @@ open-memex 把值得记住的部分——决策、约束、教训——存成可
 
 > No capture, nothing to inherit.（不记录，就无从传承。）
 
+### 一份记忆，所有 Agent 通用
+
+大多数开发者并不是只用一个 AI 工具——同一台电脑上可能装着 VS Code Copilot、
+Cursor、opencode、Claude Code。但每个工具的记忆都是孤岛：在 A 里定好的决策，B 一无所知。
+
+open-memex 天生与工具无关。记忆以 Markdown + SQLite 的形式存在项目旁边，
+所有编辑器都通过同一个 MCP 接口读写。用 `open-memex init` 接上两三个客户端，
+它们读写的是这台机器上的同一份记忆：在 VS Code 里记下的约束，opencode 会遵守；
+在 Cursor 里学到的教训，Claude Code 也看得到。
+
+> 记忆属于你，不属于工具。
+
 它也补齐了 agentic 开发工作流（spec 驱动开发、plan/implement/verify 循环）缺的那一块：
 plan 产出决策，verify 产出规则——open-memex 是让它们跨会话留存的记忆层，
 而不是每次从头重新推导。
@@ -33,6 +45,7 @@ plan 产出决策，verify 产出规则——open-memex 是让它们跨会话留
 | 分享前 review | 有——outbox + PR | 不一定 | 有 | 没有 |
 | Agent 回忆 | 会话开始注入 + 搜索 | 调 API | 人工去查 | 没有 |
 | 人类可读 | 纯 Markdown 文件 | 后台 / API | 有 | 没有 |
+| 跨 AI 工具通用 | 可以——同一台机器上的任何 MCP 客户端 | 按集成逐个对接 | 不可以 | 不可以 |
 
 - **Markdown 文件**是 source of truth（人类可读、git 友好）
 - **SQLite FTS5** 做可重建索引（BM25 关键词检索，`better-sqlite3`）
@@ -87,7 +100,7 @@ personal scope：只属于这台机器——永不同步，永远进不了仓库
 npm install -g open-memex
 ```
 
-安装的是 `0.4.1` 正式版。
+安装的是 `0.5.1` 正式版。
 
 **Alpha 版**（最新开发版，给测试者）——`alpha` 标签：
 
@@ -95,6 +108,12 @@ npm install -g open-memex
 npm install -g open-memex@alpha
 ```
 
+```sh
+open-memex init
+```
+
+不跑 `open-memex init` 把编辑器接上，安装就不算完成（支持 VS Code、Cursor、opencode，有 .sln 的项目还支持 Visual Studio）。
+
 查看已发布版本：
 
 ```sh
@@ -160,6 +179,9 @@ npx -y open-memex init --yes
 不带 `--client` 时，`init` 会**自动检测本机装了哪些编辑器，一次全接上**——
 支持用户级的编辑器走用户级（VS Code / Cursor 的 MCP 配置、opencode 原生插件），
 一次 init，所有项目通用；项目里有 solution 文件时 Visual Studio 也会一起配。
+同时会给每个编辑器装一个 **Agent Skill**（`open-memex`，opencode 用原生插件时除外——
+插件已经提供了记忆工具），懂 skill 的 agent
+不用配 MCP 也能通过 CLI 用你的记忆。
 想只配某一个编辑器？加 `--client`：
 
 > **两个"全局"不是一回事，别搞混。**
@@ -168,6 +190,12 @@ npx -y open-memex init --yes
 > - `init --global` 是把*编辑器配置*写到用户级而不是项目里：init 一次，
 >   每个项目都生效。不管包是全局安装的还是用 npx 临时跑的，效果一样。
 
+装完包还会打印一句提醒，让你跑 `open-memex init`——接线是独立的一步。
+如果你在从没跑过 init 的机器上直接敲 `open-memex`，它会问你要不要现在
+init（只在交互终端里问；脚本和 CI 里看到的还是原来的 usage）。
+init 跑完会打印一个具体的下一步——用 `open-memex add` 存一条记忆，再让
+agent 回忆它——让第一次用的用户一眼看到"跑起来了"是什么样子。
+
 **VS Code**（Copilot）：
 
 ```sh
@@ -213,7 +241,8 @@ open-memex init --client opencode --global --yes
 ```
 
 把 `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` 合并进用户级
-`~/.config/opencode/opencode.json`——一次配置，每个项目自动生效，不用逐个项目
+`~/.config/opencode/opencode.json`（如果你用的是 `opencode.jsonc`，就合并进那个）
+——一次配置，每个项目自动生效，不用逐个项目
 init。在 tools 之外还能获得关键词自动捕获和首轮上下文注入。（带注释的配置文件
 不会被改动——那种情况请手动加 `plugin` 这一行。）
 
@@ -468,8 +497,8 @@ project 草稿先住在 **appdata outbox**（git 看不见、跟分支无关）
 没经过你点名，什么都不会动。
 
 在接了 MCP 服务器的 AI 对话里，直接说 **"同步记忆"**（或 "sync memory"）——
-agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。agent 也会在新对话
-开始和任务检查点主动提这件事。
+agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。服务器也会主动告诉
+agent：新对话开始时握手里带待审草稿数，每次改记忆的 tool 返回里也带当前数（为零时不带）。
 
 ```sh
 open-memex sync-status
@@ -516,7 +545,7 @@ open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N]
 # 把项目记忆（decision/constraint/lesson/gotcha/howto）提炼成
 # AGENTS.md 片段。默认打印到 stdout；-o 写文件。人工审阅后手工合并——
 # open-memex 永不自动改写你的 AGENTS.md。片段末尾带一段"记忆卫生"
-# （§3.5 检查点指引），让读 AGENTS.md 的 agent 学会在检查点提议蒸馏捕获。
+# （§3.5 蒸馏指引），让读 AGENTS.md 的 agent 学会在任务结束时提议蒸馏捕获。
 
 open-memex propose <id...> --to project [--local-approve]
 # 一次 propose 一条或多条（一个分支、一个 PR），每条独立新 id。
@@ -568,9 +597,9 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 > **注意：** MCP 是请求/响应式的——它给 agent 提供 tools，但没有 opencode
 > 插件的关键词自动捕获和首轮上下文注入。想让 agent 主动用记忆，
 > 靠的是 agent 的 instructions：服务器在 MCP 握手的 `instructions` 里自带
-> session-start 指引（开场调 `memory_status`、检查点再调），`init` 则把更完整
-> 的版本写进编辑器的 instruction 文件。两者都是建议性的——MCP 客户端没有
-> 强制的 session-start hook。
+> session-start 指引（含开场时的 outbox 待审草稿数；改记忆的 tool 返回里也会
+> 带当前数，为零时不带），`init` 则把更完整的版本写进编辑器的 instruction
+> 文件。两者都是建议性的——MCP 客户端没有强制的 session-start hook。
 
 ## 路线图（Roadmap）
 
@@ -584,8 +613,12 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 `export` / `import` 归档做用户可携带（Markdown + manifest，不造围墙花园；
 private 默认不导出，`-a` / `--all` 全量迁移）；
 distill-to-AGENTS.md 辅助（`distill-agents`，只提议不改写——人工合并）；
-§3.5 检查点蒸馏写进 MCP 握手指令和 init 指令文件
-（agent 在检查点提议 1–3 条捕获，人来定）；找 1–2 个同事做 pilot。
+§3.5 蒸馏写进 MCP 握手指令和 init 指令文件
+（agent 在任务结束时提议 1–3 条捕获，人来定）；找 1–2 个同事做 pilot。
+
+**`0.5.0`（稳定版）：** init 体验整修——`init --global` 一次写好用户级编辑器接线（D45）；裸 `init` 自动检测已装编辑器并一次全接上（D46）；非标准 JSON 配置不再报错，而是原样保留并打印手贴片段（D47）；`uninstall` 逆转 `init` 且永不碰记忆数据（D48）；空配置文件按空白处理、不再误判为损坏（D49）。"一份记忆，所有 Agent 通用"：同一台机器上的每个编辑器，经由同一个 MCP 接口读写同一份记忆。
+
+**`0.5.1`（稳定版）：** `--help` 文案准确性修正——`mcp` 帮助写明 server 暴露 11 个工具（含 opencode 插件的 5 个 memory 工具），安装提示改指稳定版而非 `@alpha`（F27）。
 
 **未来（看信号再定，不承诺版本）：** 组织层——组织记忆仓库、curator 约定；
 原生 agent 插件（Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；
@@ -625,7 +658,7 @@ Linux：`~/.config/Code/User/mcp.json`），每个项目打开 server 都在。
 项目里如果有 `.vscode/mcp.json` 仍然优先；entry 里保留了
 `cwd=${workspaceFolder}`，project scope 按窗口照常工作。
 如果你的用户级 `mcp.json` 带注释（VS Code 接受 JSONC），`init` 不会碰它，
-只打印可直接手贴的配置片段。
+只打印可直接手贴的配置片段。空文件会被当作空白直接写入。
 
 **怎么拆掉编辑器接线？**
 `open-memex uninstall` 就是 `init` 的逆操作：删掉 MCP server 条目、opencode

package/dist/cli.js

@@ -296,8 +296,9 @@ 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.
+storage writability, VS Code MCP enablement (settings.json + system policy),
+then boots a real MCP server and runs initialize + tools/list against it —
+all eleven tools must show up.
 
 Usage: open-memex doctor
 
@@ -343,7 +344,7 @@ Usage:
 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\`) detects
+One-command project setup: \`open-memex init\` (or \`npx -y open-memex init\`) detects
 your installed editors and wires them all — user-level where the editor supports it
 (VS Code / Cursor MCP config, opencode native plugin), so one init covers every project;
 Visual Studio is included when the project has a solution file (its \`.mcp.json\`
@@ -358,9 +359,9 @@ confirms the detected editors and asks a couple of settings (keyword capture,
 first-turn injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
 \`open-memex config set <key> <value>\` changes those settings after install.
 
-Once installed globally (\`npm i -g open-memex@alpha\`) the \`open-memex\` command is
-available directly: \`open-memex mcp\` starts the stdio MCP server (same five
-memory_* tools as the opencode plugin); \`open-memex mcp --print-config <client>\`
+Once installed globally (\`npm i -g open-memex\`) the \`open-memex\` command is
+available directly: \`open-memex mcp\` starts the stdio MCP server (11 tools, a superset of
+the opencode plugin's five memory_* tools); \`open-memex mcp --print-config <client>\`
 prints a copy-paste MCP client config snippet.
 
 Scope defaults to \`project\` (derived from cwd's git remote or path).
@@ -433,7 +434,7 @@ function resolveCliScope(flags, project) {
         : project;
 }
 /** Print a copy-paste MCP client config snippet. Requires a global install
- * (`npm i -g open-memex@alpha`) so the `open-memex` command is on PATH. */
+ * (`npm i -g open-memex`) so the `open-memex` command is on PATH. */
 function printMcpConfig(client) {
     const c = client.toLowerCase();
     // D17: resolve the server command the same way `init` does.
@@ -489,13 +490,48 @@ function printMcpConfig(client) {
         process.exit(1);
     }
     if (!mc.durable) {
-        console.error(`\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex@alpha\` for faster startup.`);
+        console.error(`\n# note: no durable \`open-memex\` on PATH — snippet uses npx. \`npm i -g open-memex\` for faster startup.`);
     }
     process.exit(0);
 }
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
-    if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help")
+    if (!cmd) {
+        // D50: fresh machine + interactive terminal → offer init instead of bare usage.
+        // Non-interactive (CI/scripts/pipes) prints usage exactly as before.
+        const { offerFirstRunInit } = await import("./first-run.js");
+        const outcome = await offerFirstRunInit(async () => {
+            // Re-exec `open-memex init` as a child with inherited stdio instead of
+            // calling initProject() in-process: the offer's readline already
+            // consumed stdin's buffer, and a second readline on the same stream
+            // would see EOF on burst input instead of the user's next answers.
+            const { spawnSync } = await import("node:child_process");
+            const r = spawnSync(process.execPath, [...process.execArgv, fileURLToPath(import.meta.url), "init"], { stdio: "inherit" });
+            if (r.error)
+                throw r.error;
+            if ((r.status ?? 1) !== 0)
+                process.exit(r.status ?? 1);
+        });
+        if (outcome !== "initialized")
+            usage(0);
+        return;
+    }
+    // F28: npm runs lifecycle scripts in the background and swallows their
+    // stdout (unless --foreground-scripts), so the D50 postinstall pointer
+    // never reaches the user. Every CLI entry point therefore carries a
+    // one-line nudge on stderr until init has run or been declined — stderr
+    // keeps the MCP stdio protocol (stdout) intact, and the .init.json marker
+    // makes it once-ever. `init`/`uninstall` are excluded (already there /
+    // nothing to wire). Placed before the --help/--version early returns:
+    // `-v` is the first thing people run after installing.
+    if (cmd !== "init" && cmd !== "uninstall") {
+        const { isFirstRun } = await import("./first-run.js");
+        if (isFirstRun()) {
+            console.error("open-memex: first run? `open-memex init` wires it into your editors " +
+                "(auto-detects VS Code, Cursor, opencode — and Visual Studio for solution projects).");
+        }
+    }
+    if (cmd === "--help" || cmd === "-h" || cmd === "help")
         usage(0);
     if (cmd === "--version" || cmd === "-v") {
         // package.json sits two levels above this file in both layouts
@@ -648,7 +684,7 @@ async function main() {
         }
         return;
     }
-    // `mcp` starts the stdio MCP server (same tools as the opencode plugin).
+    // `mcp` starts the stdio MCP server (11 tools; the opencode plugin exposes 5).
     // Branched before db() — runMcpServer() does its own init, and stdout must
     // stay clean for the MCP protocol.
     if (cmd === "mcp") {

package/dist/distill-agents.js

@@ -53,10 +53,11 @@ export function distillAgentsMarkdown(opts) {
     }
     // D43 — §3.5 memory-hygiene footer (double insurance for opencode users,
     // who never see the MCP handshake / init instructions): teach the agent
-    // reading this AGENTS.md to propose distilled captures at checkpoints.
+    // reading this AGENTS.md to propose distilled captures when a task ends
+    // (D53: the checkpoint mechanism is gone).
     lines.push(`### Memory hygiene (open-memex)`);
     lines.push(``);
-    lines.push(`- At checkpoints (session start, end of a work chunk, after the user commits),`, `  distill the session: propose 1–3 short memories capturing the useful`, `  conclusion — what was learned or decided, how an issue was resolved, what`, `  to avoid, where the authoritative doc lives — not the raw transcript.`, `  Save nothing without user approval.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`);
+    lines.push(`- When you finish a task the user would describe in one sentence, distill`, `  the session: propose 1–3 short memories capturing the useful`, `  conclusion — what was learned or decided, how an issue was resolved, what`, `  to avoid, where the authoritative doc lives — not the raw transcript.`, `  Save nothing without user approval.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`);
     lines.push(``);
     return lines.join("\n");
 }