@pcircle/memesh 4.1.7 → 4.2.0

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

package/.claude-plugin/plugin.json

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

package/README.de.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,6 +26,22 @@ Dieses Paket ist die lokale Speicherschicht der MeMesh-Produktfamilie. Es ist be
 
 ---
 
+## Proof — 95.40% R@5 on LongMemEval-S
+
+MeMeshs Retrieval-Engine ist **FTS5 alleine** (kein LLM, keine Embeddings auf dem Hot Path), gemessen am öffentlichen [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) Benchmark (500 Fragen, MIT-lizenziert):
+
+| System | R@5 | Quelle |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | Eigenangabe des Anbieters |
+| Supermemory | ~82% | Schätzung des Anbieters |
+| Zep | 63.8% | LongMemEval-Paper |
+| Mem0 | 49.0% | LongMemEval-Paper |
+
+Reproduktionsbefehle, Datensatz-SHA256, rohe Ergebnisse pro Frage und Analyse bekannter Fehlschläge finden sich vollständig in [`benchmarks/longmemeval/`](benchmarks/longmemeval/). In ~10 Sekunden reproduzierbar.
+
+---
+
 ## In 60 Sekunden starten
 
 ### Schritt 1: Installation
@@ -172,6 +185,26 @@ Sie müssen nicht manuell alles speichern. MeMesh verfügt über **6 Hooks**, di
 
 ---
 
+## Configuration
+
+Die gesamte Konfiguration erfolgt über Umgebungsvariablen. Die Standardwerte sind rein lokal und ohne Netzwerk — Sie müssen nichts setzen, um ein funktionierendes System zu erhalten.
+
+| Variable | Standard | Was sie bewirkt |
+|---|---|---|
+| `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_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. |
+| `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.
+
+Wenn npm eine installierte Version als veraltet kennzeichnet (typischerweise eine Sicherheitswarnung), stellt der nächste Session-Start ein deutliches `⚠️ MeMesh <ver> is DEPRECATED`-Banner voran und `memesh update-status` zeigt dieselbe Zeile, bis Sie aktualisiert haben. Die Prüfung wird unter `~/.memesh/update-check.<version>.json` zwischengespeichert, sodass ein vorübergehender Netzwerkfehler die Warnung nicht abschwächen kann.
+
+---
+
 ## Dashboard
 
 7 Reiter, 11 Sprachen, keine externen Abhängigkeiten. Zugang unter `http://localhost:3737/dashboard` wenn der Server läuft.
@@ -218,7 +251,7 @@ Importierte Bundles bleiben durchsuchbar, aber MeMesh injiziert importierte Memo
 
 ## Smart Mode freischalten (optional)
 
-MeMesh funktioniert standardmäßig offline. Fügen Sie einen LLM API-Schlüssel nur hinzu, wenn Sie Query-Erweiterung, intelligentere Extraktion und Kompression wünschen:
+MeMesh funktioniert standardmäßig offline — Recall bleibt strikt LLM-frei (95,40 % R@5 auf LongMemEval-S, ohne LLM). Fügen Sie einen LLM API-Schlüssel nur hinzu, wenn Sie LLM-augmentierte Analyseflüsse zusätzlich nutzen möchten: intelligentere Session-Extraktion, Auto-Tagging neuer Memories, Lektionen aus Fehlern und `consolidate` / `dream` Kompression:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -233,10 +266,12 @@ memesh  # öffnet Dashboard → Settings-Reiter
 
 | | Stufe 0 (Standard) | Stufe 1 (Smart Mode) |
 |---|---|---|
-| **Search** | FTS5-Keyword-Matching | + LLM Query-Erweiterung (~97 % Recall) |
+| **Search** | FTS5 + sqlite-vec, 95,40 % R@5 (~18 ms/Query) | unverändert — Recall ist auf jeder Stufe LLM-frei |
 | **Auto-Capture** | Regelbasierte Muster | + LLM extrahiert Entscheidungen & Lektionen |
-| **Kompression** | Nicht verfügbar | `consolidate` komprimiert ausschweifende Memories |
-| **Kosten** | Kostenlos, kein API-Schlüssel | ~$0,0001 pro Suche (Haiku) |
+| **Auto-Tagging** | Nur manuelle Tags | + LLM generiert Tags für neue Memories |
+| **Fehleranalyse** | Nicht verfügbar | + LLM wandelt Session-Fehler in strukturierte Lektionen um |
+| **Kompression** | Nicht verfügbar | `consolidate` + `dream` komprimieren ausschweifende Memories |
+| **Kosten** | Kostenlos, kein API-Schlüssel | ~$0,0001 pro Analyseanfrage (Haiku) |
 
 ---
 
@@ -245,7 +280,7 @@ memesh  # öffnet Dashboard → Settings-Reiter
 | Tool | Was es tut |
 |------|-------------|
 | `remember` | Wissen mit Beobachtungen, Relationen und Tags speichern |
-| `recall` | Intelligente Suche mit Multi-Faktor-Bewertung und LLM Query-Erweiterung |
+| `recall` | FTS5 + sqlite-vec Suche mit Multi-Faktor-Bewertung (Relevanz, Aktualität, Häufigkeit, Konfidenz, zeitliche Gültigkeit) — kein LLM auf dem Hot Path |
 | `forget` | Soft-Archivierung (löscht nie) oder entfernt spezifische Beobachtungen |
 | `consolidate` | LLM-gestützte Kompression ausschweifender Memories |
 | `export` | Memories als JSON zwischen Projekten oder Teamkollegen teilen |

package/README.es.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,27 +26,70 @@ Este paquete es la capa de memoria local de la familia de productos MeMesh. Es i
 
 ---
 
+## Prueba — 95.40% R@5 en LongMemEval-S
+
+El motor de recuperación de MeMesh es **solo FTS5** (sin LLM, sin embeddings en la ruta caliente), medido contra el benchmark público [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) (500 preguntas, licencia MIT):
+
+| Sistema | R@5 | Fuente |
+|---|---|---|
+| **MeMesh (Modo A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | Auto-reporte del proveedor |
+| Supermemory | ~82% | Estimación del proveedor |
+| Zep | 63.8% | Paper de LongMemEval |
+| Mem0 | 49.0% | Paper de LongMemEval |
+
+Los comandos de reproducción, SHA256 del dataset, resultados crudos por pregunta y análisis de fallos conocidos están todos en [`benchmarks/longmemeval/`](benchmarks/longmemeval/). Re-ejecutable en ~10 segundos.
+
+---
+
 ## Primeros Pasos en 60 Segundos
 
-### Paso 1: Instala
+### Opción A — Plugin de Claude Code (instalación de una línea)
+
+Si usas Claude Code, instala MeMesh como plugin desde dentro de la CLI:
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin install memesh@pcircle-memesh
+```
+
+Claude Code conecta los hooks, skills y el servidor MCP automáticamente. Obtienes auto-captura en sesión, recuperación proactiva, el skill `/memesh` (remember / recall / learn / forget) dentro de la conversación de Claude Code, y `remember` / `recall` / `forget` / `learn` disponibles como herramientas MCP para el agente. La CLI y el dashboard local también son completamente accesibles sin ninguna instalación global adicional — `npx @pcircle/memesh <command>` ejecuta cada comando CLI, y `npx @pcircle/memesh` lanza el dashboard en `localhost:3737`. El servidor MCP usa el mismo patrón de lanzamiento basado en `npx` que los plugins oficiales de Anthropic (p. ej. `context7`), por lo que no se necesita `npm install -g` para ninguna característica.
+
+### Opción B — npm global (optimización opcional)
+
+Si quieres el binario directamente en tu `PATH` de shell (para que `memesh`, `memesh-mcp`, etc. funcionen en cualquier terminal sin la búsqueda `npx` por llamada), o quieres exponer `memesh-mcp` como un comando stdio de ruta fija a **clientes MCP que no son Claude Code** (Cursor, Cline, flujos solo de terminal):
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### Paso 1.5: Conecta MeMesh a Claude Code (recomendado, una sola vez)
+> **Notas de primera instalación (única vez):**
+> - **Módulos nativos** — `better-sqlite3` y `sqlite-vec` se instalan mediante binarios precompilados en macOS (arm64/x64), Linux (x64/arm64) y Windows x64. En plataformas poco comunes o cuando los precompilados fallan, necesitarás un toolchain C/C++ funcional.
+> - **Modelo de embedding** — la primera llamada que activa un embedding local (p. ej. `recall` con modo semántico) descarga `Xenova/all-MiniLM-L6-v2` (~80 MB) en `~/.memesh/models/`. Las llamadas subsiguientes son instantáneas. La ruta de recuperación por defecto (FTS5) no requiere esta descarga.
 
-`npm install -g` pone la CLI en el PATH y registra el servidor MCP, pero **no** conecta automáticamente los hooks de sesión de MeMesh a Claude Code. Sin estos hooks, puedes usar `memesh remember` / `recall` manualmente, pero el **bucle de captura automática** (sesión → lecciones → recall proactivo en la siguiente sesión) queda en silencio.
+### Paso 1.5: Conecta MeMesh a Claude Code (solo ruta npm)
+
+Si instalaste mediante la **Opción A** (`/plugin install memesh@pcircle-memesh`), omite este paso — Claude Code conecta los hooks del plugin automáticamente.
+
+Si instalaste mediante la **Opción B** (`npm install -g`), la CLI está en tu PATH y el servidor MCP está registrado, pero los hooks de sesión de Claude Code no se conectan automáticamente. Sin ellos, aún puedes usar `memesh remember` / `recall` manualmente, pero el **bucle de captura automática** (sesiones → lecciones → recall en la siguiente sesión) queda en silencio.
 
 ```bash
 memesh install-hooks         # añade los hooks de memesh a ~/.claude/settings.json
 memesh doctor                # confirma que "Hooks wired into Claude Code" pasa
 ```
 
-Estos hooks coexisten con tus hooks personalizados en `~/.claude/hooks/` — `install-hooks` escribe de forma aditiva y nunca sobrescribe los tuyos. Para eliminarlos: `memesh uninstall-hooks`.
+Estos hooks coexisten con cualquier hook personalizado que ya tengas en `~/.claude/hooks/` — `install-hooks` escribe entradas aditivas y nunca sobrescribe los tuyos. Para eliminarlos después: `memesh uninstall-hooks`.
 
 ### Paso 2: Guarda una decisión
 
+> Los ejemplos bash a continuación asumen que `memesh` está en tu `PATH` (Opción B). Los usuarios de la Opción A (solo plugin) tienen dos rutas equivalentes: pregunta en la conversación de Claude Code (el skill `/memesh` + las herramientas MCP cubren los mismos flujos), o reemplaza `memesh` con `npx @pcircle/memesh` en cualquier shell — mismas flags, sin necesidad de instalación global.
+
+```bash
+memesh remember "Use OAuth 2.0 with PKCE for the new auth"
+```
+
+O usa la forma explícita cuando quieres un nombre y tipo estables para filtrado posterior:
+
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
@@ -161,10 +201,10 @@ No necesitas recordar todo manualmente. MeMesh tiene **7 hooks** que capturan e
 
 | Cuándo | Qué hace MeMesh |
 |---|---|
-| **Al inicio de cada sesión** | Carga tus memorias más relevantes + advertencias proactivas de lecciones pasadas + banner de orquestación agentica |
+| **Al inicio de cada sesión** | Carga tus memorias más relevantes + advertencias proactivas de lecciones pasadas |
 | **Antes de editar archivos** | Recupera memorias vinculadas al archivo o proyecto antes de que Claude escriba código |
-| **Antes de comandos bash** | Nudge a Claude para que envíe comandos de alta verificabilidad (test, build, lint, migrate, deploy, benchmark) como agentes de fondo |
-| **Cuando pides recordar** | Detecta intención de "remember this" / "記下來" y recuerda a Claude que escriba dual (memesh + MEMORY.md) |
+| **Antes de comandos bash** | (Opt-in) Nudge a Claude para que envíe comandos de alta verificabilidad (test, build, lint, migrate, deploy, benchmark) como agentes de fondo |
+| **Cuando pides recordar** | Detecta intención de "remember this" / "guardar en memesh" / "sauvegarder dans memesh" / "記下來" (5 idiomas) y recuerda a Claude que use memesh |
 | **Después de cada `git commit`** | Registra qué cambiaste, con estadísticas de diff |
 | **Cuando Claude se detiene** | Captura archivos editados, errores corregidos y genera automáticamente lecciones estructuradas a partir de fallos |
 | **Antes de compresión de contexto** | Guarda conocimiento antes de que se pierda en límites de contexto |
@@ -173,6 +213,26 @@ No necesitas recordar todo manualmente. MeMesh tiene **7 hooks** que capturan e
 
 ---
 
+## Configuración
+
+Toda la configuración se realiza mediante variables de entorno. Los valores por defecto son solo locales y sin red — no necesitas configurar nada para tener un sistema funcional.
+
+| Variable | Por defecto | Qué hace |
+|---|---|---|
+| `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_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. |
+| `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.
+
+Cuando npm marca una versión instalada como deprecada (típicamente un aviso de seguridad), el siguiente inicio de sesión antepone un fuerte banner `⚠️ MeMesh <ver> is DEPRECATED` y `memesh update-status` muestra la misma línea hasta que actualices. La verificación se cachea en `~/.memesh/update-check.<version>.json` para que un fallo de red transitorio no atenúe la advertencia.
+
+---
+
 ## Dashboard
 
 7 pestañas, 11 idiomas, cero dependencias externas. Accede en `http://localhost:3737/dashboard` cuando el servidor está en ejecución.
@@ -219,7 +279,7 @@ Los bundles importados permanecen buscables, pero MeMesh no inyecta automáticam
 
 ## Desbloquea Modo Inteligente (Opcional)
 
-MeMesh funciona sin conexión por defecto. Añade una clave API de LLM solo si quieres expansión de consultas, extracción más inteligente y compresión:
+MeMesh funciona sin conexión por defecto — el recall permanece estrictamente sin LLM (95.40% R@5 en LongMemEval-S de fábrica). Añade una clave API de LLM solo si quieres flujos de análisis aumentados por LLM encima: extracción de sesión más inteligente, auto-etiquetado de nuevas memorias, generación de lecciones a partir de fallos, y compresión `consolidate` / `dream`:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -234,10 +294,12 @@ memesh  # abre dashboard → pestaña Settings
 
 | | Nivel 0 (por defecto) | Nivel 1 (Modo Inteligente) |
 |---|---|---|
-| **Búsqueda** | Coincidencia de palabras clave FTS5 | + expansión de consultas LLM (~97% de recall) |
+| **Búsqueda** | FTS5 + sqlite-vec, 95.40% R@5 (~18ms/consulta) | sin cambios — el recall es sin LLM en cada nivel |
 | **Auto-capture** | Patrones basados en reglas | + LLM extrae decisiones y lecciones |
-| **Compresión** | No disponible | `consolidate` comprime memorias verbosas |
-| **Costo** | Gratis, sin clave API | ~$0.0001 por búsqueda (Haiku) |
+| **Auto-etiquetado** | Solo etiquetas manuales | + LLM genera etiquetas para nuevas memorias |
+| **Análisis de fallos** | No disponible | + LLM convierte errores de sesión en lecciones estructuradas |
+| **Compresión** | No disponible | `consolidate` + `dream` comprimen memorias verbosas |
+| **Costo** | Gratis, sin clave API | ~$0.0001 por llamada de análisis (Haiku) |
 
 ---
 
@@ -246,7 +308,7 @@ memesh  # abre dashboard → pestaña Settings
 | Herramienta | Qué hace |
 |---|---|
 | `remember` | Guardar conocimiento con observaciones, relaciones y etiquetas |
-| `recall` | Búsqueda inteligente con scoring multifactor y expansión de consultas LLM |
+| `recall` | Búsqueda FTS5 + sqlite-vec con scoring multifactor (relevancia, recencia, frecuencia, confianza, validez temporal) — sin LLM en la ruta caliente |
 | `forget` | Archivo suave (nunca borra) o elimina observaciones específicas |
 | `consolidate` | Compresión impulsada por LLM de memorias verbosas |
 | `export` | Compartir memorias como JSON entre proyectos o miembros del equipo |

package/README.fr.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,6 +26,22 @@ Ce package constitue la couche de mémoire locale de la famille de produits MeMe
 
 ---
 
+## Preuve — 95,40 % R@5 sur LongMemEval-S
+
+Le moteur de récupération de MeMesh utilise **FTS5 seul** (pas de LLM, pas d'embeddings sur le chemin chaud), mesuré sur le benchmark public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) (500 questions, licence MIT) :
+
+| Système | R@5 | Source |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95,40 %** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96,6 % | Auto-déclaration de l'éditeur |
+| Supermemory | ~82 % | Estimation de l'éditeur |
+| Zep | 63,8 % | Article LongMemEval |
+| Mem0 | 49,0 % | Article LongMemEval |
+
+Les commandes de reproduction, le SHA256 du jeu de données, les résultats bruts par question et l'analyse des échecs connus se trouvent tous dans [`benchmarks/longmemeval/`](benchmarks/longmemeval/). Réexécutable en environ 10 secondes.
+
+---
+
 ## Démarrer en 60 Secondes
 
 ### Étape 1 : Installer
@@ -173,6 +186,26 @@ Vous n'avez pas besoin de tout mémoriser manuellement. MeMesh possède **7 hook
 
 ---
 
+## Configuration
+
+Toute la configuration passe par des variables d'environnement. Les valeurs par défaut sont strictement locales et sans accès réseau — vous n'avez rien à définir pour obtenir un système fonctionnel.
+
+| Variable | Défaut | Effet |
+|---|---|---|
+| `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_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. |
+| `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.
+
+Lorsque npm signale une version installée comme dépréciée (typiquement une alerte de sécurité), le prochain démarrage de session ajoute en tête une bannière forte `⚠️ MeMesh <ver> is DEPRECATED` et `memesh update-status` affiche la même ligne jusqu'à la mise à jour. La vérification est mise en cache dans `~/.memesh/update-check.<version>.json` pour qu'une panne réseau transitoire ne puisse pas atténuer l'avertissement.
+
+---
+
 ## Tableau De Bord
 
 7 onglets, 11 langues, zéro dépendance externe. Accessible à `http://localhost:3737/dashboard` quand le serveur s'exécute.
@@ -191,7 +224,7 @@ Vous n'avez pas besoin de tout mémoriser manuellement. MeMesh possède **7 hook
 
 ## Fonctionnalités Intelligentes
 
-**🧠 Recherche Intelligente** — Cherchez « sécurité login » et trouvez des mémoires sur « OAuth PKCE ». MeMesh enrichit les requêtes avec des termes connexes en utilisant votre LLM configuré.
+**🧠 Recherche Intelligente** — Cherchez « sécurité login » et trouvez des mémoires sur « OAuth PKCE ». MeMesh combine FTS5 et la similarité vectorielle sqlite-vec pour trouver des mémoires sémantiquement liées sans LLM sur le chemin chaud.
 
 **📊 Classement Avec Score** — Les résultats sont classés par pertinence (30 %) + récence (25 %) + fréquence (15 %) + confiance (15 %) + impact de rappel (10 %) + validité temporelle (5 %).
 
@@ -219,7 +252,7 @@ Les bundles importés restent consultables, mais MeMesh n'injecte pas automatiqu
 
 ## Déverrouiller Le Mode Smart (Optionnel)
 
-MeMesh fonctionne hors ligne par défaut. Ajoutez une clé API LLM uniquement si vous souhaitez l'expansion de requête, l'extraction plus intelligente et la compression :
+MeMesh fonctionne hors ligne par défaut — le rappel reste strictement sans LLM (95,40 % R@5 sur LongMemEval-S dès l'installation). Ajoutez une clé API LLM uniquement si vous voulez des flux d'analyse augmentés par LLM par-dessus : extraction de session plus intelligente, auto-tagging des nouvelles mémoires, génération de leçons depuis les défaillances et compression `consolidate` / `dream` :
 
 ```bash
 memesh config set llm.provider anthropic
@@ -234,10 +267,12 @@ memesh  # ouvre le tableau de bord → onglet Settings
 
 | | Niveau 0 (défaut) | Niveau 1 (Mode Smart) |
 |---|---|---|
-| **Recherche** | Correspondance de mots-clés FTS5 | + expansion de requête LLM (~97 % de rappel) |
+| **Recherche** | FTS5 + sqlite-vec, 95,40 % R@5 (~18 ms/requête) | inchangé — le rappel est sans LLM à tous les niveaux |
 | **Auto-capture** | Motifs basés sur les règles | + LLM extrait les décisions & leçons |
-| **Compression** | Non disponible | `consolidate` compresse les mémoires verbeux |
-| **Coût** | Gratuit, aucune clé API | ~$0.0001 par recherche (Haiku) |
+| **Auto-tagging** | Tags manuels uniquement | + LLM génère des tags pour les nouvelles mémoires |
+| **Analyse de défaillance** | Indisponible | + LLM convertit les erreurs de session en leçons structurées |
+| **Compression** | Indisponible | `consolidate` + `dream` compressent les mémoires verbeux |
+| **Coût** | Gratuit, aucune clé API | ~$0,0001 par appel d'analyse (Haiku) |
 
 ---
 
@@ -246,7 +281,7 @@ memesh  # ouvre le tableau de bord → onglet Settings
 | Outil | Ce qu'il fait |
 |---|---|
 | `remember` | Stocker les connaissances avec observations, relations et tags |
-| `recall` | Recherche intelligente avec notation multi-facteurs et expansion de requête LLM |
+| `recall` | Recherche FTS5 + sqlite-vec avec notation multi-facteurs (pertinence, récence, fréquence, confiance, validité temporelle) — pas de LLM sur le chemin chaud |
 | `forget` | Soft-archivage (jamais supprimer) ou suppression d'observations spécifiques |
 | `consolidate` | Compression des mémoires verbeux alimentée par LLM |
 | `export` | Partager les mémoires au format JSON entre projets ou membres d'équipe |

package/README.ja.md

@@ -1,6 +1,3 @@
-<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
-<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
-
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
@@ -29,17 +26,52 @@
 
 ---
 
+## エビデンス — LongMemEval-S で 95.40% R@5
+
+MeMesh の検索エンジンは **FTS5 のみ**(LLM もホットパスのエンベディングも使用しない)で、公開されている [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) ベンチマーク(500 問、MIT ライセンス)で測定された結果です:
+
+| システム | R@5 | ソース |
+|---|---|---|
+| **MeMesh (Mode A, FTS5)** | **95.40%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | ベンダー自社申告 |
+| Supermemory | ~82% | ベンダー推定値 |
+| Zep | 63.8% | LongMemEval 論文 |
+| Mem0 | 49.0% | LongMemEval 論文 |
+
+再現コマンド、データセット SHA256、問題ごとの生結果、既知失敗の分析はすべて [`benchmarks/longmemeval/`](benchmarks/longmemeval/) にあります。約 10 秒で再実行可能です。
+
+---
+
 ## 60 秒で始める
 
-### ステップ 1: インストール
+### オプション A — Claude Code プラグイン(ワンライナーインストール)
+
+Claude Code を使っている場合、CLI 内から MeMesh をプラグインとしてインストールできます:
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin install memesh@pcircle-memesh
+```
+
+Claude Code がフック、スキル、MCP サーバーを自動的にワイヤリングします。セッション内自動キャプチャ、プロアクティブリコール、Claude Code 会話内の `/memesh` スキル(remember / recall / learn / forget)、エージェント向け MCP ツールとしての `remember` / `recall` / `forget` / `learn` がすべて使えるようになります。CLI とローカルダッシュボードもグローバルインストールなしで完全にアクセス可能です — `npx @pcircle/memesh <command>` であらゆる CLI コマンドが実行でき、`npx @pcircle/memesh` で `localhost:3737` のダッシュボードが起動します。MCP サーバーは Anthropic の公式プラグイン(例: `context7`)と同じ `npx` ベースの起動パターンを使用するため、どの機能にも `npm install -g` は不要です。
+
+### オプション B — npm グローバル(オプションの最適化)
+
+シェルの `PATH` にバイナリを直接配置したい場合(`memesh`、`memesh-mcp` 等が任意のターミナルで `npx` ルックアップなしに動作)、または `memesh-mcp` を **Claude Code 以外の MCP クライアント**(Cursor、Cline、ターミナル専用フロー)に固定パスの stdio コマンドとして公開したい場合:
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### ステップ 1.5: MeMesh を Claude Code に接続(推奨、一度きり)
+> **初回インストールに関する注意(一度きり):**
+> - **ネイティブモジュール** — `better-sqlite3` と `sqlite-vec` は macOS (arm64/x64)、Linux (x64/arm64)、Windows x64 でビルド済みバイナリ経由でインストールされます。珍しいプラットフォームやビルド済みバイナリが失敗した場合は、動作する C/C++ ツールチェインが必要です。
+> - **エンベディングモデル** — ローカルエンベディングをトリガーする最初の呼び出し(例: セマンティックモードでの `recall`)で `Xenova/all-MiniLM-L6-v2`(~80 MB)が `~/.memesh/models/` にダウンロードされます。以降の呼び出しは即時です。デフォルトの検索パス(FTS5)はこのダウンロードを必要としません。
 
-`npm install -g` は CLI を PATH に配置し MCP サーバーを登録しますが、MeMesh の Claude Code セッションフックは自動的にはワイヤリング**されません**。フックがないと `memesh remember` / `recall` は手動で使えますが、**自動キャプチャループ**(セッション → レッスン → 次のセッションで自発的にリコール)はサイレントになります。
+### ステップ 1.5: MeMesh を Claude Code に接続(npm パスのみ)
+
+**オプション A**(`/plugin install memesh@pcircle-memesh`)でインストールした場合はこのステップをスキップしてください — Claude Code がプラグインフックを自動的にワイヤリングします。
+
+**オプション B**(`npm install -g`)でインストールした場合、CLI は PATH に配置され MCP サーバーは登録されますが、Claude Code セッションフックは自動的にはワイヤリングされません。フックがないと `memesh remember` / `recall` は手動で使えますが、**自動キャプチャループ**(セッション → レッスン → 次のセッションで自発的にリコール)はサイレントになります。
 
 ```bash
 memesh install-hooks         # ~/.claude/settings.json に memesh フックを追加
@@ -50,6 +82,14 @@ memesh doctor                # "Hooks wired into Claude Code" が PASS になる
 
 ### ステップ 2: 決定を記録
 
+> 以下の bash 例は `memesh` が `PATH` 上にあること(オプション B)を前提にしています。オプション A(プラグイン専用)のユーザーには等価な 2 つのパスがあります: Claude Code 会話内で尋ねる(`/memesh` スキル + MCP ツールが同じフローをカバー)か、任意のシェルで `memesh` を `npx @pcircle/memesh` に置き換える — フラグは同じで、グローバルインストール不要です。
+
+```bash
+memesh remember "Use OAuth 2.0 with PKCE for the new auth"
+```
+
+または、後でフィルタリングしたい場合に安定した名前と型を付ける明示形式:
+
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
@@ -157,13 +197,14 @@ memesh export-schema \
 
 ## Claude Code での自動動作
 
-すべてを手動で記録する必要はありません。MeMesh に **6 つのフック** があり、作業中に知識を自動キャプチャ・注入します:
+すべてを手動で記録する必要はありません。MeMesh に **7 つのフック** があり、作業中に知識を自動キャプチャ・注入します:
 
 | タイミング | MeMesh の動作 |
 |---------|-----------|
-| **セッション開始時** | 最も関連の高いメモリ + 過去の教訓から得た予防警告 + エージェント編成バナーをロード |
+| **セッション開始時** | 最も関連の高いメモリ + 過去の教訓から得た予防警告をロード |
 | **ファイル編集前** | ファイルまたはプロジェクト関連のメモリをリコール (Claude がコード執筆前) |
-| **bash コマンド実行前** | 高い検証性を持つコマンド (テスト、ビルド、lint、マイグレーション、デプロイ、ベンチマーク) をバックグラウンドエージェントとして実行するよう促す |
+| **bash コマンド実行前** | (オプトイン)高い検証性を持つコマンド(テスト、ビルド、lint、マイグレーション、デプロイ、ベンチマーク)をバックグラウンドエージェントとして実行するよう Claude を促す |
+| **記憶を依頼したとき** | "remember this" / "guardar en memesh" / "sauvegarder dans memesh" / "記下來" の意図(5 言語)を検出し、Claude に memesh 使用をリマインド |
 | **`git commit` 後** | 変更内容と diff 統計を記録 |
 | **Claude 停止時** | 編集ファイル、修正エラー、失敗から自動生成した構造化教訓をキャプチャ |
 | **コンテキスト圧縮前** | コンテキスト限界で失われる前に知識を保存 |
@@ -172,6 +213,26 @@ memesh export-schema \
 
 ---
 
+## 設定
+
+すべての設定は環境変数経由です。デフォルトはローカル専用・ネットワークなしで、何も設定せずに動作するシステムが手に入ります。
+
+| 変数 | デフォルト | 動作 |
+|---|---|---|
+| `MEMESH_DB_PATH` | `~/.memesh/knowledge-graph.db` | SQLite データベースの保存場所を上書き。 |
+| `MEMESH_AUTO_CAPTURE` | `true` | 自動キャプチャフック(`Stop`、`PreCompact`)を完全に無効化。 |
+| `MEMESH_AUTO_DETECT_LLM` | 未設定 | `1` に設定すると、memesh がシェル環境変数(`OPENAI_API_KEY` 等)からプロバイダを自動検出し BYOK エンベディングに切り替えます。**新規インストールのデフォルトはローカル ONNX(384 次元)のみ** — クラウドエンベディングを使いたい場合のみオプトインしてください。このフラグが未設定なら、シェルに `OPENAI_API_KEY` があっても無視されます。 |
+| `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` のとき、または明示的にプロバイダを設定したときのみ使用。 |
+| `OLLAMA_HOST` | `http://localhost:11434` | ローカル Ollama プロバイダ使用時の Ollama エンドポイントを上書き。 |
+
+`memesh doctor` は解決された設定を表示するため、何が有効かを確認できます。
+
+npm がインストール済みバージョンを非推奨としてフラグした場合(典型的にはセキュリティアドバイザリ)、次のセッション開始時に強い `⚠️ MeMesh <ver> is DEPRECATED` バナーが先頭に表示され、`memesh update-status` がアップグレードまで同じ行を表示し続けます。チェックは `~/.memesh/update-check.<version>.json` にキャッシュされ、一時的なネットワーク障害で警告が薄まらないようになっています。
+
+---
+
 ## ダッシュボード
 
 7 つのタブ、11 言語対応、外部依存なし。サーバー実行中は `http://localhost:3737/dashboard` でアクセス可能。
@@ -190,7 +251,7 @@ memesh export-schema \
 
 ## スマート機能
 
-**🧠 スマート検索** — 「login security」で検索すると「OAuth PKCE」についてのメモリが見つかります。設定した LLM を使いクエリを関連用語で拡張します。
+**🧠 スマート検索** — 「login security」で検索すると「OAuth PKCE」についてのメモリが見つかります。MeMesh は設定された LLM を使い、クエリを関連用語で拡張します。
 
 **📊 スコア付きランキング** — 関連性 (30%) + 新しさ (25%) + 頻度 (15%) + 信頼度 (15%) + リコール影響度 (10%) + 時間的有効性 (5%) でランク付け。
 
@@ -218,7 +279,7 @@ memesh export-schema \
 
 ## スマートモードをアンロック (オプション)
 
-MeMesh はデフォルトでオフライン動作します。クエリ拡張、より賢い抽出、圧縮が必要な場合のみ LLM API キーを追加:
+MeMesh はデフォルトでオフライン動作します — リコールは厳密に LLM フリーのまま(箱出し状態で LongMemEval-S 95.40% R@5)。LLM API キーを追加するのは、その上に LLM 拡張の分析フローを重ねたい場合のみです: より賢いセッション抽出、新規メモリの自動タグ付け、失敗からのレッスン生成、`consolidate` / `dream` 圧縮:
 
 ```bash
 memesh config set llm.provider anthropic
@@ -233,10 +294,12 @@ memesh  # ダッシュボード → Settings タブを開く
 
 | | レベル 0 (デフォルト) | レベル 1 (スマートモード) |
 |---|---|---|
-| **検索** | FTS5 キーワードマッチング | + LLM クエリ拡張 (~97% リコール率) |
+| **検索** | FTS5 + sqlite-vec、95.40% R@5(~18ms/クエリ) | 変更なし — リコールはどのレベルでも LLM フリー |
 | **自動キャプチャ** | ルールベースパターン | + LLM が判断・教訓を抽出 |
-| **圧縮** | 利用不可 | `consolidate` で冗長メモリを圧縮 |
-| **コスト** | 無料、API キー不要 | 検索あたり ~$0.0001 (Haiku) |
+| **自動タグ付け** | 手動タグのみ | + LLM が新規メモリにタグを生成 |
+| **失敗分析** | 利用不可 | + LLM がセッションエラーを構造化教訓に変換 |
+| **圧縮** | 利用不可 | `consolidate` + `dream` が冗長メモリを圧縮 |
+| **コスト** | 無料、API キー不要 | 分析呼び出しあたり ~$0.0001(Haiku) |
 
 ---
 
@@ -245,7 +308,7 @@ memesh  # ダッシュボード → Settings タブを開く
 | ツール | 機能 |
 |------|------|
 | `remember` | 観察、関係、タグ付きで知識を保存 |
-| `recall` | 多要素スコアリングと LLM クエリ拡張のスマート検索 |
+| `recall` | FTS5 + sqlite-vec 検索、多要素スコアリング(関連性、新しさ、頻度、信頼度、時間的有効性) — ホットパスに LLM なし |
 | `forget` | ソフトアーカイブ (削除されない) または特定の観察を削除 |
 | `consolidate` | LLM が冗長メモリを圧縮 |
 | `export` | メモリを JSON でシェア (プロジェクト・チーム間) |