@pcircle/memesh 4.1.7 → 4.2.1

package/README.th.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,6 +26,22 @@
 
 ---
 
+## หลักฐาน — 95.40% R@5 บน LongMemEval-S
+
+เครื่องมือเรียกคืนของ MeMesh ใช้ **FTS5 เพียงอย่างเดียว** (ไม่มี LLM ไม่มี embedding บนเส้นทางหลัก) วัดผลด้วยเบนช์มาร์กสาธารณะ [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) (500 คำถาม สัญญาอนุญาต MIT):
+
+| ระบบ | R@5 | ที่มา |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | รายงานของผู้พัฒนาเอง |
+| Supermemory | ~82% | ประมาณการของผู้พัฒนา |
+| Zep | 63.8% | เปเปอร์ LongMemEval |
+| Mem0 | 49.0% | เปเปอร์ LongMemEval |
+
+คำสั่งสำหรับทำซ้ำ SHA256 ของชุดข้อมูล ผลดิบรายคำถาม และการวิเคราะห์ความล้มเหลวที่รู้จัก ทั้งหมดอยู่ใน [`benchmarks/longmemeval/`](benchmarks/longmemeval/) รันซ้ำได้ใน ~10 วินาที
+
+---
+
 ## เริ่มต้นใน 60 วินาที
 
 ### ขั้นตอนที่ 1: ติดตั้ง
@@ -173,15 +186,36 @@ memesh export-schema \
 
 ---
 
+## การตั้งค่า
+
+การตั้งค่าทั้งหมดทำผ่านตัวแปรสภาพแวดล้อม ค่าเริ่มต้นทำงานภายในเครื่องล้วน ๆ และไม่มีเครือข่าย — ไม่ต้องตั้งค่าอะไรเพื่อให้ระบบใช้งานได้
+
+| ตัวแปร | ค่าเริ่มต้น | ทำอะไร |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | เปลี่ยนตำแหน่งฐานข้อมูล SQLite |
+| `MEMESH_AUTO_CAPTURE` | `true` | ปิดการใช้ hook จับข้อมูลอัตโนมัติทั้งหมด (`Stop`, `PreCompact`) |
+| `MEMESH_AUTO_DETECT_LLM` | ไม่ตั้ง | ตั้งเป็น `1` เพื่อให้ memesh ตรวจหาผู้ให้บริการจาก shell env (`OPENAI_API_KEY` ฯลฯ) โดยอัตโนมัติและสลับไปใช้ BYOK embeddings **ค่าเริ่มต้นของการติดตั้งใหม่คือ ONNX ภายในเครื่อง (384 มิติ) เท่านั้น** — opt-in ถ้าต้องการ embedding บนคลาวด์ ถ้าไม่ตั้งค่าธงนี้ `OPENAI_API_KEY` ที่อยู่ใน shell จะถูกเพิกเฉย |
+| `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 ของคุณ ใช้เฉพาะเมื่อ `MEMESH_AUTO_DETECT_LLM=1` หรือคุณตั้งค่าผู้ให้บริการอย่างชัดเจน |
+| `OLLAMA_HOST` | `http://localhost:11434` | เปลี่ยนปลายทาง Ollama เมื่อใช้ผู้ให้บริการ Ollama ภายในเครื่อง |
+
+`memesh doctor` พิมพ์การตั้งค่าที่ resolve แล้วเพื่อให้คุณเห็นว่าอะไรทำงานอยู่
+
+เมื่อ npm ระบุว่าเวอร์ชันที่ติดตั้งถูก deprecate (โดยทั่วไปคือ security advisory) เซสชันถัดไปจะแสดงแบนเนอร์ `⚠️ MeMesh <ver> is DEPRECATED` แบบหนักนำหน้า และ `memesh update-status` จะแสดงบรรทัดเดียวกันจนกว่าคุณจะอัปเกรด การตรวจสอบถูก cache ที่ `~/.memesh/update-check.<version>.json` เพื่อไม่ให้ความล้มเหลวเครือข่ายชั่วคราวลดความสว่างของคำเตือน
+
+---
+
 ## แดชบอร์ด
 
-7 แท็บ 11 ภาษา ไม่มีการพึ่งพิ่นภายนอก เข้าถึงได้ที่ `http://localhost:3737/dashboard` เมื่อเซิร์ฟเวอร์ทำงาน
+8 แท็บ 11 ภาษา ไม่มีการพึ่งพิ่นภายนอก เข้าถึงได้ที่ `http://localhost:3737/dashboard` เมื่อเซิร์ฟเวอร์ทำงาน
 
 | แท็บ | เห็นอะไร |
 |---|---|
+| **Insights** | ข้อมูลเชิงลึกเกี่ยวกับหน่วยความจำ — บทสรุปรายสัปดาห์และข้อเสนอรูปแบบจากเครื่องมือ dreamer; ยอมรับ/ปฏิเสธด้วยคลิกเดียว |
 | **Search** | ค้นหาข้อความแบบเต็มรูป + ความคล้ายคลึงเวกเตอร์ข้ามหน่วยความจำทั้งหมด |
 | **Browse** | รายการหน่วยความจำทั้งหมดแบบหน้าต่อหน้า พร้อมเก็บ/คืนสถานะ |
-| **Analytics** | Memory Health Score (0-100) ไทม์ไลน์ 30 วัน เมตริกค่า ความครอบคลุมความรู้ คำแนะนำการทำความสะอาด รูปแบบการทำงาน |
+| **Analytics** | Memory Health Score ไทม์ไลน์ 30 วัน ความเร็ว PM + ตัวชี้วัดการเชื่อมต่อ KG รูปแบบการทำงาน คำแนะนำการทำความสะอาด |
 | **Graph** | กราฟความรู้แบบโต้ตอบด้วยแรงโดยตรง พร้อมตัวกรองประเภท ค้นหา โหมด ego แผนความร้อนความเสมียน |
 | **Lessons** | บทเรียนโครงสร้างจากความล้มเหลวที่ผ่านมา (ข้อผิดพลาด สาเหตุ การแก้ไข การป้องกัน) |
 | **Manage** | เก็บและคืนสถานะอักษร |
@@ -199,6 +233,8 @@ memesh export-schema \
 
 **⚠️ การตรวจจับความขัดแย้ง** — ถ้าคุณมีหน่วยความจำสองอันที่ขัดแย้งกัน MeMesh เตือนคุณ
 
+**🕸️ การเชื่อมต่อกราฟความรู้** — `memesh kg backfill-relations --all-rules` เชื่อมโยงเอนทิตีกำพร้าโดยใช้การร่วมเกิดของแท็ก การจัดกลุ่มโครงการ บริบทเซสชัน และความคล้ายคลึงของชื่อ — ไม่ต้องใช้ LLM ลดอัตราเด็กกำพร้าจาก 89% เป็นต่ำกว่า 12% บนฐานความรู้ที่เป็นตัวแทน
+
 **📦 การแบ่งปันทีม** — `memesh export > team-knowledge.json` → แบ่งปันกับทีม → `memesh import team-knowledge.json`
 บันเดิลนำเข้าสามารถค้นหาได้ แต่ MeMesh ไม่ได้แทรกหน่วยความจำนำเข้าโดยอัตโนมัติลงใน hook Claude จนกว่าคุณจะตรวจสอบหรือเก็บเป็นท้องถิ่นอีกครั้ง
 
@@ -234,10 +270,12 @@ memesh  # opens dashboard → Settings tab
 
 | | ระดับ 0 (ค่าเริ่มต้น) | ระดับ 1 (Smart Mode) |
 |---|---|---|
-| **Search** | FTS5 keyword matching | + LLM query expansion (~97% recall) |
+| **Search** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms ต่อ query) | คงเดิม — recall ไม่ใช้ LLM ในทุก level |
 | **Auto-capture** | รูปแบบตามกฎ | + LLM สกัดการตัดสินใจ & บทเรียน |
-| **Compression** | ไม่พร้อมใช้ | `consolidate` บีบอัดหน่วยความจำที่มีเนื้อหามาก |
-| **Cost** | ฟรี ไม่ต้องคีย์ API | ~$0.0001 ต่อการค้นหา (Haiku) |
+| **Auto-tagging** | แท็กด้วยตนเองเท่านั้น | + LLM สร้างแท็กให้ entity ใหม่ |
+| **วิเคราะห์ความล้มเหลว** | ไม่พร้อมใช้ | + LLM แปลง session errors เป็น structured lessons |
+| **Compression** | ไม่พร้อมใช้ | `consolidate` + `dream` บีบอัดหน่วยความจำ |
+| **Cost** | ฟรี ไม่ต้องคีย์ API | ~$0.0001 ต่อ analysis call (Haiku) |
 
 ---
 

package/README.vi.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,6 +26,22 @@ Package này là tầng bộ nhớ cục bộ của dòng sản phẩm MeMesh. N
 
 ---
 
+## Proof — 95.40% 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):
+
+| Hệ thống | R@5 | Nguồn |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | Vendor self-report |
+| Supermemory | ~82% | Vendor estimate |
+| Zep | 63.8% | LongMemEval paper |
+| Mem0 | 49.0% | LongMemEval paper |
+
+Lệnh tái hiện, SHA256 của dataset, kết quả thô theo từng câu hỏi, và phân tích các lỗi đã biết đều có trong [`benchmarks/longmemeval/`](benchmarks/longmemeval/). Có thể chạy lại trong ~10 giây.
+
+---
+
 ## Bắt đầu trong 60 giây
 
 ### Bước 1: Cài đặt
@@ -173,15 +186,36 @@ Bạn không cần phải manually nhớ mọi thứ. MeMesh có **7 hooks** đ
 
 ---
 
+## Cấu hình
+
+Toàn bộ cấu hình thông qua biến môi trường. Các giá trị mặc định là local-only và zero-network — bạn không cần thiết lập gì để có một hệ thống hoạt động.
+
+| Biến | Mặc định | Tác dụng |
+|---|---|---|
+| `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_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. |
+| `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.
+
+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.
+
+---
+
 ## Dashboard
 
-7 tabs, 11 ngôn ngữ, không phụ thuộc bên ngoài. Truy cập tại `http://localhost:3737/dashboard` khi server đang chạy.
+8 tabs, 11 ngôn ngữ, không phụ thuộc bên ngoài. Truy cập tại `http://localhost:3737/dashboard` khi server đang chạy.
 
 | Tab | Bạn thấy gì |
 |-----|-------------|
+| **Insights** | Thông tin chi tiết về bộ nhớ — tóm tắt hàng tuần và đề xuất mẫu từ công cụ dreamer; chấp nhận/từ chối một cú nhấp |
 | **Search** | Full-text + vector similarity search trên tất cả memories |
 | **Browse** | Danh sách paginated tất cả entities với archive/restore |
-| **Analytics** | Memory Health Score (0-100), timeline 30 ngày, value metrics, knowledge coverage, cleanup suggestions, work patterns của bạn |
+| **Analytics** | Memory Health Score, timeline 30 ngày, tốc độ PM + chỉ số kết nối KG, work patterns, cleanup suggestions |
 | **Graph** | Interactive force-directed knowledge graph với type filters, search, ego mode, recency heatmap |
 | **Lessons** | Structured lessons từ những lỗi trong quá khứ (error, root cause, fix, prevention) |
 | **Manage** | Archive và restore entities |
@@ -199,6 +233,8 @@ Bạn không cần phải manually nhớ mọi thứ. MeMesh có **7 hooks** đ
 
 **⚠️ Conflict Detection** — Nếu bạn có hai memories mâu thuẫn với nhau, MeMesh cảnh báo bạn.
 
+**🕸️ Kết nối đồ thị tri thức** — `memesh kg backfill-relations --all-rules` liên kết các thực thể cô lập bằng cách sử dụng đồng xuất hiện thẻ, phân cụm dự án, ngữ cảnh phiên và độ tương đồng tên — không cần LLM. Giảm tỷ lệ cô lập từ 89% xuống dưới 12% trên cơ sở tri thức đại diện.
+
 **📦 Team Sharing** — `memesh export > team-knowledge.json` → chia sẻ với team → `memesh import team-knowledge.json`
 Các imported bundles vẫn có thể tìm kiếm được, nhưng MeMesh không auto-inject imported memories vào Claude hooks cho đến khi bạn review hoặc re-store chúng locally.
 
@@ -219,7 +255,7 @@ Các imported bundles vẫn có thể tìm kiếm được, nhưng MeMesh không
 
 ## Mở khóa Smart Mode (Tuỳ chọn)
 
-MeMesh hoạt động offline theo mặc định. Thêm LLM API key chỉ nếu bạn muốn query expansion, smarter extraction, và compression:
+MeMesh hoạt động offline theo mặc định — recall luôn LLM-free (95.40% R@5 trên LongMemEval-S, không cần LLM). Thêm LLM API key chỉ nếu bạn muốn các luồng phân tích LLM-augmented bổ sung: trích xuất session thông minh hơn, auto-tagging cho memories mới, phân tích lỗi thành lessons có cấu trúc, và compression `consolidate` / `dream`:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -234,10 +270,12 @@ memesh  # mở dashboard → Settings tab
 
 | | Level 0 (default) | Level 1 (Smart Mode) |
 |---|---|---|
-| **Search** | FTS5 keyword matching | + LLM query expansion (~97% recall) |
+| **Search** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms/query) | giữ nguyên — recall luôn LLM-free ở mọi level |
 | **Auto-capture** | Rule-based patterns | + LLM extracts decisions & lessons |
-| **Compression** | Không có sẵn | `consolidate` compresses verbose memories |
-| **Chi phí** | Free, no API key | ~$0.0001 per search (Haiku) |
+| **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 |
+| **Compression** | Không có sẵn | `consolidate` + `dream` nén verbose memories |
+| **Chi phí** | Free, no API key | ~$0.0001 mỗi analysis call (Haiku) |
 
 ---
 
@@ -246,7 +284,7 @@ memesh  # mở dashboard → Settings tab
 | Tool | Nó làm gì |
 |------|-------------|
 | `remember` | Lưu trữ kiến thức với observations, relations, và tags |
-| `recall` | Smart search với multi-factor scoring và LLM query expansion |
+| `recall` | Tìm kiếm FTS5 + sqlite-vec với multi-factor scoring (relevance, recency, frequency, confidence, temporal validity) — không có LLM trong hot path |
 | `forget` | Soft-archive (không bao giờ xóa) hoặc xóa observations cụ thể |
 | `consolidate` | LLM-powered compression của verbose memories |
 | `export` | Chia sẻ memories dưới dạng JSON giữa các dự án hoặc thành viên team |

package/README.zh-CN.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,17 +26,52 @@
 
 ---
 
+## 实测数据 — LongMemEval-S 上 R@5 达到 95.40%
+
+MeMesh 的检索引擎**只用 FTS5**（热路径上没有 LLM、也没有 embeddings），在公开的 [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) 基准（500 道题，MIT 许可）上的实测结果：
+
+| 系统 | R@5 | 来源 |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | 厂商自报 |
+| Supermemory | ~82% | 厂商估计 |
+| Zep | 63.8% | LongMemEval 论文 |
+| Mem0 | 49.0% | LongMemEval 论文 |
+
+复现命令、数据集 SHA256、每题原始结果以及已知失败分析全部放在 [`benchmarks/longmemeval/`](benchmarks/longmemeval/) 中。约 10 秒可重跑。
+
+---
+
 ## 60 秒快速开始
 
-### 第一步：安装
+### 选项 A — Claude Code 插件（一行安装）
+
+如果你使用 Claude Code，可以直接在 CLI 内把 MeMesh 作为插件安装：
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/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 沿用 Anthropic 官方插件（如 `context7`）相同的 `npx` 启动模式，所以任何功能都不需要 `npm install -g`。
+
+### 选项 B — npm 全局安装（可选优化）
+
+如果你想把二进制直接放在 shell `PATH` 上（这样 `memesh`、`memesh-mcp` 等可在任意终端中直接使用，不需要每次都走 `npx` 查找），或者你想把 `memesh-mcp` 作为固定路径 stdio 命令暴露给**非 Claude Code 的 MCP 客户端**（Cursor、Cline、纯终端流程）：
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### 第一步半：把 MeMesh 接入 Claude Code（推荐，一次性）
+> **首次安装注意事项（一次性）：**
+> - **原生模块** — `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）不需要这个下载。
+
+### 第一步半：把 MeMesh 接入 Claude Code（仅 npm 路径）
 
-`npm install -g` 把 CLI 放进 PATH 并注册 MCP server，但**不会**自动接上 MeMesh 的 Claude Code session hooks。没有这些 hooks，你还是可以手动用 `memesh remember` / `recall`，但**自动捕捉循环**（session → 教训 → 下次 session 主动回想）就会静默不动。
+如果你通过**选项 A**（`/plugin install memesh@pcircle-memesh`）安装，跳过这一步 — Claude Code 会自动接好插件 hooks。
+
+如果你通过**选项 B**（`npm install -g`）安装，CLI 已经在 PATH 上、MCP server 也已注册，但 Claude Code session hooks 不会自动接上。没有这些 hooks，你仍然可以手动用 `memesh remember` / `recall`，但**自动捕捉循环**（session → 教训 → 下次 session 主动回想）就会静默不动。
 
 ```bash
 memesh install-hooks         # 把 memesh hooks 加到 ~/.claude/settings.json
@@ -50,6 +82,14 @@ memesh doctor                # 确认「Hooks wired into Claude Code」通过
 
 ### 第二步：记录一个决策
 
+> 下面的 bash 示例假设 `memesh` 已在你的 `PATH` 上（选项 B）。选项 A（仅插件）用户有两条等价路径：在 Claude Code 对话内询问（`/memesh` skill + MCP 工具覆盖相同流程），或在任意 shell 中把 `memesh` 替换成 `npx @pcircle/memesh` — 参数完全相同，无需全局安装。
+
+```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"
 ```
@@ -157,13 +197,14 @@ memesh export-schema \
 
 ## Claude Code 中的自动化流程
 
-你不需要手动记住一切。MeMesh 有 **6 个钩子**在你工作时自动捕获和注入知识：
+你不需要手动记住一切。MeMesh 有 **7 个钩子**在你工作时自动捕获和注入知识：
 
 | 触发条件 | MeMesh 的动作 |
 |---------|------------|
-| **每个会话开始** | 加载最相关的记忆 + 来自过去经验教训的主动警告 + 代理编排横幅 |
+| **每个会话开始** | 加载最相关的记忆 + 来自过去经验教训的主动警告 |
 | **编辑文件前** | 回忆与该文件或项目相关的记忆，然后 Claude 才开始写代码 |
-| **执行 bash 命令前** | 推动 Claude 派遣高可验证性命令（测试、构建、lint、迁移、部署、基准测试）作为后台代理 |
+| **执行 bash 命令前** | （可选启用）推动 Claude 派遣高可验证性命令（测试、构建、lint、迁移、部署、基准测试）作为后台代理 |
+| **当你要求记忆时** | 检测「remember this」/「guardar en memesh」/「sauvegarder dans memesh」/「记下来」意图（5 种语言），并提醒 Claude 使用 memesh |
 | **每次 `git commit` 后** | 记录你的改动，附带 diff 统计 |
 | **Claude 停止时** | 捕获编辑过的文件、修复的错误、自动从失败中生成结构化经验教训 |
 | **上下文压缩前** | 在知识被上下文限制吞没前保存 |
@@ -172,15 +213,36 @@ 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_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` 或你显式配置提供商时使用。 |
+| `OLLAMA_HOST` | `http://localhost:11434` | 使用本地 Ollama 提供商时覆盖 Ollama 端点。 |
+
+`memesh doctor` 会打印解析后的配置，你可以看到当前生效的内容。
+
+当 npm 把已安装版本标记为 deprecated（通常为安全建议）时，下次 session-start 会先显示一条强烈的 `⚠️ MeMesh <ver> is DEPRECATED` 横幅，并且 `memesh update-status` 在你升级前会持续显示同一行。检查结果会缓存到 `~/.memesh/update-check.<version>.json`，避免一次临时网络故障让警告变弱。
+
+---
+
 ## 仪表板
 
-7 个标签页，11 种语言，零外部依赖。服务器运行时访问 `http://localhost:3737/dashboard`。
+8 个标签页，11 种语言，零外部依赖。服务器运行时访问 `http://localhost:3737/dashboard`。
 
 | 标签页 | 你看到什么 |
 |--------|---------|
+| **Insights** | 记忆洞察 — 来自 dreamer 引擎的每周摘要和模式提案；一键接受/拒绝 |
 | **搜索** | 全文 + 向量相似度搜索，覆盖所有记忆 |
 | **浏览** | 所有实体的分页列表，支持归档/恢复 |
-| **分析** | 内存健康评分（0-100）、30 天时间线、价值指标、知识覆盖、清理建议、你的工作模式 |
+| **分析** | 记忆健康分数、30 天时间线、PM 速度 + KG 连通性指标、工作模式、清理建议 |
 | **知识图** | 交互式力导向图，支持类型过滤、搜索、中心模式、新近度热力图 |
 | **经验教训** | 来自过去失败的结构化经验教训（错误、根本原因、修复、预防） |
 | **管理** | 归档和恢复实体 |
@@ -190,7 +252,7 @@ memesh export-schema \
 
 ## 聪慧功能
 
-**🧠 智能搜索** — 搜索"登录安全"会找到"OAuth PKCE"相关的记忆。MeMesh 用你配置的 LLM 扩展查询。
+**🧠 智能搜索** — 搜索"登录安全"也能找到"OAuth PKCE"相关的记忆。MeMesh 在热路径上用 FTS5 + sqlite-vec，零 LLM。
 
 **📊 评分排序** — 结果按相关性（30%）+ 新近度（25%）+ 频率（15%）+ 置信度（15%）+ 回忆影响（10%）+ 时间有效性（5%）排序。
 
@@ -198,6 +260,8 @@ memesh export-schema \
 
 **⚠️ 冲突检测** — 如果你有两条相互矛盾的记忆，MeMesh 会警告你。
 
+**🕸️ 知识图连通性** — `memesh kg backfill-relations --all-rules` 使用标签共现、项目聚类、会话上下文和名称相似度连接孤立实体 — 无需 LLM。在代表性知识库上将孤立率从 89% 降至 12% 以下。
+
 **📦 团队共享** — `memesh export > team-knowledge.json` → 与团队分享 → `memesh import team-knowledge.json`
 导入的包保持可搜索，但 MeMesh 不会自动将导入的记忆注入到 Claude 钩子中，直到你审查或本地重新存储它们。
 
@@ -218,7 +282,7 @@ memesh export-schema \
 
 ## 解锁智能模式（可选）
 
-MeMesh 默认离线工作。仅当你需要查询扩展、更聪慧的提取和压缩时，才添加 LLM API 密钥：
+MeMesh 默认离线工作 — 回忆始终是严格无 LLM 的（开箱即用 LongMemEval-S R@5 95.40%）。仅当你想要在此之上叠加 LLM 增强分析流程时才添加 LLM API 密钥：更聪慧的会话提取、为新记忆自动打标签、从失败生成经验教训，以及 `consolidate` / `dream` 压缩：
 
 ```bash
 memesh config set llm.provider anthropic
@@ -233,10 +297,12 @@ memesh  # 打开仪表板 → 设置标签页
 
 | | 级别 0（默认） | 级别 1（智能模式） |
 |---|---|---|
-| **搜索** | FTS5 关键词匹配 | + LLM 查询扩展（~97% 召回率） |
+| **搜索** | FTS5 + sqlite-vec，95.40% R@5（每次查询 ~18ms） | 不变 — 回忆在每个级别都是无 LLM 的 |
 | **自动捕获** | 基于规则的模式 | + LLM 提取决策和经验教训 |
-| **压缩** | 不可用 | `consolidate` 压缩冗长的记忆 |
-| **成本** | 免费，无需 API 密钥 | ~$0.0001 每次搜索（Haiku） |
+| **自动打标签** | 仅手动标签 | + LLM 为新记忆生成标签 |
+| **失败分析** | 不可用 | + LLM 把会话错误转化为结构化经验教训 |
+| **压缩** | 不可用 | `consolidate` + `dream` 压缩冗长的记忆 |
+| **成本** | 免费，无需 API 密钥 | ~$0.0001 每次分析调用（Haiku） |
 
 ---
 
@@ -245,7 +311,7 @@ memesh  # 打开仪表板 → 设置标签页
 | 工具 | 它做什么 |
 |------|--------|
 | `remember` | 存储知识，附带观察、关系和标签 |
-| `recall` | 智能搜索，多因素评分和 LLM 查询扩展 |
+| `recall` | FTS5 + sqlite-vec 搜索，附带多因素评分（相关性、新近度、频率、置信度、时间有效性）— 热路径上无 LLM |
 | `forget` | 软归档（永不删除）或移除特定观察 |
 | `consolidate` | LLM 驱动的冗长记忆压缩 |
 | `export` | 在项目或团队成员间共享内存，格式为 JSON |