superlocalmemory 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -16,6 +16,22 @@ SuperLocalMemory V3 - Intelligent local memory system for AI coding assistants.
 
 ---
 
+## [3.2.0] - 2026-03-26
+
+### Added
+- **`slm doctor` command** — comprehensive pre-flight check: Python version, all dependency groups, embedding worker functional test, Ollama connectivity, API key validation, disk space, database integrity. Supports `--json` for agent-native output.
+- **`slm hooks install`** listed in CLI reference and README.
+- Dashboard, learning (lightgbm), and performance (diskcache, orjson) dependencies now install automatically during `npm install`.
+
+### Fixed
+- **Warmup reliability** — increased subprocess timeout from 60s to 180s for first-time model download. Added step-by-step progress output and direct in-process import diagnostics when worker fails.
+- **Mode B default model** — changed from `phi3:mini` to `llama3.2` to match `provider_presets()` and reduce first-time setup friction.
+- **postinstall.js** — now installs all 5 dependency groups (core, search, dashboard, learning, performance) with clear status messages per group.
+- **Error messages** — all embedding worker failures, engine fallbacks, and dashboard errors now suggest `slm doctor` for diagnosis.
+- **pyproject.toml** — added `diskcache` and `orjson` to core dependencies; aligned optional dependency versions with core.
+
+---
+
 ## [3.0.31] - 2026-03-21
 
 ### Fixed

package/README.md

@@ -54,6 +54,7 @@ Mathematical layers contribute **+12.7 percentage points** on average across 6 c
 ```bash
 npm install -g superlocalmemory
 slm setup     # Choose mode (A/B/C)
+slm doctor    # Verify everything is working
 slm warmup    # Pre-download embedding model (~500MB, optional)
 ```
 
@@ -323,13 +324,15 @@ Three new tools for AI assistants:
 | `slm trace "..."` | Recall with per-channel score breakdown |
 | `slm status` | System status |
 | `slm health` | Math layer health (Fisher, Sheaf, Langevin) |
+| `slm doctor` | Pre-flight check (deps, worker, Ollama, database) |
 | `slm mode a/b/c` | Switch operating mode |
 | `slm setup` | Interactive first-time wizard |
 | `slm warmup` | Pre-download embedding model |
 | `slm migrate` | V2 to V3 migration |
-| `slm dashboard` | Launch web dashboard |
+| `slm dashboard` | Launch 17-tab web dashboard |
 | `slm mcp` | Start MCP server (for IDE integration) |
 | `slm connect` | Configure IDE integrations |
+| `slm hooks install` | Wire auto-memory into Claude Code hooks |
 | `slm profile list/create/switch` | Profile management |
 
 ---
@@ -367,13 +370,16 @@ Three new tools for AI assistants:
 | **Node.js** | 14+ | npm package manager |
 | **Python** | 3.11+ | V3 engine runtime |
 
-All Python dependencies install automatically during `npm install`. If anything fails, the installer shows exact fix commands. BM25 keyword search works even without embeddings — you're never fully blocked.
+All Python dependencies install automatically during `npm install` — core math, dashboard server, learning engine, and performance optimizations. If anything fails, the installer shows exact fix commands. Run `slm doctor` after install to verify everything works. BM25 keyword search works even without embeddings — you're never fully blocked.
 
 | Component | Size | When |
 |:----------|:-----|:-----|
 | Core libraries (numpy, scipy, networkx) | ~50MB | During install |
+| Dashboard & MCP server (fastapi, uvicorn) | ~20MB | During install |
+| Learning engine (lightgbm) | ~10MB | During install |
 | Search engine (sentence-transformers, torch) | ~200MB | During install |
 | Embedding model (nomic-embed-text-v1.5, 768d) | ~500MB | First use or `slm warmup` |
+| **Mode B** requires [Ollama](https://ollama.com) + a model (`ollama pull llama3.2`) | ~2GB | Manual |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.1.1"
+version = "3.2.0"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "MIT"}
@@ -27,27 +27,29 @@ dependencies = [
     "uvicorn>=0.42.0",
     "websockets>=16.0",
     "lightgbm>=4.0.0",
+    "diskcache>=5.6.0",
+    "orjson>=3.9.0",
 ]
 
 [project.optional-dependencies]
 search = [
     "sentence-transformers>=2.5.0,<4.0.0",
-    "einops>=0.7.0,<1.0.0",
+    "einops>=0.8.2",
     "torch>=2.2.0",
     "scikit-learn>=1.3.0,<2.0.0",
     "geoopt>=0.5.0",
 ]
 ui = [
-    "fastapi>=0.109.0,<1.0.0",
-    "uvicorn[standard]>=0.27.0,<1.0.0",
+    "fastapi[all]>=0.135.1",
+    "uvicorn>=0.42.0",
     "python-multipart>=0.0.6,<1.0.0",
 ]
 learning = [
-    "lightgbm>=4.0.0,<5.0.0",
+    "lightgbm>=4.0.0",
 ]
 performance = [
-    "diskcache>=5.6.0,<6.0.0",
-    "orjson>=3.9.0,<4.0.0",
+    "diskcache>=5.6.0",
+    "orjson>=3.9.0",
 ]
 full = [
     "superlocalmemory[search,ui,learning,performance]",

package/scripts/postinstall.js

@@ -102,6 +102,7 @@ const coreDeps = [
     'numpy>=1.26.0', 'scipy>=1.12.0', 'networkx>=3.0',
     'httpx>=0.24.0', 'python-dateutil>=2.9.0',
     'rank-bm25>=0.2.2', 'vaderSentiment>=3.3.2',
+    'einops>=0.8.2', 'mcp>=1.0.0',
 ];
 
 if (pipInstall(coreDeps, 'core')) {
@@ -127,6 +128,35 @@ if (pipInstall(searchDeps, 'search')) {
     console.log('  pip install sentence-transformers einops geoopt');
 }
 
+// Dashboard dependencies (IMPORTANT — enables web dashboard + MCP server)
+const dashboardDeps = ['fastapi[all]>=0.135.1', 'uvicorn>=0.42.0', 'websockets>=16.0'];
+console.log('\nInstalling dashboard & server dependencies...');
+if (pipInstall(dashboardDeps, 'dashboard')) {
+    console.log('✓ Dashboard & MCP server dependencies installed (fastapi + uvicorn)');
+} else {
+    console.log('⚠ Dashboard installation failed.');
+    console.log('  Run manually: pip install \'fastapi[all]\' uvicorn websockets');
+}
+
+// Learning dependencies (enables adaptive retrieval after 200+ signals)
+const learningDeps = ['lightgbm>=4.0.0'];
+console.log('\nInstalling learning engine...');
+if (pipInstall(learningDeps, 'learning')) {
+    console.log('✓ Learning engine installed (lightgbm — adaptive ranking)');
+} else {
+    console.log('⚠ Learning installation failed (retrieval still works without it).');
+    console.log('  Run manually: pip install lightgbm');
+}
+
+// Performance dependencies (optional — improves caching and JSON speed)
+const perfDeps = ['diskcache>=5.6.0', 'orjson>=3.9.0'];
+console.log('\nInstalling performance optimizations...');
+if (pipInstall(perfDeps, 'performance')) {
+    console.log('✓ Performance optimizations installed (diskcache + orjson)');
+} else {
+    console.log('⚠ Performance deps skipped (system works fine without them).');
+}
+
 // --- Step 4: Detect V2 installation ---
 const V2_HOME = path.join(os.homedir(), '.claude-memory');
 if (fs.existsSync(V2_HOME) && fs.existsSync(path.join(V2_HOME, 'memory.db'))) {
@@ -149,13 +179,17 @@ console.log('  ✓ SuperLocalMemory V3 installed successfully!');
 console.log('');
 console.log('  Quick start:');
 console.log('    slm setup          # First-time configuration');
-console.log('    slm status         # Check system status');
+console.log('    slm doctor         # Pre-flight check (verify everything works)');
+console.log('    slm warmup         # Pre-download embedding model (~500MB)');
 console.log('    slm remember "..." # Store a memory');
 console.log('    slm recall "..."   # Search memories');
+console.log('    slm dashboard      # Open 17-tab web dashboard');
 console.log('');
 console.log('  Prerequisites satisfied:');
 console.log('    ✓ Python 3.11+');
 console.log('    ✓ Core math & search libraries');
+console.log('    ✓ Dashboard server (fastapi, uvicorn)');
+console.log('    ✓ Learning engine (lightgbm)');
 console.log('    ✓ Data directory (~/.superlocalmemory/)');
 console.log('');
 console.log('  Docs: https://github.com/qualixar/superlocalmemory/wiki');

package/src/superlocalmemory/cli/commands.py

@@ -32,6 +32,7 @@ def dispatch(args: Namespace) -> None:
         "update": cmd_update,
         "status": cmd_status,
         "health": cmd_health,
+        "doctor": cmd_doctor,
         "trace": cmd_trace,
         "mcp": cmd_mcp,
         "warmup": cmd_warmup,
@@ -592,6 +593,254 @@ def cmd_health(args: Namespace) -> None:
     print(f"  Mode: {config.mode.value.upper()}")
 
 
+def cmd_doctor(args: Namespace) -> None:
+    """Comprehensive pre-flight check — verify everything works."""
+    import shutil
+    from pathlib import Path
+
+    use_json = getattr(args, "json", False)
+    checks: list[dict] = []
+    passed = warned = failed = 0
+
+    def _check(name: str, status: str, detail: str, fix: str = ""):
+        nonlocal passed, warned, failed
+        checks.append({"name": name, "status": status, "detail": detail, "fix": fix})
+        if status == "PASS":
+            passed += 1
+        elif status == "WARN":
+            warned += 1
+        else:
+            failed += 1
+        if not use_json:
+            tag = {"PASS": "[PASS]", "WARN": "[WARN]", "FAIL": "[FAIL]"}[status]
+            line = f"  {tag} {name}: {detail}"
+            if fix:
+                line += f"\n         Fix: {fix}"
+            print(line)
+
+    if not use_json:
+        print("SuperLocalMemory V3 — Doctor (Pre-flight Check)")
+        print("=" * 50)
+        print()
+
+    # 1. Python version
+    v = sys.version_info
+    if v >= (3, 11):
+        _check("Python", "PASS", f"{v.major}.{v.minor}.{v.micro} (>= 3.11)")
+    else:
+        _check("Python", "FAIL", f"{v.major}.{v.minor}.{v.micro} (need >= 3.11)",
+               "Install Python 3.11+ from https://python.org/downloads/")
+
+    # 2. Core deps
+    core_modules = {
+        "numpy": "numpy", "scipy": "scipy", "networkx": "networkx",
+        "httpx": "httpx", "dateutil": "python-dateutil",
+        "rank_bm25": "rank-bm25", "vaderSentiment": "vadersentiment",
+        "einops": "einops",
+    }
+    core_ok, core_versions = [], []
+    for mod, pkg in core_modules.items():
+        try:
+            m = __import__(mod)
+            ver = getattr(m, "__version__", "?")
+            core_ok.append(mod)
+            core_versions.append(f"{mod} {ver}")
+        except ImportError:
+            pass
+    if len(core_ok) == len(core_modules):
+        _check("Core deps", "PASS", ", ".join(core_versions[:4]) + "...")
+    else:
+        missing = set(core_modules) - set(core_ok)
+        _check("Core deps", "FAIL", f"Missing: {', '.join(missing)}",
+               "pip install " + " ".join(core_modules[m] for m in missing))
+
+    # 3. Search deps
+    search_mods = {"sentence_transformers": "sentence-transformers", "torch": "torch",
+                   "sklearn": "scikit-learn", "geoopt": "geoopt"}
+    search_ok = []
+    for mod, pkg in search_mods.items():
+        try:
+            __import__(mod)
+            search_ok.append(mod)
+        except ImportError:
+            pass
+    if len(search_ok) == len(search_mods):
+        _check("Search deps", "PASS", "sentence-transformers, torch, sklearn, geoopt")
+    else:
+        missing = set(search_mods) - set(search_ok)
+        _check("Search deps", "WARN", f"Missing: {', '.join(missing)}",
+               "pip install 'superlocalmemory[search]'")
+
+    # 4. Dashboard deps
+    dash_ok = True
+    for mod in ["fastapi", "uvicorn", "websockets"]:
+        try:
+            __import__(mod)
+        except ImportError:
+            dash_ok = False
+            break
+    if dash_ok:
+        _check("Dashboard deps", "PASS", "fastapi, uvicorn, websockets")
+    else:
+        _check("Dashboard deps", "WARN", "Missing dashboard deps",
+               "pip install 'fastapi[all]' uvicorn websockets")
+
+    # 5. Learning deps
+    try:
+        import lightgbm
+        _check("Learning deps", "PASS", f"lightgbm {lightgbm.__version__}")
+    except ImportError:
+        _check("Learning deps", "WARN", "lightgbm not installed",
+               "pip install lightgbm")
+    except OSError as exc:
+        _check("Learning deps", "WARN", f"lightgbm installed but broken: {exc}",
+               "brew install libomp && pip install --force-reinstall lightgbm")
+
+    # 6. Performance deps
+    perf_ok = []
+    for mod in ["diskcache", "orjson"]:
+        try:
+            __import__(mod)
+            perf_ok.append(mod)
+        except ImportError:
+            pass
+    if len(perf_ok) == 2:
+        _check("Performance deps", "PASS", "diskcache, orjson")
+    else:
+        missing = {"diskcache", "orjson"} - set(perf_ok)
+        _check("Performance deps", "WARN", f"Missing: {', '.join(missing)}",
+               "pip install diskcache orjson")
+
+    # 7. Embedding worker functional test
+    try:
+        import subprocess as _sp
+        import json as _json
+
+        env = {
+            **__import__("os").environ,
+            "CUDA_VISIBLE_DEVICES": "",
+            "PYTORCH_MPS_HIGH_WATERMARK_RATIO": "0.0",
+            "TOKENIZERS_PARALLELISM": "false",
+            "TORCH_DEVICE": "cpu",
+        }
+        proc = _sp.Popen(
+            [sys.executable, "-m", "superlocalmemory.core.embedding_worker"],
+            stdin=_sp.PIPE, stdout=_sp.PIPE, stderr=_sp.DEVNULL,
+            text=True, bufsize=1, env=env,
+        )
+        proc.stdin.write(_json.dumps({"cmd": "ping"}) + "\n")
+        proc.stdin.flush()
+
+        import select as _sel
+        ready, _, _ = _sel.select([proc.stdout], [], [], 30)
+        if ready:
+            resp = _json.loads(proc.stdout.readline())
+            if resp.get("ok"):
+                _check("Embedding worker", "PASS",
+                       f"responsive (PID {proc.pid}, Python {sys.executable})")
+            else:
+                _check("Embedding worker", "FAIL",
+                       f"error: {resp.get('error', 'unknown')}",
+                       "pip install sentence-transformers einops torch")
+        else:
+            _check("Embedding worker", "FAIL", "timed out (30s)",
+                   "slm warmup")
+        proc.stdin.write(_json.dumps({"cmd": "quit"}) + "\n")
+        proc.stdin.flush()
+        proc.wait(timeout=5)
+    except FileNotFoundError:
+        _check("Embedding worker", "FAIL", "embedding_worker module not found",
+               "Reinstall: npm install -g superlocalmemory")
+    except Exception as exc:
+        _check("Embedding worker", "FAIL", str(exc),
+               "slm warmup")
+
+    # 8. Ollama connectivity (Mode B only)
+    try:
+        from superlocalmemory.core.config import SLMConfig
+        config = SLMConfig.load()
+        if config.mode.value == "b":
+            import httpx
+            try:
+                resp = httpx.get(
+                    f"{config.llm.api_base}/api/tags", timeout=5.0,
+                )
+                if resp.status_code == 200:
+                    models = [m["name"].split(":")[0] for m in resp.json().get("models", [])]
+                    has_llm = config.llm.model.split(":")[0] in models
+                    if has_llm:
+                        _check("Ollama", "PASS",
+                               f"running, {len(models)} models, '{config.llm.model}' available")
+                    else:
+                        _check("Ollama", "WARN",
+                               f"running but '{config.llm.model}' not pulled",
+                               f"ollama pull {config.llm.model}")
+                else:
+                    _check("Ollama", "WARN", f"HTTP {resp.status_code}",
+                           "brew services start ollama")
+            except Exception:
+                _check("Ollama", "WARN", "not reachable at " + config.llm.api_base,
+                       "brew services start ollama")
+        elif config.mode.value == "c":
+            # Mode C — check API key
+            if config.llm.api_key:
+                _check("API key", "PASS",
+                       f"provider={config.llm.provider}, key=***{config.llm.api_key[-4:]}")
+            else:
+                _check("API key", "WARN", "no API key configured",
+                       "slm provider set")
+    except Exception:
+        pass  # Config load failed — already caught above
+
+    # 9. Disk space
+    slm_home = Path.home() / ".superlocalmemory"
+    try:
+        usage = shutil.disk_usage(slm_home if slm_home.exists() else Path.home())
+        free_gb = usage.free / (1024 ** 3)
+        if free_gb >= 2.0:
+            _check("Disk space", "PASS", f"{free_gb:.1f} GB free")
+        else:
+            _check("Disk space", "WARN", f"{free_gb:.1f} GB free (< 2 GB)",
+                   "Free up disk space")
+    except Exception:
+        pass
+
+    # 10. Database integrity
+    db_path = slm_home / "memory.db"
+    if db_path.exists():
+        try:
+            import sqlite3
+            conn = sqlite3.connect(str(db_path))
+            result = conn.execute("PRAGMA integrity_check").fetchone()
+            conn.close()
+            if result and result[0] == "ok":
+                size_mb = db_path.stat().st_size / (1024 * 1024)
+                _check("Database", "PASS", f"OK ({size_mb:.2f} MB)")
+            else:
+                _check("Database", "FAIL", f"integrity check: {result}",
+                       "Backup and recreate database")
+        except Exception as exc:
+            _check("Database", "FAIL", str(exc))
+    else:
+        _check("Database", "PASS", "not yet created (will initialize on first use)")
+
+    # Summary
+    if use_json:
+        from superlocalmemory.cli.json_output import json_print
+        next_actions = []
+        for c in checks:
+            if c["fix"]:
+                next_actions.append({"command": c["fix"], "description": f"Fix {c['name']}"})
+        json_print("doctor", data={
+            "checks": checks,
+            "summary": {"passed": passed, "warned": warned, "failed": failed},
+        }, next_actions=next_actions)
+    else:
+        print(f"\nSummary: {passed} passed, {warned} warnings, {failed} failed")
+        if failed > 0:
+            print("Run the suggested fix commands above, then re-run: slm doctor")
+
+
 def cmd_trace(args: Namespace) -> None:
     """Recall with per-channel score breakdown."""
     from superlocalmemory.core.engine import MemoryEngine
@@ -654,35 +903,74 @@ def cmd_mcp(_args: Namespace) -> None:
 
 def cmd_warmup(_args: Namespace) -> None:
     """Pre-download the embedding model so first use is instant."""
-    print("Downloading embedding model (nomic-ai/nomic-embed-text-v1.5)...")
-    print("This is ~500MB and only needed once.\n")
+    import superlocalmemory.core.embeddings as _emb_mod
+
+    print("SuperLocalMemory V3 — Embedding Model Warmup")
+    print("=" * 50)
+    print(f"  Python: {sys.executable}")
+    print(f"  Model:  nomic-ai/nomic-embed-text-v1.5 (~500MB)")
+    print()
+
+    # Increase timeout for first-time download
+    original_timeout = _emb_mod._SUBPROCESS_RESPONSE_TIMEOUT
+    _emb_mod._SUBPROCESS_RESPONSE_TIMEOUT = 180  # 3 min for cold start
 
     try:
         from superlocalmemory.core.config import EmbeddingConfig
         from superlocalmemory.core.embeddings import EmbeddingService
 
         config = EmbeddingConfig()
+
+        print("Step 1/3: Spawning embedding worker subprocess...")
         svc = EmbeddingService(config)
 
-        # Force model load (triggers download)
-        if svc.is_available:
-            # Verify it works
-            emb = svc.embed("warmup test")
-            if emb and len(emb) == config.dimension:
-                print(f"\nModel ready: {config.model_name} ({config.dimension}-dim)")
-                print("Semantic search is fully operational.")
-            else:
-                print("\nModel loaded but embedding verification failed.")
-                print("Run: pip install sentence-transformers einops")
+        if not svc.is_available:
+            print("\n[FAIL] Embedding service not available.")
+            _warmup_diagnose()
+            return
+
+        print("Step 2/3: Loading model (may download ~500MB on first run)...")
+        emb = svc.embed("warmup test")
+
+        if emb and len(emb) == config.dimension:
+            print("Step 3/3: Verifying embedding output...")
+            print(f"\n[PASS] Model ready: {config.model_name} ({config.dimension}-dim)")
+            print("Semantic search is fully operational.")
         else:
-            print("\nModel could not load.")
-            print("Install dependencies: pip install sentence-transformers einops torch")
+            print("\n[FAIL] Model loaded but embedding verification failed.")
+            _warmup_diagnose()
+
     except ImportError as exc:
-        print(f"\nMissing dependency: {exc}")
-        print("Install with: pip install sentence-transformers einops torch")
+        print(f"\n[FAIL] Missing dependency: {exc}")
+        print("Fix: pip install sentence-transformers einops torch")
     except Exception as exc:
-        print(f"\nWarmup failed: {exc}")
-        print("Check your internet connection and try again.")
+        print(f"\n[FAIL] Warmup failed: {exc}")
+        _warmup_diagnose()
+    finally:
+        _emb_mod._SUBPROCESS_RESPONSE_TIMEOUT = original_timeout
+
+
+def _warmup_diagnose() -> None:
+    """Diagnostic helper when warmup fails."""
+    print("\nDiagnosing...")
+    print(f"  Python executable: {sys.executable}")
+    try:
+        from sentence_transformers import SentenceTransformer
+        print("  sentence-transformers: importable")
+        m = SentenceTransformer(
+            "nomic-ai/nomic-embed-text-v1.5", trust_remote_code=True, device="cpu",
+        )
+        v = m.encode(["test"], normalize_embeddings=True)
+        print(f"  Direct embed: OK (dim={v.shape[1]})")
+        print("\n  Issue: Subprocess worker failed but direct import works.")
+        print("  This is likely a Python path mismatch between Node.js wrapper")
+        print("  and your current shell. Run: slm doctor")
+    except ImportError as ie:
+        print(f"  sentence-transformers: NOT importable ({ie})")
+        print("  Fix: pip install sentence-transformers einops torch")
+    except Exception as de:
+        print(f"  Direct embed failed: {de}")
+        print("  Run: slm doctor")
 
 
 def cmd_dashboard(args: Namespace) -> None:
@@ -690,7 +978,8 @@ def cmd_dashboard(args: Namespace) -> None:
     try:
         import uvicorn
     except ImportError:
-        print("Dashboard requires: pip install 'fastapi[all]' uvicorn")
+        print("Dashboard requires additional deps. Run: slm doctor")
+        print("Or install manually: pip install 'fastapi[all]' uvicorn")
         sys.exit(1)
 
     import socket

package/src/superlocalmemory/cli/main.py

@@ -153,6 +153,10 @@ def main() -> None:
     trace_p.add_argument("query", help="Search query")
     trace_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
 
+    # -- Diagnostics (continued) ----------------------------------------
+    doctor_p = sub.add_parser("doctor", help="Pre-flight check: deps, embedding worker, connectivity")
+    doctor_p.add_argument("--json", action="store_true", help="Output structured JSON (agent-native)")
+
     # -- Services ------------------------------------------------------
     sub.add_parser("mcp", help="Start MCP server (stdio transport for IDE integration)")
     sub.add_parser("warmup", help="Pre-download embedding model (~500MB, one-time)")

package/src/superlocalmemory/core/config.py

@@ -366,7 +366,7 @@ class SLMConfig:
                 ),
                 llm=LLMConfig(
                     provider=llm_provider or "ollama",
-                    model=llm_model or "phi3:mini",
+                    model=llm_model or "llama3.2",
                     api_base=llm_api_base or "http://localhost:11434",
                     api_key=llm_api_key or "",
                 ),

package/src/superlocalmemory/core/embeddings.py

@@ -164,7 +164,12 @@ class EmbeddingService:
                     _SUBPROCESS_RESPONSE_TIMEOUT,
                 )
                 if not resp_line:
-                    logger.warning("Worker returned empty or timed out, restarting")
+                    logger.warning(
+                        "Embedding worker timed out after %ds. On first run, model "
+                        "download can take several minutes. Run 'slm doctor' to "
+                        "diagnose or 'slm warmup' to pre-download the model.",
+                        _SUBPROCESS_RESPONSE_TIMEOUT,
+                    )
                     self._kill_worker()
                     return None
                 resp = json.loads(resp_line)
@@ -174,7 +179,11 @@ class EmbeddingService:
                 self._reset_idle_timer()
                 return resp["vectors"]
             except (BrokenPipeError, OSError, json.JSONDecodeError) as exc:
-                logger.warning("Worker communication failed: %s", exc)
+                logger.warning(
+                    "Embedding worker communication failed: %s. "
+                    "Run 'slm doctor' to check dependencies and Python version.",
+                    exc,
+                )
                 self._kill_worker()
                 return None
 
@@ -231,7 +240,12 @@ class EmbeddingService:
             logger.info("Embedding worker spawned (PID %d)", self._worker_proc.pid)
             self._worker_ready = True
         except Exception as exc:
-            logger.warning("Failed to spawn embedding worker: %s", exc)
+            logger.warning(
+                "Failed to spawn embedding worker: %s. "
+                "Run 'slm doctor' to verify your Python environment. "
+                "Using Python: %s",
+                exc, sys.executable,
+            )
             self._available = False
             self._worker_proc = None
 

package/src/superlocalmemory/core/engine.py

@@ -175,9 +175,9 @@ class MemoryEngine:
             emb = cls(emb_cfg)
             if emb.is_available:
                 return emb
-            logger.warning("EmbeddingService not available. BM25-only mode.")
+            logger.warning("EmbeddingService not available. BM25-only mode. Run 'slm doctor' to diagnose.")
         except Exception as exc:
-            logger.warning("Embeddings unavailable (%s). BM25-only mode.", exc)
+            logger.warning("Embeddings unavailable (%s). BM25-only mode. Run 'slm doctor' to diagnose.", exc)
         return None
 
     def store(

package/src/superlocalmemory/core/worker_pool.py

@@ -169,7 +169,7 @@ class WorkerPool:
 
                 resp_line = self._proc.stdout.readline()
                 if not resp_line:
-                    logger.warning("Worker returned empty, restarting")
+                    logger.warning("Worker returned empty, restarting. Run 'slm doctor' to diagnose.")
                     self._kill()
                     return {"ok": False, "error": "Worker died"}
 
@@ -177,7 +177,7 @@ class WorkerPool:
                 return json.loads(resp_line)
 
             except (BrokenPipeError, OSError, json.JSONDecodeError) as exc:
-                logger.warning("Worker communication failed: %s", exc)
+                logger.warning("Worker communication failed: %s. Run 'slm doctor' to diagnose.", exc)
                 self._kill()
                 return {"ok": False, "error": str(exc)}
 
@@ -207,7 +207,7 @@ class WorkerPool:
             )
             logger.info("Recall worker spawned (PID %d)", self._proc.pid)
         except Exception as exc:
-            logger.error("Failed to spawn recall worker: %s", exc)
+            logger.error("Failed to spawn recall worker: %s. Run 'slm doctor' to diagnose. Python: %s", exc, sys.executable)
             self._proc = None
 
     def _kill(self) -> None: