@pcircle/memesh 4.2.6 → 4.2.8

package/README.vi.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Dự án đang phát triển tích cực** — tính năng cập nhật liên tục và có thể thay đổi giữa các bản phát hành. Nếu gặp lỗi hoặc có yêu cầu tính năng, vui lòng [mở issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Vấn đề
 
 Agent coding của bạn quên mất những gì đã xảy ra giữa các phiên làm việc. Mỗi quyết định kiến trúc, bug fix, test thất bại và bài học từng trải phải được giải thích lại từ đầu. Claude Code luôn bắt đầu từ trang trắng, phát hiện lại những ràng buộc cũ, và lãng phí context cho những thứ nó đã nên biết.
@@ -42,6 +45,67 @@ Lệnh tái hiện, SHA256 của dataset, kết quả thô theo từng câu hỏ
 
 ---
 
+## Tổng quan các đường cài đặt
+
+MeMesh có **hai đường cài đặt cùng tồn tại**. Hầu hết người dùng muốn cả hai. Chúng ghi vào **cùng một cơ sở dữ liệu bộ nhớ** (`~/.memesh/knowledge-graph.db`), nên ký ức ghi trong chat Claude Code sẽ xuất hiện ở shell, và ngược lại.
+
+```mermaid
+flowchart TB
+    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+    subgraph clients["Where you use memesh from"]
+      direction LR
+      CC["Claude Code<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
+
+    CC -->|uses| A
+    TERM -->|uses| B
+    A --> DB
+    B --> DB
+```
+
+**Bạn cần đường nào?**
+
+| Bạn muốn làm gì | Đường cài đặt |
+|---|---|
+| Dùng skill `/memesh` trong cuộc trò chuyện Claude Code | Path A (plugin) |
+| Tự động capture trong Claude Code (session → bài học → recall lần sau) | Path A (plugin) |
+| Chạy `memesh remember` / `memesh recall` / `memesh doctor` ở bất kỳ terminal nào | Path B (npm-global) |
+| Mở dashboard qua `memesh` (không bị trễ khởi động `npx`) | Path B (npm-global) |
+| Cắm `memesh-mcp` vào Cursor, Cline hoặc client MCP khác | Path B (npm-global) |
+| Tất cả các mục trên | **Cài cả hai** — không xung đột |
+
+> **Nhầm lẫn phổ biến**: plugin Claude Code **không** đặt `memesh` lên `PATH` của shell. Nếu bạn chỉ chạy `/plugin install` rồi gõ `memesh reindex` trong terminal, bạn sẽ thấy `command not found`. Đó là điều bình thường — thêm `npm install -g @pcircle/memesh` để có lệnh shell.
+
+### ⚠️ Cài plugin KHÔNG cài CLI
+
+Đây là nhầm lẫn phổ biến nhất. Đọc một lần để tiết kiệm thời gian sau này:
+
+- `/plugin install memesh@pcircle-memesh` từ Claude Code → chỉ cài **Path A**. Bạn có công cụ MCP, hooks, skill `/memesh`. **KHÔNG** đặt `memesh` lên `PATH` shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` gõ trong terminal → cần **Path B** (npm-global). Không có nó: `zsh: command not found: memesh`.
+- **Thiết lập khuyến nghị cho người dùng Claude Code**: **cài cả hai**. Cùng tồn tại, chia sẻ cùng DB, không xung đột.
+
+```bash
+# Sau khi /plugin install ..., chạy luôn dòng này:
+npm install -g @pcircle/memesh
+```
+
+Nếu bạn chỉ dùng memesh qua chat Claude Code (không bao giờ gõ `memesh` trong terminal), Path A đủ rồi. Còn lại: cài cả hai.
+
+---
+
 ## Bắt đầu trong 60 giây
 
 ### Bước 1: Cài đặt
@@ -194,10 +258,10 @@ 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 thành `1` để memesh tự động phát hiện provider từ shell env (`OPENAI_API_KEY` v.v.) và chuyển sang BYOK embeddings. **Cài đặt mới mặc định chỉ dùng ONNX cục bộ (384-dim)** — opt in nếu bạn muốn cloud embeddings. Khi flag này không được đặt, một `OPENAI_API_KEY` còn sót trong shell sẽ bị bỏ qua. |
+| `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_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. Chỉ được dùng khi `MEMESH_AUTO_DETECT_LLM=1` hoặc bạn cấu hình provider tường minh. |
+| `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.
@@ -268,6 +332,17 @@ Hoặc dùng dashboard Settings tab (visual setup):
 memesh  # mở dashboard → Settings tab
 ```
 
+### 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ộ:
+
+```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`.
+
 | | Level 0 (default) | Level 1 (Smart Mode) |
 |---|---|---|
 | **Search** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms/query) | giữ nguyên — recall luôn LLM-free ở mọi level |
@@ -316,6 +391,35 @@ Core là framework-agnostic. Logic tương tự chạy từ terminal, HTTP, ho
 
 ---
 
+## Nâng cấp
+
+Plugin marketplace của Claude Code ghim phiên bản lúc cài đặt và **không** tự động cập nhật. Để lấy bản phát hành mới:
+
+**Tùy chọn A — Giao diện `/plugin`**: gỡ cài `memesh@pcircle-memesh`, rồi cài lại. Claude Code sẽ kéo phiên bản mới nhất từ marketplace.
+
+**Tùy chọn B — Script một dòng** (không cần click UI, idempotent):
+
+```bash
+# Nếu bản plugin đã cài là v4.2.5 trở lên, script đã có sẵn:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Nếu bạn cài trước v4.2.5 (tức là v4.2.4 hoặc v4.2.3),
+# script chưa nằm trong plugin của bạn. Dùng bản sao npm-global thay thế:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Giả định bạn cũng đã chạy `npm install -g @pcircle/memesh`. Nếu chưa, đây là
+# thời điểm tốt để cài — xem phần "Tổng quan các đường cài đặt" ở trên để hiểu
+# vì sao đa số người dùng muốn có cả hai đường.)
+```
+
+Script sẽ fast-forward marketplace cache, đặt phiên bản mới vào `~/.claude/plugins/cache/`, cài runtime deps, rồi trỏ lại `installed_plugins.json`. Khởi động lại Claude Code sau đó để MCP server kết nối lại.
+
+**Bản cài npm-global** (`npm install -g @pcircle/memesh`) có thể tự cập nhật qua `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+Khi bắt đầu session, banner một dòng (throttle mỗi 24h mỗi version) hiện ra khi có bản phát hành mới, và `memesh doctor` báo cáo phiên bản nâng cấp với lệnh tương ứng kênh cài đặt.
+
+---
+
 ## Đóng góp
 
 ```bash

package/README.zh-CN.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **持续开发中的项目** — 功能会持续更新，版本之间可能会有变动。遇到问题或想要新功能，请[开 issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+
 ## 问题
 
 编码代理在会话间会遗忘。每个架构决策、每次 bug 修复、失败的测试用例、每一次来之不易的经验教训都需要重新解释一遍。Claude Code 每次都从零开始，重新发现老约束，浪费上下文在早该掌握的东西上。
@@ -42,6 +45,67 @@ MeMesh 的检索引擎**只用 FTS5**（热路径上没有 LLM、也没有 embed
 
 ---
 
+## 安装路径一览
+
+MeMesh 有**两条共存的安装路径**。多数用户两条都需要。它们写入**同一份记忆数据库**（`~/.memesh/knowledge-graph.db`），所以 Claude Code 对话里记下的东西在 terminal 也看得到，反之亦然。
+
+```mermaid
+flowchart TB
+    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+    subgraph clients["Where you use memesh from"]
+      direction LR
+      CC["Claude Code<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
+
+    CC -->|uses| A
+    TERM -->|uses| B
+    A --> DB
+    B --> DB
+```
+
+**你需要哪条？**
+
+| 你想做什么 | 安装路径 |
+|---|---|
+| 在 Claude Code 对话里用 `/memesh` skill | Path A（plugin）|
+| 在 Claude Code 启用自动 capture（session → 教训 → 下次 recall） | Path A（plugin）|
+| 在任何 terminal 跑 `memesh remember` / `memesh recall` / `memesh doctor` | Path B（npm-global）|
+| 用 `memesh` 直接开 dashboard（没有 `npx` 启动延迟） | Path B（npm-global）|
+| 把 `memesh-mcp` 接到 Cursor、Cline 或其他 MCP client | Path B（npm-global）|
+| 以上全要 | **两条都装** — 不会冲突 |
+
+> **常见误会**：Claude Code 的 plugin **不会** 把 `memesh` 放到你的 shell `PATH` 上。如果你只跑 `/plugin install`，然后在 terminal 打 `memesh reindex`，你会看到 `command not found`。这是正常的 — 还要加 `npm install -g @pcircle/memesh` 才有 shell 命令。
+
+### ⚠️ 装 plugin 不会装 CLI
+
+这是最常见的踩坑点，读一次省下未来的循环：
+
+- 从 Claude Code 跑 `/plugin install memesh@pcircle-memesh` → 只装 **Path A**。给你 MCP 工具、hooks、`/memesh` skill。**不会**把 `memesh` 放到你的 shell `PATH`。
+- 在 terminal 打 `memesh reindex` / `memesh update` / `memesh doctor` → 需要 **Path B**（npm-global）。没装就会 `zsh: command not found: memesh`。
+- **Claude Code 使用者建议的安装方式**：**两条都装**。共存、共用同一份数据库、不冲突。
+
+```bash
+# 跑完 /plugin install ... 之后，再跑这个：
+npm install -g @pcircle/memesh
+```
+
+如果你只透过 Claude Code 对话用 memesh（从不在 terminal 打 `memesh`），Path A 自己就够了。其他人请两条都装。
+
+---
+
 ## 60 秒快速开始
 
 ### 选项 A — Claude Code 插件（一行安装）
@@ -221,10 +285,10 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | 覆盖 SQLite 数据库位置。 |
 | `MEMESH_AUTO_CAPTURE` | `true` | 完全禁用自动捕获 hooks（`Stop`、`PreCompact`）。 |
-| `MEMESH_AUTO_DETECT_LLM` | 未设置 | 设为 `1` 让 memesh 从 shell 环境（`OPENAI_API_KEY` 等）自动检测提供商并切换到 BYOK embeddings。**全新安装的默认值是仅本地 ONNX（384 维）** — 想用云端 embeddings 时再开启。未设置此 flag 时，shell 中残留的 `OPENAI_API_KEY` 会被忽略。 |
+| `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_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=1` 或你显式配置提供商时使用。 |
+| `OPENAI_API_KEY` | 未设置 | 你的 OpenAI 密钥。除非你设置 `MEMESH_AUTO_DETECT_LLM=0` 或显式配置提供商，否则会自动用于 LLM 功能。 |
 | `OLLAMA_HOST` | `http://localhost:11434` | 使用本地 Ollama 提供商时覆盖 Ollama 端点。 |
 
 `memesh doctor` 会打印解析后的配置，你可以看到当前生效的内容。
@@ -295,6 +359,17 @@ memesh config set llm.api-key sk-ant-...
 memesh  # 打开仪表板 → 设置标签页
 ```
 
+### 自带嵌入(可选)
+
+嵌入默认使用本地 ONNX 模型(`Xenova/all-MiniLM-L6-v2`,384 维)—— 无需 API 密钥,数据不离开你的机器,而且默认的 FTS5 召回根本不需要它。若要改用托管或本地服务器的嵌入器:
+
+```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`。
+
 | | 级别 0（默认） | 级别 1（智能模式） |
 |---|---|---|
 | **搜索** | FTS5 + sqlite-vec，95.40% R@5（每次查询 ~18ms） | 不变 — 回忆在每个级别都是无 LLM 的 |
@@ -343,6 +418,34 @@ memesh  # 打开仪表板 → 设置标签页
 
 ---
 
+## 升级
+
+Claude Code 的 plugin marketplace 在安装时把版本钉住，**不会**自动更新。要拿到新版本：
+
+**方法 A — `/plugin` 界面**：先卸载 `memesh@pcircle-memesh`，再重新安装。Claude Code 会抓取 marketplace 最新版。
+
+**方法 B — 一行命令**（无需点击 UI、幂等）：
+
+```bash
+# 如果 plugin 已经是 v4.2.5 或更新，脚本已内置：
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# 如果是 v4.2.5 之前的版本（即 v4.2.4 或 v4.2.3），
+# 脚本还没在你的 plugin 里，改用 npm-global 的副本：
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# （这假设你也运行过 `npm install -g @pcircle/memesh`。如果还没，
+# 现在正好可以一起装 — 参考上面「安装路径一览」了解为什么大多数人两条路径都装。）
+```
+
+脚本会 fast-forward marketplace cache、把新版本放入 `~/.claude/plugins/cache/`、安装 runtime deps，然后把 `installed_plugins.json` 重指向新版本。完成后请重启 Claude Code 让 MCP server 重连。
+
+**npm-global 安装**（`npm install -g @pcircle/memesh`）可以直接通过 `memesh update` 自动更新。Source checkouts：`git pull && npm install && npm run build`。
+
+Session 开始时，若有新版本可下载，会显示一行 banner（每版本每 24 小时节流一次），`memesh doctor` 会报告升级目标版本与对应命令。
+
+---
+
 ## 贡献
 
 ```bash

package/README.zh-TW.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **持續開發中的專案** — 功能會持續更新，版本之間可能會有變動。遇到問題或想要新功能，請[開 issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+
 ## 問題所在
 
 你的程式開發代理在每次對話之間就會忘記一切。每個架構決策、每個修復的臭蟲、每個失敗的測試、每個代價不菲的教訓，都得重新跟它解釋一遍。Claude Code 每次都從零開始，重新發現舊的限制條件，浪費寶貴的上下文在它本應已知的事情上。
@@ -42,6 +45,67 @@ MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌
 
 ---
 
+## 安裝路徑一覽
+
+MeMesh 有**兩條會共存的安裝路徑**。多數使用者兩條都需要。它們寫入**同一份記憶資料庫**（`~/.memesh/knowledge-graph.db`），所以 Claude Code 對話裡記下的東西在 terminal 也看得到，反之亦然。
+
+```mermaid
+flowchart TB
+    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+    subgraph clients["Where you use memesh from"]
+      direction LR
+      CC["Claude Code<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
+
+    CC -->|uses| A
+    TERM -->|uses| B
+    A --> DB
+    B --> DB
+```
+
+**你需要哪一條？**
+
+| 你想做什麼 | 安裝路徑 |
+|---|---|
+| 在 Claude Code 對話裡用 `/memesh` skill | Path A（plugin）|
+| 在 Claude Code 自動 capture（session → 教訓 → 下次 recall）| Path A（plugin）|
+| 在任何 terminal 跑 `memesh remember` / `memesh recall` / `memesh doctor` | Path B（npm-global）|
+| 用 `memesh` 直接開 dashboard（沒有 `npx` 啟動延遲）| Path B（npm-global）|
+| 把 `memesh-mcp` 接到 Cursor、Cline 或其他 MCP client | Path B（npm-global）|
+| 以上都要 | **兩條都裝** — 不會衝突 |
+
+> **常見誤會（小心踩雷）**：Claude Code 的 plugin **不會** 把 `memesh` 放到你的 shell `PATH` 上。如果你只跑 `/plugin install`，然後在 terminal 打 `memesh reindex`，你會看到 `command not found`。這是正常的 — 還要加 `npm install -g @pcircle/memesh` 才有 shell 指令。
+
+### ⚠️ 裝 plugin 不會裝 CLI
+
+這個是最常見的踩坑點，讀一次省下未來的循環：
+
+- 從 Claude Code 跑 `/plugin install memesh@pcircle-memesh` → 只裝 **Path A**。給你 MCP 工具、hooks、`/memesh` skill。**不會**把 `memesh` 放到你的 shell `PATH`。
+- 在 terminal 打 `memesh reindex` / `memesh update` / `memesh doctor` → 需要 **Path B**（npm-global）。沒裝就會 `zsh: command not found: memesh`。
+- **Claude Code 使用者建議的安裝方式**：**兩條都裝**。共存、共用同一份資料庫、不衝突。
+
+```bash
+# 跑完 /plugin install ... 之後，再跑這個：
+npm install -g @pcircle/memesh
+```
+
+如果你只透過 Claude Code 對話用 memesh（從不在 terminal 打 `memesh`），Path A 自己就夠了。其他人請兩條都裝。
+
+---
+
 ## 60 秒快速開始
 
 ### 選項 A — Claude Code 外掛（一行安裝）
@@ -221,10 +285,10 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | 覆寫 SQLite 資料庫位置。 |
 | `MEMESH_AUTO_CAPTURE` | `true` | 完全停用自動擷取 hooks（`Stop`、`PreCompact`）。 |
-| `MEMESH_AUTO_DETECT_LLM` | 未設定 | 設為 `1` 讓 memesh 從你的 shell 環境（`OPENAI_API_KEY` 等）自動偵測供應商，並切換到 BYOK 嵌入。**全新安裝的預設僅使用本地 ONNX（384-dim）** — 想要雲端嵌入時才加入。沒設定這個旗標時，shell 中閒置的 `OPENAI_API_KEY` 會被忽略。 |
+| `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_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=1` 或你明確設定供應商時才使用。 |
+| `OPENAI_API_KEY` | 未設定 | 你的 OpenAI 金鑰。除非你設定 `MEMESH_AUTO_DETECT_LLM=0` 或明確設定供應商，否則會自動用於 LLM 功能。 |
 | `OLLAMA_HOST` | `http://localhost:11434` | 使用本地 Ollama 供應商時覆寫 Ollama 的端點。 |
 
 `memesh doctor` 會印出已解析的設定，讓你看到目前實際生效的內容。
@@ -295,6 +359,17 @@ memesh config set llm.api-key sk-ant-...
 memesh  # 開啟儀表板 → Settings 分頁
 ```
 
+### 自帶嵌入(可選)
+
+嵌入預設使用本地 ONNX 模型(`Xenova/all-MiniLM-L6-v2`,384 維)—— 無需 API 金鑰,資料不離開你的機器,而且預設的 FTS5 召回根本不需要它。若要改用託管或本地伺服器的嵌入器:
+
+```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`。
+
 | | 等級 0（預設） | 等級 1（智慧模式） |
 |---|---|---|
 | **搜尋** | FTS5 + sqlite-vec，95.40% R@5（約 18ms/查詢） | 不變 — 回憶在每個等級都保持 LLM-free |
@@ -343,6 +418,34 @@ memesh  # 開啟儀表板 → Settings 分頁
 
 ---
 
+## 升級
+
+Claude Code 的 plugin marketplace 在安裝時把版本釘住，**不會**自動更新。要拿到新版本：
+
+**方法 A — `/plugin` 介面**：先 uninstall `memesh@pcircle-memesh`，再重新安裝。Claude Code 會抓 marketplace 最新版。
+
+**方法 B — 一行指令**（不用點 UI、可重複執行）：
+
+```bash
+# 如果 plugin 已經是 v4.2.5 或更新，腳本已經內建：
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# 如果是 v4.2.5 之前的版本（也就是 v4.2.4 或 v4.2.3），
+# 腳本還沒在你的 plugin 裡，改用 npm-global 的副本：
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# （這假設你也跑過 `npm install -g @pcircle/memesh`。如果還沒，
+# 現在正好可以一起裝 — 參考上面「安裝路徑一覽」說明為什麼大部分人兩條路徑都裝。）
+```
+
+腳本會 fast-forward marketplace cache、把新版本放進 `~/.claude/plugins/cache/`、安裝 runtime deps，然後把 `installed_plugins.json` 重指向新版本。執行完請重啟 Claude Code 讓 MCP server 重連。
+
+**npm-global 安裝**（`npm install -g @pcircle/memesh`）可以直接 `memesh update` 自動更新。Source checkouts：`git pull && npm install && npm run build`。
+
+Session 開始時，有新版本可下載時會跳一行 banner（每版本每 24 小時節流一次），`memesh doctor` 會回報升級目標版本與對應指令。
+
+---
+
 ## 貢獻
 
 ```bash