@pcircle/memesh 4.1.7 → 4.2.0

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）不需要这个下载。
 
-`npm install -g` 把 CLI 放进 PATH 并注册 MCP server，但**不会**自动接上 MeMesh 的 Claude Code session hooks。没有这些 hooks，你还是可以手动用 `memesh remember` / `recall`，但**自动捕捉循环**（session → 教训 → 下次 session 主动回想）就会静默不动。
+### 第一步半：把 MeMesh 接入 Claude Code（仅 npm 路径）
+
+如果你通过**选项 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,6 +213,26 @@ 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`。
@@ -190,7 +251,7 @@ memesh export-schema \
 
 ## 聪慧功能
 
-**🧠 智能搜索** — 搜索"登录安全"会找到"OAuth PKCE"相关的记忆。MeMesh 用你配置的 LLM 扩展查询。
+**🧠 智能搜索** — 搜索"登录安全"也能找到"OAuth PKCE"相关的记忆。MeMesh 在热路径上用 FTS5 + sqlite-vec，零 LLM。
 
 **📊 评分排序** — 结果按相关性（30%）+ 新近度（25%）+ 频率（15%）+ 置信度（15%）+ 回忆影响（10%）+ 时间有效性（5%）排序。
 
@@ -218,7 +279,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 +294,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 +308,7 @@ memesh  # 打开仪表板 → 设置标签页
 | 工具 | 它做什么 |
 |------|--------|
 | `remember` | 存储知识，附带观察、关系和标签 |
-| `recall` | 智能搜索，多因素评分和 LLM 查询扩展 |
+| `recall` | FTS5 + sqlite-vec 搜索，附带多因素评分（相关性、新近度、频率、置信度、时间有效性）— 热路径上无 LLM |
 | `forget` | 软归档（永不删除）或移除特定观察 |
 | `consolidate` | LLM 驱动的冗长记忆压缩 |
 | `export` | 在项目或团队成员间共享内存，格式为 JSON |

package/README.zh-TW.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,27 +26,70 @@
 
 ---
 
+## 實證 — 在 LongMemEval-S 上 R@5 達 95.40%
+
+MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌入），對照公開的 [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++ 工具鏈。
+> - **嵌入模型** — 第一次觸發本地嵌入的呼叫（例如 semantic 模式的 `recall`）會把 `Xenova/all-MiniLM-L6-v2`（約 80 MB）下載到 `~/.memesh/models/`。後續呼叫即時生效。預設的檢索路徑（FTS5）不需要這個下載。
 
-`npm install -g` 把 CLI 放上 PATH 並註冊 MCP server，但**不會**自動接上 MeMesh 的 Claude Code session hooks。沒有這些 hooks，你還是可以手動用 `memesh remember` / `recall`，但**自動捕捉迴路**（session → 教訓 → 下次 session 主動回憶）就會靜默不動。
+### 第一步半：把 MeMesh 接進 Claude Code（僅 npm 路徑需要）
+
+如果你透過**選項 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
 memesh doctor                # 確認「Hooks wired into Claude Code」過了
 ```
 
-這些 hooks 會跟你既有的 `~/.claude/hooks/` 自訂 hooks 共存 — `install-hooks` 用追加方式寫，從不覆寫你的東西。要移除：`memesh uninstall-hooks`。
+這些 hooks 會跟你既有的 `~/.claude/hooks/` 自訂 hooks 共存 — `install-hooks` 用追加方式寫入，從不覆寫你的東西。要移除：`memesh uninstall-hooks`。
 
 ### 第二步：保存一個決策
 
+> 下方的 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"
 ```
@@ -95,7 +135,7 @@ memesh
 |---------------|---------------------|
 | **使用 Claude Code 的開發者** | 在工作時自動回憶專案決策、檔案特定的經驗教訓和過去的失敗 |
 | **程式開發代理進階使用者** | 在多個 MCP 相容工具間共享一層在地記憶 |
-| **嘗試 AI 程式開發工作流的團隊** | 導出／導入專案知識，無需引入託管基礎設施 |
+| **嘗試 AI 程式開發工作流的團隊** | 匯出／匯入專案知識，無需引入託管基礎設施 |
 | **代理開發者** | 透過 MCP、HTTP、CLI 或 Python SDK 添加在地記憶 |
 
 ---
@@ -110,7 +150,7 @@ memesh
 ```bash
 memesh-mcp
 ```
-MCP 工具 + Claude Code 鉤子
+MCP 工具 + Claude Code hooks
 
 </td>
 <td width="33%" align="center">
@@ -145,52 +185,73 @@ memesh export-schema \
 |---|---|---|---|---|---|
 | **最佳用途** | 程式開發代理的在地記憶 | 本地／跨用戶端 MCP 記憶 | Cursor 原生專案記憶 | 受管應用／代理記憶 | 時間性知識圖 |
 | **安裝方式** | `npm install -g @pcircle/memesh` | 本地應用／伺服器流程 | 內建於 Cursor | 雲端 API / SDK / MCP | 服務／框架設定 |
-| **儲存位置** | 單個本地 SQLite 檔案 | 本地記憶堆疊 | Cursor 管理的規則／記憶 | 託管或自管堆疊 | 圖形資料庫 |
+| **儲存位置** | 單一本地 SQLite 檔案 | 本地記憶堆疊 | Cursor 管理的規則／記憶 | 託管或自管堆疊 | 圖形資料庫 |
 | **需要雲端** | 否 | 否（本地模式） | 取決於 Cursor 帳戶／設定 | 是（平台） | 通常是／自管 |
-| **Claude Code 鉤子** | 一級支援 | MCP 工具 | 否 | MCP 工具 | 不特別針對 Claude Code |
+| **Claude Code hooks** | 一級支援 | MCP 工具 | 否 | MCP 工具 | 不特別針對 Claude Code |
 | **儀表板** | 內建 | 內建 | Cursor 設定 | 平台儀表板 | 平台／圖表工具 |
 | **取捨** | 簡潔的本地方案，不適合企業規模 | 更寬泛的本地應用足跡 | 綁定到 Cursor | 強大的受管平台，較少本地優先 | 強大的圖形模型，設定更複雜 |
 
-**MeMesh 用立即可用的本地設定、可檢查的儲存和程式開發代理工作流鉤子來交換企業級受管基礎設施。**
+**MeMesh 用立即可用的本地設定、可檢查的儲存和程式開發代理工作流 hooks 來交換企業級受管基礎設施。**
 
 ---
 
 ## Claude Code 自動進行的事情
 
-你不需要手動記住所有事情。MeMesh 有 **6 個鉤子**在你工作時自動擷取和注入知識：
+你不需要手動記住所有事情。MeMesh 有 **7 個 hooks**，會在你工作時自動擷取與注入知識：
 
 | 何時 | MeMesh 做什麼 |
 |------|------------------|
-| **每個對話開始時** | 載入最相關的記憶 + 來自過去教訓的主動警告 + 代理協調橫幅 |
+| **每次 session 開始時** | 載入最相關的記憶 + 來自過去教訓的主動警告 |
 | **編輯檔案前** | 回憶與檔案或專案相關的記憶，再讓 Claude 寫程式碼 |
-| **執行 bash 命令前** | 促使 Claude 派遣高可驗證性命令（測試、構建、檢查、遷移、部署、基準測試）作為背景代理 |
-| **每次 `git commit` 後** | 記錄你的變更，包括差異統計 |
-| **Claude 停止時** | 擷取已編輯的檔案、已修復的錯誤，並從失敗自動生成結構化經驗教訓 |
-| **上下文壓縮前** | 在知識被上下文限制失去前保存 |
+| **執行 bash 指令前** | （可選加入）促使 Claude 將高可驗證性指令（測試、建置、檢查、遷移、部署、基準測試）派遣為背景代理 |
+| **當你要求記住** | 偵測「remember this」／「guardar en memesh」／「sauvegarder dans memesh」／「記下來」意圖（5 種語言）並提醒 Claude 使用 memesh |
+| **每次 `git commit` 之後** | 記錄你的變更，包含 diff 統計 |
+| **Claude 停止時** | 擷取已編輯的檔案、已修復的錯誤，並從失敗自動產生結構化教訓 |
+| **上下文壓縮前** | 在知識被上下文限制丟掉之前先保存 |
 
 > **隨時退出：** `export MEMESH_AUTO_CAPTURE=false`
 
 ---
 
+## 設定
+
+所有設定都透過環境變數。預設是純本地、零網路 — 你不需要設定任何東西就能取得可運作的系統。
+
+| 變數 | 預設值 | 用途 |
+|---|---|---|
+| `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 嵌入。**全新安裝的預設僅使用本地 ONNX（384-dim）** — 想要雲端嵌入時才加入。沒設定這個旗標時，shell 中閒置的 `OPENAI_API_KEY` 會被忽略。 |
+| `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | 未設定 | 設為 `1` 啟用實驗性的工作模型協定（CTO／Orchestrator／Agents 框架）。會加上 session-start 橫幅、Bash 指令提示，以及 `verify_agent_work` 遙測。協定的有效性正在量測中、尚未獲得驗證 — 想參與時才加入。**預設關閉**：核心記憶功能不需要這個旗標就能運作。 |
+| `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` 會在 session 結束時（Stop hook）執行，避免阻塞你的工作 — 結果寫入 `~/.memesh/auto-update.log`。也可在 `~/.memesh/config.json` 中以 `autoUpdate` 設定（環境變數優先）。當已安裝版本被維護者標為 deprecated（安全公告）時，即使是 `off` 也會強制允許 `patch` — 仍維持 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` 存取。
+7 個分頁、11 種語言、零外部相依性。伺服器執行時可在 `http://localhost:3737/dashboard` 存取。
 
-| 標籤 | 你會看到 |
+| 分頁 | 你會看到 |
 |-----|-------------|
-| **搜尋** | 全文 + 向量相似度搜尋所有記憶 |
-| **瀏覽** | 所有實體的分頁列表，可以歸檔／復原 |
-| **分析** | 記憶健康分數（0-100）、30 天時間線、價值指標、知識涵蓋範圍、清理建議、你的工作模式 |
-| **圖表** | 互動式力導向知識圖，具有類型篩選、搜尋、自我中心模式、近期熱力圖 |
-| **經驗教訓** | 來自過去失敗的結構化經驗教訓（錯誤、根本原因、修復、預防） |
-| **管理** | 歸檔和復原實體 |
-| **設定** | LLM 供應商設定、即時語言選擇器 |
+| **Search** | 全文 + 向量相似度搜尋所有記憶 |
+| **Browse** | 所有實體的分頁列表，可以歸檔／復原 |
+| **Analytics** | 記憶健康分數（0-100）、30 天時間線、價值指標、知識涵蓋範圍、清理建議、你的工作模式 |
+| **Graph** | 互動式力導向知識圖，具有類型篩選、搜尋、自我中心模式、近期熱力圖 |
+| **Lessons** | 來自過去失敗的結構化教訓（錯誤、根本原因、修復、預防） |
+| **Manage** | 歸檔和復原實體 |
+| **Settings** | LLM 供應商設定、即時語言選擇器 |
 
 ---
 
 ## 智慧功能
 
-**🧠 智慧搜尋** — 搜尋「登入安全」並找到關於「OAuth PKCE」的記憶。MeMesh 使用你設定的 LLM 用相關詞彙擴展查詢。
+**🧠 智慧搜尋** — 搜尋「登入安全」並找到關於「OAuth PKCE」的記憶。MeMesh 用 FTS5 + sqlite-vec 在熱路徑上保持 LLM-free，仍能跨同義詞匹配。
 
 **📊 評分排名** — 結果按相關性（30%）+ 近期性（25%）+ 頻率（15%）+ 信心（15%）+ 回憶影響（10%）+ 時間有效性（5%）排名。
 
@@ -199,44 +260,46 @@ memesh export-schema \
 **⚠️ 衝突偵測** — 如果你有兩個互相矛盾的記憶，MeMesh 會警告你。
 
 **📦 團隊共享** — `memesh export > team-knowledge.json` → 與團隊共享 → `memesh import team-knowledge.json`
-匯入的組合保持可搜尋，但 MeMesh 不會自動將匯入的記憶注入 Claude 鉤子，直到你檢查或在本地重新儲存。
+匯入的組合保持可搜尋，但 MeMesh 不會自動將匯入的記憶注入 Claude hooks，直到你檢查或在本地重新儲存。
 
 ---
 
 ## 使用範例
 
 > 「MeMesh 記得我們三週前選擇了 PKCE 而不是隱式流程。當我再次問 Claude 關於身份驗證的問題時，它已經知道了——不需要重新解釋。」
-> — **獨立開發者，正在構建 SaaS**
+> — **獨立開發者，正在打造 SaaS**
 
-> 「我們每個星期五導出團隊的記憶，星期一導入。每個人的 Claude 在新一周開始時都知道團隊上週學到的東西。」
+> 「我們每個星期五匯出團隊的記憶，星期一匯入。每個人的 Claude 在新一週開始時都知道團隊上週學到的東西。」
 > — **3 人新創公司，共享知識庫**
 
 > 「儀表板顯示我 90% 的記憶是自動生成的對話日誌。我開始有意使用 `remember` 來記錄架構決策。改變了遊戲規則。」
-> — **發現分析標籤的開發者**
+> — **發現分析分頁的開發者**
 
 ---
 
 ## 解鎖智慧模式（可選）
 
-MeMesh 預設離線工作。只有在想要查詢擴展、更聰明的擷取和壓縮時才添加 LLM API 金鑰：
+MeMesh 預設離線運作 — 回憶嚴格保持 LLM-free（開箱即用就有 LongMemEval-S 上 95.40% R@5）。只有當你想要在上層加入 LLM 增強的分析流程時，才需要加入 LLM API 金鑰：更聰明的 session 擷取、新記憶的自動標籤、從失敗產生教訓，以及 `consolidate` / `dream` 壓縮：
 
 ```bash
 memesh config set llm.provider anthropic
 memesh config set llm.api-key sk-ant-...
 ```
 
-或使用儀表板設定標籤（視覺化設定）：
+或使用儀表板 Settings 分頁（視覺化設定）：
 
 ```bash
-memesh  # 開啟儀表板 → 設定標籤
+memesh  # 開啟儀表板 → Settings 分頁
 ```
 
 | | 等級 0（預設） | 等級 1（智慧模式） |
 |---|---|---|
-| **搜尋** | FTS5 關鍵字匹配 | + LLM 查詢擴展（~97% 召回率） |
-| **自動擷取** | 基於規則的模式 | + LLM 擷取決策和經驗教訓 |
-| **壓縮** | 不可用 | `consolidate` 壓縮冗長的記憶 |
-| **成本** | 免費，無 API 金鑰 | 約 $0.0001 / 搜尋（Haiku） |
+| **搜尋** | FTS5 + sqlite-vec，95.40% R@5（約 18ms/查詢） | 不變 — 回憶在每個等級都保持 LLM-free |
+| **自動擷取** | 基於規則的模式 | + LLM 擷取決策與教訓 |
+| **自動標籤** | 僅手動標籤 | + LLM 為新記憶產生標籤 |
+| **失敗分析** | 不可用 | + LLM 將 session 錯誤轉為結構化教訓 |
+| **壓縮** | 不可用 | `consolidate` + `dream` 壓縮冗長記憶 |
+| **成本** | 免費，無需 API 金鑰 | 約 $0.0001 / 次分析呼叫（Haiku） |
 
 ---
 
@@ -245,14 +308,14 @@ memesh  # 開啟儀表板 → 設定標籤
 | 工具 | 做什麼 |
 |------|--------|
 | `remember` | 用觀察、關係和標籤儲存知識 |
-| `recall` | 智慧搜尋，包含多因素評分和 LLM 查詢擴展 |
-| `forget` | 軟體歸檔（永不刪除）或移除特定觀察 |
+| `recall` | FTS5 + sqlite-vec 搜尋，包含多因素評分（相關性、近期性、頻率、信心、時間有效性）— 熱路徑上不使用 LLM |
+| `forget` | 軟歸檔（永不刪除）或移除特定觀察 |
 | `consolidate` | LLM 驅動的冗長記憶壓縮 |
 | `export` | 在專案或團隊成員之間以 JSON 共享記憶 |
-| `import` | 匯入記憶，包含合併策略（跳過 / 覆蓋 / 追加） |
-| `learn` | 記錄來自錯誤的結構化經驗教訓（錯誤、根本原因、修復、預防） |
+| `import` | 匯入記憶，包含合併策略（跳過 / 覆寫 / 追加） |
+| `learn` | 記錄來自錯誤的結構化教訓（錯誤、根本原因、修復、預防） |
 | `user_patterns` | 分析你的工作模式——時間表、工具、優勢、學習領域 |
-| `verify_agent_work` | 保留背景代理工作的驗證報告；根據 `git diff` 進行現實檢查聲稱的檔案變更 |
+| `verify_agent_work` | 保留背景代理工作的驗證報告；以 `git diff` 對所聲稱的檔案變更做現實檢查 |
 
 ---