@pcircle/memesh 4.4.0 → 4.5.0

package/README.th.md

@@ -142,6 +142,12 @@ Hooks เหล่านี้อยู่ร่วมกับ custom hooks ท
 
 ### ขั้นตอนที่ 2: เก็บการตัดสินใจ
 
+```bash
+memesh remember "Use OAuth 2.0 with PKCE for the new auth"
+```
+
+หรือใช้รูปแบบชัดเจนเมื่อต้องการชื่อและชนิดที่คงที่สำหรับกรองภายหลัง:
+
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
@@ -273,7 +279,7 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | เปลี่ยนตำแหน่งฐานข้อมูล SQLite |
 | `MEMESH_AUTO_CAPTURE` | `true` | ปิดการใช้ hook จับข้อมูลอัตโนมัติทั้งหมด (`Stop`, `PreCompact`) |
-| `MEMESH_AUTO_DETECT_LLM` | ไม่ได้ตั้งค่า (ตรวจจับอัตโนมัติ **เปิด**) | ตั้งเป็น `0` เพื่อไม่ให้ memesh ใช้คีย์ API ที่พบในสภาพแวดล้อมของเชลล์ โดยค่าเริ่มต้น หากตั้ง `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` ไว้ และคุณยังไม่ได้กำหนดผู้ให้บริการใน `~/.memesh/config.json` memesh จะใช้คีย์นั้นสำหรับฟีเจอร์ LLM ฝั่งเขียน (การสกัดบทเรียน, auto-tagging, dream) ส่วน embeddings ไม่ได้รับผลกระทบ — ยังคงเป็น ONNX ในเครื่อง (384 มิติ) เว้นแต่คุณจะตั้ง `embedder.provider` อย่างชัดเจน |
+| `MEMESH_AUTO_DETECT_LLM` | ไม่ได้ตั้งค่า (ตรวจจับอัตโนมัติ **เปิด**) | ตั้งเป็น `0` เพื่อไม่ให้ memesh ใช้คีย์ API ที่พบในสภาพแวดล้อมของเชลล์ โดยค่าเริ่มต้น หากตั้ง `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` ไว้ และคุณยังไม่ได้กำหนดผู้ให้บริการใน `~/.memesh/config.json` memesh จะใช้คีย์นั้นสำหรับฟีเจอร์ LLM ฝั่งเขียน (การสกัดบทเรียน, auto-tagging, dream) ส่วน embeddings ไม่ได้รับผลกระทบ — ยังคงเป็นการค้นหาด้วยคีย์เวิร์ดอย่างเดียว (FTS5) เว้นแต่คุณจะตั้ง `embedder.provider` เป็น `ollama` หรือ `openai` |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | ไม่ตั้ง | ตั้งเป็น `1` เพื่อเปิดใช้โปรโตคอล working-model เชิงทดลอง (กรอบ CTO / Orchestrator / Agents) เพิ่มแบนเนอร์ตอนเริ่มเซสชัน การเตือนคำสั่ง Bash และเทเลเมตรี `verify_agent_work` ประสิทธิผลของโปรโตคอลกำลังถูกเก็บข้อมูล ยังไม่ได้พิสูจน์ — opt-in ถ้าต้องการเข้าร่วม **ค่าเริ่มต้นปิด**: ฟีเจอร์หน่วยความจำหลักทำงานได้โดยไม่ต้องเปิดธงนี้ |
 | `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` แบบ detached จะทำงานเมื่อจบเซสชัน (Stop hook) เพื่อไม่บล็อกงานของคุณ — ผลลัพธ์ลงใน `~/.memesh/auto-update.log` ตั้งใน `~/.memesh/config.json` ผ่านคีย์ `autoUpdate` ก็ได้ (env ชนะ) เมื่อเวอร์ชันที่ติดตั้งถูก deprecate (security advisory) `patch` จะถูกบังคับเปิดแม้ตั้งเป็น `off` — minor / major ยังต้องทำมือเพื่อหลีกเลี่ยงการเปลี่ยนพฤติกรรมเงียบ ๆ |
 | `OPENAI_API_KEY` | ไม่ได้ตั้งค่า | คีย์ OpenAI ของคุณ ใช้โดยอัตโนมัติสำหรับฟีเจอร์ LLM เว้นแต่คุณจะตั้ง `MEMESH_AUTO_DETECT_LLM=0` หรือกำหนดผู้ให้บริการอย่างชัดเจน |
@@ -281,6 +287,8 @@ memesh export-schema \
 
 `memesh doctor` พิมพ์การตั้งค่าที่ resolve แล้วเพื่อให้คุณเห็นว่าอะไรทำงานอยู่
 
+**ผู้ให้บริการ LLM สำรอง (Smart Mode)** ใน **Settings → “Fallback providers”** ของ dashboard คุณตั้งลูกโซ่ failover ตามลำดับได้ — เมื่อผู้ให้บริการหลักล่ม memesh จะลองตัวถัดไปในรายการตามลำดับ เพิ่มตัวสำรองแบบโลคัล [Ollama](https://ollama.com) หรือแบบคลาวด์ (OpenAI / Anthropic ต้องมี API key) ก็ได้ ข้อแลกเปลี่ยนด้านความเป็นส่วนตัว: เมื่อใช้ตัวสำรองแบบคลาวด์ ข้อความในหน่วยความจำ (ซึ่งอาจเป็นข้อมูลส่วนตัว) จะถูกส่งไปยังผู้ให้บริการนั้น จึงสำคัญถ้าคุณรันแบบโลคัลล้วนเพื่อความเป็นส่วนตัว
+
 เมื่อ npm ระบุว่าเวอร์ชันที่ติดตั้งถูก deprecate (โดยทั่วไปคือ security advisory) เซสชันถัดไปจะแสดงแบนเนอร์ `⚠️ MeMesh <ver> is DEPRECATED` แบบหนักนำหน้า และ `memesh update-status` จะแสดงบรรทัดเดียวกันจนกว่าคุณจะอัปเกรด การตรวจสอบถูก cache ที่ `~/.memesh/update-check.<version>.json` เพื่อไม่ให้ความล้มเหลวเครือข่ายชั่วคราวลดความสว่างของคำเตือน
 
 ---
@@ -349,16 +357,18 @@ memesh config set llm.api-key sk-ant-...
 memesh serve  # opens dashboard → Settings tab
 ```
 
+**ขุดเซสชันที่ผ่านมาให้เป็นหน่วยความจำ** `memesh dream run --from-transcripts` จะอ่านบันทึกเซสชัน Claude Code ของโปรเจกต์นี้ ถาม LLM หาการตัดสินใจและบทเรียนที่ซ่อนอยู่ในบทสนทนา แล้วพักไว้เป็นข้อเสนอ — ไม่มีอะไรเข้าสู่กราฟความรู้โดยอัตโนมัติ ตรวจดูทีละรายการด้วย `memesh dream show <id>` แล้ว accept เฉพาะอันที่ควรเก็บ
+
 ### ใช้ embeddings ของคุณเอง (ไม่บังคับ)
 
-โดยค่าเริ่มต้น embeddings ใช้โมเดล ONNX ในเครื่อง (`Xenova/all-MiniLM-L6-v2`, 384 มิติ) — ไม่ต้องใช้คีย์ API ไม่มีข้อมูลออกจากเครื่อง และการ recall แบบ FTS5 เริ่มต้นก็ไม่ต้องใช้เลย หากต้องการใช้ embedder แบบโฮสต์หรือเซิร์ฟเวอร์ในเครื่อง:
+โดยค่าเริ่มต้น MeMesh ทำ recall **ด้วยคีย์เวิร์ดอย่างเดียว** (FTS5) — ไม่ต้องใช้คีย์ API ไม่ต้องดาวน์โหลดโมเดล ไม่มีข้อมูลออกจากเครื่อง การค้นหาเชิงความหมาย (semantic) เป็นตัวเลือกเสริมและต้องใช้ embedder ตั้งค่าอย่างใดอย่างหนึ่ง:
 
 ```bash
 memesh config set embedder.provider openai          # or: ollama
 memesh config set embedder.model text-embedding-3-small
 ```
 
-embedder ถูกตั้งค่า**แยกจาก LLM แชท** — การเปลี่ยน `llm.provider` จะไม่เปลี่ยน embeddings ของคุณอย่างเงียบ ๆ หากเปลี่ยนไปใช้มิติที่ต่างกัน (เช่น 384 → 1536) MeMesh จะสร้างดัชนีเวกเตอร์ใหม่โดยอัตโนมัติในการเขียนครั้งถัดไป ค่า `embedder.provider` ที่รองรับ: `onnx` (ค่าเริ่มต้น ในเครื่อง), `openai`, `ollama`
+embedder ถูกตั้งค่า**แยกจาก LLM แชท** — การเปลี่ยน `llm.provider` จะไม่เปลี่ยน embeddings ของคุณอย่างเงียบ ๆ หากเปลี่ยนไปใช้มิติที่ต่างกัน (เช่น 768 → 1536) MeMesh จะสร้างดัชนีเวกเตอร์ใหม่โดยอัตโนมัติในการเขียนครั้งถัดไป ค่า `embedder.provider` ที่รองรับ: `ollama` (ในเครื่อง), `openai` (โฮสต์) หากไม่ตั้งค่าใดเลย recall จะยังคงเป็นการค้นหาด้วยคีย์เวิร์ด
 
 | | ระดับ 0 (ค่าเริ่มต้น) | ระดับ 1 (Smart Mode) |
 |---|---|---|
@@ -371,7 +381,7 @@ embedder ถูกตั้งค่า**แยกจาก LLM แชท** —
 
 ---
 
-## เครื่องมือหน่วยความจำทั้ง 9 ตัว
+## เครื่องมือหน่วยความจำทั้ง 8 ตัว
 
 | เครื่องมือ | ทำอะไร |
 |---|---|

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"
 ```
@@ -258,7 +277,7 @@ 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_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_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. Đượ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. |
@@ -266,6 +285,8 @@ Toàn bộ cấu hình thông qua biến môi trường. Các giá trị mặc
 
 `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 +355,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 +379,7 @@ Embedder được cấu hình **độc lập với LLM chat** — thay đổi `l
 
 ---
 
-## Cả 9 Memory Tools
+## Cả 8 Memory Tools
 
 | Tool | Nó làm gì |
 |------|-------------|

package/README.zh-CN.md

@@ -129,7 +129,7 @@ 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）不需要这个下载。
+> - **语义搜索是可选的** — 默认检索路径是关键词搜索（FTS5），不需要模型也不需要下载。基于语义的搜索需要一个 embedder：在本地运行 [Ollama](https://ollama.com)，或配置一个云端 embedder（见下方“嵌入”）。没有配置时，memesh 只使用关键词搜索。
 
 ### 第一步半：把 MeMesh 接入 Claude Code（仅 npm 路径）
 
@@ -285,7 +285,7 @@ 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_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_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=0` 或显式配置提供商，否则会自动用于 LLM 功能。 |
@@ -293,6 +293,8 @@ memesh export-schema \
 
 `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 +363,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 +387,7 @@ memesh config set embedder.model text-embedding-3-small
 
 ---
 
-## 全部 9 个内存工具
+## 全部 8 个内存工具
 
 | 工具 | 它做什么 |
 |------|--------|

package/README.zh-TW.md

@@ -129,7 +129,7 @@ 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）不需要這個下載。
+> - **語意搜尋是選用的** — 預設的檢索路徑是關鍵字搜尋（FTS5），不需要模型也不需要下載。以語意（意義）為基礎的搜尋需要一個 embedder：在本地執行 [Ollama](https://ollama.com)，或設定一個雲端 embedder（見下方「嵌入」）。沒有設定時，memesh 只使用關鍵字搜尋。
 
 ### 第一步半：把 MeMesh 接進 Claude Code（僅 npm 路徑需要）
 
@@ -285,7 +285,7 @@ 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_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_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=0` 或明確設定供應商，否則會自動用於 LLM 功能。 |
@@ -293,6 +293,8 @@ memesh export-schema \
 
 `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 +363,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 +387,7 @@ memesh config set embedder.model text-embedding-3-small
 
 ---
 
-## 全部 9 個記憶工具
+## 全部 8 個記憶工具
 
 | 工具 | 做什麼 |
 |------|--------|