@pcircle/memesh 4.0.3 → 4.1.1

package/README.zh-TW.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>給 Claude Code 與 MCP coding agents 的本地記憶層。</strong><br />
+    <strong>給 Claude Code 和 MCP 程式開發代理的在地記憶系統。</strong><br />
     一個 SQLite 檔案。不需要 Docker。不需要雲端。
   </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 是精簡導覽版。若要查看最新、最完整的內容，請以 [English README](README.md) 為準。
+---
 
-## 問題是什麼？
+## 問題所在
 
-coding agent 在每次 session 之間都很容易失去上下文。架構決策、除錯過程、踩過的坑、專案限制，常常要一講再講。
+你的程式開發代理在每次對話之間就會忘記一切。每個架構決策、每個修復的臭蟲、每個失敗的測試、每個代價不菲的教訓，都得重新跟它解釋一遍。Claude Code 每次都從零開始，重新發現舊的限制條件，浪費寶貴的上下文在它本應已知的事情上。
 
-**MeMesh 讓這些知識留在本機、可搜尋、可檢視，也能在之後的工作裡再次被召回。**
+**MeMesh 讓程式開發代理擁有持久、可搜尋、不斷演進的在地記憶。**
 
-這個 npm package 是 MeMesh 的本地 plugin / package 版本，重點是本地記憶，不是雲端工作台，也不是企業平台。
+這個套件是 MeMesh 產品系列的在地記憶層。我們刻意保持它的精簡和開源：用 npm 安裝，把記憶保存在 `~/.memesh/knowledge-graph.db`，然後連接到 Claude Code 或任何支援 MCP 的用戶端。託管工作區和企業級作業系統產品應該與這個套件的 README 和路線圖分開。
+
+---
 
 ## 60 秒快速開始
 
-### 1. 安裝
+### 第一步：安裝
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### 2. 記下一個決策
+### 第二步：保存一個決策
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### 3. 之後再找回來
+### 第三步：稍後回憶它
 
 ```bash
 memesh recall "login security"
-# → 即使換了說法，也能找回 "OAuth 2.0 with PKCE"
+# → 找到 "OAuth 2.0 with PKCE" 即使你搜尋的是不同的詞彙
+```
+
+**完成。** MeMesh 現在已經在跨對話記憶和回憶。
+
+如果你想驗證安裝和本地連線的整個流程：
+
+```bash
+memesh doctor
 ```
 
-打開 dashboard：
+開啟儀表板來探索你的記憶：
 
 ```bash
 memesh
 ```
 
-## 這個工具適合誰？
+<p align="center">
+  <img src="docs/images/dashboard-search.png" alt="MeMesh 搜尋 — 瞬間找到任何記憶" width="100%" />
+</p>
+
+<p align="center">
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh 分析 — 健康分數、時間線、模式、知識涵蓋範圍" width="100%" />
+</p>
+
+<p align="center">
+  <img src="docs/images/dashboard-graph.png" alt="MeMesh 圖表 — 互動式知識圖，具有類型篩選和自我中心模式" width="100%" />
+</p>
+
+---
+
+## 誰應該用 MeMesh？
+
+| 如果你是... | MeMesh 幫你... |
+|---------------|---------------------|
+| **使用 Claude Code 的開發者** | 在工作時自動回憶專案決策、檔案特定的經驗教訓和過去的失敗 |
+| **程式開發代理進階使用者** | 在多個 MCP 相容工具間共享一層在地記憶 |
+| **嘗試 AI 程式開發工作流的團隊** | 導出／導入專案知識，無需引入託管基礎設施 |
+| **代理開發者** | 透過 MCP、HTTP、CLI 或 Python SDK 添加在地記憶 |
+
+---
+
+## 專為程式開發代理設計
+
+<table>
+<tr>
+<td width="33%" align="center">
+
+**Claude Code / Desktop**
+```bash
+memesh-mcp
+```
+MCP 工具 + Claude Code 鉤子
+
+</td>
+<td width="33%" align="center">
+
+**任何 HTTP 用戶端**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
+```
+`memesh serve`（REST API）
+
+</td>
+<td width="33%" align="center">
+
+**任何 LLM（OpenAI 格式）**
+```bash
+memesh export-schema \
+  --format openai
+```
+貼到任何 API 呼叫中
+
+</td>
+</tr>
+</table>
+
+---
 
-- 使用 Claude Code、希望跨 session 保留專案脈絡的開發者
-- 使用 MCP coding agents、想共用同一份本地記憶的進階使用者
-- 小型 AI-native 開發團隊，想透過 export / import 共用專案知識
-- 想用 CLI、HTTP 或 MCP 把本地記憶接進工具流程的 agent 開發者
+## 為什麼選 MeMesh 而不是 OpenMemory、Cursor Memories、Mem0 或 Zep？
 
-## 為什麼用 MeMesh？
+| | **MeMesh** | OpenMemory | Cursor Memories | Mem0 | Zep / Graphiti |
+|---|---|---|---|---|---|
+| **最佳用途** | 程式開發代理的在地記憶 | 本地／跨用戶端 MCP 記憶 | Cursor 原生專案記憶 | 受管應用／代理記憶 | 時間性知識圖 |
+| **安裝方式** | `npm install -g @pcircle/memesh` | 本地應用／伺服器流程 | 內建於 Cursor | 雲端 API / SDK / MCP | 服務／框架設定 |
+| **儲存位置** | 單個本地 SQLite 檔案 | 本地記憶堆疊 | Cursor 管理的規則／記憶 | 託管或自管堆疊 | 圖形資料庫 |
+| **需要雲端** | 否 | 否（本地模式） | 取決於 Cursor 帳戶／設定 | 是（平台） | 通常是／自管 |
+| **Claude Code 鉤子** | 一級支援 | MCP 工具 | 否 | MCP 工具 | 不特別針對 Claude Code |
+| **儀表板** | 內建 | 內建 | Cursor 設定 | 平台儀表板 | 平台／圖表工具 |
+| **取捨** | 簡潔的本地方案，不適合企業規模 | 更寬泛的本地應用足跡 | 綁定到 Cursor | 強大的受管平台，較少本地優先 | 強大的圖形模型，設定更複雜 |
 
-- 本地優先：資料存在你自己的 SQLite 檔案裡
-- 安裝輕量：`npm install -g` 後即可使用
-- 整合直接：同時支援 CLI、HTTP、MCP
-- 對 Claude Code 友善：有 hooks，可在工作流中自動帶入相關記憶
-- 可檢視可清理：內建 dashboard，不是黑盒子
-- 較安全的匯入邊界：匯入記憶預設可搜尋，但不會直接自動注入到 Claude hooks，除非你重新檢閱或本地重存
+**MeMesh 用立即可用的本地設定、可檢查的儲存和程式開發代理工作流鉤子來交換企業級受管基礎設施。**
 
-## 在 Claude Code 會自動做什麼？
+---
 
-MeMesh 目前會在 5 個時機點協助你：
+## Claude Code 自動進行的事情
 
-- session 開始時，載入專案相關記憶與已知教訓
-- 編輯檔案前，先查回與該檔案或專案相關的記憶
-- `git commit` 後，記錄你做了什麼變更
-- session 結束時，整理本次修復、錯誤與 lesson learned
-- context compact 前，先把重要內容寫回本地記憶
+你不需要手動記住所有事情。MeMesh 有 **6 個鉤子**在你工作時自動擷取和注入知識：
 
-## Dashboard 有什麼？
+| 何時 | MeMesh 做什麼 |
+|------|------------------|
+| **每個對話開始時** | 載入最相關的記憶 + 來自過去教訓的主動警告 + 代理協調橫幅 |
+| **編輯檔案前** | 回憶與檔案或專案相關的記憶，再讓 Claude 寫程式碼 |
+| **執行 bash 命令前** | 促使 Claude 派遣高可驗證性命令（測試、構建、檢查、遷移、部署、基準測試）作為背景代理 |
+| **每次 `git commit` 後** | 記錄你的變更，包括差異統計 |
+| **Claude 停止時** | 擷取已編輯的檔案、已修復的錯誤，並從失敗自動生成結構化經驗教訓 |
+| **上下文壓縮前** | 在知識被上下文限制失去前保存 |
 
-Dashboard 目前提供 7 個分頁，並支援 11 種語言：
+> **隨時退出：** `export MEMESH_AUTO_CAPTURE=false`
 
-- Search：搜尋記憶
-- Browse：瀏覽全部記憶
-- Analytics：看健康度、趨勢與使用情況
-- Graph：看知識關聯圖
-- Lessons：看過去的教訓
-- Manage：封存或還原記憶
-- Settings：設定 LLM provider 與語言
+---
 
-## Smart Mode 是什麼？
+## 儀表板
 
-MeMesh 預設就能離線使用。若你額外設定 LLM API key，可以啟用更智慧的能力，例如：
+7 個標籤、11 種語言、零外部相依性。伺服器執行時可在 `http://localhost:3737/dashboard` 存取。
 
-- query expansion
-- 更好的自動萃取
-- 更聰明的記憶整理與壓縮
+| 標籤 | 你會看到 |
+|-----|-------------|
+| **搜尋** | 全文 + 向量相似度搜尋所有記憶 |
+| **瀏覽** | 所有實體的分頁列表，可以歸檔／復原 |
+| **分析** | 記憶健康分數（0-100）、30 天時間線、價值指標、知識涵蓋範圍、清理建議、你的工作模式 |
+| **圖表** | 互動式力導向知識圖，具有類型篩選、搜尋、自我中心模式、近期熱力圖 |
+| **經驗教訓** | 來自過去失敗的結構化經驗教訓（錯誤、根本原因、修復、預防） |
+| **管理** | 歸檔和復原實體 |
+| **設定** | LLM 供應商設定、即時語言選擇器 |
 
-不設定也可以正常使用核心功能。
+---
 
-## 更多資訊
+## 智慧功能
 
-- 完整功能、比較、API 與 release 細節：請看 [English README](README.md)
-- 平台整合方式：請看 [docs/platforms/README.md](docs/platforms/README.md)
-- API 參考：請看 [docs/api/API_REFERENCE.md](docs/api/API_REFERENCE.md)
+**🧠 智慧搜尋** — 搜尋「登入安全」並找到關於「OAuth PKCE」的記憶。MeMesh 使用你設定的 LLM 用相關詞彙擴展查詢。
 
-## 開發與驗證
+**📊 評分排名** — 結果按相關性（30%）+ 近期性（25%）+ 頻率（15%）+ 信心（15%）+ 回憶影響（10%）+ 時間有效性（5%）排名。
+
+**🔄 知識演進** — 決策會改變。`forget` 歸檔舊記憶（永不刪除）。`supersedes` 關係連結舊 → 新。你的 AI 總是看到最新版本。
+
+**⚠️ 衝突偵測** — 如果你有兩個互相矛盾的記憶，MeMesh 會警告你。
+
+**📦 團隊共享** — `memesh export > team-knowledge.json` → 與團隊共享 → `memesh import team-knowledge.json`
+匯入的組合保持可搜尋，但 MeMesh 不會自動將匯入的記憶注入 Claude 鉤子，直到你檢查或在本地重新儲存。
+
+---
+
+## 使用範例
+
+> 「MeMesh 記得我們三週前選擇了 PKCE 而不是隱式流程。當我再次問 Claude 關於身份驗證的問題時，它已經知道了——不需要重新解釋。」
+> — **獨立開發者，正在構建 SaaS**
+
+> 「我們每個星期五導出團隊的記憶，星期一導入。每個人的 Claude 在新一周開始時都知道團隊上週學到的東西。」
+> — **3 人新創公司，共享知識庫**
+
+> 「儀表板顯示我 90% 的記憶是自動生成的對話日誌。我開始有意使用 `remember` 來記錄架構決策。改變了遊戲規則。」
+> — **發現分析標籤的開發者**
+
+---
+
+## 解鎖智慧模式（可選）
+
+MeMesh 預設離線工作。只有在想要查詢擴展、更聰明的擷取和壓縮時才添加 LLM API 金鑰：
+
+```bash
+memesh config set llm.provider anthropic
+memesh config set llm.api-key sk-ant-...
+```
+
+或使用儀表板設定標籤（視覺化設定）：
+
+```bash
+memesh  # 開啟儀表板 → 設定標籤
+```
+
+| | 等級 0（預設） | 等級 1（智慧模式） |
+|---|---|---|
+| **搜尋** | FTS5 關鍵字匹配 | + LLM 查詢擴展（~97% 召回率） |
+| **自動擷取** | 基於規則的模式 | + LLM 擷取決策和經驗教訓 |
+| **壓縮** | 不可用 | `consolidate` 壓縮冗長的記憶 |
+| **成本** | 免費，無 API 金鑰 | 約 $0.0001 / 搜尋（Haiku） |
+
+---
+
+## 全部 9 個記憶工具
+
+| 工具 | 做什麼 |
+|------|--------|
+| `remember` | 用觀察、關係和標籤儲存知識 |
+| `recall` | 智慧搜尋，包含多因素評分和 LLM 查詢擴展 |
+| `forget` | 軟體歸檔（永不刪除）或移除特定觀察 |
+| `consolidate` | LLM 驅動的冗長記憶壓縮 |
+| `export` | 在專案或團隊成員之間以 JSON 共享記憶 |
+| `import` | 匯入記憶，包含合併策略（跳過 / 覆蓋 / 追加） |
+| `learn` | 記錄來自錯誤的結構化經驗教訓（錯誤、根本原因、修復、預防） |
+| `user_patterns` | 分析你的工作模式——時間表、工具、優勢、學習領域 |
+| `verify_agent_work` | 保留背景代理工作的驗證報告；根據 `git diff` 進行現實檢查聲稱的檔案變更 |
+
+---
+
+## 架構
+
+```
+                    ┌─────────────────┐
+                    │   核心引擎      │
+                    │  （8 項操作）  │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           │                 │                 │
+     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
+           │                 │                 │
+           └─────────────────┼─────────────────┘
+                             │
+                    SQLite + FTS5 + sqlite-vec
+                    (~/.memesh/knowledge-graph.db)
+```
+
+核心與框架無關。同一邏輯從終端、HTTP 或 MCP 執行。
+
+---
+
+## 貢獻
 
 ```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 項測試
+npm run test:e2e-dashboard
 ```
+
+儀表板：`cd dashboard && npm install && npm run dev`
+
+---
+
+<p align="center">
+  <strong>MIT</strong> — 由 <a href="https://pcircle.ai">PCIRCLE AI</a> 製作
+</p>