@pcircle/memesh 4.0.1 → 4.0.3

package/README.zh-TW.md

@@ -3,253 +3,108 @@
 <p align="center">
   <h1 align="center">MeMesh LLM Memory</h1>
   <p align="center">
-    <strong>最輕量的通用 AI 記憶層。</strong><br />
-    一個 SQLite 檔案。任何 LLM。零雲端依賴。
-  </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>
+    <strong>給 Claude Code 與 MCP coding agents 的本地記憶層。</strong><br />
+    一個 SQLite 檔案。不需要 Docker。不需要雲端。
   </p>
 </p>
 
----
+> 這份繁體中文 README 是精簡導覽版。若要查看最新、最完整的內容，請以 [English README](README.md) 為準。
 
-## 問題所在
+## 問題是什麼？
 
-你的 AI 在每次對話結束後都會忘記一切。每一個決策、每一次修復、每一個學到的教訓——全部歸零。你不斷重新解釋相同的背景，Claude 反覆重新發現相同的模式，而你的 AI 知識庫每次都從零開始。
+coding agent 在每次 session 之間都很容易失去上下文。架構決策、除錯過程、踩過的坑、專案限制，常常要一講再講。
 
-**MeMesh 讓每個 AI 都能擁有持久、可搜尋、持續進化的記憶。**
+**MeMesh 讓這些知識留在本機、可搜尋、可檢視，也能在之後的工作裡再次被召回。**
 
----
+這個 npm package 是 MeMesh 的本地 plugin / package 版本，重點是本地記憶，不是雲端工作台，也不是企業平台。
 
-## 60 秒快速上手
+## 60 秒快速開始
 
-### 步驟一：安裝
+### 1. 安裝
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### 步驟二：AI 開始記憶
+### 2. 記下一個決策
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### 步驟三：AI 召回記憶
+### 3. 之後再找回來
 
 ```bash
 memesh recall "login security"
-# → 搜尋「login security」也能找到「OAuth 2.0 with PKCE」
+# → 即使換了說法，也能找回 "OAuth 2.0 with PKCE"
 ```
 
-**就這樣。** MeMesh 已開始在不同對話之間記憶與召回。
-
-執行以下指令探索你的記憶庫：
+打開 dashboard：
 
 ```bash
 memesh
 ```
 
-<p align="center">
-  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — 瞬間找到任何記憶" width="100%" />
-</p>
-
-<p align="center">
-  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — 深入了解 AI 的知識" width="100%" />
-</p>
-
-<p align="center">
-  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — 互動式知識圖譜，支援類型篩選與自我模式" width="100%" />
-</p>
-
----
-
-## 這是為誰設計的？
-
-| 如果你是… | MeMesh 能幫你… |
-|---------------|---------------------|
-| **使用 Claude Code 的開發者** | 自動記憶決策、模式與每次對話中的心得 |
-| **以 LLM 打造產品的團隊** | 透過匯出/匯入共享團隊知識，讓每個人的 AI 脈絡保持一致 |
-| **AI Agent 開發者** | 透過 MCP、HTTP API 或 Python SDK 賦予 Agent 持久記憶 |
-| **同時使用多款 AI 工具的重度用戶** | 一個記憶層，相容 Claude、GPT、LLaMA、Ollama 或任何 MCP 客戶端 |
-
----
-
-## 與所有工具相容
-
-<table>
-<tr>
-<td width="33%" align="center">
-
-**Claude Code / Desktop**
-```bash
-memesh-mcp
-```
-MCP 協議（自動設定）
-
-</td>
-<td width="33%" align="center">
-
-**Python / LangChain**
-```python
-from memesh import MeMesh
-m = MeMesh()
-m.recall("auth")
-```
-`pip install memesh`
-
-</td>
-<td width="33%" align="center">
-
-**任何 LLM（OpenAI 格式）**
-```bash
-memesh export-schema \
-  --format openai
-```
-貼入任何 API 呼叫
-
-</td>
-</tr>
-</table>
-
----
-
-## 為何不用 Mem0 / Zep？
+## 這個工具適合誰？
 
-| | **MeMesh** | Mem0 | Zep |
-|---|---|---|---|
-| **安裝時間** | 5 秒 | 30–60 分鐘 | 30+ 分鐘 |
-| **設定方式** | `npm i -g` — 完成 | Neo4j + VectorDB + API 金鑰 | Neo4j + 設定 |
-| **儲存方式** | 單一 SQLite 檔案 | Neo4j + Qdrant | Neo4j |
-| **離線使用** | 支援，始終如此 | 不支援 | 不支援 |
-| **儀表板** | 內建（7 個頁籤 + 分析） | 無 | 無 |
-| **依賴套件** | 6 | 20+ | 10+ |
-| **價格** | 永久免費 | 免費方案／付費 | 免費方案／付費 |
+- 使用 Claude Code、希望跨 session 保留專案脈絡的開發者
+- 使用 MCP coding agents、想共用同一份本地記憶的進階使用者
+- 小型 AI-native 開發團隊，想透過 export / import 共用專案知識
+- 想用 CLI、HTTP 或 MCP 把本地記憶接進工具流程的 agent 開發者
 
-**MeMesh 的取捨：** 放棄企業級多租戶功能，換來**即時安裝、零基礎設施、百分之百隱私**。
+## 為什麼用 MeMesh？
 
----
+- 本地優先：資料存在你自己的 SQLite 檔案裡
+- 安裝輕量：`npm install -g` 後即可使用
+- 整合直接：同時支援 CLI、HTTP、MCP
+- 對 Claude Code 友善：有 hooks，可在工作流中自動帶入相關記憶
+- 可檢視可清理：內建 dashboard，不是黑盒子
+- 較安全的匯入邊界：匯入記憶預設可搜尋，但不會直接自動注入到 Claude hooks，除非你重新檢閱或本地重存
 
-## 自動運作的功能
+## 在 Claude Code 會自動做什麼？
 
-你不需要手動記憶每一件事。MeMesh 有 **4 個 Hook**，在你不做任何事的情況下自動擷取知識：
+MeMesh 目前會在 5 個時機點協助你：
 
-| 時機 | MeMesh 做了什麼 |
-|------|------------------|
-| **每次工作階段開始** | 載入最相關的記憶 + 來自過去教訓的主動警告 |
-| **每次 `git commit` 後** | 記錄你的變更內容與差異統計 |
-| **Claude 結束時** | 擷取已編輯的檔案、已修復的錯誤，並自動從失敗中產生結構化教訓 |
-| **上下文壓縮前** | 在知識因上下文限制消失前儲存起來 |
+- session 開始時，載入專案相關記憶與已知教訓
+- 編輯檔案前，先查回與該檔案或專案相關的記憶
+- `git commit` 後，記錄你做了什麼變更
+- session 結束時，整理本次修復、錯誤與 lesson learned
+- context compact 前，先把重要內容寫回本地記憶
 
-> **隨時退出：** `export MEMESH_AUTO_CAPTURE=false`
+## Dashboard 有什麼？
 
----
+Dashboard 目前提供 7 個分頁，並支援 11 種語言：
 
-## 儀表板
+- Search：搜尋記憶
+- Browse：瀏覽全部記憶
+- Analytics：看健康度、趨勢與使用情況
+- Graph：看知識關聯圖
+- Lessons：看過去的教訓
+- Manage：封存或還原記憶
+- Settings：設定 LLM provider 與語言
 
-7 個頁籤、11 種語言、零外部依賴。伺服器啟動後在 `http://localhost:3737/dashboard` 存取。
+## Smart Mode 是什麼？
 
-| 頁籤 | 內容 |
-|------|------|
-| **Search** | 跨所有記憶的全文搜尋 + 向量相似度搜尋 |
-| **Browse** | 所有實體的分頁列表，支援封存/還原 |
-| **Analytics** | 記憶健康分數（0-100）、30 天時間軸、價值指標、知識覆蓋率、清理建議、你的工作模式 |
-| **Graph** | 互動式力導向知識圖譜，支援類型篩選、搜尋、自我模式、時間熱力圖 |
-| **Lessons** | 從過去失敗中產生的結構化教訓（錯誤、根因、修復方法、預防措施） |
-| **Manage** | 封存與還原實體 |
-| **Settings** | LLM 提供者設定、語言選擇 |
+MeMesh 預設就能離線使用。若你額外設定 LLM API key，可以啟用更智慧的能力，例如：
 
----
+- query expansion
+- 更好的自動萃取
+- 更聰明的記憶整理與壓縮
 
-## 智慧功能
+不設定也可以正常使用核心功能。
 
-**🧠 智慧搜尋** — 搜尋「login security」就能找到關於「OAuth PKCE」的記憶。MeMesh 使用你設定的 LLM 將查詢擴展為相關詞彙。
+## 更多資訊
 
-**📊 評分排名** — 結果依相關性（35%）+ 最近使用時間（25%）+ 使用頻率（20%）+ 可信度（15%）+ 資訊時效性（5%）排序。
+- 完整功能、比較、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)
 
-**🔄 知識演進** — 決策會改變。`forget` 是封存舊記憶（從不真正刪除）。`supersedes` 關係將舊記憶與新記憶連結。你的 AI 始終看到最新版本。
-
-**⚠️ 衝突偵測** — 若有兩條記憶相互矛盾，MeMesh 會發出警告。
-
-**📦 團隊共享** — `memesh export > team-knowledge.json` → 分享給團隊 → `memesh import team-knowledge.json`
-
----
-
-## 啟用智慧模式（選用）
-
-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） |
-
----
-
-## 全部 8 個記憶工具
-
-| 工具 | 功能說明 |
-|------|-------------|
-| `remember` | 儲存知識，支援觀察記錄、關聯關係與標籤 |
-| `recall` | 智慧搜尋，結合多因子評分與 LLM 查詢擴展 |
-| `forget` | 軟封存（從不真正刪除）或移除特定觀察記錄 |
-| `consolidate` | LLM 驅動的冗長記憶壓縮 |
-| `export` | 將記憶以 JSON 格式分享給其他專案或團隊成員 |
-| `import` | 匯入記憶，支援合併策略（跳過 / 覆寫 / 附加） |
-| `learn` | 記錄來自錯誤的結構化教訓（錯誤、根因、修復方法、預防措施） |
-| `user_patterns` | 分析你的工作模式 — 時程、工具、強項、學習方向 |
-
----
-
-## 架構
-
-```
-                    ┌─────────────────┐
-                    │   Core Engine   │
-                    │  (8 operations) │
-                    └────────┬────────┘
-           ┌─────────────────┼─────────────────┐
-           │                 │                 │
-     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 -- --run    # 413 tests
+cd memesh-llm-memory
+npm install
+npm run build
+npm test
 ```
-
-儀表板：`cd dashboard && npm install && npm run dev`
-
----
-
-<p align="center">
-  <strong>MIT</strong> — 由 <a href="https://pcircle.ai">PCIRCLE AI</a> 開發
-</p>