@pcircle/memesh 4.2.6 → 4.2.8

package/README.ko.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **활발히 개발 중인 프로젝트** — 기능이 지속적으로 업데이트되며 릴리스 간에 변경될 수 있습니다. 버그나 기능 요청이 있으면 [issue를 열어주세요](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## 문제점
 
 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버립니다. 아키텍처 결정, 버그 수정, 실패한 테스트, 힘들게 얻은 교훈 — 매번 다시 설명해야 합니다. Claude Code는 매번 새로 시작하고, 이미 알아야 할 제약 조건을 다시 발견하며, 불필요하게 컨텍스트를 소비합니다.
@@ -42,6 +45,67 @@ MeMesh의 검색 엔진은 **FTS5 단독**(핫 패스에 LLM 없음, 임베딩
 
 ---
 
+## 설치 경로 한눈에 보기
+
+MeMesh에는 **공존하는 두 가지 설치 경로**가 있습니다. 대부분의 사용자는 둘 다 필요합니다. 동일한 **메모리 데이터베이스**(`~/.memesh/knowledge-graph.db`)에 기록되므로 Claude Code 채팅에서 저장한 기억이 셸에서도 보이고 그 반대도 마찬가지입니다.
+
+```mermaid
+flowchart TB
+    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+    subgraph clients["Where you use memesh from"]
+      direction LR
+      CC["Claude Code<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
+
+    CC -->|uses| A
+    TERM -->|uses| B
+    A --> DB
+    B --> DB
+```
+
+**어느 쪽이 필요한가요?**
+
+| 하고 싶은 일 | 설치 경로 |
+|---|---|
+| Claude Code 대화에서 `/memesh` skill 사용 | Path A(플러그인) |
+| Claude Code에서 자동 캡처(session → 교훈 → 다음 recall) | Path A(플러그인) |
+| 터미널에서 `memesh remember` / `memesh recall` / `memesh doctor` 실행 | Path B(npm-global) |
+| `memesh`로 대시보드 바로 열기(`npx` 시작 지연 없음) | Path B(npm-global) |
+| `memesh-mcp`를 Cursor, Cline 또는 기타 MCP 클라이언트에 연결 | Path B(npm-global) |
+| 위 전부 | **둘 다 설치** — 충돌 없음 |
+
+> **흔한 오해**: Claude Code 플러그인은 `memesh`를 셸 `PATH`에 **추가하지 않습니다**. `/plugin install`만 실행하고 터미널에 `memesh reindex`를 입력하면 `command not found`가 나옵니다. 정상입니다 — 셸 명령을 쓰려면 `npm install -g @pcircle/memesh`도 실행해야 합니다.
+
+### ⚠️ 플러그인 설치만으로는 CLI가 설치되지 않습니다
+
+가장 흔한 혼란입니다. 한 번만 읽어두면 됩니다:
+
+- Claude Code에서 `/plugin install memesh@pcircle-memesh` → **Path A만** 설치. MCP 도구, hooks, `/memesh` skill을 제공. `memesh`를 셸 `PATH`에 **추가하지 않음**.
+- 터미널에서 `memesh reindex` / `memesh update` / `memesh doctor` 입력 → **Path B**(npm-global)가 필요. 없으면 `zsh: command not found: memesh`.
+- **Claude Code 사용자 권장 설정**: **둘 다 설치**. 공존하며 동일한 데이터베이스를 공유하고 충돌하지 않습니다.
+
+```bash
+# /plugin install ... 후에 이것도 실행:
+npm install -g @pcircle/memesh
+```
+
+Claude Code 대화에서만 memesh를 사용한다면(터미널에서 `memesh`를 입력하지 않는다면) Path A만으로 충분합니다. 나머지는 둘 다 설치하세요.
+
+---
+
 ## 60초 안에 시작하기
 
 ### 옵션 A — Claude Code 플러그인 (한 줄 설치)
@@ -221,10 +285,10 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | SQLite 데이터베이스 위치를 재정의합니다. |
 | `MEMESH_AUTO_CAPTURE` | `true` | 자동 캡처 훅(`Stop`, `PreCompact`)을 완전히 비활성화합니다. |
-| `MEMESH_AUTO_DETECT_LLM` | unset | `1`로 설정하면 memesh가 셸 환경 변수(`OPENAI_API_KEY` 등)에서 프로바이더를 자동 감지하고 BYOK 임베딩으로 전환합니다. **새 설치의 기본값은 로컬 ONNX(384-dim) 전용** — 클라우드 임베딩을 원하면 옵트인하세요. 이 플래그가 설정되지 않으면, 셸에 남아있는 `OPENAI_API_KEY`는 무시됩니다. |
+| `MEMESH_AUTO_DETECT_LLM` | 미설정(자동 감지 **켜짐**) | `0`으로 설정하면 memesh가 셸 환경에서 발견한 API 키를 사용하지 않습니다. 기본적으로 `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST`가 설정되어 있고 `~/.memesh/config.json`에 프로바이더를 구성하지 않았다면, memesh는 쓰기 측 LLM 기능(통합, 교훈 추출, 자동 태깅, dream)에 이를 사용합니다. 임베딩은 영향을 받지 않습니다 — `embedder.provider`를 명시적으로 설정하지 않는 한 로컬 ONNX(384차원)로 유지됩니다. |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | unset | `1`로 설정하면 실험적 작업 모델 프로토콜(CTO / Orchestrator / Agents 프레이밍)을 활성화합니다. 세션 시작 배너, Bash 명령 nudge, `verify_agent_work` 텔레메트리를 추가합니다. 이 프로토콜의 효과는 측정 중이며 아직 입증되지 않았습니다 — 참여하려면 옵트인하세요. **기본값은 OFF**: 코어 메모리 기능은 이 플래그 없이도 작동합니다. |
 | `MEMESH_AUTO_UPDATE` | `off` | 자동 업데이트 정책. `off`(기본값)는 자동 업데이트하지 않습니다; `patch`는 `X.Y.Z → X.Y.Z+N`을 허용합니다; `minor`는 `X.Y.Z → X.Y+1.0`을 추가합니다; `major`는 모든 bump를 허용합니다. 허용된 경우, 분리된 `npm install -g`가 세션 종료 시(Stop 훅) 실행되어 작업을 차단하지 않습니다 — 결과는 `~/.memesh/auto-update.log`에 기록됩니다. `~/.memesh/config.json`에서도 `autoUpdate`로 설정 가능합니다(env가 우선). 설치된 버전이 메인테이너에 의해 deprecated된 경우(보안 권고), `off`에서도 `patch`가 강제 허용됩니다 — minor / major bump는 조용한 동작 변화를 피하기 위해 수동으로 유지됩니다. |
-| `OPENAI_API_KEY` | unset | OpenAI 키. `MEMESH_AUTO_DETECT_LLM=1`이거나 명시적으로 프로바이더를 구성한 경우에만 사용됩니다. |
+| `OPENAI_API_KEY` | 미설정 | OpenAI 키. `MEMESH_AUTO_DETECT_LLM=0`을 설정하거나 프로바이더를 명시적으로 구성하지 않는 한 LLM 기능에 자동으로 사용됩니다. |
 | `OLLAMA_HOST` | `http://localhost:11434` | 로컬 Ollama 프로바이더를 사용할 때 Ollama 엔드포인트를 재정의합니다. |
 
 `memesh doctor`는 활성화된 항목을 볼 수 있도록 해결된 구성을 출력합니다.
@@ -295,6 +359,17 @@ memesh config set llm.api-key sk-ant-...
 memesh  # 대시보드 열기 → Settings 탭
 ```
 
+### 자체 임베딩 사용 (선택)
+
+임베딩은 기본적으로 로컬 ONNX 모델(`Xenova/all-MiniLM-L6-v2`, 384차원)을 사용합니다 — API 키 불필요, 데이터가 기기를 벗어나지 않으며, 기본 FTS5 리콜은 아예 필요하지 않습니다. 호스팅형 또는 로컬 서버 임베더를 쓰려면:
+
+```bash
+memesh config set embedder.provider openai          # or: ollama
+memesh config set embedder.model text-embedding-3-small
+```
+
+임베더는 **채팅 LLM과 독립적으로** 구성됩니다 — `llm.provider`를 바꿔도 임베딩이 조용히 바뀌지 않습니다. 다른 차원(예: 384 → 1536)으로 전환하면 MeMesh가 다음 쓰기 시 벡터 인덱스를 자동으로 재구축합니다. 지원되는 `embedder.provider`: `onnx`(기본, 로컬), `openai`, `ollama`.
+
 | | Level 0 (기본) | Level 1 (스마트 모드) |
 |---|---|---|
 | **검색** | FTS5 + sqlite-vec, R@5 95.40% (~18ms/쿼리) | 변경 없음 — 회상은 모든 레벨에서 LLM-free |
@@ -343,6 +418,35 @@ memesh  # 대시보드 열기 → Settings 탭
 
 ---
 
+## 업그레이드
+
+Claude Code의 plugin marketplace는 설치 시 버전을 고정하며 **자동으로 업데이트되지 않습니다**. 새 릴리스를 가져오려면:
+
+**옵션 A — `/plugin` UI**: `memesh@pcircle-memesh`를 제거한 후 다시 설치합니다. Claude Code가 marketplace의 최신 버전을 가져옵니다.
+
+**옵션 B — 한 줄 스크립트** (UI 클릭 불필요, 멱등):
+
+```bash
+# plugin이 v4.2.5 이상이면 스크립트가 함께 제공됩니다:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# v4.2.5 이전 버전(즉 v4.2.4 또는 v4.2.3)을 설치한 경우,
+# 스크립트가 plugin에 아직 없습니다. npm-global 사본을 사용하세요:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (이는 `npm install -g @pcircle/memesh`도 실행했다고 가정합니다. 아직 안 했다면
+# 지금이 적기입니다 — 위의 "설치 경로 한눈에 보기" 섹션에서 대부분의 사용자가
+# 두 경로를 모두 원하는 이유를 확인하세요.)
+```
+
+스크립트는 marketplace cache를 fast-forward하고, 새 버전을 `~/.claude/plugins/cache/`에 스테이징하고, runtime deps를 설치하고, `installed_plugins.json`을 새 버전으로 다시 가리킵니다. 완료 후 MCP server가 다시 연결되도록 Claude Code를 재시작하세요.
+
+**npm-global 설치**(`npm install -g @pcircle/memesh`)는 `memesh update`로 자체 업데이트할 수 있습니다. Source checkouts: `git pull && npm install && npm run build`.
+
+세션 시작 시 새 릴리스가 있으면 한 줄 배너가 표시됩니다(버전당 24시간 스로틀). `memesh doctor`는 업그레이드 대상과 채널별 명령을 보고합니다.
+
+---
+
 ## 기여하기
 
 ```bash

package/README.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Actively developed project** — features evolve and may change between releases. If you hit a bug or have a feature request, please [open an issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## The Problem
 
 Your coding agent forgets what happened between sessions. Every architecture decision, bug fix, failed test, and hard-won lesson has to be re-explained. Claude Code starts fresh, re-discovers old constraints, and burns context on things it should already know.
@@ -42,6 +45,65 @@ Reproduction commands, dataset SHA256, raw per-question results, and known-failu
 
 ---
 
+## Install paths at a glance
+
+MeMesh has **two install paths that coexist**. Most users want both. They write to the **same memory database** (`~/.memesh/knowledge-graph.db`), so memories captured in Claude Code chat appear in your shell, and vice versa.
+
+```mermaid
+flowchart TB
+    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+    subgraph clients["Where you use memesh from"]
+      direction LR
+      CC["Claude Code<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
+
+    CC -->|uses| A
+    TERM -->|uses| B
+    A --> DB
+    B --> DB
+```
+
+**Which one do you need?**
+
+| What you want to do | Install path |
+|---|---|
+| Use the `/memesh` skill inside a Claude Code conversation | Path A (plugin) |
+| Get auto-capture (sessions → lessons → recall) in Claude Code | Path A (plugin) |
+| Run `memesh remember` / `memesh recall` / `memesh doctor` in any terminal | Path B (npm-global) |
+| Open the local dashboard via `memesh` (no `npx` lookup delay) | Path B (npm-global) |
+| Plug `memesh-mcp` into Cursor, Cline, or another MCP client | Path B (npm-global) |
+| All of the above | **Install both** — they don't conflict |
+
+### ⚠️ Installing the plugin does NOT install the CLI
+
+This is the most common confusion. Read this once and you'll save yourself the loop:
+
+- `/plugin install memesh@pcircle-memesh` from inside Claude Code → installs **Path A only**. Gives you MCP tools, hooks, the `/memesh` skill. Does **NOT** put `memesh` on your shell `PATH`.
+- `memesh reindex` / `memesh update` / `memesh doctor` typed in a normal terminal → needs **Path B** (npm-global). Without it: `zsh: command not found: memesh`.
+- **Recommended setup for Claude Code users**: install **both**. They coexist, share the same database, never conflict.
+
+```bash
+# After /plugin install ..., also run this:
+npm install -g @pcircle/memesh
+```
+
+If you only use memesh through Claude Code chat (never type `memesh` in a terminal), Path A alone is enough. Everyone else: install both.
+
+---
+
 ## Get Started in 60 Seconds
 
 ### Option A — Claude Code plugin (one-line install)
@@ -53,7 +115,11 @@ If you use Claude Code, install MeMesh as a plugin from inside the CLI:
 /plugin install memesh@pcircle-memesh
 ```
 
-Claude Code wires hooks, skills, and the MCP server automatically. You get in-session auto-capture, proactive recall, the `/memesh` skill (remember / recall / learn / forget) inside the Claude Code conversation, and `remember` / `recall` / `forget` / `learn` available as MCP tools to the agent. The CLI and the local dashboard are also fully accessible without any extra global install — `npx @pcircle/memesh <command>` runs every CLI command, and `npx @pcircle/memesh` launches the dashboard at `localhost:3737`. The MCP server runs directly from the plugin's bundled compiled output — no `npx` lookup, no `npm install -g`, no build step needed. If the native `better-sqlite3` binding is missing on first start (e.g. after a Node major upgrade), the launcher self-heals by rebuilding it in-process before continuing.
+Claude Code wires hooks, skills, and the MCP server automatically. You get in-session auto-capture, proactive recall, the `/memesh` skill (remember / recall / learn / forget) inside the Claude Code conversation, and `remember` / `recall` / `forget` / `learn` available as MCP tools to the agent.
+
+The MCP server runs directly from the plugin's bundled compiled output — no `npx` lookup, no build step needed. If the native `better-sqlite3` binding is missing on first start (e.g. after a Node major upgrade), the launcher self-heals by rebuilding it in-process.
+
+> **This installs the plugin only.** You can run CLI commands via `npx @pcircle/memesh <command>` if you absolutely don't want a global install, but typing plain `memesh` in a terminal will report `command not found`. To get a real shell `memesh` command, also run **Option B** below — both paths coexist and share the same memory database. The "Install paths at a glance" diagram above covers this.
 
 ### Option B — npm global (optional optimisation)
 
@@ -221,10 +287,10 @@ All configuration is via environment variables. Defaults are local-only and zero
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Override the SQLite database location. |
 | `MEMESH_AUTO_CAPTURE` | `true` | Disable the auto-capture hooks (`Stop`, `PreCompact`) entirely. |
-| `MEMESH_AUTO_DETECT_LLM` | unset | Set to `1` to let memesh auto-detect a provider from your shell env (`OPENAI_API_KEY` etc.) and switch to BYOK embeddings. **Default fresh-install is local ONNX (384-dim) only** — opt in if you want cloud embeddings. Without this flag set, an `OPENAI_API_KEY` lying around in your shell is ignored. |
+| `MEMESH_AUTO_DETECT_LLM` | unset (auto-detect **on**) | Set to `0` to stop memesh using an API key it finds in your shell env. By default, if `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` is set and you have not configured a provider in `~/.memesh/config.json`, memesh uses it for write-side LLM features (consolidation, lesson extraction, auto-tagging, dream). Embeddings are unaffected — they stay local ONNX (384-dim) unless you explicitly set `embedder.provider`. |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | unset | Set to `1` to enable an experimental working-model protocol (CTO / Orchestrator / Agents framing). Adds a session-start banner, a Bash command nudge, and `verify_agent_work` telemetry. The protocol's effectiveness is being instrumented, not yet proven — opt in if you want to participate. **Default is OFF**: the core memory features work without this flag. |
 | `MEMESH_AUTO_UPDATE` | `off` | Auto-update policy. `off` (default) never auto-updates; `patch` allows `X.Y.Z → X.Y.Z+N`; `minor` adds `X.Y.Z → X.Y+1.0`; `major` allows any bump. When permitted, a detached `npm install -g` fires at session end (Stop hook) so it never blocks your work — outcomes land in `~/.memesh/auto-update.log`. Also settable as `autoUpdate` in `~/.memesh/config.json` (env wins). When the installed version is deprecated by maintainers (security advisory), `patch` is force-allowed even on `off` — minor / major bumps still stay manual to avoid silent behaviour drift. |
-| `OPENAI_API_KEY` | unset | Your OpenAI key. Only used when `MEMESH_AUTO_DETECT_LLM=1` or you explicitly configure the provider. |
+| `OPENAI_API_KEY` | unset | Your OpenAI key. Used automatically for LLM features unless you set `MEMESH_AUTO_DETECT_LLM=0` or configure a provider explicitly. |
 | `OLLAMA_HOST` | `http://localhost:11434` | Override the Ollama endpoint when using a local Ollama provider. |
 
 `memesh doctor` prints the resolved configuration so you can see what's active.
@@ -295,6 +361,17 @@ Or use the dashboard Settings tab (visual setup):
 memesh  # opens dashboard → Settings tab
 ```
 
+### Bring-your-own embeddings (optional)
+
+Embeddings default to a local ONNX model (`Xenova/all-MiniLM-L6-v2`, 384-dim) — no API key, nothing leaves your machine, and the default FTS5 recall path doesn't need them at all. To use a hosted or local-server embedder instead:
+
+```bash
+memesh config set embedder.provider openai          # or: ollama
+memesh config set embedder.model text-embedding-3-small
+```
+
+The embedder is configured **independently of the chat LLM** — changing `llm.provider` never silently changes your embeddings. If you switch to an embedder with a different dimension (e.g. 384 → 1536), MeMesh rebuilds the vector index automatically on the next write. Supported `embedder.provider` values: `onnx` (default, local), `openai`, `ollama`.
+
 | | Level 0 (default) | Level 1 (Smart Mode) |
 |---|---|---|
 | **Search** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms/query) | unchanged — recall is LLM-free at every level |
@@ -352,7 +429,16 @@ Claude Code's plugin marketplace pins versions at install time and does **not**
 **Option B — one-line script** (no UI clicking, idempotent):
 
 ```bash
+# If your plugin install is v4.2.5 or newer, the script ships inside it:
 bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# If you installed before v4.2.5 (i.e. you're on v4.2.4 or v4.2.3),
+# the script isn't in your plugin yet. Use the npm-global copy instead:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (That assumes you've also run `npm install -g @pcircle/memesh`. If you
+# haven't, this is also a good moment to — see the "Install paths at a
+# glance" section above for why most users want both paths.)
 ```
 
 The script fast-forwards the marketplace cache, stages the new version under `~/.claude/plugins/cache/`, installs runtime deps, and re-points `installed_plugins.json`. Restart Claude Code afterwards so the MCP server reconnects.

package/README.pt.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Projeto em desenvolvimento ativo** — funcionalidades evoluem continuamente e podem mudar entre releases. Em caso de bug ou pedido de funcionalidade, por favor [abra uma issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## O Problema
 
 Seu agente de código esquece tudo entre sessões. Toda decisão arquitetônica, correção de bug, teste que falhou e lição conquistada na marra precisa ser re-explicada. Claude Code sempre começa do zero, redescobre restrições antigas e queima contexto em coisas que já deveria saber.
@@ -42,6 +45,67 @@ Comandos de reprodução, SHA256 do dataset, resultados brutos por pergunta e an
 
 ---
 
+## Caminhos de instalação resumidos
+
+MeMesh tem **dois caminhos de instalação que coexistem**. A maioria dos usuários quer ambos. Ambos escrevem no **mesmo banco de dados de memória** (`~/.memesh/knowledge-graph.db`), então memórias capturadas no chat do Claude Code aparecem no seu shell, e vice-versa.
+
+```mermaid
+flowchart TB
+    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+    subgraph clients["Where you use memesh from"]
+      direction LR
+      CC["Claude Code<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
+
+    CC -->|uses| A
+    TERM -->|uses| B
+    A --> DB
+    B --> DB
+```
+
+**Qual você precisa?**
+
+| O que você quer fazer | Caminho de instalação |
+|---|---|
+| Usar o skill `/memesh` numa conversa do Claude Code | Path A (plugin) |
+| Auto-captura no Claude Code (sessão → lições → recall seguinte) | Path A (plugin) |
+| Rodar `memesh remember` / `memesh recall` / `memesh doctor` em qualquer terminal | Path B (npm-global) |
+| Abrir o dashboard via `memesh` (sem atraso de inicialização do `npx`) | Path B (npm-global) |
+| Conectar `memesh-mcp` ao Cursor, Cline ou outro cliente MCP | Path B (npm-global) |
+| Tudo acima | **Instale ambos** — não conflitam |
+
+> **Confusão comum**: o plugin do Claude Code **não** coloca `memesh` no `PATH` do seu shell. Se você só rodar `/plugin install` e depois digitar `memesh reindex` num terminal, vai ver `command not found`. É normal — adicione `npm install -g @pcircle/memesh` também para acesso pelo shell.
+
+### ⚠️ Instalar o plugin NÃO instala o CLI
+
+É a confusão mais comum. Leia uma vez e economize tempo no futuro:
+
+- `/plugin install memesh@pcircle-memesh` no Claude Code → instala **apenas Path A**. Te dá ferramentas MCP, hooks, o skill `/memesh`. **NÃO** coloca `memesh` no `PATH` do seu shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` num terminal → precisa do **Path B** (npm-global). Sem ele: `zsh: command not found: memesh`.
+- **Configuração recomendada para usuários do Claude Code**: **instale ambos**. Coexistem, compartilham o mesmo banco, sem conflito.
+
+```bash
+# Depois de /plugin install ..., rode também isto:
+npm install -g @pcircle/memesh
+```
+
+Se você só usa memesh pelo chat do Claude Code (nunca digita `memesh` num terminal), Path A sozinho basta. Os demais: instale ambos.
+
+---
+
 ## Comece em 60 Segundos
 
 ### Passo 1: Instale
@@ -194,10 +258,10 @@ Toda a configuração é feita por variáveis de ambiente. Os padrões são loca
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Sobrescreve a localização do banco SQLite. |
 | `MEMESH_AUTO_CAPTURE` | `true` | Desativa completamente os hooks de auto-captura (`Stop`, `PreCompact`). |
-| `MEMESH_AUTO_DETECT_LLM` | unset | Defina como `1` para que o memesh detecte automaticamente um provedor a partir do seu env de shell (`OPENAI_API_KEY` etc.) e mude para embeddings BYOK. **A instalação fresca por padrão é apenas ONNX local (384-dim)** — opte se quiser embeddings na nuvem. Sem essa flag, uma `OPENAI_API_KEY` esquecida no seu shell é ignorada. |
+| `MEMESH_AUTO_DETECT_LLM` | não definido (autodetecção **ligada**) | Defina como `0` para que o memesh NÃO use uma chave de API encontrada no ambiente do shell. Por padrão, se `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` estiver definida e você não tiver configurado um provedor em `~/.memesh/config.json`, o memesh a usa para as funções LLM de escrita (consolidação, extração de lições, autotagging, dream). Os embeddings não são afetados — permanecem em ONNX local (384-dim) a menos que você defina `embedder.provider` explicitamente. |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | unset | Defina como `1` para habilitar um protocolo experimental de modelo de trabalho (enquadramento CTO / Orchestrator / Agents). Adiciona um banner de início de sessão, um nudge para comandos Bash e telemetria `verify_agent_work`. A eficácia do protocolo está sendo instrumentada, ainda não comprovada — opte se quiser participar. **Padrão é OFF**: as funcionalidades de memória core funcionam sem essa flag. |
 | `MEMESH_AUTO_UPDATE` | `off` | Política de auto-update. `off` (padrão) nunca faz auto-update; `patch` permite `X.Y.Z → X.Y.Z+N`; `minor` adiciona `X.Y.Z → X.Y+1.0`; `major` permite qualquer bump. Quando permitido, um `npm install -g` desanexado dispara no fim da sessão (hook Stop) para nunca bloquear seu trabalho — os resultados aparecem em `~/.memesh/auto-update.log`. Também configurável como `autoUpdate` em `~/.memesh/config.json` (env vence). Quando a versão instalada é depreciada pelos mantenedores (advisory de segurança), `patch` é forçado mesmo em `off` — bumps minor / major continuam manuais para evitar drift silencioso de comportamento. |
-| `OPENAI_API_KEY` | unset | Sua chave OpenAI. Usada apenas quando `MEMESH_AUTO_DETECT_LLM=1` ou você configura o provedor explicitamente. |
+| `OPENAI_API_KEY` | não definido | Sua chave da OpenAI. Usada automaticamente para as funções LLM a menos que você defina `MEMESH_AUTO_DETECT_LLM=0` ou configure um provedor explicitamente. |
 | `OLLAMA_HOST` | `http://localhost:11434` | Sobrescreve o endpoint do Ollama ao usar um provedor Ollama local. |
 
 `memesh doctor` imprime a configuração resolvida para você ver o que está ativo.
@@ -268,6 +332,17 @@ Ou use a aba Settings do dashboard (setup visual):
 memesh  # abre dashboard → aba Settings
 ```
 
+### Use seus próprios embeddings (opcional)
+
+Os embeddings usam por padrão um modelo ONNX local (`Xenova/all-MiniLM-L6-v2`, 384-dim) — sem chave de API, nada sai da sua máquina, e o recall FTS5 padrão nem precisa deles. Para usar um embedder hospedado ou de servidor local:
+
+```bash
+memesh config set embedder.provider openai          # or: ollama
+memesh config set embedder.model text-embedding-3-small
+```
+
+O embedder é configurado **independentemente do LLM de chat** — mudar `llm.provider` nunca muda seus embeddings silenciosamente. Se você trocar para uma dimensão diferente (ex.: 384 → 1536), o MeMesh reconstrói o índice vetorial automaticamente na próxima escrita. Valores de `embedder.provider` suportados: `onnx` (padrão, local), `openai`, `ollama`.
+
 | | Level 0 (padrão) | Level 1 (Smart Mode) |
 |---|---|---|
 | **Busca** | FTS5 + sqlite-vec, 95,40% R@5 (~18ms/query) | inalterado — recall é LLM-free em todos os níveis |
@@ -316,6 +391,35 @@ Core é agnóstico a framework. A mesma lógica roda de terminal, HTTP ou MCP.
 
 ---
 
+## Atualizando
+
+O plugin marketplace do Claude Code fixa versões no momento da instalação e **não** atualiza automaticamente. Para obter uma nova versão:
+
+**Opção A — UI `/plugin`**: desinstale `memesh@pcircle-memesh`, depois reinstale. O Claude Code busca a versão mais recente do marketplace.
+
+**Opção B — Script de uma linha** (sem cliques na UI, idempotente):
+
+```bash
+# Se o seu plugin instalado for v4.2.5 ou mais recente, o script já está incluído:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Se você instalou antes de v4.2.5 (ou seja, v4.2.4 ou v4.2.3),
+# o script ainda não está no seu plugin. Use a cópia npm-global no lugar:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Isso assume que você também executou `npm install -g @pcircle/memesh`. Se não,
+# este é um bom momento para fazê-lo — veja a seção "Caminhos de instalação resumidos"
+# acima para entender por que a maioria dos usuários quer ambos os caminhos.)
+```
+
+O script fast-forwarded o cache do marketplace, prepara a nova versão em `~/.claude/plugins/cache/`, instala runtime deps e repõe o ponteiro de `installed_plugins.json`. Reinicie o Claude Code depois para o MCP server reconectar.
+
+**Instalações npm-global** (`npm install -g @pcircle/memesh`) podem se auto-atualizar via `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+No início da sessão aparece um banner de uma linha (limitado a uma vez por 24h por versão) quando há uma nova versão disponível, e `memesh doctor` reporta o alvo de upgrade com o comando específico do canal.
+
+---
+
 ## Contribuindo
 
 ```bash

package/README.th.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **โปรเจกต์อยู่ระหว่างพัฒนาอย่างต่อเนื่อง** — ฟีเจอร์มีการอัปเดตอย่างต่อเนื่องและอาจเปลี่ยนแปลงระหว่างเวอร์ชัน หากพบบักหรือมีคำขอฟีเจอร์ กรุณา[เปิด issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)
+
 ## ปัญหา
 
 เอเจนต์คิดโค้ดลืมสิ่งที่เกิดขึ้นระหว่างเซสชัน ทุกการตัดสินใจด้านสถาปัตยกรรม การแก้บั๊ก การทดสอบที่ล้มเหลว และบทเรียนที่ยากที่สุดต้องอธิบายซ้ำ Claude Code เริ่มต้นใหม่ ค้นพบข้อจำกัดเดิม และใช้ context ไปกับสิ่งที่น่าจะรู้อยู่แล้ว
@@ -42,17 +45,93 @@
 
 ---
 
+## ภาพรวมเส้นทางการติดตั้ง
+
+MeMesh มี **เส้นทางการติดตั้งสองเส้นที่อยู่ร่วมกันได้** ผู้ใช้ส่วนใหญ่ต้องการทั้งคู่ ทั้งสองเขียนลงใน **ฐานข้อมูลความจำเดียวกัน** (`~/.memesh/knowledge-graph.db`) ดังนั้นความจำที่บันทึกในแชท Claude Code จะปรากฏใน shell และในทางกลับกัน
+
+```mermaid
+flowchart TB
+    classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+    classDef pathA  fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+    classDef pathB  fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+    classDef db     fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+    subgraph clients["Where you use memesh from"]
+      direction LR
+      CC["Claude Code<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
+
+    CC -->|uses| A
+    TERM -->|uses| B
+    A --> DB
+    B --> DB
+```
+
+**คุณต้องการเส้นทางไหน?**
+
+| สิ่งที่คุณต้องการทำ | เส้นทางการติดตั้ง |
+|---|---|
+| ใช้ skill `/memesh` ในการสนทนา Claude Code | Path A (plugin) |
+| Auto-capture ใน Claude Code (session → บทเรียน → recall ครั้งถัดไป) | Path A (plugin) |
+| รัน `memesh remember` / `memesh recall` / `memesh doctor` ใน terminal | Path B (npm-global) |
+| เปิด dashboard ผ่าน `memesh` (ไม่มีดีเลย์ของ `npx`) | Path B (npm-global) |
+| เสียบ `memesh-mcp` เข้ากับ Cursor, Cline หรือ MCP client อื่น | Path B (npm-global) |
+| ทั้งหมดข้างต้น | **ติดตั้งทั้งสอง** — ไม่ขัดแย้งกัน |
+
+> **ความเข้าใจผิดที่พบบ่อย**: plugin ของ Claude Code **ไม่** ใส่ `memesh` ลงใน `PATH` ของ shell ถ้าคุณรันแค่ `/plugin install` แล้วพิมพ์ `memesh reindex` ใน terminal คุณจะเห็น `command not found` — เป็นเรื่องปกติ ต้องเพิ่ม `npm install -g @pcircle/memesh` ด้วย เพื่อใช้คำสั่งใน shell
+
+### ⚠️ การติดตั้ง plugin ไม่ได้ติดตั้ง CLI
+
+นี่คือความสับสนที่พบบ่อยที่สุด อ่านครั้งเดียวจะประหยัดเวลาในอนาคต:
+
+- `/plugin install memesh@pcircle-memesh` จากภายใน Claude Code → ติดตั้ง **เฉพาะ Path A**ให้ MCP tools, hooks, skill `/memesh`**ไม่ได้** ใส่ `memesh` ลงใน `PATH` ของ shell
+- `memesh reindex` / `memesh update` / `memesh doctor` ใน terminal → ต้องใช้ **Path B** (npm-global) ถ้าไม่มี: `zsh: command not found: memesh`
+- **การติดตั้งที่แนะนำสำหรับผู้ใช้ Claude Code**: **ติดตั้งทั้งสอง** อยู่ร่วมกัน ใช้ DB เดียวกัน ไม่ขัดแย้งกัน
+
+```bash
+# หลังจาก /plugin install ... ให้รันคำสั่งนี้ด้วย:
+npm install -g @pcircle/memesh
+```
+
+ถ้าคุณใช้ memesh ผ่านแชท Claude Code เท่านั้น (ไม่เคยพิมพ์ `memesh` ใน terminal), Path A อย่างเดียวก็พอ คนอื่นๆ ให้ติดตั้งทั้งสอง
+
+---
+
 ## เริ่มต้นใน 60 วินาที
 
-### ขั้นตอนที่ 1: ติดตั้ง
+### ตัวเลือก A — Claude Code plugin (ติดตั้งด้วยบรรทัดเดียว)
+
+ถ้าใช้ Claude Code ติดตั้ง MeMesh เป็น plugin จากใน CLI ได้เลย:
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin install memesh@pcircle-memesh
+```
+
+Claude Code จะเชื่อม hooks, skills และ MCP server ให้อัตโนมัติ คุณจะได้ auto-capture ในระหว่าง session, การเรียกคืนแบบเชิงรุก, `/memesh` skill (remember / recall / learn / forget) ในบทสนทนา Claude Code และเครื่องมือ `remember` / `recall` / `forget` / `learn` แบบ MCP สำหรับเอเจนต์ — โดยไม่ต้องลง global หรือสั่ง build เพิ่ม
+
+### ตัวเลือก B — npm global (ตัวเลือกเสริม)
+
+ถ้าต้องการ binary บน shell `PATH` (เพื่อให้ `memesh`, `memesh-mcp` ฯลฯ ใช้ได้ใน terminal ใดก็ได้โดยไม่ต้องผ่าน `npx`) หรือต้องการเปิด `memesh-mcp` ให้ MCP client อื่น (Cursor, Cline, terminal-only flows):
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### ขั้นตอนที่ 1.5: เชื่อม MeMesh เข้ากับ Claude Code (แนะนำ, ครั้งเดียว)
+### ขั้นตอนที่ 1.5: เชื่อม MeMesh เข้ากับ Claude Code (เฉพาะเส้นทาง npm)
 
-`npm install -g` ติดตั้ง CLI ลงใน PATH และลงทะเบียน MCP server แต่**ไม่ได้**เชื่อม session hooks ของ MeMesh เข้ากับ Claude Code โดยอัตโนมัติ ถ้าไม่มี hooks เหล่านี้ คุณยังใช้ `memesh remember` / `recall` แบบ manual ได้ แต่**วงรอบจับข้อมูลอัตโนมัติ** (session → บทเรียน → เรียกคืนเชิงรุกใน session ถัดไป) จะเงียบ
+ถ้าติดตั้งผ่าน **ตัวเลือก A** (`/plugin install memesh@pcircle-memesh`) ข้ามขั้นนี้ไปได้ — Claude Code เชื่อม plugin hooks ให้แล้ว
+
+ถ้าติดตั้งผ่าน **ตัวเลือก B** (`npm install -g`) CLI อยู่บน PATH และ MCP server ลงทะเบียนแล้ว แต่ session hooks ของ Claude Code **ไม่ได้** เชื่อมอัตโนมัติ ถ้าไม่มี hooks เหล่านี้ คุณยังใช้ `memesh remember` / `recall` แบบ manual ได้ แต่**วงรอบจับข้อมูลอัตโนมัติ** (session → บทเรียน → เรียกคืนเชิงรุกใน session ถัดไป) จะเงียบ
 
 ```bash
 memesh install-hooks         # เพิ่ม hooks ของ memesh ลงใน ~/.claude/settings.json
@@ -194,10 +273,10 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | เปลี่ยนตำแหน่งฐานข้อมูล SQLite |
 | `MEMESH_AUTO_CAPTURE` | `true` | ปิดการใช้ hook จับข้อมูลอัตโนมัติทั้งหมด (`Stop`, `PreCompact`) |
-| `MEMESH_AUTO_DETECT_LLM` | ไม่ตั้ง | ตั้งเป็น `1` เพื่อให้ memesh ตรวจหาผู้ให้บริการจาก shell env (`OPENAI_API_KEY` ฯลฯ) โดยอัตโนมัติและสลับไปใช้ BYOK embeddings **ค่าเริ่มต้นของการติดตั้งใหม่คือ ONNX ภายในเครื่อง (384 มิติ) เท่านั้น** — opt-in ถ้าต้องการ embedding บนคลาวด์ ถ้าไม่ตั้งค่าธงนี้ `OPENAI_API_KEY` ที่อยู่ใน shell จะถูกเพิกเฉย |
+| `MEMESH_AUTO_DETECT_LLM` | ไม่ได้ตั้งค่า (ตรวจจับอัตโนมัติ **เปิด**) | ตั้งเป็น `0` เพื่อไม่ให้ memesh ใช้คีย์ API ที่พบในสภาพแวดล้อมของเชลล์ โดยค่าเริ่มต้น หากตั้ง `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` ไว้ และคุณยังไม่ได้กำหนดผู้ให้บริการใน `~/.memesh/config.json` memesh จะใช้คีย์นั้นสำหรับฟีเจอร์ LLM ฝั่งเขียน (consolidation, การสกัดบทเรียน, auto-tagging, dream) ส่วน embeddings ไม่ได้รับผลกระทบ — ยังคงเป็น ONNX ในเครื่อง (384 มิติ) เว้นแต่คุณจะตั้ง `embedder.provider` อย่างชัดเจน |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | ไม่ตั้ง | ตั้งเป็น `1` เพื่อเปิดใช้โปรโตคอล working-model เชิงทดลอง (กรอบ CTO / Orchestrator / Agents) เพิ่มแบนเนอร์ตอนเริ่มเซสชัน การเตือนคำสั่ง Bash และเทเลเมตรี `verify_agent_work` ประสิทธิผลของโปรโตคอลกำลังถูกเก็บข้อมูล ยังไม่ได้พิสูจน์ — opt-in ถ้าต้องการเข้าร่วม **ค่าเริ่มต้นปิด**: ฟีเจอร์หน่วยความจำหลักทำงานได้โดยไม่ต้องเปิดธงนี้ |
 | `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` แบบ detached จะทำงานเมื่อจบเซสชัน (Stop hook) เพื่อไม่บล็อกงานของคุณ — ผลลัพธ์ลงใน `~/.memesh/auto-update.log` ตั้งใน `~/.memesh/config.json` ผ่านคีย์ `autoUpdate` ก็ได้ (env ชนะ) เมื่อเวอร์ชันที่ติดตั้งถูก deprecate (security advisory) `patch` จะถูกบังคับเปิดแม้ตั้งเป็น `off` — minor / major ยังต้องทำมือเพื่อหลีกเลี่ยงการเปลี่ยนพฤติกรรมเงียบ ๆ |
-| `OPENAI_API_KEY` | ไม่ตั้ง | คีย์ OpenAI ของคุณ ใช้เฉพาะเมื่อ `MEMESH_AUTO_DETECT_LLM=1` หรือคุณตั้งค่าผู้ให้บริการอย่างชัดเจน |
+| `OPENAI_API_KEY` | ไม่ได้ตั้งค่า | คีย์ OpenAI ของคุณ ใช้โดยอัตโนมัติสำหรับฟีเจอร์ LLM เว้นแต่คุณจะตั้ง `MEMESH_AUTO_DETECT_LLM=0` หรือกำหนดผู้ให้บริการอย่างชัดเจน |
 | `OLLAMA_HOST` | `http://localhost:11434` | เปลี่ยนปลายทาง Ollama เมื่อใช้ผู้ให้บริการ Ollama ภายในเครื่อง |
 
 `memesh doctor` พิมพ์การตั้งค่าที่ resolve แล้วเพื่อให้คุณเห็นว่าอะไรทำงานอยู่
@@ -268,6 +347,17 @@ memesh config set llm.api-key sk-ant-...
 memesh  # opens dashboard → Settings tab
 ```
 
+### ใช้ embeddings ของคุณเอง (ไม่บังคับ)
+
+โดยค่าเริ่มต้น embeddings ใช้โมเดล ONNX ในเครื่อง (`Xenova/all-MiniLM-L6-v2`, 384 มิติ) — ไม่ต้องใช้คีย์ API ไม่มีข้อมูลออกจากเครื่อง และการ recall แบบ FTS5 เริ่มต้นก็ไม่ต้องใช้เลย หากต้องการใช้ embedder แบบโฮสต์หรือเซิร์ฟเวอร์ในเครื่อง:
+
+```bash
+memesh config set embedder.provider openai          # or: ollama
+memesh config set embedder.model text-embedding-3-small
+```
+
+embedder ถูกตั้งค่า**แยกจาก LLM แชท** — การเปลี่ยน `llm.provider` จะไม่เปลี่ยน embeddings ของคุณอย่างเงียบ ๆ หากเปลี่ยนไปใช้มิติที่ต่างกัน (เช่น 384 → 1536) MeMesh จะสร้างดัชนีเวกเตอร์ใหม่โดยอัตโนมัติในการเขียนครั้งถัดไป ค่า `embedder.provider` ที่รองรับ: `onnx` (ค่าเริ่มต้น ในเครื่อง), `openai`, `ollama`
+
 | | ระดับ 0 (ค่าเริ่มต้น) | ระดับ 1 (Smart Mode) |
 |---|---|---|
 | **Search** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms ต่อ query) | คงเดิม — recall ไม่ใช้ LLM ในทุก level |
@@ -316,7 +406,35 @@ Core เป็นอิสระจากเฟรมเวิร์ก ตร
 
 ---
 
-## บริจาค
+## การอัปเกรด
+
+Claude Code plugin marketplace ปักหมุดเวอร์ชันตอนติดตั้ง และ **ไม่** อัปเดตอัตโนมัติ วิธีรับเวอร์ชันใหม่:
+
+**ตัวเลือก A — `/plugin` UI**: ถอนการติดตั้ง `memesh@pcircle-memesh` แล้วติดตั้งใหม่ Claude Code จะดึงเวอร์ชันล่าสุดจาก marketplace
+
+**ตัวเลือก B — สคริปต์บรรทัดเดียว** (ไม่ต้องคลิก UI, idempotent):
+
+```bash
+# ถ้า plugin ของคุณเป็น v4.2.5 ขึ้นไป สคริปต์อยู่ในนั้นแล้ว:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# ถ้าคุณติดตั้งก่อน v4.2.5 (คือ v4.2.4 หรือ v4.2.3)
+# สคริปต์ยังไม่อยู่ใน plugin ของคุณ ใช้สำเนา npm-global แทน:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (สมมติว่าคุณรัน `npm install -g @pcircle/memesh` แล้ว ถ้ายังก็ทำตอนนี้เลย —
+# ผู้ใช้ส่วนใหญ่ต้องการทั้งสองเส้นทาง ดู "ภาพรวมเส้นทางการติดตั้ง" ด้านบน)
+```
+
+สคริปต์จะ fast-forward marketplace cache, ติดตั้งเวอร์ชันใหม่ใน `~/.claude/plugins/cache/`, ลง runtime deps และชี้ `installed_plugins.json` ไปยังเวอร์ชันใหม่ รีสตาร์ท Claude Code เพื่อให้ MCP server reconnect
+
+**การติดตั้งแบบ npm-global** (`npm install -g @pcircle/memesh`) อัปเดตได้ด้วย `memesh update` Source checkouts: `git pull && npm install && npm run build`
+
+ตอนเริ่ม session ระบบแสดง banner บรรทัดเดียว (throttle ทุก 24 ชั่วโมงต่อเวอร์ชัน) เมื่อมีเวอร์ชันใหม่ และ `memesh doctor` รายงานเวอร์ชันเป้าหมายพร้อมคำสั่งที่เหมาะกับ channel นั้น
+
+---
+
+## การร่วมพัฒนา
 
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory