@pcircle/memesh 4.0.3 → 4.1.0

package/README.vi.md

@@ -1,110 +1,284 @@
+<!-- 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ớ cục bộ cho Claude Code và các coding agent tương thích MCP.</strong><br />
-    Một tệp SQLite. Không cần Docker. Không cần phụ thuộc vào cloud.
+    <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>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-22c55e?style=flat-square" alt="Node" /></a>
+    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
   </p>
 </p>
 
-> README tiếng Việt này là bản giới thiệu rút gọn. Để xem nội dung đầy đủ và mới nhất, hãy dùng [English README](README.md) làm bản tham chiếu chính.
+---
 
-## MeMesh giải quyết vấn đề gì?
+## Vấn đề
 
-Coding agent thường mất ngữ cảnh giữa các session. Quyết định kiến trúc, lỗi đã sửa, bài học đã rút ra và các ràng buộc của dự án cứ phải giải thích lại nhiều lầ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.
 
-**MeMesh giữ lại phần kiến thức đó trên máy cục bộ, cho phép tìm kiếm, xem lại và dùng lại khi cầ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.**
 
-Gói npm này là phiên bản plugin / package chạy cục bộ của MeMesh. Nó không phải sản phẩm workspace trên cloud hay toàn bộ nền tảng enterprise.
+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
 
-### 1. Cài đặt
+### Bước 1: Cài đặt
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### 2. Lưu một quyết đị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"
 ```
 
-### 3. Gọi lại sau này
+### Bước 3: Gọi lại sau này
 
 ```bash
 memesh recall "login security"
-# → vẫn tìm được "OAuth 2.0 with PKCE" dù dùng cách diễn đạt khác
+# → Tìm "OAuth 2.0 with PKCE" dù bạn tìm kiếm bằng từ khá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:
+Mở dashboard để khám phá bộ nhớ của bạn:
 
 ```bash
 memesh
 ```
 
+<p align="center">
+  <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 — health score, timeline, patterns, knowledge coverage" width="100%" />
+</p>
+
+<p align="center">
+  <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?
 
-- Nhà phát triển dùng Claude Code và muốn giữ ngữ cảnh dự án giữa các session
-- Người dùng nâng cao muốn dùng chung một bộ nhớ cục bộ cho nhiều MCP coding agents
-- Nhóm AI-native nhỏ muốn chia sẻ kiến thức dự án qua export / import
-- Nhà phát triển agent muốn tích hợp bộ nhớ cục bộ qua CLI, HTTP hoặc MCP
+| Nếu bạn là... | MeMesh giúp bạn... |
+|---------------|---------------------|
+| **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 |
+
+---
+
+## Thiết kế cho Coding Agent trước hết
+
+<table>
+<tr>
+<td width="33%" align="center">
+
+**Claude Code / Desktop**
+```bash
+memesh-mcp
+```
+MCP tools + Claude Code hooks
+
+</td>
+<td width="33%" align="center">
+
+**Bất kỳ HTTP Client**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
+```
+`memesh serve` (REST API)
+
+</td>
+<td width="33%" align="center">
+
+**Bất kỳ LLM (định dạng OpenAI)**
+```bash
+memesh export-schema \
+  --format openai
+```
+Dán tools vào bất kỳ API call nào
+
+</td>
+</tr>
+</table>
+
+---
+
+## Tại sao không dùng OpenMemory, Cursor Memories, Mem0, hay Zep?
 
-## Vì sao chọn MeMesh?
+| | **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 |
 
-- Local-first: dữ liệu nằm trong tệp SQLite của chính bạn
-- Cài đặt gọn nhẹ: `npm install -g` là có thể dùng
-- Tích hợp rõ ràng: hỗ trợ CLI, HTTP và MCP
-- Hợp với Claude Code: hooks giúp kéo đúng ngữ cảnh vào lúc làm việc
-- Dễ kiểm tra và dọn dẹp: dashboard giúp nhìn thấy bộ nhớ, không phải hộp đen
-- Ranh giới tin cậy an toàn hơn: bộ nhớ import vẫn tìm kiếm được, nhưng không tự động inject vào Claude hooks nếu chưa được rà soát hoặc lưu lại tại máy cục bộ
+**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.**
 
-## MeMesh tự động làm gì trong Claude Code?
+---
 
-Hiện tại, MeMesh hỗ trợ ở 5 thời điểm:
+## Điều gì xảy ra tự động trong Claude Code
 
-- khi bắt đầu session, nạp các memory liên quan và bài học đã biết
-- trước khi sửa file, gọi lại memory liên quan đến file hoặc dự án
-- sau `git commit`, ghi lại thay đổi vừa thực hiện
-- khi kết thúc session, tổng hợp lỗi, bản sửa và lessons learned
-- trước khi compact context, lưu lại những gì quan trọng vào bộ nhớ cục bộ
+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:
 
-## Dashboard có gì?
+| 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 |
+| **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 |
 
-Dashboard hiện có 7 tab và hỗ trợ 11 ngôn ngữ:
+> **Opt out bất kỳ lúc nào:** `export MEMESH_AUTO_CAPTURE=false`
 
-- Search: tìm memory
-- Browse: xem toàn bộ memory
-- Analytics: theo dõi độ khỏe và xu hướng
-- Graph: xem quan hệ kiến thức
-- Lessons: xem lại bài học
-- Manage: lưu trữ và khôi phục
-- Settings: cấu hình LLM provider và ngôn ngữ
+---
 
-## Smart Mode là gì?
+## Dashboard
 
-Mặc định MeMesh chạy offline. Nếu bạn thêm LLM API key, bạn có thể bật thêm các khả năng như:
+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.
 
-- query expansion
-- tự động trích xuất tốt hơn
-- sắp xếp và nén thông minh hơn
+| 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 |
 
-Ngay cả khi không có API key, phần cốt lõi vẫn hoạt động bình thường.
+---
 
-## Tìm hiểu thêm
+## Tính năng thông minh
 
-- Tính năng đầy đủ, so sánh, API và thông tin release: [English README](README.md)
-- Hướng dẫn tích hợp: [docs/platforms/README.md](docs/platforms/README.md)
-- Tài liệu API: [docs/api/API_REFERENCE.md](docs/api/API_REFERENCE.md)
+**🧠 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.
 
-## Phát triển và kiểm thử
+**📊 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.
+
+---
+
+## Ví dụ sử dụng
+
+> "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**
+
+> "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ẻ**
+
+> "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 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:
+
+```bash
+memesh config set llm.provider anthropic
+memesh config set llm.api-key sk-ant-...
+```
+
+Hoặc dùng dashboard Settings tab (visual setup):
+
+```bash
+memesh  # mở dashboard → Settings tab
+```
+
+| | Level 0 (default) | Level 1 (Smart Mode) |
+|---|---|---|
+| **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) |
+
+---
+
+## Cả 9 Memory Tools
+
+| 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 |
+| `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
+
+```
+                    ┌─────────────────┐
+                    │   Core Engine   │
+                    │  (8 operations) │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           │                 │                 │
+     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
+           │                 │                 │
+           └─────────────────┼─────────────────┘
+                             │
+                    SQLite + FTS5 + sqlite-vec
+                    (~/.memesh/knowledge-graph.db)
+```
+
+Core là framework-agnostic. Logic tương tự chạy từ terminal, HTTP, hoặc MCP.
+
+---
+
+## Đó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
+cd memesh-llm-memory && npm install && npm run build
+npm test             # 489 tests
+npm run test:e2e-dashboard
 ```
+
+Dashboard: `cd dashboard && npm install && npm run dev`
+
+---
+
+<p align="center">
+  <strong>MIT</strong> — Được tạo bởi <a href="https://pcircle.ai">PCIRCLE AI</a>
+</p>