@pcircle/memesh 4.2.6 → 4.2.8

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.6",
+      "version": "4.2.8",
       "author": {
         "name": "PCIRCLE AI"
       },

package/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "4.2.6",
+  "version": "4.2.8",
   "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.
@@ -42,6 +45,67 @@ Reproduktionsbefehle, Datensatz-SHA256, rohe Ergebnisse pro Frage und Analyse be
 
 ---
 
+## Installationspfade auf einen Blick
+
+MeMesh hat **zwei Installationspfade, die nebeneinander existieren**. Die meisten Nutzer brauchen beide. Beide schreiben in die **selbe Speicher-Datenbank** (`~/.memesh/knowledge-graph.db`), so dass im Claude-Code-Chat erfasste Memories auch in deiner Shell erscheinen und umgekehrt.
+
+```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
+```
+
+**Welchen brauchst du?**
+
+| Was du willst | Installationspfad |
+|---|---|
+| `/memesh` skill im Claude-Code-Chat verwenden | Path A (Plugin) |
+| Auto-Capture in Claude Code (Session → Lessons → nächste Recall) | Path A (Plugin) |
+| `memesh remember` / `memesh recall` / `memesh doctor` im Terminal | Path B (npm-global) |
+| `memesh` direkt zum Öffnen des Dashboards (ohne `npx`-Startverzögerung) | Path B (npm-global) |
+| `memesh-mcp` an Cursor, Cline oder andere MCP-Clients anbinden | Path B (npm-global) |
+| Alles oben | **Beide installieren** — kein Konflikt |
+
+> **Häufiges Missverständnis**: Das Claude-Code-Plugin legt `memesh` **nicht** auf deinen Shell-`PATH`. Wenn du nur `/plugin install` läufst und dann im Terminal `memesh reindex` tippst, siehst du `command not found`. Das ist normal — für den Shell-Befehl brauchst du zusätzlich `npm install -g @pcircle/memesh`.
+
+### ⚠️ Das Plugin installiert NICHT das CLI
+
+Das ist die häufigste Verwechslung. Einmal lesen, spart dir später Zeit:
+
+- `/plugin install memesh@pcircle-memesh` aus Claude Code → installiert **nur Path A**. Du erhältst MCP-Tools, Hooks, das `/memesh` skill. `memesh` landet **nicht** auf deinem Shell-`PATH`.
+- `memesh reindex` / `memesh update` / `memesh doctor` im Terminal → braucht **Path B** (npm-global). Sonst: `zsh: command not found: memesh`.
+- **Empfohlenes Setup für Claude-Code-Nutzer**: **beide installieren**. Koexistieren, teilen sich dieselbe DB, kein Konflikt.
+
+```bash
+# Nach /plugin install ..., auch das ausführen:
+npm install -g @pcircle/memesh
+```
+
+Wenn du memesh nur im Claude-Code-Chat verwendest (nie `memesh` im Terminal tippst), reicht Path A. Alle anderen: beide installieren.
+
+---
+
 ## In 60 Sekunden starten
 
 ### Schritt 1: Installation
@@ -193,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.
@@ -267,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 |
@@ -315,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.
@@ -42,6 +45,67 @@ Los comandos de reproducción, SHA256 del dataset, resultados crudos por pregunt
 
 ---
 
+## Vista rápida de las rutas de instalación
+
+MeMesh tiene **dos rutas de instalación que coexisten**. La mayoría de usuarios quiere ambas. Escriben en la **misma base de datos de memoria** (`~/.memesh/knowledge-graph.db`), por lo que los recuerdos capturados en el chat de Claude Code aparecen en tu shell, y viceversa.
+
+```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
+```
+
+**¿Cuál necesitas?**
+
+| Lo que quieres hacer | Ruta de instalación |
+|---|---|
+| Usar el skill `/memesh` dentro de una conversación de Claude Code | Path A (plugin) |
+| Auto-captura en Claude Code (sesión → lecciones → recall siguiente) | Path A (plugin) |
+| Ejecutar `memesh remember` / `memesh recall` / `memesh doctor` en cualquier terminal | Path B (npm-global) |
+| Abrir el dashboard con `memesh` (sin retraso de arranque de `npx`) | Path B (npm-global) |
+| Conectar `memesh-mcp` a Cursor, Cline u otro cliente MCP | Path B (npm-global) |
+| Todo lo anterior | **Instala ambos** — no entran en conflicto |
+
+> **Confusión común**: el plugin de Claude Code **no** pone `memesh` en tu `PATH` del shell. Si solo ejecutas `/plugin install` y luego escribes `memesh reindex` en una terminal, verás `command not found`. Es normal — añade `npm install -g @pcircle/memesh` también para acceso desde el shell.
+
+### ⚠️ Instalar el plugin NO instala el CLI
+
+Es la confusión más común. Léelo una vez y te ahorrarás un bucle futuro:
+
+- `/plugin install memesh@pcircle-memesh` desde Claude Code → instala **solo Path A**. Te da herramientas MCP, hooks, el skill `/memesh`. **NO** pone `memesh` en tu `PATH` del shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` en una terminal → necesita **Path B** (npm-global). Sin él: `zsh: command not found: memesh`.
+- **Configuración recomendada para usuarios de Claude Code**: **instala ambos**. Coexisten, comparten la misma base de datos, no conflictúan.
+
+```bash
+# Después de /plugin install ..., ejecuta también esto:
+npm install -g @pcircle/memesh
+```
+
+Si solo usas memesh a través del chat de Claude Code (nunca tecleas `memesh` en una terminal), Path A solo es suficiente. Para todos los demás: instala ambos.
+
+---
+
 ## Primeros Pasos en 60 Segundos
 
 ### Opción A — Plugin de Claude Code (instalación de una línea)
@@ -221,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.
@@ -295,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 |
@@ -343,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.
@@ -42,6 +45,67 @@ Les commandes de reproduction, le SHA256 du jeu de données, les résultats brut
 
 ---
 
+## Aperçu des chemins d'installation
+
+MeMesh a **deux chemins d'installation coexistants**. La plupart des utilisateurs veulent les deux. Ils écrivent dans la **même base de données mémoire** (`~/.memesh/knowledge-graph.db`), donc les mémoires capturées dans Claude Code apparaissent dans votre shell, et 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
+```
+
+**Lequel vous faut-il ?**
+
+| Ce que vous voulez faire | Chemin d'installation |
+|---|---|
+| Utiliser le skill `/memesh` dans une conversation Claude Code | Path A (plugin) |
+| Auto-capture dans Claude Code (session → leçons → recall suivant) | Path A (plugin) |
+| Exécuter `memesh remember` / `memesh recall` / `memesh doctor` dans n'importe quel terminal | Path B (npm-global) |
+| Ouvrir le dashboard via `memesh` (sans délai de démarrage `npx`) | Path B (npm-global) |
+| Brancher `memesh-mcp` à Cursor, Cline ou un autre client MCP | Path B (npm-global) |
+| Tout ce qui précède | **Installez les deux** — ils ne sont pas en conflit |
+
+> **Confusion courante** : le plugin Claude Code **ne** met **pas** `memesh` sur votre `PATH` shell. Si vous lancez seulement `/plugin install` puis tapez `memesh reindex` dans un terminal, vous verrez `command not found`. C'est normal — il faut aussi `npm install -g @pcircle/memesh` pour l'accès shell.
+
+### ⚠️ Installer le plugin n'installe PAS le CLI
+
+C'est la confusion la plus fréquente. Lisez ceci une fois et vous gagnerez du temps plus tard :
+
+- `/plugin install memesh@pcircle-memesh` depuis Claude Code → installe **uniquement Path A**. Vous obtenez les outils MCP, les hooks, le skill `/memesh`. `memesh` n'est **PAS** ajouté à votre `PATH` shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` dans un terminal → nécessite **Path B** (npm-global). Sans : `zsh: command not found: memesh`.
+- **Configuration recommandée pour les utilisateurs Claude Code** : **installez les deux**. Coexistent, partagent la même base de données, aucun conflit.
+
+```bash
+# Après /plugin install ..., exécutez aussi ceci :
+npm install -g @pcircle/memesh
+```
+
+Si vous utilisez memesh uniquement via le chat Claude Code (jamais `memesh` dans un terminal), Path A suffit. Tous les autres : installez les deux.
+
+---
+
 ## Démarrer en 60 Secondes
 
 ### Étape 1 : Installer
@@ -194,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.
@@ -268,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 |
@@ -316,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 はいつも初期状態から始まり、既に知っているはずの制約を再発見し、貴重なコンテキストを無駄にします。
@@ -42,6 +45,67 @@ MeMesh の検索エンジンは **FTS5 のみ**(LLM もホットパスのエン
 
 ---
 
+## インストールパス早見表
+
+MeMesh には**共存する 2 つのインストールパス**があります。ほとんどのユーザーは両方が必要です。両者は**同じメモリデータベース**（`~/.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 → 学習 → 次回リコール） | 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` | 未設定 | `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` は解決された設定を表示するため、何が有効かを確認できます。
@@ -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`。
+
 | | レベル 0 (デフォルト) | レベル 1 (スマートモード) |
 |---|---|---|
 | **検索** | FTS5 + sqlite-vec、95.40% R@5(~18ms/クエリ) | 変更なし — リコールはどのレベルでも LLM フリー |
@@ -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`。
+
+セッション開始時、新しいリリースがあると 1 行のバナーが表示されます（バージョンごとに 24 時間スロットル）。`memesh doctor` はアップグレードターゲットとチャンネル固有のコマンドを報告します。
+
+---
+
 ## コントリビュート
 
 ```bash