open-memex 0.6.0 → 0.6.1-alpha.3

package/README.zh-CN.md

@@ -1,238 +1,176 @@
 # open-memex
 
-> 共享组织记忆层，帮助人与 AI 捕获、沉淀并复用组织知识。
+> 给你的 AI 编程助手装一个长期记忆——在本机上、用纯 Markdown 保存、你用的每个工具共享同一份。
 
 [![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)
+[English README](./README.md)
+
+每次打开 AI 编程会话都是从零开始：你得重新解释项目背景，助手把同样的坑再踩一遍，昨天的决策在聊天结束时就消失了。open-memex 让你的助手拥有跨会话的记忆：说一次"记住：我们周五发布"，下周不管你用 Copilot、Cursor、opencode 还是 Claude Code，它都已经知道——因为它们读写的是同一台机器上的同一份本地记忆。
+
+- **免费开源**（Apache-2.0）。无账号、无云端、无遥测——一切都在你本机，都是你能打开、能编辑的文件。
+- **本地优先**：记忆是纯 Markdown 文件（事实来源），外加一个可重建的 SQLite 关键词索引。除非你明确要分享，否则任何东西都不会离开你的机器。
+- **一份记忆，所有助手**：一条命令把几个编辑器都接上，它们共享同一份记忆，不再各存一份互不可见。
+
+第一次接触？这份 README 带你在一分钟左右从安装走到"记忆生效"。跑通之后，[概念指南](./docs/CONCEPTS.zh-CN.md)会把心智模型讲透。
+
+## 目录
+
+- [快速开始](#快速开始)
+- [核心概念](#核心概念)
+- [编辑器与功能对照](#编辑器与功能对照)
+- [安装](#安装)
+- [为你的编辑器做设置](#为你的编辑器做设置)
+- [init 到底改了你机器上的什么](#init-到底改了你机器上的什么)
+- [捕获：记忆是怎么存下来的](#捕获记忆是怎么存下来的)
+- [助手拿到的工具](#助手拿到的工具)
+- [记忆类型](#记忆类型)
+- [团队工作流：通过 Git 共享记忆](#团队工作流通过-git-共享记忆)
+- [回想：记忆是怎么回来的](#回想记忆是怎么回来的)
+- [安全与数据](#安全与数据)
+- [局限性](#局限性)
+- [升级](#升级)
+- [存储布局](#存储布局)
+- [配置](#配置)
+- [CLI 参考](#cli-参考)
+- [MCP 服务器](#mcp-服务器)
+- [作用域详解](#作用域详解)
+- [故障排查](#故障排查)
+- [常见问题](#常见问题)
+- [项目状态](#项目状态)
+
+## 快速开始
+
+需要 **Node.js ≥ 22.6**（用 `node -v` 检查）。然后：
 
-给 AI 编程助手的本地优先持久记忆：一个 [opencode](https://opencode.ai) 插件，
-加上一个通用 MCP server（VS Code Copilot、Cursor、Claude Code、Visual Studio 等）。
-
-## 为什么需要 open-memex？
+```sh
+npm install -g open-memex
+open-memex init
+```
 
-工程知识只存在于两个地方：代码里，和人的脑子里。
-每个新的 AI 编程会话都从零开始——同样的项目背景要反复讲，同样的坑要反复踩，
-同样的事故教训在聊天结束时就消失了。
+`init` 会检测你已安装的编辑器（VS Code、Cursor、opencode，以及项目里有 solution 文件时的 Visual Studio），把每个编辑器都接到 open-memex 上。之后重启编辑器。
 
-open-memex 把值得记住的部分——决策、约束、教训——存成可 review 的 Markdown，
-并在下一次会话开始时自动注入回去。
+**亲眼看它生效**（30 秒）：
 
-> No capture, nothing to inherit.（不记录，就无从传承。）
+```sh
+open-memex add "这个项目在周五发布"
+```
 
-### 一份记忆，所有 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 也看得到。
+```sh
+open-memex doctor
+```
 
-> 记忆属于你，不属于工具。
+## 核心概念
 
-它也补齐了 agentic 开发工作流（spec 驱动开发、plan/implement/verify 循环）缺的那一块：
-plan 产出决策，verify 产出规则——open-memex 是让它们跨会话留存的记忆层，
-而不是每次从头重新推导。
+三个概念能解释 open-memex 几乎所有的事。
 
-## 和其它方案的对比
+**1. 两种作用域：`project` 和 `personal`。**
+每条记忆属于两个地方之一：
 
-| | open-memex | 云端记忆服务 | Wiki / 文档平台 | 聊天记录 |
-|---|---|---|---|---|
-| 数据在哪 | 你的机器 + 你的仓库 | 服务商服务器 | 中心服务器 | 聊天结束就没了 |
-| 分享前 review | 有——outbox + PR | 不一定 | 有 | 没有 |
-| Agent 回忆 | 会话开始注入 + 搜索 | 调 API | 人工去查 | 没有 |
-| 人类可读 | 纯 Markdown 文件 | 后台 / API | 有 | 没有 |
-| 跨 AI 工具通用 | 可以——同一台机器上的任何 MCP 客户端 | 按集成逐个对接 | 不可以 | 不可以 |
+- **project（项目）**——关于某个代码库的知识（决策、约束、教训）。按当前仓库自动归属，你永远不需要手动设置。
+- **personal（个人）**——关于*你*的知识（偏好、习惯），在每个项目里都适用。它只存在于这台机器上，永远进不了任何仓库。
 
-- **Markdown 文件**是 source of truth（人类可读、git 友好）
-- **SQLite FTS5** 做可重建索引（BM25 关键词检索，`better-sqlite3`）
-- **零云端**、零账号、零第三方 API
-- 直接跑在 opencode 内嵌的 Bun 运行时里；CLI 和 MCP server 跑在 Node 下——开发时无需构建（发布的 npm 包带预编译好的 JS）、无需安装 Bun
+关于你的事实（"我喜欢简洁的 diff"）进 `personal`；其他默认进当前项目。
 
-## 架构
+**2. 捕获 → 回想。**
+记忆以小型 Markdown 文件保存，一条事实一个文件。每个新会话的第一轮，open-memex 自动把最相关的若干条交给你的助手，它一开场就已经知道。助手也能随时搜全量记忆。你永远不需要自己去"加载"任何东西。
 
-```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：只属于这台机器——永不同步，永远进不了仓库。
-```
+**3. 你的文件，你做主。**
+Markdown 文件是事实来源——打开、编辑、删除、用 grep 搜都行。旁边的 SQLite 索引只是搜索加速器，随时可以从文件重建（`open-memex reindex`）。团队共享（当你需要时）走的是和代码一样的评审流程：没有任何东西会被自动分享（见[团队工作流](#团队工作流通过-git-共享记忆)）。
 
-## 安装
+## 编辑器与功能对照
 
-### 前置要求
+open-memex 用两种方式接编辑器：原生的 **opencode 插件**，和标准的 **MCP 服务器**（任何支持 MCP 的编辑器都能用）。（MCP，即 Model Context Protocol，是编辑器给助手加工具的开放标准；open-memex 在你的编辑器里表现为一组 `memory_*` 工具。）你能得到什么，取决于编辑器走哪条路：
 
-- **Node.js ≥ 22.6**（`open-memex doctor` 会帮你检查）
+| 编辑器 | 设置方式 | 工具 | 会话开始时回想 | 关键词自动捕获 |
+|---|---|---|---|---|
+| opencode（原生插件，推荐） | `open-memex init --client opencode --global` | 5 个核心工具 | 内置——每个会话第一轮 | 有——`remember …`、`记住…` |
+| VS Code（Copilot） | `open-memex init --client vscode` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
+| Cursor | `open-memex init --client cursor` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
+| Claude Code | `claude mcp add open-memex -- open-memex mcp` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
+| Visual Studio 2022 17.14+ / 2026 | `open-memex init --client visualstudio` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
+| Codex 与其他 MCP 客户端 | `open-memex mcp --print-config` | 经 MCP 全 11 个 | 经 MCP 握手引导* | 无——你开口让助手保存 |
 
-### 第一步——安装 CLI
+\* MCP 没有硬性的会话开始钩子，所以 open-memex 在 MCP 握手中把引导发给助手（包括有多少草稿在等同步），`init` 还会把完整版写进编辑器的指令文件。实践中助手会遵循这些引导；只有 opencode 插件是真正的内置第一轮注入。[助手拿到的工具](#助手拿到的工具)一节列出了 5 个核心工具和另外 6 个工作流工具，"5 个 vs 11 个"的切分在那里写明白。
 
-#### 稳定版 vs Alpha 版
+同一台机器上的所有编辑器读写的是**同一份**记忆——在 VS Code 里捕获的一条约束，在 opencode 里会被遵守；在 Cursor 里学到的教训，会出现在 Claude Code 面前。（不同机器之间不自动同步，见[常见问题](#常见问题)。）
 
-**稳定版**（推荐大多数用户）——`latest` 标签：
+`init` 还会给 VS Code 和 Cursor（以及 per-project MCP 模式下的 opencode）安装一个 **Agent Skill**（一份教懂 skill 的助手用 CLI 的短指令文件）。opencode 原生插件接好时，那里不装 skill——插件已经提供了记忆工具，再加一套指令只会让助手变话痨。
 
-```sh
-npm install -g open-memex
-```
+## 和别的方案比
 
-安装的是 `0.5.1` 正式版。
+| | open-memex | 指令文件（`CLAUDE.md`、`AGENTS.md` 等） | 云记忆服务 | 聊天记录 |
+|---|---|---|---|---|
+| 存在哪 | 你的机器 + 你的仓库 | 仓库里 | 服务商服务器 | 聊天结束就没了 |
+| 谁维护 | 工作中顺手捕获、你评审 | 你手写并手动更新 | 服务商 | — |
+| 跨 AI 工具 | 可以——任何 MCP 客户端（同机） | 每个工具有自己的约定文件 | 按集成逐个接 | 不行 |
+| 分享前评审 | 有——outbox + Pull Request | 有——就是文件 | 看服务商 | 没有 |
+| 人类可读 | 纯 Markdown 文件 | 可以 | 面板 / API | 不行 |
 
-**Alpha 版**（最新开发版，给测试者）——`alpha` 标签：
+指令文件适合放少数常驻规则——继续用它（open-memex 甚至能从你的记忆里给它起草，见下文 `distill-agents`）。open-memex 管的是那堆不断增长的、没人记得要写下来的决策、教训和偏好。
 
-```sh
-npm install -g open-memex@alpha
-```
+## 安装
 
-```sh
-open-memex init
-```
+### 环境要求
 
-不跑 `open-memex init` 把编辑器接上，安装就不算完成（支持 VS Code、Cursor、opencode，有 .sln 的项目还支持 Visual Studio）。
+- **Node.js ≥ 22.6**（`open-memex doctor` 会替你核查）
 
-查看已发布版本：
+### 安装 CLI
 
 ```sh
-npm view open-memex version         # 最新稳定版
-npm view open-memex@alpha version   # 最新 alpha 版
+npm install -g open-memex
 ```
 
-Alpha 版可能有毛边——欢迎报 bug。
+这是稳定版。装包时可能会打印一行提醒让你运行 `open-memex init`——编辑器接线是单独的一步（下面第 2 步），没看到这行提醒也不用担心，直接运行 `init` 就行。
 
-**免安装——用 npx 直接跑：**
+另有两种方式：
 
-```sh
-npx -y open-memex <命令>          # 例如 npx -y open-memex init --client vscode
-npx -y open-memex@alpha <命令>   # alpha 线，免安装
-```
+- **免安装，用 npx 直接跑**：`npx -y open-memex <command>` 免安装运行任意命令（如 `npx -y open-memex init --client vscode`）。启动慢一些，但无需安装卸载。
+- **Alpha 版**（功能最新、毛边更多，给测试者）：`npm install -g open-memex@alpha`。用 `npm view open-memex version`（稳定版）和 `npm view open-memex@alpha version`（alpha 版）看当前发布了什么。
+
+装完找不到 `open-memex` 命令，是 PATH 的问题——见[故障排查](#故障排查)。
 
-**从源码安装**（最新开发版，`main` 分支）：
+### 从源码安装（给贡献者）
 
 ```sh
 git clone -b main https://github.com/stoneskin/open-memex.git
 cd open-memex
 npm install
-node --experimental-strip-types src/cli.ts <命令>
+node --experimental-strip-types src/cli.ts <command>
 ```
 
-#### 提示 "'open-memex' 不是内部命令"？——PATH 设置
-
-`npm install -g` 会把 `open-memex` 启动器放到 npm 的全局 bin 目录。
-如果终端找不到它，说明该目录不在你的 `PATH` 里：
-
-1. 先找到这个目录：`npm config get prefix`
-   - **Windows：** 启动器（`open-memex.cmd`）就在该目录下，例如
-     `C:\Users\<你>\AppData\Roaming\npm`
-   - **macOS / Linux：** 在 `<prefix>/bin` 下，例如 `/usr/local/bin`
-     或 `~/.nvm/versions/node/v22.x.x/bin`
-2. 把它加进 `PATH`：
-   - **Windows：** 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 →
-     把该目录加到*用户*的 `Path` 里 → **重启终端**。用 `where open-memex` 验证。
-   - **macOS / Linux：** 在 `~/.zshrc`（或 `~/.bashrc`）里加一行
-     `export PATH="$(npm prefix -g)/bin:$PATH"`，重启 shell，
-     用 `command -v open-memex` 验证。
-3. 没有管理员权限 / 不想动 `PATH`？用上面的 npx 形式——npx 自己解析包，
-   不需要改 `PATH`。
-
-#### Windows 重装报 "`EBUSY` / `EPERM`（`better_sqlite3.node`）"
-
-Windows 下被进程加载的 DLL 是锁死的：如果 open-memex MCP server 正在运行
-（VS Code MCP 面板、Cursor 等），`npm install -g open-memex` 替换不了
-`better_sqlite3.node`，就会报 `EBUSY` / `EPERM`。先停掉 MCP server
-（或退出编辑器），再重跑安装。还不行的话，手动删掉全局 npm 目录下的
-`node_modules/open-memex` 和 `node_modules/.open-memex-*` 临时目录，再装。
-
-### 第二步——给你的编辑器一键配置
+## 为你的编辑器做设置
 
-在**项目根目录**下运行（这样 project scope 会解析到这个仓库）：
+在**项目根目录**（你正在工作的仓库顶层文件夹）运行 `init`，让项目作用域正好落到这个仓库上：
 
 ```sh
 open-memex init --yes
-# ……没先装包的话：
+# ……或者不先装包，直接：
 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`：
-
-> **两个"全局"不是一回事，别搞混。**
-> - `npm install -g open-memex` 是把*包*装到全局：让 `open-memex` 命令出现在
->   你的 PATH 里。
-> - `init --global` 是把*编辑器配置*写到用户级而不是项目里：init 一次，
->   每个项目都生效。不管包是全局安装的还是用 npx 临时跑的，效果一样。
-
-装完包还会打印一句提醒，让你跑 `open-memex init`——接线是独立的一步。
-如果你在从没跑过 init 的机器上直接敲 `open-memex`，它会问你要不要现在
-init（只在交互终端里问；脚本和 CI 里看到的还是原来的 usage）。
-init 跑完会打印一个具体的下一步——用 `open-memex add` 存一条记忆，再让
-agent 回忆它——让第一次用的用户一眼看到"跑起来了"是什么样子。
+`--yes` 表示接受 `init` 每个问题的推荐默认值（要接哪些编辑器、自动捕获、第一轮回想）。想逐题回答就去掉它。不带 `--client` 时，`init` 检测你已装的编辑器并全部接上——初始化一次，所有项目通用。只想接一个编辑器，就传 `--client`：
 
 **VS Code**（Copilot）：
 
 ```sh
 open-memex init --client vscode
-# ……没先装包的话：
-npx -y open-memex init --client vscode
 ```
 
-配项目级 `.vscode/mcp.json` 和用户级 Copilot instructions，然后重新加载窗口，
-在 Copilot Chat 的 MCP 面板里确认 `open-memex` server 已启动。终端交互模式下
-`init` 会问你要配到项目级还是用户级，而不是替你猜；`--global` 直接强制
-用户级。
+写入 MCP 服务器配置并可干净重载；重载窗口，确认 Copilot Chat 的 MCP 面板里 `open-memex` 服务器已启动。默认把配置写到 VS Code 的*用户级*配置（每个项目都生效）；也可以写到项目级 `.vscode/mcp.json`。
 
-**Cursor：**
+**Cursor**：
 
 ```sh
 open-memex init --client cursor
 ```
 
-和 VS Code 一个套路：默认写项目级 `.cursor/mcp.json`，`--global`
-（或终端里 `init` 问你时选用户级）就写用户级，外加用户级 Copilot
-instructions。
-
-**一次配置、所有项目通用（VS Code / Cursor）：**
-
-```sh
-open-memex init --client vscode --global --yes
-```
-
-把 server 条目写到编辑器的*用户级* MCP 配置（Windows 下是
-`%APPDATA%\Code\User\mcp.json`，macOS 是
-`~/Library/Application Support/Code/User/mcp.json`，Linux 是
-`~/.config/Code/User/mcp.json`；Cursor 是 `~/.cursor/mcp.json`），
-而不是写到项目里——init 一次，每个项目打开自动启动 server。
-如果某个项目自己定义了 `.vscode/mcp.json`，项目级的优先。
-如果用户级文件里带注释（VS Code 接受 JSONC），`init` 不会碰这个文件，
-只打印可直接手贴的配置片段。
+形态和 VS Code 一样：默认用户级 MCP 配置，可选项目级 `.cursor/mcp.json`，外加 Copilot 风格的指令文件。
 
 **opencode**（原生插件——推荐）：
 
@@ -240,178 +178,198 @@ open-memex init --client vscode --global --yes
 open-memex init --client opencode --global --yes
 ```
 
-把 `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]` 合并进用户级
-`~/.config/opencode/opencode.json`（如果你用的是 `opencode.jsonc`，就合并进那个）
-——一次配置，每个项目自动生效，不用逐个项目
-init。在 tools 之外还能获得关键词自动捕获和首轮上下文注入。（带注释的配置文件
-不会被改动——那种情况请手动加 `plugin` 这一行。）
+把原生插件并入你的用户级 `~/.config/opencode/opencode.json`（如果你已有的是 `opencode.jsonc`，就并进那个）——一次设置，每个项目都生效，不用逐项目 init。你会得到 5 个核心工具、关键词自动捕获和第一轮上下文注入。（配置文件里有注释时它不会动，`init` 会打印要手动加的那一行。）
 
-**opencode**（作为普通 MCP 客户端）：
+**opencode**（作为普通 MCP 消费者）：
 
 ```sh
 open-memex init --client opencode
 ```
 
-写项目级 `opencode.jsonc`（`type: "local"`）。只有当你更想要纯 MCP 而不是原生
-插件时才需要。
+写一个项目级 `opencode.jsonc`，里面放 MCP 服务器。只有当你偏好普通 MCP、不要原生插件时才需要——代价是没有关键词捕获和内置注入。
 
-**Claude Code**（在项目根目录运行）：
+**Claude Code**（在项目根目录）：
 
 ```sh
 claude mcp add open-memex -- open-memex mcp
-# ……或打印配置片段：open-memex mcp --print-config claude
+# ……或者打印配置片段：open-memex mcp --print-config claude
 ```
 
-**Visual Studio**（在 solution 目录运行）：
+**Visual Studio**（在 solution 目录）：
 
 ```sh
 open-memex init --client visualstudio
 ```
 
-写 solution 级 `.mcp.json` 和用户级 Copilot instructions。需要
-Visual Studio 2022 17.14+ 或 Visual Studio 2026（**仅 Windows**）。
-Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，
-所以上面的 VS Code 配置同样可用。
+写 solution 级 `.mcp.json`。需要 Visual Studio 2022 17.14+ 或 Visual Studio 2026（仅 Windows）。Visual Studio 也会自动发现 `.vscode/mcp.json` 和 `.cursor/mcp.json`，所以上面的 VS Code 设置同样有效。
 
-**Codex：** 暂无 `init` 客户端——以 `open-memex mcp --print-config` 为起点手动添加
-（`config.toml` 的 `[mcp_servers]`，或 `codex mcp add`）。
+**Codex**：暂时没有 `init` 客户端——用 `open-memex mcp --print-config` 的输出手动加服务器（`config.toml` 里的 `[mcp_servers]`，或 `codex mcp add`）。
 
-**拆掉接线：**
+### 一次设置、所有项目通用（VS Code / Cursor）
+
+```sh
+open-memex init --client vscode --global --yes
+```
+
+> **两个"全局"不是一回事，别搞混。**
+> - `npm install -g open-memex` 是把*软件包*装到全局：让 `open-memex` 命令进 PATH。
+> - `init --global` 是把*编辑器配置*写到用户级而不是项目级：一次初始化，所有项目都能用。包是全局装还是 npx 跑，它的效果都一样。
+
+`--global` 形式把服务器配置写进编辑器的*用户级* MCP 配置（Windows 上是 `%APPDATA%\Code\User\mcp.json`，macOS 上是 `~/Library/Application Support/Code/User/mcp.json`，Linux 上是 `~/.config/Code/User/mcp.json`；Cursor 是 `~/.cursor/mcp.json`），而不是项目里——初始化一次，服务器在每个项目都会启动。项目自己定义了 `.vscode/mcp.json` 时，项目级的仍然优先。如果用户级文件里有注释（编辑器接受 JSONC），`init` 不会动它，会打印出需要手动粘贴的那段确切片段。
+
+### `init` 的行为说明
+
+- 已有配置文件是**合并、永不覆盖**——重复运行 `init` 是安全的。`--force` 会重写我们写入的条目。
+- 当 PATH 上没有可持久使用的 `open-memex`（例如一次性 npx 运行时），`init` 会往配置里写一条 `npx -y open-memex mcp` 服务器命令，让设置之后照样能用。之后 `npm i -g open-memex` + `open-memex init --force` 可以切到更快的直连命令。
+- 在交互终端上，`init` 会列出检测到的编辑器并请你确认；脚本和 CI 环境从不提问，会接上所有检测到的编辑器。
+- 如果你在一台从未完成 init 的机器上只运行 `open-memex`（不带任何参数），它会问你要不要顺手跑 init（仅限交互终端）。
+
+### 移除接线
 
 ```sh
 open-memex uninstall --yes
 ```
 
-`init` 的逆操作——删掉 MCP server 条目、opencode 插件行和 Copilot
-instructions 里的 open-memex 段。不带 `--client` 时把检测到的编辑器全清掉
-（项目级和用户级都清）；`--global` 只清用户级。你的记忆数据永远不会被碰。
-
-`init` 说明：
-
-- Copilot 记忆 instructions 默认写到**用户级**
-  （`~/.copilot/copilot-instructions.md`；Visual Studio 是
-  `%USERPROFILE%\copilot-instructions.md`）——所有项目生效，永不 checkin
-  到 repo，没装 open-memex 的同事看不到、也不会出错。团队人人都用
-  open-memex 时可用 `--instructions project` 改写
-  `.github/copilot-instructions.md`。
-- 不带 `--client` 时，`init` 自动检测已安装的编辑器（VS Code 看 `PATH` 有没有
-  `code` / 安装位置 / 已有的用户级配置；Cursor 看 `PATH` 有没有 `cursor` 或
-  `~/.cursor`；opencode 看 `PATH` 有没有 `opencode` 或其配置目录；项目里有
-  `.sln` 时算上 Visual Studio），一次全接上——支持用户级的走用户级，
-  一次 init，所有项目通用。
-- 在终端里会列出检测到的编辑器，请你确认是一次全配还是只配一个，
-  再问是否开启关键词自动捕获、是否在首轮注入记忆。`--yes` 全用默认值；
-  脚本 / 非 TTY 环境不提问，直接配所有检测到的编辑器。
-- 已有配置文件会被**合并，不会被覆盖**——重复运行是安全的。
-  `--force` 强制覆盖。
-- `--global` 把 MCP server 条目写到编辑器的用户级配置（VS Code / Cursor）——
-  一次配置，所有项目通用。opencode 的 `--global` 走用户级原生插件，
-  不用逐个项目 init；Visual Studio 按设计保持 solution 级。
-- 如果 `PATH` 上没有可用的 `open-memex`（比如一次性 npx），`init` 会把
-  `npx -y open-memex mcp` 写进配置，配置照样能用。
-  以后 `npm i -g open-memex` + `open-memex init --force` 可切换到更快
-  的直接调用。
-
-### 第三步——验证
+撤销 `init`——移除 MCP 服务器条目、opencode 插件行、Agent Skill，以及编辑器指令文件里的 open-memex 段落。不带 `--client` 时会清理所有检测到的编辑器；`--global` 把清理范围限定在用户级接线。你的记忆数据永不触碰。
+
+## init 到底改了你机器上的什么
+
+`init` 写入的所有东西，一处列清：
+
+- **记忆数据**（首次使用时创建，不是 `init` 本身写的）：Windows 上是 `%APPDATA%\open-memex\`，macOS/Linux 上是 `~/.local/share/open-memex/`——你的记忆文件和搜索索引。`uninstall` 永不修改这里的任何东西。
+- **编辑器接线**（由 `open-memex uninstall` 移除）：
+  - opencode：一条 `"plugin"` 条目，并入 `~/.config/opencode/opencode.json`（或 `.jsonc`）。改名之前遗留的 `my-o-memory` 旧条目会同时被清掉。
+  - VS Code / Cursor：用户级或项目级 MCP 配置里的一条 `open-memex` 服务器条目，外加 Copilot 指令文件里的一段 open-memex 内容（默认是用户级 `~/.copilot/copilot-instructions.md`；`--instructions project` 改为写进仓库的 `.github/copilot-instructions.md`，适合团队全员都用 open-memex 的情况）。
+  - Visual Studio：solution 旁边的 `.mcp.json`。
+  - Agent Skill：VS Code（`~/.copilot/skills/`）、Cursor（`~/.cursor/skills/`）或 per-project MCP 模式下的 opencode（`~/.config/opencode/skills/`）各自一个 `skills/open-memex/` 文件夹。
+- **你的仓库**：什么都不写。只有你明确运行 `submit` 时（见团队工作流），文件才会落进仓库——且只是本地提交，永不自动推送。
+
+带注释（JSONC）或无法安全解析的文件永不被重写：`init` 会打印需要手动粘贴的那段确切片段。
+
+## 捕获：记忆是怎么存下来的
+
+三种存入方式：
+
+- **关键词触发**（仅 opencode 原生插件）：说 `remember …`、`note that …`、`don't forget …`、`TIL …`、`save this …`——中文 `记住…` / `记一下` / `记录一下` / `别忘了…`——这句话就被存下来，不需要任何工具调用。捕获默认进当前 **project**；`remember for me …`、`记住我…`、`替我记…`、`我觉得…`、`我喜欢…` 这类"这是关于我"的信号会改为进 **personal**；`我们决定…`、`帮我们记住…` 等团队语境仍留在项目里。
+- **助手主动保存**：在任何编辑器里，你让助手记住某件事（或者你陈述了一个值得记的事实、它自己判断该保存），它会调用 `memory_add`。上面的路由是启发式规则；你可以明说"存到我的个人记忆"，或用 CLI 加 `--scope` 明确指定。
+- **CLI**：`open-memex add "…"`，可选 `--scope` / `--tags` / `--type`。
+
+**脱敏。** 把敏感内容包在 `<private>…</private>` 里，它在保存前会被整段剥离。识别出的密钥（API key、token、高熵凭证）会被就地掩码——保留前 4 个字符（让你能认出是哪个 key），其余替换——记忆仍会保存。随时安全地预览一句话会被捕获成什么样：
 
 ```sh
-open-memex doctor
+open-memex capture --dry-run "…"
 ```
 
-检查：Node 版本、配置来源、当前目录的 scope 解析、存储可写性，
-然后启动一个真实的 MCP server 做 `initialize` + `tools/list`——
-十一个 tools 都必须出现。
+万一密钥还是溜进了记忆，`open-memex forget <id>` 把它删掉。
+
+## 助手拿到的工具
 
-## Agent 可用的 tools
+MCP 服务器暴露十一个工具；opencode 原生插件暴露其中五个核心的（标 ●）。另外六个是团队评审工作流工具——只有当你通过 Git 共享记忆时才用得上。
 
-| Tool | 作用 |
+| 工具 | 做什么 |
 |---|---|
-| `memory_add`       | 保存事实、偏好、决定、笔记 |
-| `memory_search`    | BM25 关键词检索，跨 project + personal 记忆 |
-| `memory_list`      | 按 scope 列出记忆，最新的在前 |
-| `memory_supersede` | 用新版本替换一条记忆（保留替换链） |
-| `memory_forget`    | 按 id 删除一条记忆 |
-| `memory_status`    | 显示同步队列：outbox 草稿、repo 评审状态、未提交文件 |
-| `memory_submit`    | 把点名的草稿移入 repo memory 目录（建本地分支 + commit） |
-| `memory_propose`   | 把 personal 记忆复制到 project scope 作为评审候选 |
-| `memory_promote`   | 推进 `proposed → approved → published`（或 reject / resubmit） |
-| `memory_resolve`   | 列出冲突的记忆文件 / 对单个做三路合并 |
-| `memory_pr_status` | 把分支 PR 的 GitHub 状态映射到每条记忆的评审状态 |
-
-## 捕获（Capture）
-
-- **关键词触发**（opencode 原生插件，扫描用户消息）：中文 `记住…` /
-  `记一下` / `记录一下` / `别忘了…`，英文 `remember …` / `note that …` /
-  `don't forget …` / `TIL …` / `save this …`。
-  Scope 路由：第一人称单数进 **personal**（`记住我…`、`替我记…`、
-  `我觉得…`、`我喜欢…`、`remember for me`）；第一人称复数进当前
-  **project** scope（`我们认为…`、`我们决定…`、`帮我们记住…`）。
-- **Agent 主动调用** `memory_add`
-- **脱敏**：`<private>…</private>` 标签内的内容会被剥离；检测到的密钥
-  （API key、token、高熵凭据）就地打码——保留前 4 个字符，其余替换为 `x`——
-  然后照常保存。用 `open-memex capture --dry-run "…"` 预览一条消息会被如何捕获。
-
-## 记忆类型（Memory types）
-
-11 种类型——`type` 说明这条记忆是什么，`tags` 说明它和什么有关：
-
-| 类型 | 记录什么 |
+| ● `memory_add`       | 保存一条事实、偏好、决策、笔记 |
+| ● `memory_search`    | 关键词搜索（BM25），横跨项目 + 个人记忆 |
+| ● `memory_list`      | 列出某个作用域的记忆，最新在前 |
+| ● `memory_supersede` | 用新版本替换一条记忆（保留 supersede 链） |
+| ● `memory_forget`    | 按 id 删除一条记忆 |
+| `memory_status`      | 显示同步队列：outbox 草稿、仓库评审状态、未提交文件 |
+| `memory_submit`      | 把指定的草稿移进仓库记忆目录（本地分支 + 提交） |
+| `memory_propose`     | 把个人记忆复制到项目作用域，作为评审候选 |
+| `memory_promote`     | 推进 `proposed → approved → published`（或拒绝 / 重新提交） |
+| `memory_resolve`     | 列出冲突的记忆文件 / 对某个做三方合并 |
+| `memory_pr_status`   | 把分支 PR 的 GitHub 状态映射到每条记忆的评审状态 |
+
+所以 MCP 接入的编辑器永远是全套；opencode 插件主攻捕获与回想，工作流类的事走 CLI 或 MCP 接入的编辑器。
+
+## 记忆类型
+
+每条记忆有一个 `type`（它是什么）和 `tags`（它关于什么）。内置十一种类型：
+
+| 类型 | 捕获什么 |
 |---|---|
 | `fact` | 关于项目或世界的稳定事实 |
-| `preference` | 某人做事的偏好 |
-| `decision` | 做过的选择——为什么、权衡了什么 |
-| `constraint` | 不能违反的规则 |
-| `todo` | 以后要做的承诺 |
-| `knowledge` | 持久的领域或架构知识 |
-| `howto` | 验证过的做法 |
+| `preference` | 某人喜欢怎么做事 |
+| `decision` | 一个已做的选择——为什么选、代价是什么 |
+| `constraint` | 不可违反的规则 |
+| `todo` | 承诺以后要做的事 |
+| `knowledge` | 耐久的领域或架构知识 |
+| `howto` | 一个验证可行的步骤 |
 | `gotcha` | 要避开的坑 |
-| `lesson` | 事故或错误教会我们的东西 |
+| `lesson` | 一次事故或错误教会我们的东西 |
 | `observation` | 注意到的现象，还不是结论 |
 | `reference` | 指向权威文档的指针（不复制内容） |
 
-## 团队记忆工作流
+`--type` 接受任意字符串，但坚持用内置这十一种，会让会话开始时的标签、搜索和 `distill-agents` 的输出保持可预期。
+
+## 团队工作流：通过 Git 共享记忆
 
-个人笔记永远私有。项目知识走一条显式、可 review 的流水线——没有任何东西会自动分享：
+**一个人用？你可以跳过这一节**——上面就是单人使用的全部产品。下面的事永远不会自动发生。
+
+个人笔记保持私密。项目知识当你选择分享时，走一条显式、可评审的流水线，形状和代码评审一样：
 
 ```
-capture → outbox（本地草稿）→ submit → 仓库（.ai/open-memex/）→ PR review → published → recall
+捕获 → outbox（草稿，本地）→ submit → 仓库（.ai/open-memex/）→ PR 评审 → 已发布 → 回想
 ```
 
-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 都能用。
+1. **捕获**——日常工作中随手存下决策、坑、教训，都是草稿。
+2. **评审**——草稿停在本地 outbox 里（你机器上，git 看不见）；`open-memex sync-status`——或者直接在聊天里说"sync memory"（"同步记忆"）——看有啥待处理的。
+3. **提交**——由你点名记忆；它们进入 `<仓库>/.ai/open-memex/` 并在当前分支形成一个本地提交。open-memex 永不自动推送；它会打印推送和建 PR 的命令，拿到你明确许可的助手可以替你执行。
+4. **PR 评审**——记忆是纯 Markdown；评审者走正常分支/PR 流程批准、要求修改或拒绝。
+5. **回想**——已发布的记忆在会话开始时注入，平时也能随时搜，人和助手都一样。
+
+看护共享记忆的人遵循 [维护者约定](./docs/CURATOR.md)：什么该批准、什么该打回、哪些卫生规则让共享记忆不腐烂。
+
+## 回想：记忆是怎么回来的
+
+每个会话的第一轮，open-memex 把一个 `[OPEN-MEMEX]` 块注入助手的上下文：最新的项目记忆（默认前 8 条）和你的个人偏好（默认前 5 条）。长这样：
+
+```text
+[OPEN-MEMEX]
+
+User profile / preferences:
+- I prefer concise diffs
 
-Reviewer 守则：[docs/CURATOR.md](./docs/CURATOR.md)。
+Project knowledge (my-repo):
+- [decision] We deploy on Fridays; the release train leaves at 10:00
+
+Use the `memory_search` tool to look up more. Use `memory_add` to save new facts.
+Do not mention this block to the user unless asked.
+```
+
+这是一个快照，不是全量记忆——其余的随时用 `memory_search` 就能查。两个前 N 的数都可以配（见[配置](#配置)）。对 MCP 客户端，这个块以握手引导的形式送达、由助手遵循；opencode 插件则在第一轮直接注入。
 
 ## 安全与数据
 
-- **本地优先：** 所有东西都在你的机器上（`%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 索引可以从文件重建。
+- **本地优先：** 一切住在你机器上（Windows 是 `%APPDATA%\open-memex`，macOS/Linux 是 `~/.local/share/open-memex`），外加你自己选择的仓库。零云调用、零账号、零第三方 API、零遥测。
+- **密钥不进记忆：** `<private>…</private>` 包住的内容会被剥离；识别出的 API key/token 在保存前就地掩码。用 `open-memex capture --dry-run "…"` 预览。
+- **个人永不同步：** `personal` 作用域只存在于这台机器——导出时默认排除，永远进不了仓库。
+- **分享可审计：** 团队记忆只能靠显式 `submit` 移动，走分支/PR 评审，每次 `promote` 状态迁移都记进该记忆的 `review_history`（谁 / 何时 / 为什么）。
+- **文件是你的：** Markdown 是事实来源——手工查看、编辑、删除都行；SQLite 索引从文件重建。
 
-## Scope
+## 局限性
 
-- **project** — 绑定当前仓库（用 git origin URL 哈希做 key，无 remote 则用 cwd）。新记忆默认进这里。
-- **personal** — 跨所有项目全局，**仅本机，永不上传/同步**。放个人偏好。（v1 叫 `user`，`migrate --to-v2` 会自动改名。）
+把边界写明白，免得你事后意外：
 
-完整 scope 模型（key 推导、迁移、visibility、保留名）见
-[docs/SCOPES.md](./docs/SCOPES.md)。
+- **关键词搜索，不是语义搜索。** 回想走 BM25 关键词匹配：搜的是你存下的词，不是近义改写。（用自然问句没问题——"如何/请问"这类提问词会在匹配前过滤掉，不会稀释结果。）任何 embedding 模型没经你明确同意，永不下载。
+- **单台机器。** 同一台机器上的编辑器共享记忆；没有跨机器同步。用 `export` / `import` 压缩包（见下）手动搬家。
+- **快照，不是全部。** 会话开始的回想是前 N 条快照（默认项目 8 + 个人 5）；更老的记忆 `memory_search` 一步就能到，但不会同时全在上下文里。
+- **MCP 的引导是建议性的。** opencode 之外，主动捕获和回想靠助手遵循握手指令——MCP 里没有硬性的会话开始钩子。工具本身在被调用时永远可靠。
+- **捕获路由是启发式的。** 带"个人"信号的短语（`remember for me …`、`我喜欢…`）进个人作用域；其余默认进当前项目。猜错时，把作用域说出声，或者 CLI 加 `--scope`。
 
-## 检索（Retrieval）
+## 升级
+
+```sh
+npm install -g open-memex@latest   # 或 @alpha
+```
 
-每个会话的首轮，`open-memex` 会往 system prompt 里注入一个 `[OPEN-MEMEX]` 块，
-包含 top-N 最新 project 记忆 + top-N 个人偏好。Agent 也可以随时调用
-`memory_search` 按需检索。
+编辑器配置指向已安装的 `open-memex` 命令，所以升级不需要重新接线。大版本升级后跑一次 `open-memex init --force`，把已装的 Agent Skill 和指令文件刷新到最新文案。如果你是从源码安装或挪过包的位置，`--force` 也会把 opencode 插件路径重新指好。
 
 ## 存储布局
 
 ```
 %APPDATA%\open-memex\               (Windows)
-$XDG_DATA_HOME/open-memex/          (Linux/macOS)
+~/.local/share/open-memex/          (macOS/Linux; 设置了 $XDG_DATA_HOME 则用它)
 ├── index.db                         # SQLite FTS5 索引（可重建）
 └── memories/
     ├── personal/
@@ -420,250 +378,226 @@ $XDG_DATA_HOME/open-memex/          (Linux/macOS)
         └── <id>.md
 ```
 
-每个 `.md` 文件是 v2 YAML frontmatter（`id, scope, scope_key, visibility, role,
-type, importance, status, tags, created_at, updated_at, schema_version` 等）+
-记忆正文。可以手工编辑——插件启动时按文件 mtime 重新同步。
-Markdown 是 source of truth，SQLite 索引是派生的、可重建的
-（`open-memex reindex`）。
+每个 `.md` 文件是一条记忆：YAML frontmatter（`id, scope, type, tags, created_at, schema_version` 等）后跟正文。你可以手工编辑——索引会从文件重新同步，Markdown 永远是事实来源（`open-memex reindex` 从零重建索引）。
 
-## 配置（Config）
+一旦你 `submit`，项目记忆还会以 Markdown 文件的形式住进 `<仓库>/.ai/open-memex/`（由 `memoryDir` 配置），跟着分支和 PR 像其他文件一样流转。
 
-可选文件 `~/.config/opencode/open-memex.jsonc`（可用 `MY_O_MEMORY_CONFIG`
-改路径；`MY_O_MEMORY_HOME` 改存储根目录）。
+## 配置
+
+设置放在 `~/.config/opencode/open-memex.jsonc`——路径里的 `opencode` 是历史名；这一个文件由所有客户端共享。用 `MY_O_MEMORY_CONFIG` 覆盖配置路径，用 `MY_O_MEMORY_HOME` 覆盖存储根目录（改名之前留下的旧环境变量名，仍然有效）。
 
 默认值：
 
 ```jsonc
 {
-  "maxProjectMemories": 8,    // 首轮注入的 project 记忆条数
-  "maxProfileItems": 5,       // 首轮注入的个人偏好条数
-  "injectOnFirstTurn": true,  // [OPEN-MEMEX] system-prompt 块
+  "maxProjectMemories": 8,    // 第一轮注入的项目记忆条数上限
+  "maxProfileItems": 5,       // 第一轮注入的个人条数上限
+  "injectOnFirstTurn": true,  // [OPEN-MEMEX] 系统提示块
   "keywordCaptureEnabled": true,
   "logLevel": "info",          // info | debug
-  "memoryDir": ".ai/open-memex" // 仓库内项目记忆目录，相对于仓库根目录
+  "memoryDir": ".ai/open-memex" // 仓库内项目记忆目录，相对于仓库根
 }
 ```
 
-project scope 的记忆以"一个记忆一个 Markdown 文件"的形式存放在
-`<仓库>/<memoryDir>/`（默认 `.ai/open-memex/`）下，可经 git 共享；
-personal 记忆只存本地 appdata，永不离开本机。已有的 appdata 项目文件会在
-首次写入/同步时自动搬进仓库目录。
-
-`open-memex config` 打印生效配置（默认值 + 文件）。
-安装后改设置：
+`open-memex config` 打印生效配置（默认值 + 文件）。安装后改设置：
 
 ```sh
 open-memex config set keywordCaptureEnabled false
 open-memex config set maxProjectMemories 12
+open-memex config set sync.autoPull true   # MCP 会话开始时尽力而为地 pull
 ```
 
-可设置的 key：`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、
-`keywordCaptureEnabled`、`logLevel`、`memoryDir`。完整设计见
-[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)。
+可设置的键：`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`logLevel`、`memoryDir`，以及 `sync.autoPull`（带点的键，写入嵌套的 `sync` 对象）。完整设计：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)。
 
 ## CLI 参考
 
-安装与健康检查：
+设置与健康：
 
 ```sh
 open-memex init [--client vscode|cursor|opencode|visualstudio]
               [--instructions personal|project] [--global] [--force] [--yes]
 open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]
 open-memex config                                  # 打印生效配置
-open-memex config set <key> <value>                # 改设置
+open-memex config set <key> <value>                # 改一个设置
 open-memex doctor                                  # 环境健康检查
+open-memex audit                                   # 记忆健康检查（近重复、陈旧、断链）
 open-memex capture --dry-run "记住我喜欢简洁的回答"  # 预览关键词捕获
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
-open-memex --help      # 本帮助
-open-memex <command> --help  # 单个命令的帮助
+open-memex --help      # 这份参考
+open-memex <command> --help  # 某个命令的帮助
 open-memex --version   # 已安装版本
 ```
 
 记忆操作：
 
 ```sh
-open-memex add "This repo uses better-sqlite3" --type project-config
+open-memex add "This repo uses better-sqlite3" --type fact
 open-memex search "auth flow"
+open-memex search "auth flow" --explain   # 显示 FTS 表达式、分数、被生命周期藏掉的计数
 open-memex list --scope project
 open-memex supersede <id> "Updated content"
 open-memex status <id> deprecated
 open-memex forget <id>
 ```
 
-团队评审工作流（Phase 2B —— 两个家，各管一段）：
+团队评审工作流（两个家，一个阶段一个）：
 
-project 草稿先住在 **appdata outbox**（git 看不见、跟分支无关）；只有你
-点名批准的草稿，才会被移入 `<repo>/.ai/open-memex/`，之后随分支和 PR 走。
-没经过你点名，什么都不会动。
-
-在接了 MCP 服务器的 AI 对话里，直接说 **"同步记忆"**（或 "sync memory"）——
-agent 会查状态、把 outbox 草稿逐条摘要、问你同步哪几条。服务器也会主动告诉
-agent：新对话开始时握手里带待审草稿数，每次改记忆的 tool 返回里也带当前数（为零时不带）。
+项目草稿住在 **appdata outbox** 里（git 看不见、与分支无关）；只有你批准的草稿才进 `<仓库>/.ai/open-memex/`，在那里跟随分支和 PR。你不点名，什么都不动。在接了 MCP 服务器的 AI 聊天里，直接说 **"sync memory"**（或"同步记忆"）——助手会跑状态检查、把 outbox 草稿摘要给你、问你要同步哪些。服务器也会主动告知助手：会话开始的握手里报当前等待的草稿数，每个改记忆的工具结果在非零时也带这个数。
 
 ```sh
 open-memex sync-status
-# 看索引上次同步的时间和触发方、outbox（待同步）、repo 里的评审状态
-# （draft / proposed / approved / published / rejected），
-# 以及 repo 里还没 commit 的记忆文件。
+# 显示索引上次同步的时间（和触发源）、outbox
+# （待同步）、仓库评审状态
+# （draft / proposed / approved / published / rejected）、
+# 以及任何未提交的仓库记忆文件。
 
 open-memex submit <id...> [--branch <name>] [--base <branch>]
-# 把你点名的草稿移入 .ai/open-memex/，状态变为 proposed：
-# 复制、改 review_state、在当前分支本地 git commit。
-# 永不自动建分支——建分支是你说了算（或 Agent 拿到你明确批准走全链时）。
-# 全有或全无；冲突（同 id 不同内容）干净回滚。
-# 打印 push + gh pr 命令；Agent 拿到你的 Yes 后会自己走完 push/PR。
-# --branch <name> 先建分支再提交（Agent 全链路径）。
-# PR 默认 base 是当前分支；--base 可改到 main 或集成支。
+# 把你点名的草稿移进 .ai/open-memex/，标为 "proposed"：
+# 复制、翻转 review_state、在当前分支本地 git 提交。
+# 永不自己建分支——建分支是你（或拿到完整链路明确许可的助手）的事。
+# 全有全無；冲突（同 id 不同内容）干净地中止。
+# 打印 push + gh pr 命令；持有你 Yes 的助手可以一并执行 push/PR。
+# --branch <name> 先建分支（助手全链路路径）。PR base 默认是当前分支
+# （记忆 PR 叠在你的工作分支上）；--base 可改指到 main 或你的评审分支。
 
 open-memex pr-status [--apply]
-# 读分支的 GitHub PR，把它的状态映射到每条 in-repo 记忆：
-# PR merged → published，PR approved → approved（approved_by = reviewer），
-# changes requested 只给建议。默认只报告；--apply 在本地执行映射的流转（不 push）。
+# 读分支的 GitHub PR，把状态映射到每条仓库内记忆：
+# PR 合并 → published，PR 批准 → approved（approved_by = 评审者），
+# 要求修改 → 只给建议。默认只报告；--apply 在本地执行映射的迁移（不推送）。
 
 open-memex pull
-# 从 git 远端拉共享记忆：fetch + 只允许 fast-forward。
-# 分支 diverged 时直接报错退出——open-memex 永不强行 merge；
-# 手工解决（rebase 或 merge）后再 pull。成功后本地索引重新同步。
-# pull 默认只显式触发；`open-memex config set sync.autoPull true`
-# 可在 MCP session start 时尝试自动 pull（失败永不阻塞 session）。
+# 从 git 远程拉共享记忆：fetch + 純 fast-forward。
+# 分支分叉则明确报错失败——open-memex 永不强制合并；手工解决后再 pull。
+# 成功后本地索引重新同步。pull 默认显式触发；设置
+# `open-memex config set sync.autoPull true` 可在 MCP 会话开始时尽力拉一次
+# （拉失败永不阻塞会话）。
 
 open-memex push
-# 把当前分支（含已 submit 的记忆）push 到 git 远端。
-# 只显式触发——open-memex 永不自动 push。
+# 把当前分支（连同已提交的记忆）推送到 git 远程。
+# 只能显式触发——open-memex 永不自作主张推送。
 
 open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
-# 把记忆打包成可携带的 .tar.gz（markdown 原件 + manifest.json），
-# 用于搬到另一台机器或导入别的工具。默认排除 visibility:private 的记忆；
-# --all / -a 全量包含（完整迁移）。
+# 把记忆打包成可移植的 .tar.gz（markdown + manifest.json），用于
+# 搬到另一台机器或另一个应用。默认排除 visibility:private 的记忆；
+# --all / -a 包含全部（完整迁移）。
 
 open-memex import <bundle.tar.gz> [--dry-run]
-# 恢复 export 的包：personal 记忆进 personal 目录；project 记忆按当前
-# 项目重新编号 scope_key，进 outbox 当草稿。内容相同的 id 跳过；
-# 内容冲突的 id 只报告，永不覆盖。
+# 恢复一个包：个人记忆进个人目录；项目记忆
+# 重新键到当前项目、作为草稿落进 outbox。
+# 同 id 的跳过；冲突的 id 只报告、永不覆写。
 
 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。片段末尾带一段"记忆卫生"
-# （§3.5 蒸馏指引），让读 AGENTS.md 的 agent 学会在任务结束时提议蒸馏捕获。
+# 从项目记忆中提炼出一段 AGENTS.md 片段
+# （决策、约束、教训、坑、howto）。打印 markdown；
+# -o 写进文件。你评审后手工并入——open-memex
+# 永不自己改写你的 AGENTS.md。片段末尾带一节
+# “记忆卫生”内容，让读 AGENTS.md 的助手在任务结束时学会主动提出提炼捕获。
 
 open-memex propose <id...> --to project [--local-approve]
-# 一次 propose 一条或多条（一个分支、一个 PR），每条独立新 id。
-# 全有或全无：id 有错整批回滚，不会留半截。
-# 把一条 personal 记忆复制到 project scope 进入评审（复制而非移动，
-# personal 原件保留）。结果落在 outbox；准备好进 repo 时再 sync-status / submit。
+# 一次提议一条或多条个人记忆（一个分支、一个 PR）；
+# 每条复制并生成新 id。全有全無：任何一条 id 出错，整批中止，绝不半途。
+# 把一条个人记忆复制到项目作用域作为评审候选
+# （是复制不是移动——个人原件保留）。结果落进 outbox；
+# 准备进仓库时再跑 sync-status / submit。
 open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
-# 晋升一步：proposed → approved → published（或用 --reject 驳回并附注原因）。
-# 每次流转都追加到记忆的 review_history（谁、何时、为什么）。
-# 驳回不删文件，由你决定：接受（关 PR 删分支）、改完 --resubmit 再审、
-# 或留着当 [rejected] 记录。
+# 向前推进一步：proposed → approved → published（或带说明拒绝）。
+# 每次迁移都记进该记忆的 review_history（谁/何时/为什么）。
+# 被拒绝不会删除文件——由你决定：接受（关掉 PR、删分支）、改完 --resubmit 再来一轮，或留着做 [rejected] 记录。
 open-memex resolve [id-or-path]
-# 列出冲突中的记忆文件，或对其中一个做字段级 3-way 合并。
-# 语义冲突只报告、不自动解决。
+# 列出冲突的记忆文件，或对某一个做字段级三方合并。
+# 语义冲突只报告、永不自动解决。
 ```
 
-打理共享记忆的人遵循 curator 公约——`docs/CURATOR.md`：
-批什么、退回什么，以及防止共享记忆腐烂的卫生规则。
+看护共享记忆的人遵循维护者约定——`docs/CURATOR.md`：什么该批准、什么该打回、哪些卫生规则让共享记忆不腐烂。
 
 维护：
 
 ```sh
-open-memex where        # 显示存储与配置文件路径
-open-memex scopes       # 列出 project scope 及记忆条数
+open-memex where        # 显示存储与配置路径
+open-memex scopes       # 列出各项目作用域及记忆计数
 open-memex reindex      # 从 markdown 重建 SQLite 索引
-open-memex migrate --to-v2 [--dry-run]   # v1 数据 → v2
+open-memex audit        # 记忆健康检查：近重复对、陈旧记忆、断裂的取代链
+open-memex migrate --to-v2 [--dry-run]   # v1 数据 → v2（把 user 作用域改名为 personal）
 ```
 
-CLI 跑在 Node 22 下。从源码 checkout 使用时走内置的实验性 TypeScript loader（无需构建）；
-发布的 npm 包带预编译好的 JS（发布时间执行 `npm run build`）。
-从源码 checkout 使用时，每条命令前加
-`node --experimental-strip-types src/cli.ts`（简单场景也可用
-`npm run cli -- <命令>`——但 npm 会吞掉未知的 `--flag` 参数，
-所以推荐直接用 `node`）。
+CLI 在 Node 22 下运行。从源码 checkout 跑时用内置的实验性 TypeScript 加载器（免构建步骤）；发布到 npm 的包是预编译好的 JS（发版时 `npm run build`）。从源码 checkout 时，每条命令前面加 `node --experimental-strip-types src/cli.ts`（简单情况可用 `npm run cli -- <command>`——npm 会吞掉不认识的 `--flag` 参数，所以优先用直连 `node`）。
 
-## MCP server
+## MCP 服务器
 
-同一个十一个 memory tools，走 Model Context Protocol 的 stdio server——
-不需要宿主专属插件，任何 MCP 客户端都能用 open-memex。
+同一组记忆工具，走 Model Context Protocol、经 stdio 服务器提供——不需要任何宿主专用插件。任何 MCP 客户端都能用 open-memex。
 
 ```sh
 open-memex mcp               # 全局安装后
-npx -y open-memex mcp  # 免安装
+npx -y open-memex mcp        # 无需安装
 ```
 
-project scope 从进程工作目录解析，所以配置 server 时 cwd 要指向项目根目录
-（`init` 会帮你处理好）。
-
-> **注意：** MCP 是请求/响应式的——它给 agent 提供 tools，但没有 opencode
-> 插件的关键词自动捕获和首轮上下文注入。想让 agent 主动用记忆，
-> 靠的是 agent 的 instructions：服务器在 MCP 握手的 `instructions` 里自带
-> session-start 指引（含开场时的 outbox 待审草稿数；改记忆的 tool 返回里也会
-> 带当前数，为零时不带），`init` 则把更完整的版本写进编辑器的 instruction
-> 文件。两者都是建议性的——MCP 客户端没有强制的 session-start hook。
-
-## 路线图（Roadmap）
-
-**`0.3.0`（稳定版）：** 通用 MCP server、`open-memex` bin/CLI、
-一键 `init` 配置、中文关键词捕获（含 personal/project 路由）、
-`config` / `capture --dry-run` / `doctor` 助手命令、Visual Studio 支持。
-
-**`0.4.0`（稳定版）：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
-`sync-status` → `submit`（本地分支+commit，push/PR 拿你的 Yes 才做）
-→ `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。
-
-**`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 的增强路径）；
-本地 embedding 做基准测试门控的实验（**未经明确 opt-in 绝不下载
-embedding 模型**）；云端 `RemoteProvider` 定制只在多仓库共享、
-ACL 或合规需求出现时才做。
-
-设计细节：[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)（append-only 决策日志）。
-
-## 常见问题（FAQ）
-
-**装完之后，每个项目都要初始化 open-memex 吗（像其他 app 那样）？**
-分两层。数据层不需要——没有 per-project 初始化的概念：数据目录按需自动创建，
-project scope 从当前目录的 git remote 或路径自动推导，记忆天然按项目隔离，
-零配置。编辑器接线只需要一步：直接跑 `open-memex init`（不带参数），它会自动
-检测你装好的编辑器（VS Code、Cursor、opencode；项目里有 `.sln` 时还有 Visual
-Studio）并一次全接上——支持用户级配置的编辑器就写用户级，一次 init 所有项目
-通用。只想接某一个编辑器？用
-`open-memex init --client <vscode|cursor|opencode|visualstudio>`。
-想给 VS Code / Cursor 强制写用户级？加 `--global`。
-Copilot 记忆指令默认写用户级（`~/.copilot/`），那个是全局的。
-
-**opencode 需要跑 `init` 吗？**
-两条路。推荐：`open-memex init --client opencode --global`——自动把原生插件
-合并进 `~/.config/opencode/opencode.json`。一次配置，所有项目生效，还多拿
-关键词自动捕获和首轮记忆注入。想手写？往那个文件里加
-`"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]`
-（填 open-memex 的实际安装路径）就行。当纯 MCP 用：
-`open-memex init --client opencode` 写项目级 `opencode.jsonc`（无 hooks）。
-如果你的用户级配置里带注释，`init` 不会碰它，只打印手动步骤。
-
-**VS Code 呢——跑一次就行，还是每个项目都要跑？**
-跑一次就行。直接 `open-memex init` 会自动检测到 VS Code，把 MCP server 写进
-VS Code 的用户级 `mcp.json`（Windows：`%APPDATA%/Code/User/mcp.json`；
-macOS：`~/Library/Application Support/Code/User/mcp.json`；
-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
-插件行和 Copilot instructions 里的 open-memex 段。不带 `--client` 时把检测
-到的编辑器全清掉；`--global` 只清用户级。你的记忆数据永远不会被碰。
+项目作用域由进程当前工作目录解析，所以配置服务器时把 cwd 设到项目根（`init` 会替你处理）。
+
+> **注意：** MCP 是请求/响应模型——它给助手的是工具，不是 opencode 插件那种自动关键词捕获或第一轮注入。主动用记忆靠助手的指令：服务器在 MCP 握手 `instructions` 里发会话开始引导（包括会话开始时的 outbox 草稿实时数、以及每个改记忆的工具结果非零时附带的待处理数），`init` 把完整版写进编辑器的指令文件。两者都是建议性的——没有任何 MCP 消费者提供硬性的会话开始钩子。
+
+## 作用域详解
+
+- **project（项目）**——限定在当前仓库，键由 git origin URL 的 hash 派生（所以同一仓库的多个 clone 共享一个作用域），没有远程时退回到当前工作目录路径。新记忆的默认作用域。
+- **personal（个人）**——横跨你的所有项目，仅限本机，永不向外同步。放个人偏好用。（v1 里叫 `user`；`migrate --to-v2` 会改名。）
+
+完整的 scope 模型（键派生、迁移、可见性、保留名）见 [docs/SCOPES.md](./docs/SCOPES.md)。[概念指南](./docs/CONCEPTS.zh-CN.md)把心智模型完整走了一遍。
+
+## 故障排查
+
+**`open-memex` 无法识别 / 命令找不到。**
+全局 `npm install -g` 把 `open-memex` 启动器放在 npm 的全局 bin 文件夹里。终端找不到命令，就是这个文件夹不在 PATH 上：
+
+1. 找到这个文件夹：`npm config get prefix`
+   - **Windows：** 启动器（`open-memex.cmd`）直接在这个文件夹里，如 `C:\Users\<你>\AppData\Roaming\npm`
+   - **macOS / Linux：** 在 `<prefix>/bin`，如 `/usr/local/bin` 或 `~/.nvm/versions/node/v22.x.x/bin`
+2. 把它加进 PATH：
+   - **Windows：** 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 把文件夹加到*用户*的 `Path` → **重启终端**。用 `where open-memex` 验证。
+   - **macOS / Linux：** 往 `~/.zshrc`（或 `~/.bashrc`）加 `export PATH="$(npm prefix -g)/bin:$PATH"`，重启 shell，用 `command -v open-memex` 验证。
+3. 没有管理员权限 / 不想动 PATH？用 npx 形式——`npx -y open-memex <command>` 自己解析包，不需要改 PATH。
+
+**`EBUSY` / `EPERM` 报错落在 `better_sqlite3.node` 上（Windows）。**
+Windows 上已加载的 DLL 是锁定的：如果 open-memex 的 MCP 服务器正在运行（VS Code 的 MCP 面板、Cursor 等），`npm install -g open-memex` 换不掉 `better_sqlite3.node`，会以 `EBUSY` / `EPERM` 失败。先停掉 MCP 服务器（或退出编辑器），再重装。若仍失败，删掉全局 npm 根目录下的 `node_modules/open-memex` 和任何 `node_modules/.open-memex-*` 临时文件夹，再装一次。
+
+**`init` 说某个配置文件它没动。**
+你的编辑器配置里有注释（JSONC）或 JSON 不合法，open-memex 永不重写它无法安全解析的文件。`init` 已经把要加的确切片段打印出来了——手动粘贴进去就好。opencode 配置同理：有注释时，手动把 `"plugin"` 那一行加上。
+
+**感觉有问题——跑 `open-memex doctor`。**
+它检查 Node 版本、配置来源、当前目录的作用域解析、存储可写性，并确认 VS Code 没有把 MCP 禁用；然后启动一个真实 MCP 服务器，对它跑 `initialize` + `tools/list`——十一个工具必须全部出现。它还会报告改名之前遗留的 `my-o-memory` 引用（如果某编辑器配置里还留着旧包名的话）。
+
+## 常见问题
+
+**需要用 git 吗？**
+不需要。捕获和回想在任何文件夹里都能用——没有 git 仓库时，项目作用域就按文件夹路径键。只有团队工作流（`submit` / PR 评审）需要 git，而且它是可选的。
+
+**我用好几个编辑器，它们真共享一份记忆吗？**
+真的——在同一台机器上。每个接好的编辑器读写的是同一份本地记忆；每个编辑器具体能得到什么，见[编辑器与功能对照](#编辑器与功能对照)。在 VS Code 里存的决策，到 opencode 里会被遵守。
+
+**我在公司和家里两台电脑工作，记忆能同步吗？**
+不能自动同步——记忆按设计是逐机器存的，你的个人作用域永远不离开它被创建的那台机器。手动搬家：在一个机器跑 `open-memex export`，在另一台跑 `open-memex import`。通过 Git 共享的项目记忆（团队工作流）会随仓库走，所以在第二台克隆仓库就把*已发布的项目*记忆带过去了——个人的会故意留在原地。
+
+**真的是免费的吗？需要账号吗？**
+免费开源（Apache-2.0）。无账号、无注册、无遥测、无云调用。它永远不"打电话回家"，因为压根没有家可打：open-memex 唯一会碰的网络，是你明确推送时你自己的 git 远程。
+
+**我不小心把一个密钥粘进了记忆，怎么办？**
+`open-memex search "<其中一段>"` 找到那条记忆，再 `open-memex forget <id>` 删掉。下次要避免：把敏感文本包在 `<private>…</private>` 里（保存前被剥离）——识别出的 API key 和 token 还会自动掩码。任何一句话都能先安全预览：`open-memex capture --dry-run "…"`。
+
+**每个项目都要跑一遍 `init` 吗？**
+不用。数据层什么都不需要——项目作用域由当前目录的 git 远程或路径自动派生，记忆天然按项目隔离、零设置。编辑器接线是每台机器一次 `open-memex init`（编辑器支持时就是用户级）。升级后（`--force`）或换编辑器时再跑。
+
+**opencode 需要 `init` 吗？**
+两条路。推荐：`open-memex init --client opencode --global`——它把原生 open-memex 插件并入 `~/.config/opencode/opencode.json`。一次设置、所有项目生效，还多出关键词自动捕获和第一轮记忆注入。想全手动？把 `"plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]`（已安装包的路径）加进那个文件也行。走普通 MCP 的话：`open-memex init --client opencode` 写一个项目级 `opencode.jsonc`（没有钩子）。你的 用户级配置带注释时，`init` 不会动它，会打印手动步骤。
+
+**VS Code——`init` 跑一次还是每个项目跑？**
+跑一次就够。直接 `open-memex init` 会自动检测 VS Code 并把 MCP 服务器条目写进 VS Code 的用户级 `mcp.json`（Windows 在 `%APPDATA%/Code/User/mcp.json`，macOS 在 `~/Library/Application Support/Code/User/mcp.json`，Linux 在 `~/.config/Code/User/mcp.json`），服务器在每个项目都会启动。项目里有项目级 `.vscode/mcp.json` 时仍以它优先，而该条目保留 `cwd=${workspaceFolder}`，所以项目作用域按窗口各自解析。如果你的 用户级 `mcp.json` 里有注释（VS Code 接受 JSONC），`init` 不动它，会打印确切片段让你手动添加。空文件会被当作空白，直接写入。
+
+**怎么移除编辑器接线？**
+`open-memex uninstall` 撤销 `init`：移除 MCP 服务器条目、opencode 插件行、Agent Skill 目录，以及 Copilot 指令里的 open-memex 段落。不带 `--client` 时清理所有检测到的编辑器；`--global` 把清理限制在用户级接线。你的记忆永不被动。
+
+## 项目状态
+
+open-memex 是稳定且日常在用的；当前稳定线以 `latest` 发到 npm 上，`alpha` 构建给测试者。发版历史在 [GitHub Releases](https://github.com/stoneskin/open-memex/releases)；设计决策记录在只追加的日志 [docs/V2-DESIGN.md](./docs/V2-DESIGN.md) 里。
+
+在望的方向（不承诺版本号）：更多编辑器的原生助手插件（作为在同一组 MCP 工具之上的增强路径）；本地 embedding 作为可选择开启的实验（没经询问，永不下载任何模型）；只有在真实多仓库共享、ACL 或合规需求出现时才做 org 层。
 
 ## 许可证