superlocalmemory 3.1.0 → 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)
 ```
 
@@ -84,7 +85,7 @@ slm status
 }
 ```
 
-24 MCP tools available. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools.
+27 MCP tools + 7 resources available. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Continue, Cody, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, and 17+ AI tools. **V3.1: Active Memory tools auto-learn your patterns.**
 
 ### Dual Interface: MCP + CLI
 
@@ -247,6 +248,42 @@ slm dashboard    # Opens at http://localhost:8765
 
 ---
 
+## Active Memory (V3.1) — Memory That Learns
+
+Most AI memory systems are passive databases — you store, you search, you get results. **SuperLocalMemory learns.**
+
+Every recall you make generates learning signals. Over time, the system adapts to your patterns:
+
+| Phase | Signals | What Happens |
+|-------|---------|-------------|
+| **Baseline** | 0-19 | Cross-encoder ranking (default behavior) |
+| **Rule-Based** | 20+ | Heuristic boosts: recency, access count, trust score |
+| **ML Model** | 200+ | LightGBM model trained on YOUR usage patterns |
+
+### Zero-Cost Learning Signals
+No LLM tokens spent. Four mathematical signals computed locally:
+- **Co-Retrieval** — memories retrieved together strengthen their connections
+- **Confidence Lifecycle** — accessed facts get boosted, unused facts decay
+- **Channel Performance** — tracks which retrieval channel works best for your queries
+- **Entropy Gap** — surprising content gets prioritized for deeper indexing
+
+### Auto-Capture & Auto-Recall
+```bash
+slm hooks install     # Install Claude Code hooks for invisible injection
+slm observe "We decided to use PostgreSQL"  # Auto-detects decisions, bugs, preferences
+slm session-context   # Get relevant context at session start
+```
+
+### MCP Active Memory Tools
+Three new tools for AI assistants:
+- `session_init` — call at session start, get relevant project context automatically
+- `observe` — send conversation content, auto-captures decisions/bugs/preferences
+- `report_feedback` — explicit feedback for faster learning
+
+**No competitor learns at zero token cost.** Mem0, Zep, and Letta all require cloud LLM calls for their learning loops. SLM learns through mathematics.
+
+---
+
 ## Features
 
 ### Retrieval
@@ -287,13 +324,15 @@ slm dashboard    # Opens at http://localhost:8765
 | `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 |
 
 ---
@@ -331,13 +370,16 @@ slm dashboard    # Opens at http://localhost:8765
 | **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/docs/getting-started.md

@@ -2,7 +2,7 @@
 > SuperLocalMemory V3 Documentation
 > https://superlocalmemory.com | Part of Qualixar
 
-Get your AI's memory system running in under 5 minutes.
+Get your AI's memory system running in under 5 minutes. **V3.1: Now with Active Memory — your memory learns from your usage and gets smarter over time, at zero token cost.**
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.1.0",
+  "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.0"
+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,
@@ -291,6 +292,12 @@ def cmd_recall(args: Namespace) -> None:
         ])
         return
 
+    # Record learning signals (CLI path — works without MCP)
+    try:
+        _cli_record_signals(config, args.query, response.results)
+    except Exception:
+        pass
+
     if not response.results:
         print("No memories found.")
         return
@@ -298,6 +305,26 @@ def cmd_recall(args: Namespace) -> None:
         print(f"  {i}. [{r.score:.2f}] {r.fact.content[:120]}")
 
 
+def _cli_record_signals(config, query, results):
+    """Record learning signals from CLI recall (no MCP dependency)."""
+    from pathlib import Path
+    from superlocalmemory.learning.feedback import FeedbackCollector
+    from superlocalmemory.learning.signals import LearningSignals
+    slm_dir = Path.home() / ".superlocalmemory"
+    pid = config.active_profile
+    fact_ids = [r.fact.fact_id for r in results[:10]]
+    if not fact_ids:
+        return
+    FeedbackCollector(slm_dir / "learning.db").record_implicit(
+        profile_id=pid, query=query,
+        fact_ids_returned=fact_ids, fact_ids_available=fact_ids,
+    )
+    signals = LearningSignals(slm_dir / "learning.db")
+    signals.record_co_retrieval(pid, fact_ids)
+    for fid in fact_ids[:5]:
+        LearningSignals.boost_confidence(str(slm_dir / "memory.db"), fid)
+
+
 def cmd_forget(args: Namespace) -> None:
     """Delete memories matching a query."""
     from superlocalmemory.core.engine import MemoryEngine
@@ -566,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
@@ -628,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:
@@ -664,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:

package/src/superlocalmemory/learning/feedback.py

@@ -314,3 +314,6 @@ class FeedbackCollector:
             }
         finally:
             conn.close()
+
+    # Alias used by dashboard routes
+    get_feedback_summary = get_summary

package/src/superlocalmemory/mcp/tools_active.py

@@ -17,10 +17,37 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import logging
+from pathlib import Path
 from typing import Callable
 
 logger = logging.getLogger(__name__)
 
+MEMORY_DIR = Path.home() / ".superlocalmemory"
+DB_PATH = MEMORY_DIR / "memory.db"
+
+
+def _emit_event(event_type: str, payload: dict | None = None,
+                source_agent: str = "mcp_client") -> None:
+    """Emit an event to the EventBus (best-effort, never raises)."""
+    try:
+        from superlocalmemory.infra.event_bus import EventBus
+        bus = EventBus.get_instance(str(DB_PATH))
+        bus.emit(event_type, payload=payload, source_agent=source_agent,
+                 source_protocol="mcp")
+    except Exception:
+        pass
+
+
+def _register_agent(agent_id: str, profile_id: str) -> None:
+    """Register an agent in the AgentRegistry (best-effort)."""
+    try:
+        from superlocalmemory.core.registry import AgentRegistry
+        registry_path = MEMORY_DIR / "agents.json"
+        registry = AgentRegistry(persist_path=registry_path)
+        registry.register_agent(agent_id, profile_id)
+    except Exception:
+        pass
+
 
 def register_active_tools(server, get_engine: Callable) -> None:
     """Register 3 active memory tools on *server*."""
@@ -78,6 +105,14 @@ def register_active_tools(server, get_engine: Callable) -> None:
             except Exception:
                 pass
 
+            # Register agent + emit event
+            _register_agent("mcp_client", pid)
+            _emit_event("agent.connected", {
+                "agent_id": "mcp_client",
+                "project_path": project_path,
+                "memory_count": len(memories),
+            })
+
             return {
                 "success": True,
                 "context": context,
@@ -148,6 +183,14 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 metadata={"agent_id": agent_id, "source": "auto-observe"},
             )
 
+            if stored:
+                _emit_event("memory.created", {
+                    "agent_id": agent_id,
+                    "category": decision.category,
+                    "content_preview": content[:80],
+                    "source": "auto-observe",
+                }, source_agent=agent_id)
+
             return {
                 "captured": stored,
                 "category": decision.category,
@@ -191,6 +234,13 @@ def register_active_tools(server, get_engine: Callable) -> None:
 
             count = engine._adaptive_learner.get_feedback_count(pid)
 
+            _emit_event("pattern.learned", {
+                "fact_id": fact_id,
+                "feedback": feedback,
+                "total_signals": count,
+                "phase": 1 if count < 50 else (2 if count < 200 else 3),
+            })
+
             return {
                 "success": True,
                 "feedback_id": record.feedback_id,

package/src/superlocalmemory/mcp/tools_core.py

@@ -15,10 +15,25 @@ from __future__ import annotations
 
 import json
 import logging
+from pathlib import Path
 from typing import Any, Callable
 
 logger = logging.getLogger(__name__)
 
+_DB_PATH = str(Path.home() / ".superlocalmemory" / "memory.db")
+
+
+def _emit_event(event_type: str, payload: dict | None = None,
+                source_agent: str = "mcp_client") -> None:
+    """Emit an event to the EventBus (best-effort, never raises)."""
+    try:
+        from superlocalmemory.infra.event_bus import EventBus
+        bus = EventBus.get_instance(_DB_PATH)
+        bus.emit(event_type, payload=payload, source_agent=source_agent,
+                 source_protocol="mcp")
+    except Exception:
+        pass
+
 
 def _record_recall_hits(get_engine: Callable, query: str, results: list[dict]) -> None:
     """Record implicit feedback + learning signals for each recall.
@@ -89,6 +104,11 @@ def register_core_tools(server, get_engine: Callable) -> None:
                 "session_id": session_id,
             })
             if result.get("ok"):
+                _emit_event("memory.created", {
+                    "content_preview": content[:80],
+                    "agent_id": agent_id,
+                    "fact_count": result.get("count", 0),
+                }, source_agent=agent_id)
                 return {"success": True, "fact_ids": result.get("fact_ids", []), "count": result.get("count", 0)}
             return {"success": False, "error": result.get("error", "Store failed")}
         except Exception as exc:
@@ -108,6 +128,12 @@ def register_core_tools(server, get_engine: Callable) -> None:
                     _record_recall_hits(get_engine, query, result.get("results", []))
                 except Exception:
                     pass  # Feedback is non-critical, never block recall
+                _emit_event("memory.recalled", {
+                    "query": query[:80],
+                    "result_count": result.get("result_count", 0),
+                    "query_type": result.get("query_type", "unknown"),
+                    "agent_id": agent_id,
+                }, source_agent=agent_id)
                 return {
                     "success": True,
                     "results": result.get("results", []),
@@ -362,6 +388,10 @@ def register_core_tools(server, get_engine: Callable) -> None:
             })
             if result.get("ok"):
                 logger.info("Memory deleted: %s by agent: %s", fact_id[:16], agent_id)
+                _emit_event("memory.deleted", {
+                    "fact_id": fact_id,
+                    "agent_id": agent_id,
+                }, source_agent=agent_id)
                 return {"success": True, "deleted": fact_id, "agent_id": agent_id}
             return {"success": False, "error": result.get("error", "Delete failed")}
         except Exception as exc:

package/src/superlocalmemory/server/routes/agents.py

@@ -43,13 +43,15 @@ async def get_agents(
     if not REGISTRY_AVAILABLE:
         return {"agents": [], "count": 0, "message": "Agent registry not available"}
     try:
-        engine = getattr(request.app.state, "engine", None)
-        if engine and hasattr(engine, '_db'):
-            registry = AgentRegistry(engine._db)
-            agents = registry.list_agents(protocol=protocol, limit=limit)
-            stats = registry.get_stats()
-            return {"agents": agents, "count": len(agents), "stats": stats}
-        return {"agents": [], "count": 0, "message": "Engine not initialized"}
+        from pathlib import Path
+        registry_path = Path.home() / ".superlocalmemory" / "agents.json"
+        registry = AgentRegistry(persist_path=registry_path)
+        agents = registry.list_agents()
+        return {
+            "agents": agents,
+            "count": len(agents),
+            "stats": {"total_agents": len(agents)},
+        }
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Agent registry error: {str(e)}")
 
@@ -60,11 +62,11 @@ async def get_agent_stats(request: Request):
     if not REGISTRY_AVAILABLE:
         return {"total_agents": 0, "message": "Agent registry not available"}
     try:
-        engine = getattr(request.app.state, "engine", None)
-        if engine and hasattr(engine, '_db'):
-            registry = AgentRegistry(engine._db)
-            return registry.get_stats()
-        return {"total_agents": 0, "message": "Engine not initialized"}
+        from pathlib import Path
+        registry_path = Path.home() / ".superlocalmemory" / "agents.json"
+        registry = AgentRegistry(persist_path=registry_path)
+        agents = registry.list_agents()
+        return {"total_agents": len(agents)}
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Agent stats error: {str(e)}")
 

package/src/superlocalmemory/server/routes/learning.py

@@ -104,7 +104,7 @@ async def learning_status():
         feedback = _get_feedback()
         if feedback:
             try:
-                old_stats = feedback.get_feedback_summary()
+                old_stats = feedback.get_feedback_summary(active_profile)
                 if isinstance(old_stats, dict):
                     old_stats["feedback_count"] = signal_count
                     old_stats["active_profile"] = active_profile
@@ -274,8 +274,9 @@ async def feedback_stats():
         by_type = {}
 
         if feedback:
-            summary = feedback.get_feedback_summary()
-            total = summary.get("total_signals", 0)
+            profile = get_active_profile()
+            summary = feedback.get_feedback_summary(profile)
+            total = summary.get("total", summary.get("total_signals", 0))
             by_channel = summary.get("by_channel", {})
             by_type = summary.get("by_type", {})
 

package/src/superlocalmemory/server/routes/lifecycle.py

@@ -38,32 +38,32 @@ async def lifecycle_status():
         conn = sqlite3.connect(str(DB_PATH))
         conn.row_factory = sqlite3.Row
 
-        # Try V3 schema first (atomic_facts with lifecycle_state)
+        # Try V3 schema first (atomic_facts with lifecycle column)
         states = {}
         try:
             rows = conn.execute(
-                "SELECT lifecycle_state, COUNT(*) as cnt "
-                "FROM atomic_facts WHERE profile_id = ? GROUP BY lifecycle_state",
+                "SELECT lifecycle, COUNT(*) as cnt "
+                "FROM atomic_facts WHERE profile_id = ? GROUP BY lifecycle",
                 (profile,),
             ).fetchall()
             states = {
-                (row['lifecycle_state'] or 'active'): row['cnt']
+                (row['lifecycle'] or 'active'): row['cnt']
                 for row in rows
             }
         except sqlite3.OperationalError:
             # V2 fallback: memories table
             try:
                 rows = conn.execute(
-                    "SELECT lifecycle_state, COUNT(*) as cnt "
-                    "FROM memories WHERE profile = ? GROUP BY lifecycle_state",
+                    "SELECT lifecycle, COUNT(*) as cnt "
+                    "FROM memories WHERE profile = ? GROUP BY lifecycle",
                     (profile,),
                 ).fetchall()
                 states = {
-                    (row['lifecycle_state'] or 'active'): row['cnt']
+                    (row['lifecycle'] or 'active'): row['cnt']
                     for row in rows
                 }
             except sqlite3.OperationalError:
-                # No lifecycle_state column at all
+                # No lifecycle column at all — count everything as active
                 total = conn.execute(
                     "SELECT COUNT(*) FROM atomic_facts WHERE profile_id = ?",
                     (profile,),
@@ -80,7 +80,7 @@ async def lifecycle_status():
                     "SELECT AVG(julianday('now') - julianday(created_at)) as avg_age, "
                     "MIN(julianday('now') - julianday(created_at)) as min_age, "
                     "MAX(julianday('now') - julianday(created_at)) as max_age "
-                    "FROM atomic_facts WHERE profile_id = ? AND lifecycle_state = ?",
+                    "FROM atomic_facts WHERE profile_id = ? AND lifecycle = ?",
                     (profile, state),
                 ).fetchone()
                 if row and row['avg_age'] is not None:

package/src/superlocalmemory/server/routes/memories.py

@@ -46,53 +46,37 @@ def _fetch_graph_data(
 ) -> tuple[list, list, list]:
     """Fetch graph nodes, links, clusters from V3 or V2 schema."""
     if use_v3:
-        # Graph-first: fetch edges, then get connected nodes, then fill slots
+        # Recency-first: get the most recent nodes, then find their edges
         cursor.execute("""
-            SELECT source_id as source, target_id as target,
-                   weight, edge_type as relationship_type
-            FROM graph_edges WHERE profile_id = ?
-            ORDER BY weight DESC
-        """, (profile,))
-        all_links = cursor.fetchall()
+            SELECT fact_id as id, content, fact_type as category,
+                   confidence as importance, session_id as project_name,
+                   created_at
+            FROM atomic_facts
+            WHERE profile_id = ? AND confidence >= ?
+            ORDER BY created_at DESC
+            LIMIT ?
+        """, (profile, min_importance / 10.0, max_nodes))
+        nodes = cursor.fetchall()
 
-        connected_ids = set()
-        for lk in all_links:
-            connected_ids.add(lk['source'])
-            connected_ids.add(lk['target'])
+        node_ids = {n['id'] for n in nodes}
 
-        # Fetch connected nodes first (these have edges to display)
-        connected_nodes: list = []
-        if connected_ids:
-            ph = ','.join('?' * len(connected_ids))
+        # Fetch edges between these nodes
+        if node_ids:
+            ph = ','.join('?' * len(node_ids))
+            id_list = list(node_ids)
             cursor.execute(f"""
-                SELECT fact_id as id, content, fact_type as category,
-                       confidence as importance, session_id as project_name,
-                       created_at
-                FROM atomic_facts
-                WHERE profile_id = ? AND fact_id IN ({ph})
-            """, [profile] + list(connected_ids))
-            connected_nodes = cursor.fetchall()
-
-        # Fill remaining slots with top-confidence unconnected nodes
-        remaining = max_nodes - len(connected_nodes)
-        if remaining > 0:
-            existing = {n['id'] for n in connected_nodes}
-            cursor.execute("""
-                SELECT fact_id as id, content, fact_type as category,
-                       confidence as importance, session_id as project_name,
-                       created_at
-                FROM atomic_facts
-                WHERE profile_id = ? AND confidence >= ?
-                ORDER BY confidence DESC, created_at DESC
-                LIMIT ?
-            """, (profile, min_importance / 10.0, remaining + len(existing)))
-            for n in cursor.fetchall():
-                if n['id'] not in existing:
-                    connected_nodes.append(n)
-                    if len(connected_nodes) >= max_nodes:
-                        break
-
-        nodes = connected_nodes[:max_nodes]
+                SELECT source_id as source, target_id as target,
+                       weight, edge_type as relationship_type
+                FROM graph_edges
+                WHERE profile_id = ?
+                  AND source_id IN ({ph}) AND target_id IN ({ph})
+                ORDER BY weight DESC
+            """, [profile] + id_list + id_list)
+            all_links = cursor.fetchall()
+        else:
+            all_links = []
+
+        links = all_links
         for n in nodes:
             n['entities'] = []
             n['content_preview'] = _preview(n.get('content'))
@@ -101,7 +85,33 @@ def _fetch_graph_data(
         node_ids = {n['id'] for n in nodes}
         links = [lk for lk in all_links
                  if lk['source'] in node_ids and lk['target'] in node_ids]
-        return nodes, links, []
+
+        # Compute clusters from memory_scenes
+        clusters = []
+        try:
+            cursor.execute("""
+                SELECT scene_id, theme, fact_ids_json
+                FROM memory_scenes WHERE profile_id = ?
+            """, (profile,))
+            for row in cursor.fetchall():
+                fact_ids = []
+                try:
+                    fact_ids = json.loads(row.get('fact_ids_json', '[]') or '[]')
+                except (json.JSONDecodeError, TypeError):
+                    pass
+                # Only include clusters that overlap with displayed nodes
+                overlap = [fid for fid in fact_ids if fid in node_ids]
+                if overlap:
+                    clusters.append({
+                        'cluster_id': row['scene_id'],
+                        'size': len(fact_ids),
+                        'visible_size': len(overlap),
+                        'theme': row.get('theme', ''),
+                    })
+        except Exception:
+            pass
+
+        return nodes, links, clusters
 
     # V2 fallback
     try:
@@ -362,15 +372,54 @@ async def get_clusters(request: Request):
         profile = get_active_profile()
         unclustered = 0
 
-        if _has_table(cursor, 'scene_facts'):
+        # V3 schema: memory_scenes stores fact_ids_json (JSON array)
+        if _has_table(cursor, 'memory_scenes'):
             cursor.execute("""
-                SELECT s.scene_id as cluster_id, COUNT(sf.fact_id) as member_count,
-                       s.summary, s.created_at as first_memory
-                FROM scenes s JOIN scene_facts sf ON s.scene_id = sf.scene_id
-                WHERE s.profile_id = ? GROUP BY s.scene_id ORDER BY member_count DESC
+                SELECT scene_id as cluster_id, theme, fact_ids_json,
+                       entity_ids_json, created_at as first_memory
+                FROM memory_scenes WHERE profile_id = ?
+                ORDER BY created_at DESC
             """, (profile,))
-            clusters = [dict(r, top_entities=[]) for r in cursor.fetchall()]
+            raw_scenes = cursor.fetchall()
+            clusters = []
+            for scene in raw_scenes:
+                fact_ids = []
+                try:
+                    fact_ids = json.loads(scene.get('fact_ids_json', '[]') or '[]')
+                except (json.JSONDecodeError, TypeError):
+                    pass
+                entity_ids = []
+                try:
+                    entity_ids = json.loads(scene.get('entity_ids_json', '[]') or '[]')
+                except (json.JSONDecodeError, TypeError):
+                    pass
+                clusters.append({
+                    'cluster_id': scene['cluster_id'],
+                    'member_count': len(fact_ids),
+                    'categories': scene.get('theme', ''),
+                    'summary': scene.get('theme', ''),
+                    'first_memory': scene.get('first_memory', ''),
+                    'top_entities': entity_ids[:5],
+                })
+            # Filter out empty clusters
+            clusters = [c for c in clusters if c['member_count'] > 0]
+            clusters.sort(key=lambda c: c['member_count'], reverse=True)
+
+            # Count facts not in any scene
+            all_scene_fact_ids = set()
+            for scene in raw_scenes:
+                try:
+                    ids = json.loads(scene.get('fact_ids_json', '[]') or '[]')
+                    all_scene_fact_ids.update(ids)
+                except (json.JSONDecodeError, TypeError):
+                    pass
+            total_facts = cursor.execute(
+                "SELECT COUNT(*) as c FROM atomic_facts WHERE profile_id = ?",
+                (profile,),
+            ).fetchone()['c']
+            unclustered = total_facts - len(all_scene_fact_ids)
         else:
+            # V2 fallback
             try:
                 cursor.execute("""
                     SELECT cluster_id, COUNT(*) as member_count,
@@ -382,8 +431,14 @@ async def get_clusters(request: Request):
                 clusters = [dict(r, top_entities=[]) for r in cursor.fetchall()]
             except Exception:
                 clusters = []
-            cursor.execute("SELECT COUNT(*) as c FROM memories WHERE cluster_id IS NULL AND profile = ?", (profile,))
-            unclustered = cursor.fetchone()['c']
+            try:
+                cursor.execute(
+                    "SELECT COUNT(*) as c FROM memories WHERE cluster_id IS NULL AND profile = ?",
+                    (profile,),
+                )
+                unclustered = cursor.fetchone()['c']
+            except Exception:
+                unclustered = 0
 
         conn.close()
         return {"clusters": clusters, "total_clusters": len(clusters), "unclustered_count": unclustered}
@@ -392,21 +447,41 @@ async def get_clusters(request: Request):
 
 
 @router.get("/api/clusters/{cluster_id}")
-async def get_cluster_detail(request: Request, cluster_id: int, limit: int = Query(50, ge=1, le=200)):
-    """Get detailed view of a specific cluster."""
+async def get_cluster_detail(request: Request, cluster_id: str, limit: int = Query(50, ge=1, le=200)):
+    """Get detailed view of a specific cluster (scene)."""
     try:
         conn = get_db_connection()
         conn.row_factory = dict_factory
         cursor = conn.cursor()
         profile = get_active_profile()
 
-        if _has_table(cursor, 'scene_facts'):
-            cursor.execute("""
-                SELECT f.fact_id as id, f.content, f.fact_type as category,
-                       f.confidence as importance, f.created_at
-                FROM atomic_facts f JOIN scene_facts sf ON f.fact_id = sf.fact_id
-                WHERE sf.scene_id = ? AND f.profile_id = ? ORDER BY f.confidence DESC LIMIT ?
-            """, (str(cluster_id), profile, limit))
+        if _has_table(cursor, 'memory_scenes'):
+            # Get fact IDs from the scene's JSON array
+            cursor.execute(
+                "SELECT fact_ids_json, theme FROM memory_scenes "
+                "WHERE scene_id = ? AND profile_id = ?",
+                (cluster_id, profile),
+            )
+            scene_row = cursor.fetchone()
+            if scene_row:
+                fact_ids = []
+                try:
+                    fact_ids = json.loads(scene_row.get('fact_ids_json', '[]') or '[]')
+                except (json.JSONDecodeError, TypeError):
+                    pass
+                if fact_ids:
+                    ph = ','.join('?' * min(len(fact_ids), limit))
+                    cursor.execute(f"""
+                        SELECT fact_id as id, content, fact_type as category,
+                               confidence as importance, created_at
+                        FROM atomic_facts
+                        WHERE profile_id = ? AND fact_id IN ({ph})
+                        ORDER BY confidence DESC
+                    """, [profile] + fact_ids[:limit])
+                else:
+                    cursor.execute("SELECT 1 WHERE 0")  # empty result
+            else:
+                cursor.execute("SELECT 1 WHERE 0")  # empty result
         else:
             cursor.execute("""
                 SELECT id, content, summary, category, project_name, importance, created_at, tags