superlocalmemory 3.4.25 → 3.4.31

package/CHANGELOG.md

@@ -10,6 +10,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.4.31] - 2026-04-24
+
+Dashboard truth, memory vs fact clarity, and self-cleaning pending queue.
+
+### Changed
+- **Dashboard now shows both memory counts honestly.** Parent memories
+  (what you stored) and atomic facts (what retrieval indexes) appear as
+  two distinct cards with their ratio. No more "Total Memories: 6,000"
+  when you actually have 2,000 memories decomposed into 6,000 facts.
+- **"Browse atomic facts"** relabeled for clarity — this view lists the
+  indexed atomic units.
+- **Visible search box** in the Memories tab — previously hidden behind
+  the Recall Lab only. Search now debounces 280 ms on input.
+
+### Added
+- **`/api/memories/{id}/detail`** — full memory + all child atomic facts
+  in one call. Powers the click-to-expand modal.
+- **`/api/facts/{id}`** — single atomic fact detail with source memory
+  content, entities, and canonical entities.
+- **Pagination UI** — Prev/Next controls show "Showing 1–50 of 6,123".
+  Previously hardcoded to 50 with no navigation.
+- **CSV export** — new `format=csv` option on `/api/export` plus a
+  dedicated "Export All (CSV)" menu item. JSON and JSONL still work.
+- **Export progress toast** — "Preparing JSON export…" notification
+  before the download starts.
+- **`total_facts` + `facts_per_memory`** in `/api/stats` response.
+- **Pending queue auto-cleanup** — the maintenance scheduler now sweeps
+  the pending queue every cycle: completed rows > 7 days, failed rows
+  over retry limit, and stuck rows > 7 days are removed; a 30-day hard
+  cap prevents runaway growth on any status.
+
+### Fixed
+- **Test isolation** — `pending_store` now honors `SLM_DATA_DIR`. Four
+  MCP remember tests were writing to the live `~/.superlocalmemory/`
+  instead of `tmp_path`. Root conftest now forces `SLM_DATA_DIR=tmp_path`
+  for every test unless explicitly opted out.
+- **Fact click popup** — was calling `/api/v3/recall/trace` with a text
+  substring (re-query by first 100 chars) and colliding with the memory
+  row click handler. Now scoped to `.fact-result-item` only, hits the
+  new `/api/facts/{fact_id}` endpoint.
+- **Memory modal ID confusion** — the modal labeled `mem.id` as "ID"
+  regardless of whether it was a memory_id or fact_id. Now displays
+  both "Memory ID" and "Fact ID" when they differ.
+- **Memory modal hydration** — fetches the full memory + fact list
+  asynchronously when opened, so source content and entity data appear
+  even for rows that arrived from the search endpoint.
+
+---
+
+## [3.4.30] - 2026-04-24
+
+Multi-IDE shared worker, silent migration, and security hardening.
+
+### Added
+- **Multi-IDE RAM sharing.** MCP processes share a single recall worker
+  via the daemon. Total RSS stays below 2 GB with four IDEs open.
+- **Feedback and learning signals** flow from every IDE session to the
+  daemon, not just the first.
+- **Setup wizard** validates the data directory at install time and
+  rejects iCloud, Dropbox, OneDrive, Box, Google Drive, and
+  `Library/CloudStorage` paths that silently corrupt SQLite WAL.
+- **One-time upgrade banner** after `pip install -U` / `npm install -g`
+  points users to `slm doctor`.
+- **`docs/errors.md`** — canonical error catalog with codes, recovery
+  steps, exit codes, and HTTP status mappings.
+- **CI matrix** now runs on `ubuntu-22.04`, `macos-14` (Apple Silicon),
+  and `windows-latest` with `portalocker`.
+
+### Changed
+- **Silent, atomic data migration** on upgrade — no manual steps.
+- **Migration serialized via file lock** so parallel pip + npm installs
+  cannot race.
+- **Concurrent-safe MCP engine singleton** with double-checked locking.
+- Pool adapter returns frozen dataclasses instead of `SimpleNamespace`.
+
+### Security
+- File permissions tightened: marker files written at 0600, parent
+  directories at 0700.
+- Symlink-following blocked on version marker reads.
+- Cloud-synced directory detection extended to `Library/CloudStorage`
+  (macOS 13+).
+
+### Fixed
+- Silent error swallows in daemon shutdown, migration probe, and banner
+  emission now log at WARNING.
+- Fenced-out `complete()` writes (stale worker claims) emit a WARNING
+  log instead of vanishing silently.
+- Daemon-start migration guarded behind `is_ready` sentinel — skips
+  when already applied.
+
+---
+
 ## [3.4.23] - 2026-04-21
 
 Critical hotfix on top of 3.4.22 for two end-user-facing regressions.

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">SuperLocalMemory V3.4</h1>
 <p align="center"><strong>Every other AI forgets. Yours won't.</strong><br/><em>Infinite memory for Claude Code, Cursor, Windsurf, and any MCP-compatible AI client.</em></p>
-<p align="center"><code>v3.4.21</code> — Install once. Every session remembers the last. Automatically.</p>
+<p align="center"><code>v3.4.25</code> — Install once. Every session remembers the last. Automatically.</p>
 <p align="center"><strong>Backed by 3 published research papers</strong> (arXiv preprints + Zenodo-archived) · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
 
 <p align="center">
@@ -20,6 +20,7 @@
   <a href="https://superlocalmemory.com"><img src="https://img.shields.io/badge/Web-superlocalmemory.com-ff6b35?style=for-the-badge" alt="Website"/></a>
   <a href="#dual-interface-mcp--cli"><img src="https://img.shields.io/badge/MCP-Native-blue?style=for-the-badge" alt="MCP Native"/></a>
   <a href="#dual-interface-mcp--cli"><img src="https://img.shields.io/badge/CLI-Agent--Native-green?style=for-the-badge" alt="CLI Agent-Native"/></a>
+  <a href="#multilingual-embedding-support"><img src="https://img.shields.io/badge/Multilingual-30%2B_Languages-ff69b4?style=for-the-badge" alt="Multilingual 30+ Languages"/></a>
 </p>
 
 <p align="center">
@@ -342,6 +343,12 @@ Built-in compliance tools: GDPR Article 15/17 export + complete erasure, tamper-
 
 ---
 
+## Multilingual Embedding Support
+
+**v3.4.24+:** Plug in any OpenAI-compatible embedding endpoint — Ollama, vLLM, LiteLLM, or self-hosted models like `bge-m3`, `multilingual-e5`, `Qwen3-Embedding`. Configure from the dashboard (Settings > Step 3) or `config.json`. SLM's math layer (Fisher-Rao, Sheaf, Langevin) is language-agnostic — swap the embedding model and all 30+ languages work at full retrieval quality. No cloud dependency. No code changes. Your data, your language, your model.
+
+---
+
 ## Web Dashboard
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.25",
+  "version": "3.4.31",
   "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.4.25"
+version = "3.4.31"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}
@@ -52,6 +52,8 @@ dependencies = [
     # V3.4.3: Unified Brain
     "psutil>=5.9.0",
     "structlog>=24.0.0,<27.0.0",
+    # Cross-platform file locking for single-daemon enforcement.
+    "portalocker>=2.7.0,<4.0.0",
     # V3.4.18: Semantic search + cross-encoder reranker (npm install parity).
     # Previously under [search] extra — pip users silently lost 30pp of recall
     # quality vs. npm users. Now ships by default for both install paths.

package/src/superlocalmemory/__init__.py

@@ -1,3 +1,3 @@
 """SuperLocalMemory — information-geometric agent memory."""
 
-__version__ = "3.4.25"
+__version__ = "3.4.31"

package/src/superlocalmemory/cli/daemon.py

@@ -199,7 +199,10 @@ def ensure_daemon() -> bool:
         return _wait_for_daemon(timeout=60)
 
     except Exception as exc:
-        logger.debug("ensure_daemon error: %s", exc)
+        # Daemon auto-start is the entry point for dashboard / mesh /
+        # health features; failure here silently disables all of them.
+        # Log at WARNING so operators can see it in production logs.
+        logger.warning("ensure_daemon error: %s (run `slm doctor`)", exc)
         return False
     finally:
         if lock_fd:
@@ -386,8 +389,10 @@ def _flush_observe_buffer() -> None:
             decision = auto.evaluate(content)
             if decision.capture:
                 auto.capture(content, category=decision.category)
-        except Exception:
-            pass  # Don't let one bad observation kill the batch
+        except Exception as exc:
+            # Swallow per-observation to protect the batch, but log so
+            # a pattern of dropped observations is visible.
+            logger.warning("observation dropped during batch: %s", exc)
 
     logger.info("Observe debounce: processed %d observations (from buffer)", len(batch))
 
@@ -489,16 +494,55 @@ class DaemonHandler(BaseHTTPRequestHandler):
                 response = engine.recall(
                     query, limit=limit, session_id=session_id,
                 )
-                results = [
-                    {"content": r.fact.content, "score": round(r.score, 4),
-                     "fact_type": getattr(r.fact.fact_type, 'value', str(r.fact.fact_type)),
-                     "fact_id": r.fact.fact_id}
-                    for r in response.results
-                ]
+                # Return the same field shape as recall_worker._handle_recall,
+                # so MCP processes that proxy through the daemon get recall_trace-
+                # compatible data without a second round trip.
+                memory_ids = list({
+                    r.fact.memory_id for r in response.results[:limit]
+                    if r.fact.memory_id
+                })
+                memory_map = (
+                    engine._db.get_memory_content_batch(memory_ids)
+                    if memory_ids else {}
+                )
+                results = []
+                for r in response.results[:limit]:
+                    fact_type = getattr(r.fact, "fact_type", None)
+                    lifecycle = getattr(r.fact, "lifecycle", None)
+                    results.append({
+                        "fact_id": r.fact.fact_id,
+                        "memory_id": r.fact.memory_id,
+                        "content": r.fact.content[:300],
+                        "source_content": memory_map.get(r.fact.memory_id, ""),
+                        "score": round(r.score, 4),
+                        "confidence": round(r.confidence, 4),
+                        "trust_score": round(r.trust_score, 4),
+                        "channel_scores": {
+                            k: round(v, 4)
+                            for k, v in (r.channel_scores or {}).items()
+                        },
+                        "fact_type": fact_type.value
+                            if fact_type and hasattr(fact_type, "value") else "",
+                        "lifecycle": lifecycle.value
+                            if lifecycle and hasattr(lifecycle, "value") else "",
+                        "access_count": getattr(r.fact, "access_count", 0),
+                        "evidence_chain": list(
+                            getattr(r, "evidence_chain", []) or []
+                        ),
+                    })
                 self._send_json(200, {
-                    "results": results, "count": len(results),
+                    "ok": True,
+                    "query": query,
                     "query_type": response.query_type,
+                    "result_count": len(results),
                     "retrieval_time_ms": round(response.retrieval_time_ms, 1),
+                    "channel_weights": {
+                        k: round(v, 3)
+                        for k, v in (response.channel_weights or {}).items()
+                    },
+                    "total_candidates": getattr(response, "total_candidates", 0),
+                    "results": results,
+                    "count": len(results),  # backward compat alias
                 })
             except Exception as exc:
                 self._send_json(500, {"error": str(exc)})
@@ -541,14 +585,21 @@ class DaemonHandler(BaseHTTPRequestHandler):
                 body = self._read_body()
                 content = body.get("content", "")
                 tags = body.get("tags", "")
+                extra_meta = body.get("metadata") or {}
                 if not content:
                     self._send_json(400, {"error": "content required"})
                     return
 
                 engine = _get_engine()
                 metadata = {"tags": tags} if tags else {}
+                if isinstance(extra_meta, dict):
+                    metadata.update(extra_meta)
                 fact_ids = engine.store(content, metadata=metadata)
-                self._send_json(200, {"fact_ids": fact_ids, "count": len(fact_ids)})
+                self._send_json(200, {
+                    "ok": True,
+                    "fact_ids": fact_ids,
+                    "count": len(fact_ids),
+                })
             except Exception as exc:
                 self._send_json(500, {"error": str(exc)})
             return
@@ -589,17 +640,16 @@ _server_start_time = time.monotonic()
 
 def _shutdown_server() -> None:
     global _engine, _server
-    # V3.3.28: Flush any buffered observations before shutdown
     try:
         _flush_observe_buffer()
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("flush observe buffer on shutdown failed: %s", exc)
     time.sleep(0.5)
     if _engine is not None:
         try:
             _engine.close()
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("engine close on shutdown failed: %s", exc)
         _engine = None
     if _server is not None:
         _server.shutdown()
@@ -627,6 +677,30 @@ def start_server(port: int = _DEFAULT_PORT, idle_timeout: int | None = None) ->
         "SLM_DAEMON_IDLE_TIMEOUT", str(_DEFAULT_IDLE_TIMEOUT),
     ))
 
+    # Banner is advisory — a broken data dir must never prevent the daemon
+    # from starting, so the swallow here is intentional.
+    try:
+        from superlocalmemory import __version__ as _slm_ver
+        from superlocalmemory.cli.version_banner import check_and_emit_upgrade_banner
+        check_and_emit_upgrade_banner(_slm_ver)
+    except Exception as exc:
+        logger.warning("upgrade banner on daemon start failed: %s", exc)
+
+    # Apply the v3.4.26 data-dir migration now — the daemon is the
+    # authoritative holder of the DB, so this is the right place to do
+    # it unconditionally (``migrate`` is idempotent).
+    try:
+        from pathlib import Path as _P
+        from superlocalmemory.migrations.v3_4_25_to_v3_4_26 import (
+            is_ready as _is_ready, migrate as _migrate,
+        )
+        _data = _P(os.environ.get("SLM_DATA_DIR")
+                   or _P.home() / ".superlocalmemory")
+        if not _is_ready(_data):
+            _migrate(_data)
+    except Exception as exc:
+        logger.warning("v3.4.26 migration on daemon start failed: %s", exc)
+
     # Write PID + port files
     _PID_FILE.parent.mkdir(parents=True, exist_ok=True)
     _PID_FILE.write_text(str(os.getpid()))

package/src/superlocalmemory/cli/doctor_cmd.py

@@ -0,0 +1,152 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""slm doctor — preflight and health checks.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+import sys
+from pathlib import Path
+from typing import Any
+
+_DEFAULT_DATA_DIR = Path.home() / ".superlocalmemory"
+
+
+def _check_python() -> dict[str, Any]:
+    v = sys.version_info
+    ok = (v.major, v.minor) >= (3, 10)
+    return {
+        "name": "python",
+        "status": "ok" if ok else "error",
+        "detail": f"Python {v.major}.{v.minor}.{v.micro}",
+        "hint": None if ok else "SLM requires Python >= 3.10",
+    }
+
+
+def _check_platform() -> dict[str, Any]:
+    return {
+        "name": "platform",
+        "status": "ok",
+        "detail": f"{platform.system()} {platform.release()} {platform.machine()}",
+        "hint": None,
+    }
+
+
+def _check_portalocker() -> dict[str, Any]:
+    try:
+        import portalocker  # noqa: F401
+        return {
+            "name": "portalocker",
+            "status": "ok",
+            "detail": "installed",
+            "hint": None,
+        }
+    except ImportError:
+        return {
+            "name": "portalocker",
+            "status": "error",
+            "detail": "not installed",
+            "hint": "pip install --upgrade superlocalmemory",
+        }
+
+
+def _check_data_dir(data_dir: Path) -> dict[str, Any]:
+    from superlocalmemory.core import safe_fs
+    try:
+        safe_fs.validate_data_dir(data_dir)
+        return {
+            "name": "data directory",
+            "status": "ok",
+            "detail": str(data_dir),
+            "hint": None,
+        }
+    except safe_fs.SafeFsError as exc:
+        return {
+            "name": "data directory",
+            "status": "error",
+            "detail": str(data_dir),
+            "hint": str(exc),
+        }
+
+
+def _check_migration(data_dir: Path) -> dict[str, Any]:
+    from superlocalmemory.migrations.v3_4_25_to_v3_4_26 import is_ready
+    ok = is_ready(data_dir)
+    return {
+        "name": "v3.4.26 migration",
+        "status": "ok" if ok else "warn",
+        "detail": "ready" if ok else "not migrated yet",
+        "hint": None if ok else
+        "Run once: python -m superlocalmemory.migrations.v3_4_25_to_v3_4_26",
+    }
+
+
+def _check_queue_db(data_dir: Path) -> dict[str, Any]:
+    queue = data_dir / "recall_queue.db"
+    if queue.exists():
+        return {
+            "name": "queue database",
+            "status": "ok",
+            "detail": f"{queue} ({queue.stat().st_size} bytes)",
+            "hint": None,
+        }
+    return {
+        "name": "queue database",
+        "status": "warn",
+        "detail": "not yet created",
+        "hint": "The daemon will create this on first use.",
+    }
+
+
+def run_checks(*, data_dir: Path | None = None) -> dict[str, Any]:
+    dd = Path(data_dir) if data_dir is not None else _DEFAULT_DATA_DIR
+    checks = [
+        _check_python(),
+        _check_platform(),
+        _check_portalocker(),
+        _check_data_dir(dd),
+        _check_migration(dd),
+        _check_queue_db(dd),
+    ]
+    has_error = any(c["status"] == "error" for c in checks)
+    exit_code = 1 if has_error else 0
+    return {
+        "data_dir": str(dd),
+        "checks": checks,
+        "exit_code": exit_code,
+    }
+
+
+def _print_report(report: dict[str, Any]) -> None:
+    glyphs = {"ok": "\u2713", "warn": "\u26a0", "error": "\u2717"}
+    print(f"SLM doctor — data dir: {report['data_dir']}\n")
+    for c in report["checks"]:
+        g = glyphs.get(c["status"], "?")
+        print(f" {g} {c['name']:<20} {c['detail']}")
+        if c.get("hint"):
+            print(f"      {c['hint']}")
+    print(f"\nExit code: {report['exit_code']}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    parser = argparse.ArgumentParser(prog="slm-doctor")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    parser.add_argument("--data-dir", type=Path, default=None)
+    args = parser.parse_args(argv)
+    report = run_checks(data_dir=args.data_dir)
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        _print_report(report)
+    return int(report["exit_code"])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/superlocalmemory/cli/main.py

@@ -79,6 +79,34 @@ def main() -> None:
     from superlocalmemory.cli.json_output import _get_version
     _ver = _get_version()
 
+    # One-time post-upgrade banner — silent for fresh installs and
+    # same-version runs. Guarded against I/O errors internally.
+    from superlocalmemory.cli.version_banner import check_and_emit_upgrade_banner
+    if check_and_emit_upgrade_banner(_ver):
+        # First post-upgrade invocation: apply the data-dir migration if
+        # it's safe. When the previous-version daemon is still running
+        # we defer — the next daemon start picks it up.
+        try:
+            import logging as _logging
+            from pathlib import Path as _P
+            from superlocalmemory.migrations.v3_4_25_to_v3_4_26 import (
+                migrate_if_safe as _migrate_if_safe,
+            )
+            _data = _P(_os.environ.get("SLM_DATA_DIR")
+                       or _P.home() / ".superlocalmemory")
+            _res = _migrate_if_safe(_data)
+            if _res.get("status") == "deferred":
+                print(
+                    "  note: data migration deferred — the running SLM "
+                    "daemon will apply it on its next restart."
+                )
+        except Exception as _mig_exc:
+            import logging as _logging
+            _logging.getLogger(__name__).warning(
+                "v3.4.26 migrate_if_safe failed: %s — run `slm doctor`", _mig_exc,
+            )
+            print("  note: data migration check failed — run `slm doctor` to diagnose.")
+
     parser = argparse.ArgumentParser(
         prog="slm",
         description=f"SuperLocalMemory V3 ({_ver}) — AI agent memory with mathematical foundations",

package/src/superlocalmemory/cli/pending_store.py

@@ -24,12 +24,21 @@ License: Elastic-2.0
 from __future__ import annotations
 
 import json
+import os
 import sqlite3
 import time
 from pathlib import Path
 
-_DEFAULT_DIR = Path.home() / ".superlocalmemory"
+
+def _default_dir() -> Path:
+    """Honor SLM_DATA_DIR so tests can isolate via tmp_path."""
+    return Path(os.environ.get("SLM_DATA_DIR") or Path.home() / ".superlocalmemory")
+
+
 _PENDING_DB = "pending.db"
+_MAX_RETRIES = 3
+_STUCK_DAYS = 7
+_DEAD_LETTER_DAYS = 30
 
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS pending_memories (
@@ -47,7 +56,7 @@ CREATE TABLE IF NOT EXISTS pending_memories (
 
 def _get_db(base_dir: Path | None = None) -> sqlite3.Connection:
     """Open pending.db with WAL mode. Creates if needed."""
-    d = base_dir or _DEFAULT_DIR
+    d = base_dir or _default_dir()
     d.mkdir(parents=True, exist_ok=True)
     db_path = d / _PENDING_DB
     conn = sqlite3.connect(str(db_path), timeout=5)
@@ -128,7 +137,7 @@ def mark_failed(row_id: int, error: str, base_dir: Path | None = None) -> None:
 
 def pending_count(base_dir: Path | None = None) -> int:
     """Count unprocessed pending memories."""
-    d = base_dir or _DEFAULT_DIR
+    d = base_dir or _default_dir()
     db_path = d / _PENDING_DB
     if not db_path.exists():
         return 0
@@ -156,3 +165,46 @@ def cleanup_done(days: int = 7, base_dir: Path | None = None) -> int:
         return cur.rowcount
     finally:
         conn.close()
+
+
+def cleanup_stale(base_dir: Path | None = None) -> dict[str, int]:
+    """Sweep stale rows from pending.db. Runs periodically from the daemon.
+
+    Removes:
+    - `done` rows older than 7 days (already processed)
+    - `failed` rows that exceeded max retries (moved to dead-letter via deletion)
+    - `pending` rows stuck more than 7 days (test pollution, crashed workers)
+    - Everything older than 30 days regardless of status (hard cap)
+    """
+    conn = _get_db(base_dir)
+    try:
+        done = conn.execute(
+            "DELETE FROM pending_memories WHERE status = 'done' "
+            "AND created_at < datetime('now', ?)",
+            (f"-{_STUCK_DAYS} days",),
+        ).rowcount
+        failed = conn.execute(
+            "DELETE FROM pending_memories WHERE status = 'failed' "
+            "AND retry_count >= ?",
+            (_MAX_RETRIES,),
+        ).rowcount
+        stuck = conn.execute(
+            "DELETE FROM pending_memories WHERE status = 'pending' "
+            "AND created_at < datetime('now', ?)",
+            (f"-{_STUCK_DAYS} days",),
+        ).rowcount
+        hard_cap = conn.execute(
+            "DELETE FROM pending_memories "
+            "WHERE created_at < datetime('now', ?)",
+            (f"-{_DEAD_LETTER_DAYS} days",),
+        ).rowcount
+        conn.commit()
+        return {
+            "done": done,
+            "failed_over_retries": failed,
+            "stuck_pending": stuck,
+            "hard_cap_expired": hard_cap,
+            "total": done + failed + stuck + hard_cap,
+        }
+    finally:
+        conn.close()

package/src/superlocalmemory/cli/post_install.py

@@ -21,6 +21,21 @@ def run_post_install():
     print("=" * 30)
     print()
 
+    # Upgrade banner — fires when a prior-version user runs
+    # ``npm install -g superlocalmemory@latest``. Silent on fresh
+    # installs (setup wizard handles welcome).
+    try:
+        from superlocalmemory import __version__ as _slm_ver
+        from superlocalmemory.cli.version_banner import (
+            check_and_emit_upgrade_banner,
+        )
+        if check_and_emit_upgrade_banner(_slm_ver):
+            # Upgrade detected — the banner already covered it;
+            # skip the V2 path + fresh-install copy and return.
+            return
+    except Exception:
+        pass
+
     # Step 1: Check for V2 installation
     from superlocalmemory.storage.v2_migrator import V2Migrator
 

package/src/superlocalmemory/cli/setup_wizard.py

@@ -556,6 +556,26 @@ def run_wizard(auto: bool = False) -> None:
         print("  ⚠ Skipped (sentence-transformers not installed)")
         verified = False
 
+    # v3.4.26 options — data-dir safety + queue toggle. One prompt max.
+    try:
+        from superlocalmemory.cli.wizard_v3426_options import (
+            persist_v3426_options,
+            prompt_v3426_options,
+            validate_install_data_dir,
+        )
+        ok, reason = validate_install_data_dir(_SLM_HOME)
+        if not ok:
+            print()
+            print("  ⚠ Data directory check failed:")
+            for line in reason.splitlines():
+                print(f"    {line}")
+            print()
+        v3426_opts = prompt_v3426_options(interactive=interactive)
+        persist_v3426_options(v3426_opts, _SLM_HOME)
+    except Exception as exc:
+        # Wizard must never crash over an advisory feature.
+        print(f"  (v3.4.26 options step skipped: {exc})")
+
     # -- Done --
     _mark_complete()