@pcircle/memesh 4.0.2 → 4.1.0

package/README.vi.md

@@ -1,10 +1,13 @@
+<!-- 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">
   <h1 align="center">MeMesh LLM Memory</h1>
   <p align="center">
-    <strong>Lớp bộ nhớ AI phổ quát nhẹ nhất.</strong><br />
-    Một file SQLite. Mọi LLM. Không cần đám mây.
+    <strong>Bộ nhớ cục bộ cho Claude Code và các agent coding MCP.</strong><br />
+    Một file SQLite. Không Docker. Không cần cloud.
   </p>
   <p align="center">
     <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
@@ -16,15 +19,17 @@
 
 ---
 
-## Vấn Đề
+## 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.
 
-AI của bạn quên sạch mọi thứ sau mỗi phiên làm việc. Mọi quyết định, mọi lần sửa lỗi, mọi bài học rút ra — biến mất. Bạn phải giải thích lại cùng một bối cảnh, Claude lại khám phá lại cùng một pattern, và kiến thức AI của cả nhóm cứ reset về không mỗi lần.
+**MeMesh cung cấp bộ nhớ cục bộ, có khả năng tìm kiếm và phát triển liên tục cho các agent coding.**
 
-**MeMesh trao cho mọi AI bộ nhớ bền vững, có thể tìm kiếm và không ngừng phát triển.**
+Package này là tầng bộ nhớ cục bộ của dòng sản phẩm MeMesh. Nó được thiết kế nhỏ gọn và mã nguồn mở: cài đặt qua npm, lưu bộ nhớ của bạn trong `~/.memesh/knowledge-graph.db`, và kết nối với Claude Code hoặc bất kỳ client tương thích MCP nào. Các sản phẩm workspace theo dõi và hệ điều hành enterprise nên được giữ riêng biệt với README và roadmap của package này.
 
 ---
 
-## Bắt Đầu Trong 60 Giây
+## Bắt đầu trong 60 giây
 
 ### Bước 1: Cài đặt
 
@@ -32,20 +37,26 @@ AI của bạn quên sạch mọi thứ sau mỗi phiên làm việc. Mọi quy
 npm install -g @pcircle/memesh
 ```
 
-### Bước 2: AI của bạn ghi nhớ
+### Bước 2: Lưu một quyết định
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### Bước 3: AI của bạn gợi nhớ
+### Bước 3: Gọi lại sau này
 
 ```bash
 memesh recall "login security"
-# → Tìm thấy "OAuth 2.0 with PKCE" dù tìm bằng từ khác
+# → Tìm "OAuth 2.0 with PKCE" dù bạn tìm kiếm bằng từ khác
 ```
 
-**Vậy là xong.** MeMesh đã bắt đầu ghi nhớ và gợi nhớ xuyên suốt các phiên làm việc.
+**Vậy thôi.** MeMesh giờ đã nhớ và gọi lại thông tin qua các phiên làm việc.
+
+Nếu bạn muốn kiểm tra cài đặt và dây điều khiển cục bộ từ đầu đến cuối:
+
+```bash
+memesh doctor
+```
 
 Mở dashboard để khám phá bộ nhớ của bạn:
 
@@ -54,31 +65,31 @@ memesh
 ```
 
 <p align="center">
-  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — tìm bất kỳ ký ức nào ngay lập tức" width="100%" />
+  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — tìm bất kỳ bộ nhớ nào instantly" width="100%" />
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — hiểu rõ tri thức của AI bạn" width="100%" />
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — health score, timeline, patterns, knowledge coverage" width="100%" />
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — đồ thị tri thức tương tác với bộ lọc loại và chế độ ego" width="100%" />
+  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — interactive knowledge graph with type filters and ego mode" width="100%" />
 </p>
 
 ---
 
-## Dành Cho Ai?
+## Dành cho ai?
 
 | Nếu bạn là... | MeMesh giúp bạn... |
 |---------------|---------------------|
-| **Lập trình viên dùng Claude Code** | Tự động ghi nhớ quyết định, pattern và bài học qua các phiên làm việc |
-| **Nhóm xây dựng sản phẩm với LLM** | Chia sẻ kiến thức nhóm qua xuất/nhập, giữ ngữ cảnh AI của mọi người đồng bộ |
-| **Nhà phát triển AI agent** | Trao cho agent bộ nhớ bền vững qua MCP, HTTP API hoặc Python SDK |
-| **Người dùng nặng với nhiều công cụ AI** | Một lớp bộ nhớ dùng được với Claude, GPT, LLaMA, Ollama hoặc bất kỳ MCP client nào |
+| **Nhà phát triển sử dụng Claude Code** | Tự động gọi lại các quyết định dự án, bài học cụ thể theo file, và những lỗi trong quá khứ khi bạn làm việc |
+| **Power user của coding agent** | Chia sẻ một tầng bộ nhớ cục bộ qua các công cụ tương thích MCP |
+| **Nhóm thử nghiệm workflow AI coding** | Export/import kiến thức dự án mà không cần hạ tầng được quản lý |
+| **Nhà phát triển agent** | Thêm bộ nhớ cục bộ thông qua MCP, HTTP, CLI, hoặc Python SDK |
 
 ---
 
-## Tương Thích Với Tất Cả
+## Thiết kế cho Coding Agent trước hết
 
 <table>
 <tr>
@@ -88,23 +99,23 @@ memesh
 ```bash
 memesh-mcp
 ```
-Giao thức MCP (tự động cấu hình)
+MCP tools + Claude Code hooks
 
 </td>
 <td width="33%" align="center">
 
-**Python / LangChain**
-```python
-from memesh import MeMesh
-m = MeMesh()
-m.recall("auth")
+**Bất kỳ HTTP Client**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
 ```
-`pip install memesh`
+`memesh serve` (REST API)
 
 </td>
 <td width="33%" align="center">
 
-**Mọi LLM (định dạng OpenAI)**
+**Bất kỳ LLM (định dạng OpenAI)**
 ```bash
 memesh export-schema \
   --format openai
@@ -117,107 +128,124 @@ Dán tools vào bất kỳ API call nào
 
 ---
 
-## Tại Sao Không Dùng Mem0 / Zep?
+## Tại sao không dùng OpenMemory, Cursor Memories, Mem0, hay Zep?
 
-| | **MeMesh** | Mem0 | Zep |
-|---|---|---|---|
-| **Thời gian cài đặt** | 5 giây | 30–60 phút | 30+ phút |
-| **Cấu hình** | `npm i -g` — xong | Neo4j + VectorDB + API key | Neo4j + config |
-| **Lưu trữ** | Một file SQLite | Neo4j + Qdrant | Neo4j |
-| **Hoạt động offline** | Có, luôn luôn | Không | Không |
-| **Dashboard** | Tích hợp sẵn (7 tab + phân tích) | Không có | Không có |
-| **Phụ thuộc** | 6 | 20+ | 10+ |
-| **Giá** | Miễn phí mãi mãi | Gói miễn phí / Trả phí | Gói miễn phí / Trả phí |
+| | **MeMesh** | OpenMemory | Cursor Memories | Mem0 | Zep / Graphiti |
+|---|---|---|---|---|---|
+| **Phù hợp nhất cho** | Bộ nhớ cục bộ cho coding agent | Bộ nhớ MCP cục bộ/cross-client | Bộ nhớ dự án native Cursor | Bộ nhớ app/agent được quản lý | Temporal knowledge graphs |
+| **Hình thức cài đặt** | `npm install -g @pcircle/memesh` | Local app/server flow | Tích hợp vào Cursor | Cloud API / SDK / MCP | Service/framework setup |
+| **Lưu trữ** | Một file SQLite cục bộ | Local memory stack | Cursor-managed rules/memories | Hosted hoặc self-hosted stack | Graph database |
+| **Cloud cần thiết** | Không | Không ở chế độ local | Tuỳ thuộc vào cài đặt tài khoản Cursor | Có cho platform | Thường có/self-hosted |
+| **Claude Code hooks** | First-class | MCP tools | Không | MCP tools | Không dành riêng cho Claude Code |
+| **Dashboard** | Tích hợp sẵn | Tích hợp sẵn | Cài đặt Cursor | Platform dashboard | Platform/graph tooling |
+| **Tradeoff** | Wedge cục bộ đơn giản, không phải quy mô enterprise | Footprint local app rộng hơn | Bị khóa vào Cursor | Platform được quản lý mạnh mẽ, local-first ít hơn | Strong graph model, heavier setup |
 
-**MeMesh đánh đổi:** tính năng multi-tenant cấp doanh nghiệp để lấy **cài đặt tức thì, không hạ tầng, bảo mật 100%**.
+**MeMesh đánh đổi hạ tầng được quản lý quy mô enterprise để có setup cục bộ tức thì, lưu trữ có thể kiểm tra, và coding-agent workflow hooks.**
 
 ---
 
-## Những Gì Xảy Ra Tự Động
+## Điều gì xảy ra tự động trong Claude Code
 
-Bạn không cần phải tự ghi nhớ mọi thứ. MeMesh có **4 hook** tự động thu thập kiến thức mà không cần bạn làm gì:
+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 khi bắt đầu phiên** | Tải các ký ức liên quan nhất + cảnh báo chủ động từ bài học trước đó |
-| **Sau mỗi `git commit`** | Ghi lại những gì bạn thay đổi, kèm thống kê diff |
-| **Khi Claude kết thúc** | Thu thập file đã sửa, lỗi đã fix và tự động tạo bài học có cấu trúc từ các lỗi |
-| **Trước khi nén context** | Lưu kiến thức trước khi mất do giới hạn context |
+| **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 |
+| **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 |
+| **Trước khi context compact** | Lưu kiến thức trước khi nó bị mất do context limits |
 
-> **Tắt bất cứ lúc nào:** `export MEMESH_AUTO_CAPTURE=false`
+> **Opt out bất kỳ lúc nào:** `export MEMESH_AUTO_CAPTURE=false`
 
 ---
 
 ## Dashboard
 
-7 tab, 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.
+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.
 
-| Tab | Nội dung |
-|-----|----------|
-| **Search** | Tìm kiếm toàn văn + tương tự vector trên tất cả ký ức |
-| **Browse** | Danh sách phân trang của tất cả thực thể với lưu trữ/khôi phục |
-| **Analytics** | Điểm Sức khỏe Bộ nhớ (0-100), timeline 30 ngày, chỉ số giá trị, phạm vi kiến thức, đề xuất dọn dẹp, pattern làm việc |
-| **Graph** | Đồ thị tri thức tương tác dạng lực với bộ lọc loại, tìm kiếm, chế độ ego, heatmap mức độ mới |
-| **Lessons** | Bài học có cấu trúc từ các lỗi trước đó (lỗi, nguyên nhân gốc, cách sửa, phòng ngừa) |
-| **Manage** | Lưu trữ và khôi phục thực thể |
-| **Settings** | Cấu hình nhà cung cấp LLM, chọn ngôn ngữ |
+| Tab | Bạn thấy gì |
+|-----|-------------|
+| **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 |
+| **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 |
+| **Settings** | LLM provider config, instant language selector |
 
 ---
 
-## Tính Năng Thông Minh
+## Tính năng thông minh
 
-**🧠 Tìm kiếm thông minh** — Tìm "login security" là ra ký ức về "OAuth PKCE". MeMesh mở rộng truy vấn bằng các thuật ngữ liên quan qua LLM đã cấu hình.
+**🧠 Smart Search** — Tìm "login security" và tìm thấy memories về "OAuth PKCE". MeMesh mở rộng queries với các terms liên quan bằng LLM được cấu hình của bạn.
+
+**📊 Scored Ranking** — Kết quả được xếp hạng theo relevance (30%) + recency (25%) + frequency (15%) + confidence (15%) + recall impact (10%) + temporal validity (5%).
+
+**🔄 Knowledge Evolution** — Quyết định thay đổi. `forget` archives old memories (không bao giờ xóa). `supersedes` relations liên kết old → new. AI của bạn luôn thấy phiên bản mới nhất.
+
+**⚠️ Conflict Detection** — Nếu bạn có hai memories mâu thuẫn với nhau, MeMesh cảnh báo bạ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.
+
+---
 
-**📊 Xếp hạng theo điểm** — Kết quả được xếp hạng theo mức liên quan (35%) + thời gian sử dụng gần nhất (25%) + tần suất (20%) + độ tin cậy (15%) + thông tin còn hiệu lực không (5%).
+## Ví dụ sử dụng
 
-**🔄 Tiến hóa kiến thức** — Quyết định thay đổi. `forget` lưu trữ ký ức cũ (không bao giờ xóa thật sự). Quan hệ `supersedes` nối cũ với mới. AI của bạn luôn thấy phiên bản mới nhất.
+> "MeMesh đã nhớ rằng chúng tôi chọn PKCE thay vì implicit flow ba tuần trước. Khi tôi hỏi Claude về auth lại, nó đã biết — không cần giải thích lại."
+> — **Nhà phát triển solo, xây dựng SaaS**
 
-**⚠️ Phát hiện mâu thuẫn** — Nếu có hai ký ức mâu thuẫn nhau, MeMesh sẽ cảnh báo.
+> "Chúng tôi export team memory mỗi thứ Sáu và import thứ Hai. Claude của mỗi người bắt đầu tuần biết những gì team đã học tuần trước."
+> — **Startup 3 người, knowledge base được chia sẻ**
 
-**📦 Chia sẻ nhóm** — `memesh export > team-knowledge.json` → chia sẻ với nhóm → `memesh import team-knowledge.json`
+> "Dashboard cho tôi thấy 90% memories của tôi là auto-generated session logs. Tôi bắt đầu sử dụng `remember` có ý định cho architectural decisions. Game changer."
+> — **Nhà phát triển khám phá ra Analytics tab**
 
 ---
 
-## Mở Khóa Chế Độ Thông Minh (Tùy Chọn)
+## Mở khóa Smart Mode (Tuỳ chọn)
 
-MeMesh hoạt động hoàn toàn offline theo mặc định. Thêm API key của LLM để mở khóa tìm kiếm thông minh hơ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:
 
 ```bash
 memesh config set llm.provider anthropic
 memesh config set llm.api-key sk-ant-...
 ```
 
-Hoặc dùng tab Cài đặt trong dashboard (cấu hình trực quan):
+Hoặc dùng dashboard Settings tab (visual setup):
 
 ```bash
-memesh  # mở dashboard → tab Cài đặt
+memesh  # mở dashboard → Settings tab
 ```
 
-| | Cấp 0 (mặc định) | Cấp 1 (Chế độ thông minh) |
+| | Level 0 (default) | Level 1 (Smart Mode) |
 |---|---|---|
-| **Tìm kiếm** | Khớp từ khóa FTS5 | + Mở rộng truy vấn bằng LLM (~97% recall) |
-| **Tự động thu thập** | Pattern dựa trên quy tắc | + LLM trích xuất quyết định & bài học |
-| **Nén** | Không có | `consolidate` nén ký ức dài dòng |
-| **Chi phí** | Miễn phí, không cần API key | ~$0.0001 mỗi tìm kiếm (Haiku) |
+| **Search** | FTS5 keyword matching | + LLM query expansion (~97% recall) |
+| **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) |
 
 ---
 
-## Tất Cả 8 Công Cụ Bộ Nhớ
+## Cả 9 Memory Tools
 
-| Công cụ | Chức năng |
+| Tool | Nó làm gì |
 |------|-------------|
-| `remember` | Lưu kiến thức kèm quan sát, quan hệ và thẻ nhãn |
-| `recall` | Tìm kiếm thông minh với scoring đa nhân tố và mở rộng truy vấn bằng LLM |
-| `forget` | Lưu trữ mềm (không bao giờ xóa thật) hoặc xóa quan sát cụ thể |
-| `consolidate` | Nén ký ức dài dòng bằng LLM |
-| `export` | Chia sẻ ký ức dạng JSON giữa dự án hoặc thành viên nhóm |
-| `import` | Nhập ký ức với chiến lược gộp (bỏ qua / ghi đè / nối thêm) |
-| `learn` | Ghi lại bài học có cấu trúc từ sai lầm (lỗi, nguyên nhân gốc, cách sửa, phòng ngừa) |
-| `user_patterns` | Phân tích pattern làm việc — lịch trình, công cụ, điểm mạnh, lĩnh vực cần học |
+| `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 |
+| `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 |
+| `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` |
 
 ---
 
-## Kiến Trúc
+## Kiến trúc
 
 ```
                     ┌─────────────────┐
@@ -234,16 +262,17 @@ memesh  # mở dashboard → tab Cài đặt
                     (~/.memesh/knowledge-graph.db)
 ```
 
-Core độc lập với framework. Logic giống nhau chạy từ terminal, HTTP hoặc MCP.
+Core là framework-agnostic. Logic tương tự chạy từ terminal, HTTP, hoặc MCP.
 
 ---
 
-## Đóng Góp
+## Đóng góp
 
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
 cd memesh-llm-memory && npm install && npm run build
-npm test -- --run    # 413 tests
+npm test             # 489 tests
+npm run test:e2e-dashboard
 ```
 
 Dashboard: `cd dashboard && npm install && npm run dev`