@pcircle/memesh 4.2.7 → 4.2.9

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "memesh",
       "source": "./",
       "description": "MeMesh — Local memory for Claude Code and MCP coding agents. One SQLite file, zero cloud required.",
-      "version": "4.2.7",
+      "version": "4.2.9",
       "author": {
         "name": "PCIRCLE AI"
       },

package/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "4.2.7",
+  "version": "4.2.9",
   "homepage": "https://pcircle.ai/memesh-llm-memory",
   "repository": "https://github.com/PCIRCLE-AI/memesh-llm-memory",
   "license": "MIT",

package/README.de.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Aktiv entwickeltes Projekt** — Funktionen entwickeln sich kontinuierlich weiter und können sich zwischen Releases ändern. Bei Bugs oder Feature-Wünschen bitte [ein Issue eröffnen](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Das Problem
 
 Ihr Coding-Agent vergisst, was zwischen Sessions passiert ist. Jede Architekturentscheidung, jede Bugfix, jeder fehlgeschlagene Test und jede hart erarbeitete Erkenntnis muss erneut erklärt werden. Claude Code startet von vorne, entdeckt alte Constraints neu und verschwendet Context auf Dinge, die es längst wissen sollte.
@@ -254,10 +257,10 @@ Die gesamte Konfiguration erfolgt über Umgebungsvariablen. Die Standardwerte si
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Überschreibt den Speicherort der SQLite-Datenbank. |
 | `MEMESH_AUTO_CAPTURE` | `true` | Deaktiviert die Auto-Capture-Hooks (`Stop`, `PreCompact`) vollständig. |
-| `MEMESH_AUTO_DETECT_LLM` | nicht gesetzt | Auf `1` setzen, damit memesh einen Provider aus Ihrer Shell-Umgebung (`OPENAI_API_KEY` etc.) automatisch erkennt und auf BYOK-Embeddings umschaltet. **Standard bei einer frischen Installation ist ausschließlich lokales ONNX (384-dim)** — Opt-in, falls Sie Cloud-Embeddings wünschen. Ohne dieses Flag wird ein in der Shell vorhandener `OPENAI_API_KEY` ignoriert. |
+| `MEMESH_AUTO_DETECT_LLM` | nicht gesetzt (Auto-Erkennung **an**) | Auf `0` setzen, damit memesh einen im Shell-Environment gefundenen API-Schlüssel NICHT verwendet. Standardmäßig nutzt memesh einen gesetzten `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` für schreibseitige LLM-Funktionen (Konsolidierung, Lesson-Extraktion, Auto-Tagging, Dream), sofern in `~/.memesh/config.json` kein Provider konfiguriert ist. Embeddings sind nicht betroffen — sie bleiben lokal ONNX (384-dim), außer du setzt `embedder.provider` explizit. |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | nicht gesetzt | Auf `1` setzen, um ein experimentelles Working-Model-Protokoll zu aktivieren (CTO / Orchestrator / Agents-Framing). Fügt ein Session-Start-Banner, einen Bash-Befehls-Nudge und `verify_agent_work`-Telemetrie hinzu. Die Wirksamkeit des Protokolls wird derzeit instrumentiert, ist aber noch nicht erwiesen — Opt-in, falls Sie teilnehmen möchten. **Standard ist OFF**: Die Kern-Memory-Funktionen arbeiten ohne dieses Flag. |
 | `MEMESH_AUTO_UPDATE` | `off` | Auto-Update-Richtlinie. `off` (Standard) aktualisiert nie automatisch; `patch` erlaubt `X.Y.Z → X.Y.Z+N`; `minor` ergänzt `X.Y.Z → X.Y+1.0`; `major` erlaubt jedes Bump. Wenn zugelassen, läuft am Session-Ende (Stop-Hook) ein abgekoppeltes `npm install -g`, sodass es Ihre Arbeit nie blockiert — Ergebnisse landen in `~/.memesh/auto-update.log`. Ebenfalls als `autoUpdate` in `~/.memesh/config.json` setzbar (Env hat Vorrang). Wenn die installierte Version von den Maintainern als veraltet markiert wird (Sicherheitswarnung), wird `patch` auch bei `off` erzwungen erlaubt — Minor- / Major-Bumps bleiben manuell, um stille Verhaltensänderungen zu vermeiden. |
-| `OPENAI_API_KEY` | nicht gesetzt | Ihr OpenAI-Schlüssel. Wird nur verwendet, wenn `MEMESH_AUTO_DETECT_LLM=1` gesetzt ist oder Sie den Provider explizit konfigurieren. |
+| `OPENAI_API_KEY` | nicht gesetzt | Dein OpenAI-Schlüssel. Wird automatisch für LLM-Funktionen genutzt, außer du setzt `MEMESH_AUTO_DETECT_LLM=0` oder konfigurierst einen Provider explizit. |
 | `OLLAMA_HOST` | `http://localhost:11434` | Überschreibt den Ollama-Endpoint, wenn ein lokaler Ollama-Provider verwendet wird. |
 
 `memesh doctor` gibt die aufgelöste Konfiguration aus, sodass Sie sehen, was aktiv ist.
@@ -328,6 +331,17 @@ Oder nutzen Sie den Dashboard-Settings-Reiter (visuelles Setup):
 memesh  # öffnet Dashboard → Settings-Reiter
 ```
 
+### Eigene Embeddings verwenden (optional)
+
+Embeddings nutzen standardmäßig ein lokales ONNX-Modell (`Xenova/all-MiniLM-L6-v2`, 384-dim) — kein API-Schlüssel, nichts verlässt deinen Rechner, und der Standard-FTS5-Recall braucht sie gar nicht. Um stattdessen einen gehosteten oder lokalen Embedder zu nutzen:
+
+```bash
+memesh config set embedder.provider openai          # or: ollama
+memesh config set embedder.model text-embedding-3-small
+```
+
+Der Embedder wird **unabhängig vom Chat-LLM** konfiguriert — `llm.provider` zu ändern ändert nie stillschweigend deine Embeddings. Wechselst du zu einer anderen Dimension (z. B. 384 → 1536), baut MeMesh den Vektorindex beim nächsten Schreibvorgang automatisch neu auf. Unterstützte `embedder.provider`-Werte: `onnx` (Standard, lokal), `openai`, `ollama`.
+
 | | Stufe 0 (Standard) | Stufe 1 (Smart Mode) |
 |---|---|---|
 | **Search** | FTS5 + sqlite-vec, 95,40 % R@5 (~18 ms/Query) | unverändert — Recall ist auf jeder Stufe LLM-frei |
@@ -376,6 +390,35 @@ Der Kern ist Framework-agnostisch. Dieselbe Logik läuft vom Terminal, HTTP oder
 
 ---
 
+## Aktualisieren
+
+Der Plugin-Marketplace von Claude Code fixiert Versionen zum Installationszeitpunkt und aktualisiert **nicht** automatisch. So holst du dir ein neues Release:
+
+**Option A — `/plugin` UI**: `memesh@pcircle-memesh` deinstallieren, dann neu installieren. Claude Code holt die neueste Marketplace-Version.
+
+**Option B — Einzeiler-Skript** (kein UI-Klicken, idempotent):
+
+```bash
+# Wenn deine Plugin-Installation v4.2.5 oder neuer ist, ist das Skript enthalten:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Bei Installationen vor v4.2.5 (also v4.2.4 oder v4.2.3)
+# ist das Skript noch nicht im Plugin. Nutze stattdessen die npm-global-Kopie:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Das setzt voraus, dass du auch `npm install -g @pcircle/memesh` ausgeführt hast.
+# Falls nicht, ist jetzt ein guter Moment dafür — siehe oben „Installationspfade auf
+# einen Blick" für die Gründe, warum die meisten Nutzer beide Pfade wollen.)
+```
+
+Das Skript fast-forwarded den Marketplace-Cache, legt die neue Version unter `~/.claude/plugins/cache/` ab, installiert Runtime-Dependencies und zeigt `installed_plugins.json` neu. Starte danach Claude Code neu, damit der MCP-Server sich neu verbindet.
+
+**npm-global-Installationen** (`npm install -g @pcircle/memesh`) können sich via `memesh update` selbst aktualisieren. Source-Checkouts: `git pull && npm install && npm run build`.
+
+Beim Session-Start erscheint ein einzeiliges Banner (pro Version alle 24h gedrosselt), wenn ein neueres Release verfügbar ist, und `memesh doctor` meldet das Upgrade-Ziel mit kanalspezifischem Befehl.
+
+---
+
 ## Beitragen
 
 ```bash

package/README.es.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Proyecto en desarrollo activo** — las funcionalidades evolucionan continuamente y pueden cambiar entre versiones. Si encuentras un bug o tienes una solicitud de funcionalidad, por favor [abre un issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## El Problema
 
 Tu agente de codificación olvida lo que sucedió en sesiones anteriores. Cada decisión arquitectónica, corrección de bugs, prueba fallida y lección aprendida con esfuerzo debe explicarse de nuevo. Claude Code comienza desde cero, redescubre restricciones antiguas y gasta contexto en cosas que ya debería saber.
@@ -282,10 +285,10 @@ Toda la configuración se realiza mediante variables de entorno. Los valores por
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Sobrescribe la ubicación de la base de datos SQLite. |
 | `MEMESH_AUTO_CAPTURE` | `true` | Desactiva por completo los hooks de auto-captura (`Stop`, `PreCompact`). |
-| `MEMESH_AUTO_DETECT_LLM` | sin definir | Establece a `1` para que memesh auto-detecte un proveedor desde tu env de shell (`OPENAI_API_KEY` etc.) y cambie a embeddings BYOK. **La instalación nueva por defecto es solo ONNX local (384-dim)** — opta por activarlo si quieres embeddings en la nube. Sin esta flag activada, una `OPENAI_API_KEY` que ande por tu shell se ignora. |
+| `MEMESH_AUTO_DETECT_LLM` | sin definir (autodetección **activada**) | Ponlo en `0` para que memesh NO use una clave de API encontrada en el entorno del shell. Por defecto, si `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` está definida y no has configurado un proveedor en `~/.memesh/config.json`, memesh la usa para las funciones LLM de escritura (consolidación, extracción de lecciones, autoetiquetado, dream). Los embeddings no se ven afectados — siguen siendo ONNX local (384-dim) salvo que definas `embedder.provider` explícitamente. |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | sin definir | Establece a `1` para activar un protocolo experimental de modelo de trabajo (encuadre CTO / Orquestador / Agentes). Añade un banner al inicio de sesión, un nudge de comando Bash y telemetría `verify_agent_work`. La efectividad del protocolo se está instrumentando, aún no probada — opta por activarlo si quieres participar. **Por defecto está OFF**: las características de memoria centrales funcionan sin esta flag. |
 | `MEMESH_AUTO_UPDATE` | `off` | Política de auto-actualización. `off` (por defecto) nunca auto-actualiza; `patch` permite `X.Y.Z → X.Y.Z+N`; `minor` añade `X.Y.Z → X.Y+1.0`; `major` permite cualquier bump. Cuando se permite, un `npm install -g` independiente se dispara al final de la sesión (hook Stop) por lo que nunca bloquea tu trabajo — los resultados aterrizan en `~/.memesh/auto-update.log`. También configurable como `autoUpdate` en `~/.memesh/config.json` (env gana). Cuando los mantenedores deprecan la versión instalada (aviso de seguridad), `patch` se fuerza a permitir incluso en `off` — los bumps minor / major siguen siendo manuales para evitar deriva silenciosa de comportamiento. |
-| `OPENAI_API_KEY` | sin definir | Tu clave de OpenAI. Solo se usa cuando `MEMESH_AUTO_DETECT_LLM=1` o configuras explícitamente el proveedor. |
+| `OPENAI_API_KEY` | sin definir | Tu clave de OpenAI. Se usa automáticamente para las funciones LLM salvo que definas `MEMESH_AUTO_DETECT_LLM=0` o configures un proveedor explícitamente. |
 | `OLLAMA_HOST` | `http://localhost:11434` | Sobrescribe el endpoint de Ollama cuando uses un proveedor Ollama local. |
 
 `memesh doctor` imprime la configuración resuelta para que puedas ver qué está activo.
@@ -356,6 +359,17 @@ O usa la pestaña Configuración del dashboard (configuración visual):
 memesh  # abre dashboard → pestaña Settings
 ```
 
+### Usa tus propios embeddings (opcional)
+
+Los embeddings usan por defecto un modelo ONNX local (`Xenova/all-MiniLM-L6-v2`, 384-dim) — sin clave de API, nada sale de tu máquina, y el recall FTS5 por defecto ni los necesita. Para usar un embedder alojado o de servidor local:
+
+```bash
+memesh config set embedder.provider openai          # or: ollama
+memesh config set embedder.model text-embedding-3-small
+```
+
+El embedder se configura **independientemente del LLM de chat** — cambiar `llm.provider` nunca cambia tus embeddings en silencio. Si cambias a una dimensión distinta (p. ej. 384 → 1536), MeMesh reconstruye el índice vectorial automáticamente en la siguiente escritura. Valores de `embedder.provider` soportados: `onnx` (por defecto, local), `openai`, `ollama`.
+
 | | Nivel 0 (por defecto) | Nivel 1 (Modo Inteligente) |
 |---|---|---|
 | **Búsqueda** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms/consulta) | sin cambios — el recall es sin LLM en cada nivel |
@@ -404,6 +418,35 @@ El core es agnóstico de framework. La misma lógica se ejecuta desde terminal,
 
 ---
 
+## Actualizar
+
+El plugin marketplace de Claude Code fija las versiones en el momento de la instalación y **no** se actualiza automáticamente. Para obtener una nueva versión:
+
+**Opción A — Interfaz `/plugin`**: desinstala `memesh@pcircle-memesh`, luego reinstala. Claude Code obtiene la versión más reciente del marketplace.
+
+**Opción B — Script en una línea** (sin hacer clic en la UI, idempotente):
+
+```bash
+# Si tu plugin instalado es v4.2.5 o posterior, el script viene incluido:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Si instalaste antes de v4.2.5 (es decir, v4.2.4 o v4.2.3),
+# el script aún no está en tu plugin. Usa la copia npm-global en su lugar:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Esto asume que también ejecutaste `npm install -g @pcircle/memesh`. Si no lo has hecho,
+# este es un buen momento para hacerlo — consulta la sección "Vista rápida de las rutas
+# de instalación" arriba para entender por qué la mayoría de los usuarios quieren ambas.)
+```
+
+El script fast-forwarded el caché del marketplace, prepara la nueva versión en `~/.claude/plugins/cache/`, instala las runtime deps y repunta `installed_plugins.json`. Reinicia Claude Code después para que el MCP server se reconecte.
+
+**Las instalaciones npm-global** (`npm install -g @pcircle/memesh`) pueden auto-actualizarse mediante `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+Al inicio de sesión aparece un banner de una línea (limitado a una vez cada 24h por versión) cuando hay una nueva versión disponible, y `memesh doctor` reporta el objetivo de actualización con el comando específico del canal.
+
+---
+
 ## Contribuir
 
 ```bash

package/README.fr.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Projet en développement actif** — les fonctionnalités évoluent continuellement et peuvent changer entre les versions. En cas de bug ou de demande de fonctionnalité, merci d'[ouvrir une issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Le Problème
 
 Votre agent de codage oublie ce qui s'est passé d'une session à l'autre. Chaque décision architecturale, correction de bug, test échoué et leçon apprise difficilement doit être réexpliquée. Claude Code redémarre à zéro, redécouvre les anciennes contraintes et gaspille du contexte sur des éléments qu'il devrait déjà connaître.
@@ -255,10 +258,10 @@ Toute la configuration passe par des variables d'environnement. Les valeurs par
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | Remplace l'emplacement de la base SQLite. |
 | `MEMESH_AUTO_CAPTURE` | `true` | Désactive entièrement les hooks d'auto-capture (`Stop`, `PreCompact`). |
-| `MEMESH_AUTO_DETECT_LLM` | non défini | Mettre à `1` pour laisser memesh détecter automatiquement un fournisseur depuis l'environnement shell (`OPENAI_API_KEY`, etc.) et basculer sur des embeddings BYOK. **L'installation neuve par défaut utilise uniquement ONNX local (384 dimensions)** — activez cette option si vous voulez des embeddings cloud. Sans ce flag, une `OPENAI_API_KEY` présente dans le shell est ignorée. |
+| `MEMESH_AUTO_DETECT_LLM` | non défini (détection auto **activée**) | Mettre à `0` pour empêcher memesh d'utiliser une clé API trouvée dans l'environnement du shell. Par défaut, si `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` est définie et qu'aucun fournisseur n'est configuré dans `~/.memesh/config.json`, memesh l'utilise pour les fonctions LLM d'écriture (consolidation, extraction de leçons, auto-tagging, dream). Les embeddings ne sont pas affectés — ils restent en ONNX local (384-dim) sauf si vous définissez explicitement `embedder.provider`. |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | non défini | Mettre à `1` pour activer un protocole de modèle de travail expérimental (cadre CTO / Orchestrateur / Agents). Ajoute une bannière en début de session, un nudge sur les commandes Bash et la télémétrie `verify_agent_work`. L'efficacité du protocole est instrumentée mais pas encore prouvée — activez-la si vous souhaitez participer. **Désactivé par défaut** : les fonctionnalités de mémoire principales fonctionnent sans ce flag. |
 | `MEMESH_AUTO_UPDATE` | `off` | Politique de mise à jour automatique. `off` (défaut) ne met jamais à jour automatiquement ; `patch` autorise `X.Y.Z → X.Y.Z+N` ; `minor` ajoute `X.Y.Z → X.Y+1.0` ; `major` autorise tout incrément. Quand c'est permis, un `npm install -g` détaché s'exécute en fin de session (hook Stop) pour ne jamais bloquer votre travail — les résultats arrivent dans `~/.memesh/auto-update.log`. Configurable aussi via `autoUpdate` dans `~/.memesh/config.json` (la variable d'environnement l'emporte). Quand la version installée est dépréciée par les mainteneurs (alerte de sécurité), `patch` est forcé même en `off` — les incréments minor / major restent manuels pour éviter une dérive de comportement silencieuse. |
-| `OPENAI_API_KEY` | non défini | Votre clé OpenAI. Utilisée uniquement quand `MEMESH_AUTO_DETECT_LLM=1` ou que vous configurez explicitement le fournisseur. |
+| `OPENAI_API_KEY` | non défini | Votre clé OpenAI. Utilisée automatiquement pour les fonctions LLM sauf si vous mettez `MEMESH_AUTO_DETECT_LLM=0` ou configurez un fournisseur explicitement. |
 | `OLLAMA_HOST` | `http://localhost:11434` | Remplace l'endpoint Ollama lors de l'utilisation d'un fournisseur Ollama local. |
 
 `memesh doctor` affiche la configuration résolue pour que vous puissiez voir ce qui est actif.
@@ -329,6 +332,17 @@ Ou utilisez l'onglet Settings du tableau de bord (configuration visuelle) :
 memesh  # ouvre le tableau de bord → onglet Settings
 ```
 
+### Utilisez vos propres embeddings (optionnel)
+
+Les embeddings utilisent par défaut un modèle ONNX local (`Xenova/all-MiniLM-L6-v2`, 384-dim) — aucune clé API, rien ne quitte votre machine, et le recall FTS5 par défaut n'en a pas besoin. Pour utiliser un embedder hébergé ou de serveur local :
+
+```bash
+memesh config set embedder.provider openai          # or: ollama
+memesh config set embedder.model text-embedding-3-small
+```
+
+L'embedder se configure **indépendamment du LLM de chat** — changer `llm.provider` ne change jamais silencieusement vos embeddings. Si vous passez à une dimension différente (p. ex. 384 → 1536), MeMesh reconstruit l'index vectoriel automatiquement à la prochaine écriture. Valeurs `embedder.provider` prises en charge : `onnx` (par défaut, local), `openai`, `ollama`.
+
 | | Niveau 0 (défaut) | Niveau 1 (Mode Smart) |
 |---|---|---|
 | **Recherche** | FTS5 + sqlite-vec, 95,40 % R@5 (~18 ms/requête) | inchangé — le rappel est sans LLM à tous les niveaux |
@@ -377,6 +391,35 @@ Le cœur est agnostique du framework. La même logique s'exécute depuis le term
 
 ---
 
+## Mise à Jour
+
+Le plugin marketplace de Claude Code fige les versions à l'installation et **ne** se met **pas** à jour automatiquement. Pour récupérer une nouvelle version :
+
+**Option A — Interface `/plugin`** : désinstaller `memesh@pcircle-memesh`, puis réinstaller. Claude Code récupère la dernière version du marketplace.
+
+**Option B — Script en une ligne** (sans cliquer dans l'UI, idempotent) :
+
+```bash
+# Si votre plugin est en v4.2.5 ou plus récent, le script est embarqué :
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Si vous avez installé avant v4.2.5 (c.-à-d. v4.2.4 ou v4.2.3),
+# le script n'est pas encore dans votre plugin. Utilisez la copie npm-global :
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Cela suppose que vous avez aussi exécuté `npm install -g @pcircle/memesh`. Sinon,
+# c'est le bon moment — voir la section « Aperçu des chemins d'installation »
+# ci-dessus pour comprendre pourquoi la plupart des utilisateurs veulent les deux.)
+```
+
+Le script fast-forward le cache marketplace, place la nouvelle version dans `~/.claude/plugins/cache/`, installe les runtime deps, et repointe `installed_plugins.json`. Redémarrez Claude Code ensuite pour que le serveur MCP se reconnecte.
+
+**Les installations npm-global** (`npm install -g @pcircle/memesh`) peuvent s'auto-mettre à jour via `memesh update`. Source checkouts : `git pull && npm install && npm run build`.
+
+Au démarrage de session, une bannière sur une ligne s'affiche (limitée à une fois par 24h par version) quand une nouvelle version est disponible, et `memesh doctor` indique la cible de mise à jour avec la commande adaptée au canal.
+
+---
+
 ## Contribuer
 
 ```bash

package/README.ja.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **活発に開発中のプロジェクト** — 機能は継続的に更新され、リリース間で変更される可能性があります。バグや機能要望がある場合は[issue を開いてください](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+
 ## 課題
 
 コーディングエージェントはセッション間で記憶を失います。アーキテクチャの決定、バグ修正、テスト失敗、苦労して得た教訓 — すべてを毎回説明し直さなければなりません。Claude Code はいつも初期状態から始まり、既に知っているはずの制約を再発見し、貴重なコンテキストを無駄にします。
@@ -282,10 +285,10 @@ memesh export-schema \
 |---|---|---|
 | `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | SQLite データベースの保存場所を上書き。 |
 | `MEMESH_AUTO_CAPTURE` | `true` | 自動キャプチャフック(`Stop`、`PreCompact`)を完全に無効化。 |
-| `MEMESH_AUTO_DETECT_LLM` | 未設定 | `1` に設定すると、memesh がシェル環境変数(`OPENAI_API_KEY` 等)からプロバイダを自動検出し BYOK エンベディングに切り替えます。**新規インストールのデフォルトはローカル ONNX(384 次元)のみ** — クラウドエンベディングを使いたい場合のみオプトインしてください。このフラグが未設定なら、シェルに `OPENAI_API_KEY` があっても無視されます。 |
+| `MEMESH_AUTO_DETECT_LLM` | 未設定(自動検出**オン**) | `0` に設定すると、シェル環境で見つかった API キーを memesh が使用しなくなります。デフォルトでは、`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `OLLAMA_HOST` が設定されていて `~/.memesh/config.json` にプロバイダを構成していない場合、memesh は書き込み側の LLM 機能(統合、レッスン抽出、自動タグ付け、dream)にそれを使用します。エンベディングは影響を受けません — `embedder.provider` を明示的に設定しない限りローカル ONNX(384 次元)のままです。 |
 | `MEMESH_ENABLE_AGENTIC_ORCHESTRATION` | 未設定 | `1` に設定すると、実験的なワーキングモデルプロトコル(CTO / Orchestrator / Agents のフレーミング)が有効になります。セッション開始バナー、Bash コマンドの促し、`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` は任意のバンプを許可。許可されている場合、デタッチ実行された `npm install -g` がセッション終了時(Stop フック)に発火するため作業をブロックしません — 結果は `~/.memesh/auto-update.log` に記録されます。`~/.memesh/config.json` の `autoUpdate` でも設定可能(env が優先)。インストール済みバージョンがメンテナーによって非推奨化された場合(セキュリティアドバイザリ)、`off` でも `patch` は強制的に許可されます — minor / major バンプはサイレントな挙動変化を避けるため手動のままです。 |
-| `OPENAI_API_KEY` | 未設定 | 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` は解決された設定を表示するため、何が有効かを確認できます。
@@ -356,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`。
+
 | | レベル 0 (デフォルト) | レベル 1 (スマートモード) |
 |---|---|---|
 | **検索** | FTS5 + sqlite-vec、95.40% R@5(~18ms/クエリ) | 変更なし — リコールはどのレベルでも LLM フリー |
@@ -404,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`。
+
+セッション開始時、新しいリリースがあると 1 行のバナーが表示されます（バージョンごとに 24 時間スロットル）。`memesh doctor` はアップグレードターゲットとチャンネル固有のコマンドを報告します。
+
+---
+
 ## コントリビュート
 
 ```bash

package/README.ko.md

@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **활발히 개발 중인 프로젝트** — 기능이 지속적으로 업데이트되며 릴리스 간에 변경될 수 있습니다. 버그나 기능 요청이 있으면 [issue를 열어주세요](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## 문제점
 
 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버립니다. 아키텍처 결정, 버그 수정, 실패한 테스트, 힘들게 얻은 교훈 — 매번 다시 설명해야 합니다. Claude Code는 매번 새로 시작하고, 이미 알아야 할 제약 조건을 다시 발견하며, 불필요하게 컨텍스트를 소비합니다.
@@ -282,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`는 활성화된 항목을 볼 수 있도록 해결된 구성을 출력합니다.
@@ -356,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 |
@@ -404,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,19 +16,11 @@
 
 ---
 
-## 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.
-
-**MeMesh gives coding agents persistent, searchable, evolving local memory.**
-
-This package is the local memory layer of the MeMesh product family. It is intentionally small and open-source: install it with npm, keep your memory in `~/.memesh/knowledge-graph.db`, and connect it to Claude Code or any MCP-compatible client. Hosted workspace and enterprise operating-system products should stay separate from this package's README and roadmap.
-
----
+**MeMesh** — the open-source **memory layer** for Claude Code & MCP agents. One SQLite file. No cloud. Plugs into any LLM.
 
-## Proof — 95.40% R@5 on LongMemEval-S
+## 95.40% R@5 on LongMemEval-S — beats Mem0 by 46 points
 
-MeMesh's retrieval engine is **FTS5 alone** (no LLM, no embeddings on the hot path), measured against the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark (500 questions, MIT-licensed):
+MeMesh's retrieval is **FTS5 alone** — no LLM, no embeddings on the hot path. Measured against the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark (500 questions, MIT-licensed):
 
 | System | R@5 | Source |
 |---|---|---|
@@ -38,7 +30,18 @@ MeMesh's retrieval engine is **FTS5 alone** (no LLM, no embeddings on the hot pa
 | Zep | 63.8% | LongMemEval paper |
 | Mem0 | 49.0% | LongMemEval paper |
 
-Reproduction commands, dataset SHA256, raw per-question results, and known-failure analysis are all in [`benchmarks/longmemeval/`](benchmarks/longmemeval/). Re-runnable in ~10 seconds.
+Re-runnable in ~10 seconds. Full instructions, dataset SHA256, raw per-question results, and known-failure analysis: [`benchmarks/longmemeval/REPRODUCE.md`](benchmarks/longmemeval/REPRODUCE.md).
+
+---
+
+## The Problem
+
+Your coding agent forgets 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.
+
+**MeMesh gives coding agents persistent, searchable, evolving local memory.** Install with npm, memory lives in `~/.memesh/knowledge-graph.db`, plug into Claude Code or any MCP-compatible client.
+
+> [!IMPORTANT]
+> Actively developed — features may change between releases. [Open an issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues) for bugs or feature requests.
 
 ---
 
@@ -284,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.
@@ -358,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 |

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.
@@ -255,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.
@@ -329,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 |
@@ -377,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