@pcircle/memesh 4.4.0 → 4.5.1

package/README.vi.md

@@ -29,7 +29,7 @@ Package này là tầng bộ nhớ cục bộ của dòng sản phẩm MeMesh. N
 
 ---
 
-## Proof — 95.60% R@5 trên LongMemEval-S
+## Bằng chứng — 95.60% R@5 trên LongMemEval-S
 
 Engine truy hồi của MeMesh là **chỉ FTS5** (không LLM, không embeddings trên hot path), được đo trên benchmark công khai [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) (500 câu hỏi, giấy phép MIT):
 
@@ -108,7 +108,20 @@ Nếu bạn chỉ dùng memesh qua chat Claude Code (không bao giờ gõ `memes
 
 ## Bắt đầu trong 60 giây
 
-### Bước 1: Cài đặt
+### Lựa chọn A — Plugin Claude Code (cài một dòng)
+
+Nếu bạn dùng Claude Code, cài MeMesh dưới dạng plugin ngay trong CLI:
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin install memesh@pcircle-memesh
+```
+
+Claude Code tự động kết nối hooks, skills và MCP server. Bạn có auto-capture trong phiên, recall chủ động, skill `/memesh` trong cuộc trò chuyện, và `remember` / `recall` / `forget` / `learn` dưới dạng công cụ MCP cho agent.
+
+### Lựa chọn B — npm global (tối ưu tuỳ chọn)
+
+Nếu bạn muốn binary nằm thẳng trên `PATH` (để `memesh` chạy được ở bất kỳ terminal nào mà không có độ trễ `npx`), hoặc muốn expose `memesh-mcp` như lệnh stdio đường dẫn cố định cho các MCP client ngoài Claude Code (Cursor, Cline):
 
 ```bash
 npm install -g @pcircle/memesh
@@ -127,6 +140,12 @@ Các hooks này cùng tồn tại với bất kỳ hook tùy chỉnh nào trong
 
 ### Bước 2: Lưu một quyết định
 
+```bash
+memesh remember "Use OAuth 2.0 with PKCE for the new auth"
+```
+
+Hoặc dùng dạng tường minh khi bạn muốn một tên và kiểu ổn định để lọc về sau:
+
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
@@ -234,13 +253,12 @@ Dán tools vào bất kỳ API call nào
 
 ## Điều gì xảy ra tự động trong Claude Code
 
-Bạn không cần phải manually nhớ mọi thứ. MeMesh có **7 hooks** để capture và inject kiến thức khi bạn làm việc:
+Bạn không cần phải manually nhớ mọi thứ. MeMesh có **6 hooks** để capture và inject kiến thức khi bạn làm việc:
 
 | Khi nào | MeMesh làm gì |
 |------|------------------|
 | **Mỗi lần session bắt đầu** | Load những memories liên quan nhất + cảnh báo chủ động từ bài học trong quá khứ + agentic-orchestration banner |
 | **Trước khi chỉnh sửa file** | Gọi lại memories liên quan đến file hoặc dự án trước khi Claude viết code |
-| **Trước bash commands** | Hướng dẫn Claude dispatch những commands có độ xác minh cao (test, build, lint, migrate, deploy, benchmark) dưới dạng background agents |
 | **Khi bạn yêu cầu ghi nhớ** | Phát hiện ý định "remember this" / "記下來" và nhắc nhở (use memesh|ghi memesh) |
 | **Sau mỗi `git commit`** | Ghi lại những gì bạn thay đổi, với diff stats |
 | **Khi Claude dừng** | Capture những file đã chỉnh sửa, lỗi đã sửa, và auto-generate structured lessons từ failures |
@@ -258,14 +276,15 @@ Toàn bộ cấu hình thông qua biến môi trường. Các giá trị mặc
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Ghi đè vị trí của database SQLite. |
 | `MEMESH_AUTO_CAPTURE` | `true` | Tắt hoàn toàn các hooks auto-capture (`Stop`, `PreCompact`). |
-| `MEMESH_AUTO_DETECT_LLM` | chưa đặt (tự động phát hiện **bật**) | Đặt `0` để memesh KHÔNG dùng khóa API tìm thấy trong môi trường shell. Mặc định, nếu `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` được đặt và bạn chưa cấu hình nhà cung cấp trong `~/.memesh/config.json`, memesh sẽ dùng nó cho các tính năng LLM phía ghi (hợp nhất, trích xuất bài học, tự gắn thẻ, dream). Embeddings không bị ảnh hưởng — vẫn là ONNX cục bộ (384 chiều) trừ khi bạn đặt `embedder.provider` một cách rõ ràng. |
-| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | chưa đặt | Đặt thành `1` để bật một giao thức working-model thử nghiệm (CTO / Orchestrator / Agents framing). Thêm session-start banner, một Bash command nudge, và telemetry `verify_agent_work`. Hiệu quả của giao thức đang được instrument, chưa được chứng minh — opt in nếu bạn muốn tham gia. **Mặc định là OFF**: các tính năng bộ nhớ cốt lõi vẫn hoạt động mà không cần flag này. |
+| `MEMESH_AUTO_DETECT_LLM` | chưa đặt (tự động phát hiện **bật**) | Đặt `0` để memesh KHÔNG dùng khóa API tìm thấy trong môi trường shell. Mặc định, nếu `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` được đặt và bạn chưa cấu hình nhà cung cấp trong `~/.memesh/config.json`, memesh sẽ dùng nó cho các tính năng LLM phía ghi (hợp nhất, trích xuất bài học, tự gắn thẻ, dream). Embeddings không bị ảnh hưởng — vẫn chỉ tìm kiếm theo từ khóa (FTS5) trừ khi bạn đặt `embedder.provider` thành `ollama` hoặc `openai`. |
 | `MEMESH_AUTO_UPDATE` | `off` | Chính sách auto-update. `off` (mặc định) không bao giờ tự cập nhật; `patch` cho phép `X.Y.Z → X.Y.Z+N`; `minor` thêm `X.Y.Z → X.Y+1.0`; `major` cho phép mọi bump. Khi được phép, một `npm install -g` detached chạy ở cuối session (Stop hook) để không bao giờ chặn công việc của bạn — kết quả lưu vào `~/.memesh/auto-update.log`. Cũng có thể đặt là `autoUpdate` trong `~/.memesh/config.json` (env thắng). Khi phiên bản đã cài bị maintainers đánh dấu deprecated (security advisory), `patch` sẽ được force-allowed ngay cả khi `off` — minor / major bumps vẫn manual để tránh behaviour drift im lặng. |
 | `OPENAI_API_KEY` | chưa đặt | Khóa OpenAI của bạn. Được dùng tự động cho các tính năng LLM trừ khi bạn đặt `MEMESH_AUTO_DETECT_LLM=0` hoặc cấu hình nhà cung cấp một cách rõ ràng. |
 | `OLLAMA_HOST` | `http://localhost:11434` | Ghi đè endpoint Ollama khi dùng local Ollama provider. |
 
 `memesh doctor` in ra cấu hình đã resolve để bạn thấy cái gì đang active.
 
+**Nhà cung cấp LLM dự phòng (Smart Mode).** Trong dashboard, tại **Settings → “Fallback providers”**, bạn có thể đặt một chuỗi failover có thứ tự — memesh thử lần lượt từng nhà cung cấp khi cái chính bị hỏng. Thêm một fallback cục bộ [Ollama](https://ollama.com), hoặc một cái trên cloud (OpenAI / Anthropic, cần API key). Đánh đổi về quyền riêng tư: khi dùng fallback cloud, văn bản bộ nhớ — vốn có thể riêng tư — sẽ được gửi tới nhà cung cấp đó, điều này quan trọng nếu bạn chạy hoàn toàn cục bộ vì quyền riêng tư.
+
 Khi npm gắn cờ phiên bản đã cài là deprecated (thường là security advisory), session-start kế tiếp sẽ thêm banner mạnh `⚠️ MeMesh <ver> is DEPRECATED` ở đầu và `memesh update-status` hiển thị cùng dòng đó cho đến khi bạn nâng cấp. Kết quả check được cache tại `~/.memesh/update-check.<version>.json` để một lỗi mạng tạm thời không làm mờ cảnh báo.
 
 ---
@@ -334,20 +353,22 @@ Hoặc dùng dashboard Settings tab (visual setup):
 memesh serve  # mở dashboard → Settings tab
 ```
 
+**Khai thác các phiên trước thành bộ nhớ.** `memesh dream run --from-transcripts` đọc bản ghi phiên Claude Code của dự án này, hỏi LLM về các quyết định và bài học ẩn trong cuộc trò chuyện, rồi lưu tạm chúng dưới dạng đề xuất — không có gì tự động vào đồ thị của bạn. Xem lại từng cái bằng `memesh dream show <id>` và chấp nhận những cái đáng giữ.
+
 ### Dùng embeddings của riêng bạn (tùy chọn)
 
-Mặc định embeddings dùng mô hình ONNX cục bộ (`Xenova/all-MiniLM-L6-v2`, 384 chiều) — không cần khóa API, không có gì rời khỏi máy bạn, và recall FTS5 mặc định thậm chí không cần đến. Để dùng embedder lưu trữ đám mây hoặc máy chủ cục bộ:
+Mặc định MeMesh recall **chỉ theo từ khóa** (FTS5) — không cần khóa API, không tải mô hình, không có gì rời khỏi máy bạn. Tìm kiếm ngữ nghĩa (theo ý nghĩa) là tùy chọn và cần một embedder. Hãy cấu hình một trong số:
 
 ```bash
 memesh config set embedder.provider openai          # or: ollama
 memesh config set embedder.model text-embedding-3-small
 ```
 
-Embedder được cấu hình **độc lập với LLM chat** — thay đổi `llm.provider` không bao giờ âm thầm thay đổi embeddings của bạn. Nếu bạn chuyển sang chiều khác (ví dụ 384 → 1536), MeMesh tự động xây dựng lại chỉ mục vector ở lần ghi tiếp theo. Các giá trị `embedder.provider` được hỗ trợ: `onnx` (mặc định, cục bộ), `openai`, `ollama`.
+Embedder được cấu hình **độc lập với LLM chat** — thay đổi `llm.provider` không bao giờ âm thầm thay đổi embeddings của bạn. Nếu bạn chuyển sang chiều khác (ví dụ 768 → 1536), MeMesh tự động xây dựng lại chỉ mục vector ở lần ghi tiếp theo. Các giá trị `embedder.provider` được hỗ trợ: `ollama` (cục bộ), `openai` (đám mây). Không đặt gì thì recall vẫn là tìm kiếm theo từ khóa.
 
 | | Level 0 (default) | Level 1 (Smart Mode) |
 |---|---|---|
-| **Search** | FTS5 + sqlite-vec, 95.60% R@5 | giữ nguyên — recall luôn LLM-free ở mọi level |
+| **Tìm kiếm** | FTS5 + sqlite-vec, 95.60% R@5 | giữ nguyên — recall luôn LLM-free ở mọi level |
 | **Auto-capture** | Rule-based patterns | + LLM extracts decisions & lessons |
 | **Auto-tagging** | Chỉ thẻ thủ công | + LLM tự động gắn nhãn entity mới |
 | **Phân tích lỗi** | Không có sẵn | + LLM chuyển session errors thành structured lessons |
@@ -356,7 +377,7 @@ Embedder được cấu hình **độc lập với LLM chat** — thay đổi `l
 
 ---
 
-## Cả 9 Memory Tools
+## Cả 7 Memory Tools
 
 | Tool | Nó làm gì |
 |------|-------------|
@@ -367,7 +388,6 @@ Embedder được cấu hình **độc lập với LLM chat** — thay đổi `l
 | `import` | Import memories với merge strategies (skip / overwrite / append) |
 | `learn` | Ghi lại structured lessons từ những sai lầm (error, root cause, fix, prevention) |
 | `user_patterns` | Phân tích work patterns của bạn — schedule, tools, strengths, learning areas |
-| `verify_agent_work` | Persist một verification report cho background-agent work; reality-checks claimed file changes với `git diff` |
 
 ---
 
@@ -376,7 +396,7 @@ Embedder được cấu hình **độc lập với LLM chat** — thay đổi `l
 ```
                     ┌─────────────────┐
                     │   Core Engine   │
-                    │  (8 operations) │
+                    │  (7 operations) │
                     └────────┬────────┘
            ┌─────────────────┼─────────────────┐
            │                 │                 │

package/README.zh-CN.md

@@ -117,7 +117,7 @@ npm install -g @pcircle/memesh
 /plugin install memesh@pcircle-memesh
 ```
 
-Claude Code 会自动接好 hooks、skills 以及 MCP server。你将获得会话内自动捕获、主动回忆、Claude Code 对话内的 `/memesh` skill（remember / recall / learn / forget），并且 `remember` / `recall` / `forget` / `learn` 也以 MCP 工具提供给代理使用。CLI 和本地仪表板也都无需额外全局安装即可访问 — `npx @pcircle/memesh <command>` 可以执行所有 CLI 命令，`npx @pcircle/memesh` 会在 `localhost:3737` 启动仪表板。MCP server 直接从插件内置的编译产物启动 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地构建步骤。如果 `better-sqlite3` 原生 binding 在首次启动时缺失（例如 Node 主版本升级后），启动器会在进程内自动重新编译后继续执行。
+Claude Code 会自动接好 hooks、skills 以及 MCP server。你将获得会话内自动捕获、主动回忆、Claude Code 对话内的 `/memesh` skill（remember / recall / learn / forget），并且 `remember` / `recall` / `forget` / `learn` 也以 MCP 工具提供给代理使用。CLI 和本地仪表板也都无需额外全局安装即可访问 — `npx @pcircle/memesh <command>` 可以执行所有 CLI 命令，`npx @pcircle/memesh` 会在 `localhost:3737` 启动仪表板。MCP server 直接从插件内置的编译产物启动 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地构建步骤。memesh 通过 Node 内置的 `node:sqlite`（22.13+）存放数据，所以升级 Node 不会留下一个为错误 runtime 编译的二进制文件。
 
 ### 选项 B — npm 全局安装（可选优化）
 
@@ -128,8 +128,8 @@ npm install -g @pcircle/memesh
 ```
 
 > **首次安装注意事项（一次性）：**
-> - **原生模块** — `better-sqlite3` 和 `sqlite-vec` 在 macOS（arm64/x64）、Linux（x64/arm64）和 Windows x64 上均通过预构建二进制安装。在不常见的平台或预构建失败时，需要可用的 C/C++ 工具链。
-> - **embedding 模型** — 第一次触发本地 embedding 的调用（例如带语义模式的 `recall`）会下载 `Xenova/all-MiniLM-L6-v2`（~80 MB）到 `~/.memesh/models/`。后续调用是即时的。默认检索路径（FTS5）不需要这个下载。
+> - **不需要编译器** — 数据库引擎就是 Node 自己的 `node:sqlite`。负责「按意思搜索」的 `sqlite-vec` 以预编译文件形式提供 macOS（arm64/x64）、Linux（x64/arm64）和 Windows x64；在其他平台它就是不存在，回忆保持关键词搜索。这里没有任何东西会执行安装脚本，所以 `npm install --ignore-scripts` 也能装出完全可用的 memesh。
+> - **语义搜索是可选的** — 默认检索路径是关键词搜索（FTS5），不需要模型也不需要下载。基于语义的搜索需要一个 embedder：在本地运行 [Ollama](https://ollama.com)，或配置一个云端 embedder（见下方“嵌入”）。没有配置时，memesh 只使用关键词搜索。
 
 ### 第一步半：把 MeMesh 接入 Claude Code（仅 npm 路径）
 
@@ -261,13 +261,12 @@ memesh export-schema \
 
 ## Claude Code 中的自动化流程
 
-你不需要手动记住一切。MeMesh 有 **7 个钩子**在你工作时自动捕获和注入知识：
+你不需要手动记住一切。MeMesh 有 **6 个钩子**在你工作时自动捕获和注入知识：
 
 | 触发条件 | MeMesh 的动作 |
 |---------|------------|
 | **每个会话开始** | 加载最相关的记忆 + 来自过去经验教训的主动警告 |
 | **编辑文件前** | 回忆与该文件或项目相关的记忆，然后 Claude 才开始写代码 |
-| **执行 bash 命令前** | （可选启用）推动 Claude 派遣高可验证性命令（测试、构建、lint、迁移、部署、基准测试）作为后台代理 |
 | **当你要求记忆时** | 检测「remember this」/「guardar en memesh」/「sauvegarder dans memesh」/「记下来」意图（5 种语言），并提醒 Claude 使用 memesh |
 | **每次 `git commit` 后** | 记录你的改动，附带 diff 统计 |
 | **Claude 停止时** | 捕获编辑过的文件、修复的错误、自动从失败中生成结构化经验教训 |
@@ -285,14 +284,15 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | 覆盖 SQLite 数据库位置。 |
 | `MEMESH_AUTO_CAPTURE` | `true` | 完全禁用自动捕获 hooks（`Stop`、`PreCompact`）。 |
-| `MEMESH_AUTO_DETECT_LLM` | 未设置（自动检测**开启**） | 设为 `0` 让 memesh 不使用它在 shell 环境中找到的 API 密钥。默认情况下，如果设置了 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` 且你没有在 `~/.memesh/config.json` 中配置提供商，memesh 会用它来跑写入侧的 LLM 功能（整合、经验提取、自动打标签、dream）。嵌入不受影响 —— 除非你显式设置 `embedder.provider`，否则保持本地 ONNX（384 维）。 |
-| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | 未设置 | 设为 `1` 启用一个实验性工作模型协议（CTO / Orchestrator / Agents 框架）。会增加一个 session-start 横幅、Bash 命令提示，以及 `verify_agent_work` 遥测。该协议的有效性正在被检测中、尚未被证实 — 想参与实验时再开启。**默认 OFF**：核心内存功能不依赖此 flag。 |
+| `MEMESH_AUTO_DETECT_LLM` | 未设置（自动检测**开启**） | 设为 `0` 让 memesh 不使用它在 shell 环境中找到的 API 密钥。默认情况下，如果设置了 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` 且你没有在 `~/.memesh/config.json` 中配置提供商，memesh 会用它来跑写入侧的 LLM 功能（整合、经验提取、自动打标签、dream）。嵌入不受影响 —— 除非你把 `embedder.provider` 显式设置为 `ollama` 或 `openai`，否则保持仅关键词（FTS5）。 |
 | `MEMESH_AUTO_UPDATE` | `off` | 自动升级策略。`off`（默认）从不自动升级；`patch` 允许 `X.Y.Z → X.Y.Z+N`；`minor` 增加 `X.Y.Z → X.Y+1.0`；`major` 允许任意版本跳升。允许时，一个分离的 `npm install -g` 会在会话结束（Stop hook）触发，所以从不阻塞你的工作 — 结果落在 `~/.memesh/auto-update.log`。也可以在 `~/.memesh/config.json` 里写为 `autoUpdate`（环境变量优先）。当已安装版本被维护者标记为 deprecated（安全建议）时，`patch` 会被强制允许，即便策略是 `off` — minor / major 升级仍保持手动，避免行为静默漂移。 |
 | `OPENAI_API_KEY` | 未设置 | 你的 OpenAI 密钥。除非你设置 `MEMESH_AUTO_DETECT_LLM=0` 或显式配置提供商，否则会自动用于 LLM 功能。 |
 | `OLLAMA_HOST` | `http://localhost:11434` | 使用本地 Ollama 提供商时覆盖 Ollama 端点。 |
 
 `memesh doctor` 会打印解析后的配置，你可以看到当前生效的内容。
 
+**备用 LLM 提供商（Smart Mode）。** 在 dashboard 的 **Settings → “Fallback providers”** 可以设置一条有顺序的故障转移链——当主要提供商不可用时，memesh 会依次改用列表里的下一个。可以加本地的 [Ollama](https://ollama.com) 备用，或云端的（OpenAI / Anthropic，需要 API key）。隐私权衡：一旦用到云端备用，记忆内容（可能是私密的）会被发送到该提供商，所以如果你为了隐私只跑本地，这点需要注意。
+
 当 npm 把已安装版本标记为 deprecated（通常为安全建议）时，下次 session-start 会先显示一条强烈的 `⚠️ MeMesh <ver> is DEPRECATED` 横幅，并且 `memesh update-status` 在你升级前会持续显示同一行。检查结果会缓存到 `~/.memesh/update-check.<version>.json`，避免一次临时网络故障让警告变弱。
 
 ---
@@ -361,20 +361,22 @@ memesh config set llm.api-key sk-ant-...
 memesh serve  # 打开仪表板 → 设置标签页
 ```
 
+**把过去的会话挖成记忆。** `memesh dream run --from-transcripts` 会读取这个项目的 Claude Code 会话记录，请 LLM 找出藏在对话里的决策与教训，再把它们暂存为提案——不会自动写入你的知识图谱。用 `memesh dream show <id>` 逐一查看，挑值得保留的 accept。
+
 ### 自带嵌入(可选)
 
-嵌入默认使用本地 ONNX 模型(`Xenova/all-MiniLM-L6-v2`,384 维)—— 无需 API 密钥,数据不离开你的机器,而且默认的 FTS5 召回根本不需要它。若要改用托管或本地服务器的嵌入器:
+默认情况下 MeMesh 只做**关键词**召回(FTS5)—— 无需 API 密钥,无需下载模型,数据不离开你的机器。语义(基于含义的)搜索是可选的,需要一个嵌入器。配置其中之一:
 
 ```bash
 memesh config set embedder.provider openai          # or: ollama
 memesh config set embedder.model text-embedding-3-small
 ```
 
-嵌入器**独立于对话 LLM** 配置 —— 更改 `llm.provider` 绝不会悄悄改变你的嵌入。如果切换到不同维度(如 384 → 1536),MeMesh 会在下次写入时自动重建向量索引。支持的 `embedder.provider` 取值:`onnx`(默认,本地)、`openai`、`ollama`。
+嵌入器**独立于对话 LLM** 配置 —— 更改 `llm.provider` 绝不会悄悄改变你的嵌入。如果切换到不同维度(如 768 → 1536),MeMesh 会在下次写入时自动重建向量索引。支持的 `embedder.provider` 取值:`ollama`(本地)、`openai`(托管)。两者都不设置时,召回保持关键词搜索。
 
 | | 级别 0（默认） | 级别 1（智能模式） |
 |---|---|---|
-| **搜索** | FTS5 + sqlite-vec，95.60% R@5（每次回忆约 4ms） | 不变 — 回忆在每个级别都是无 LLM 的 |
+| **搜索** | FTS5 + sqlite-vec，95.60% R@5 | 不变 — 回忆在每个级别都是无 LLM 的 |
 | **自动捕获** | 基于规则的模式 | + LLM 提取决策和经验教训 |
 | **自动打标签** | 仅手动标签 | + LLM 为新记忆生成标签 |
 | **失败分析** | 不可用 | + LLM 把会话错误转化为结构化经验教训 |
@@ -383,7 +385,7 @@ memesh config set embedder.model text-embedding-3-small
 
 ---
 
-## 全部 9 个内存工具
+## 全部 7 个内存工具
 
 | 工具 | 它做什么 |
 |------|--------|
@@ -394,7 +396,6 @@ memesh config set embedder.model text-embedding-3-small
 | `import` | 导入内存，支持合并策略（跳过 / 覆盖 / 追加） |
 | `learn` | 从错误中记录结构化经验教训（错误、根本原因、修复、预防） |
 | `user_patterns` | 分析你的工作模式——日程、工具、优势、学习领域 |
-| `verify_agent_work` | 为后台代理工作保存验证报告；对照 `git diff` 验证声称的文件改动 |
 
 ---
 
@@ -403,7 +404,7 @@ memesh config set embedder.model text-embedding-3-small
 ```
                     ┌─────────────────┐
                     │   Core Engine   │
-                    │  (8 operations) │
+                    │  (7 operations) │
                     └────────┬────────┘
            ┌─────────────────┼─────────────────┐
            │                 │                 │

package/README.zh-TW.md

@@ -117,7 +117,7 @@ npm install -g @pcircle/memesh
 /plugin install memesh@pcircle-memesh
 ```
 
-Claude Code 會自動接好 hooks、skills 和 MCP server。你會獲得對話內自動擷取、主動回憶、可在 Claude Code 對話中使用的 `/memesh` skill（remember / recall / learn / forget），以及代理可呼叫的 `remember` / `recall` / `forget` / `learn` MCP 工具。CLI 與本地儀表板無需任何額外的全域安裝就能完整使用 — `npx @pcircle/memesh <command>` 可執行所有 CLI 指令，`npx @pcircle/memesh` 可在 `localhost:3737` 啟動儀表板。MCP server 直接從外掛內建的編譯產物啟動 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地建置步驟。如果 `better-sqlite3` 原生 binding 在第一次啟動時缺少（例如 Node 主版本升級後），啟動器會在程序內自動重新編譯後繼續執行。
+Claude Code 會自動接好 hooks、skills 和 MCP server。你會獲得對話內自動擷取、主動回憶、可在 Claude Code 對話中使用的 `/memesh` skill（remember / recall / learn / forget），以及代理可呼叫的 `remember` / `recall` / `forget` / `learn` MCP 工具。CLI 與本地儀表板無需任何額外的全域安裝就能完整使用 — `npx @pcircle/memesh <command>` 可執行所有 CLI 指令，`npx @pcircle/memesh` 可在 `localhost:3737` 啟動儀表板。MCP server 直接從外掛內建的編譯產物啟動 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地建置步驟。memesh 透過 Node 內建的 `node:sqlite`（22.13+）存放資料，所以升級 Node 不會留下一個為錯誤 runtime 編譯的二進位檔。
 
 ### 選項 B — npm 全域安裝（可選最佳化）
 
@@ -128,8 +128,8 @@ npm install -g @pcircle/memesh
 ```
 
 > **首次安裝注意事項（一次性）：**
-> - **原生模組** — `better-sqlite3` 與 `sqlite-vec` 在 macOS（arm64/x64）、Linux（x64/arm64）和 Windows x64 上會以預先編譯的二進位安裝。在較少見的平台或預編譯失敗時，你需要可運作的 C/C++ 工具鏈。
-> - **嵌入模型** — 第一次觸發本地嵌入的呼叫（例如 semantic 模式的 `recall`）會把 `Xenova/all-MiniLM-L6-v2`（約 80 MB）下載到 `~/.memesh/models/`。後續呼叫即時生效。預設的檢索路徑（FTS5）不需要這個下載。
+> - **不需要編譯器** — 資料庫引擎就是 Node 自己的 `node:sqlite`。負責「用意思搜尋」的 `sqlite-vec` 以預先編譯好的檔案形式提供 macOS（arm64/x64）、Linux（x64/arm64）和 Windows x64；在其他平台它就是不存在，回憶維持關鍵字搜尋。這裡沒有任何東西會執行安裝腳本，所以 `npm install --ignore-scripts` 也能裝出完全可用的 memesh。
+> - **語意搜尋是選用的** — 預設的檢索路徑是關鍵字搜尋（FTS5），不需要模型也不需要下載。以語意（意義）為基礎的搜尋需要一個 embedder：在本地執行 [Ollama](https://ollama.com)，或設定一個雲端 embedder（見下方「嵌入」）。沒有設定時，memesh 只使用關鍵字搜尋。
 
 ### 第一步半：把 MeMesh 接進 Claude Code（僅 npm 路徑需要）
 
@@ -261,13 +261,12 @@ memesh export-schema \
 
 ## Claude Code 自動進行的事情
 
-你不需要手動記住所有事情。MeMesh 有 **7 個 hooks**，會在你工作時自動擷取與注入知識：
+你不需要手動記住所有事情。MeMesh 有 **6 個 hooks**，會在你工作時自動擷取與注入知識：
 
 | 何時 | MeMesh 做什麼 |
 |------|------------------|
 | **每次 session 開始時** | 載入最相關的記憶 + 來自過去教訓的主動警告 |
 | **編輯檔案前** | 回憶與檔案或專案相關的記憶，再讓 Claude 寫程式碼 |
-| **執行 bash 指令前** | （可選加入）促使 Claude 將高可驗證性指令（測試、建置、檢查、遷移、部署、基準測試）派遣為背景代理 |
 | **當你要求記住** | 偵測「remember this」／「guardar en memesh」／「sauvegarder dans memesh」／「記下來」意圖（5 種語言）並提醒 Claude 使用 memesh |
 | **每次 `git commit` 之後** | 記錄你的變更，包含 diff 統計 |
 | **Claude 停止時** | 擷取已編輯的檔案、已修復的錯誤，並從失敗自動產生結構化教訓 |
@@ -285,14 +284,15 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | 覆寫 SQLite 資料庫位置。 |
 | `MEMESH_AUTO_CAPTURE` | `true` | 完全停用自動擷取 hooks（`Stop`、`PreCompact`）。 |
-| `MEMESH_AUTO_DETECT_LLM` | 未設定（自動偵測**開啟**） | 設為 `0` 讓 memesh 不使用它在 shell 環境中找到的 API 金鑰。預設情況下，如果設定了 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` 且你沒有在 `~/.memesh/config.json` 設定供應商，memesh 會用它來跑寫入側的 LLM 功能（整合、經驗提取、自動打標籤、dream）。嵌入不受影響 —— 除非你明確設定 `embedder.provider`，否則保持本地 ONNX（384 維）。 |
-| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | 未設定 | 設為 `1` 啟用實驗性的工作模型協定（CTO／Orchestrator／Agents 框架）。會加上 session-start 橫幅、Bash 指令提示，以及 `verify_agent_work` 遙測。協定的有效性正在量測中、尚未獲得驗證 — 想參與時才加入。**預設關閉**：核心記憶功能不需要這個旗標就能運作。 |
+| `MEMESH_AUTO_DETECT_LLM` | 未設定（自動偵測**開啟**） | 設為 `0` 讓 memesh 不使用它在 shell 環境中找到的 API 金鑰。預設情況下，如果設定了 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` 且你沒有在 `~/.memesh/config.json` 設定供應商，memesh 會用它來跑寫入側的 LLM 功能（整合、經驗提取、自動打標籤、dream）。嵌入不受影響 —— 除非你把 `embedder.provider` 明確設定為 `ollama` 或 `openai`，否則保持僅關鍵字（FTS5）。 |
 | `MEMESH_AUTO_UPDATE` | `off` | 自動更新策略。`off`（預設）永不自動更新；`patch` 允許 `X.Y.Z → X.Y.Z+N`；`minor` 加上 `X.Y.Z → X.Y+1.0`；`major` 允許任何升級。允許時，分離的 `npm install -g` 會在 session 結束時（Stop hook）執行，避免阻塞你的工作 — 結果寫入 `~/.memesh/auto-update.log`。也可在 `~/.memesh/config.json` 中以 `autoUpdate` 設定（環境變數優先）。當已安裝版本被維護者標為 deprecated（安全公告）時，即使是 `off` 也會強制允許 `patch` — 仍維持 minor／major 升級的手動門檻，避免靜默行為偏移。 |
 | `OPENAI_API_KEY` | 未設定 | 你的 OpenAI 金鑰。除非你設定 `MEMESH_AUTO_DETECT_LLM=0` 或明確設定供應商，否則會自動用於 LLM 功能。 |
 | `OLLAMA_HOST` | `http://localhost:11434` | 使用本地 Ollama 供應商時覆寫 Ollama 的端點。 |
 
 `memesh doctor` 會印出已解析的設定，讓你看到目前實際生效的內容。
 
+**備援 LLM 供應商（Smart Mode）。** 在 dashboard 的 **Settings → 「Fallback providers」** 可以設定一條有順序的備援鏈——當你的主要供應商掛掉時，memesh 會依序改用清單裡的下一個。可以加本機的 [Ollama](https://ollama.com) 備援，或雲端的（OpenAI / Anthropic，需要 API key）。隱私取捨：一旦用到雲端備援，記憶內容（可能是私密的）會被送到那個供應商，所以如果你為了隱私只跑本機，這點要留意。
+
 當 npm 將已安裝版本標為 deprecated（通常是安全公告），下次 session-start 會在前面附上強警示橫幅 `⚠️ MeMesh <ver> is DEPRECATED`，`memesh update-status` 也會持續顯示同一行直到你升級為止。檢查結果會被快取於 `~/.memesh/update-check.<version>.json`，以避免短暫網路失敗讓警示變淡。
 
 ---
@@ -361,20 +361,22 @@ memesh config set llm.api-key sk-ant-...
 memesh serve  # 開啟儀表板 → Settings 分頁
 ```
 
+**把過去的對話挖成記憶。** `memesh dream run --from-transcripts` 會讀這個專案的 Claude Code 對話記錄，請 LLM 找出藏在對話裡的決策與教訓，再把它們暫存成提案——不會自動寫進你的知識圖譜。用 `memesh dream show <id>` 逐一檢視，挑值得留的 accept。
+
 ### 自帶嵌入(可選)
 
-嵌入預設使用本地 ONNX 模型(`Xenova/all-MiniLM-L6-v2`,384 維)—— 無需 API 金鑰,資料不離開你的機器,而且預設的 FTS5 召回根本不需要它。若要改用託管或本地伺服器的嵌入器:
+預設情況下 MeMesh 只做**關鍵字**召回(FTS5)—— 無需 API 金鑰,無需下載模型,資料不離開你的機器。語意(以意義為基礎的)搜尋是選用的,需要一個嵌入器。設定其中之一:
 
 ```bash
 memesh config set embedder.provider openai          # or: ollama
 memesh config set embedder.model text-embedding-3-small
 ```
 
-嵌入器**獨立於對話 LLM** 設定 —— 更改 `llm.provider` 絕不會悄悄改變你的嵌入。如果切換到不同維度(如 384 → 1536),MeMesh 會在下次寫入時自動重建向量索引。支援的 `embedder.provider` 取值:`onnx`(預設,本地)、`openai`、`ollama`。
+嵌入器**獨立於對話 LLM** 設定 —— 更改 `llm.provider` 絕不會悄悄改變你的嵌入。如果切換到不同維度(如 768 → 1536),MeMesh 會在下次寫入時自動重建向量索引。支援的 `embedder.provider` 取值:`ollama`(本地)、`openai`(託管)。兩者都不設定時,召回保持關鍵字搜尋。
 
 | | 等級 0（預設） | 等級 1（智慧模式） |
 |---|---|---|
-| **搜尋** | FTS5 + sqlite-vec，95.60% R@5（每次回憶約 4ms） | 不變 — 回憶在每個等級都保持 LLM-free |
+| **搜尋** | FTS5 + sqlite-vec，95.60% R@5 | 不變 — 回憶在每個等級都保持 LLM-free |
 | **自動擷取** | 基於規則的模式 | + LLM 擷取決策與教訓 |
 | **自動標籤** | 僅手動標籤 | + LLM 為新記憶產生標籤 |
 | **失敗分析** | 不可用 | + LLM 將 session 錯誤轉為結構化教訓 |
@@ -383,7 +385,7 @@ memesh config set embedder.model text-embedding-3-small
 
 ---
 
-## 全部 9 個記憶工具
+## 全部 7 個記憶工具
 
 | 工具 | 做什麼 |
 |------|--------|
@@ -394,7 +396,6 @@ memesh config set embedder.model text-embedding-3-small
 | `import` | 匯入記憶，包含合併策略（跳過 / 覆寫 / 追加） |
 | `learn` | 記錄來自錯誤的結構化教訓（錯誤、根本原因、修復、預防） |
 | `user_patterns` | 分析你的工作模式——時間表、工具、優勢、學習領域 |
-| `verify_agent_work` | 保留背景代理工作的驗證報告；以 `git diff` 對所聲稱的檔案變更做現實檢查 |
 
 ---
 
@@ -403,7 +404,7 @@ memesh config set embedder.model text-embedding-3-small
 ```
                     ┌─────────────────┐
                     │   核心引擎      │
-                    │  （8 項操作）  │
+                    │  （7 項操作）  │
                     └────────┬────────┘
            ┌─────────────────┼─────────────────┐
            │                 │                 │