superlocalmemory 4.0.9 → 4.1.0

package/src/superlocalmemory/core/memory_health.py

@@ -0,0 +1,266 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+
+"""Tell the owner, in their own words, whether their memory works.
+
+Until now the only way to learn that 43.7% of a store could not be found by
+asking a question was to write the SQL yourself. One machine sat in exactly
+that state for months while every status line it showed said the system was
+healthy, because nothing measured reachability and nothing reported it.
+
+So this module answers four questions a non-engineer can act on:
+
+  * How many memories do I have?
+  * How many can actually be found by asking a question?
+  * How many were withheld because a model wrote them, not me?
+  * Is anything still being repaired?
+
+Read-only, and every query is bounded. Fail-soft by construction: a missing
+table or column yields ``None`` for that line rather than an exception, because
+a health report that crashes on an old store is worse than one that says "not
+known yet".
+
+Consumed by ``slm doctor``, ``GET /api/v3/memory-health``, and the dashboard.
+One implementation so the three cannot disagree with each other.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["MemoryHealth", "measure", "describe"]
+
+
+@dataclass(frozen=True)
+class MemoryHealth:
+    """A store's answer-ability, counted rather than assumed."""
+
+    #: Memories that recall is allowed to return.
+    live_facts: int = 0
+    #: Of those, how many have a vector projection, i.e. can be found by
+    #: meaning rather than only by matching words.
+    findable_by_meaning: int = 0
+    #: Memories with no vector at all. These are reachable by keyword only.
+    missing_vector: int = 0
+    #: Machine-written summaries withheld from recall and kept for display.
+    withheld_summaries: int = 0
+    #: Summaries preserved in the display table.
+    display_summaries: int = 0
+    #: Memories hidden by the retention system, excluding the withheld ones.
+    hidden_by_forgetting: int = 0
+    #: Rows whose retention zone contradicts their retention score, i.e. hidden
+    #: while the maths says to keep them. Should be zero after repair.
+    inconsistently_hidden: int = 0
+    #: Present only when a table or column was absent.
+    unavailable: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def reachability(self) -> float:
+        """Share of live memories findable by meaning, 0.0-1.0."""
+        if self.live_facts <= 0:
+            return 1.0
+        return self.findable_by_meaning / self.live_facts
+
+    @property
+    def healthy(self) -> bool:
+        """Whether anything here warrants telling the owner about."""
+        return (
+            self.reachability >= 0.99
+            and self.missing_vector == 0
+            and self.inconsistently_hidden == 0
+        )
+
+
+def measure(db_path: str | Path) -> MemoryHealth:
+    """Count the store's answer-ability. Read-only; never raises."""
+    unavailable: list[str] = []
+    try:
+        conn = sqlite3.connect(f"file:{Path(db_path)}?mode=ro", uri=True)
+    except sqlite3.Error as exc:
+        logger.debug("memory health: cannot open %s: %s", db_path, exc)
+        return MemoryHealth(unavailable=("database",))
+
+    try:
+        if not _table_exists(conn, "atomic_facts"):
+            return MemoryHealth(unavailable=("atomic_facts",))
+
+        # Quarantine came in 4.0.10. On an older store every fact is "live",
+        # which is the honest reading of a store that has no withheld rows.
+        has_q = _has_column(conn, "atomic_facts", "quarantined")
+        if not has_q:
+            unavailable.append("quarantined")
+        live_clause = "COALESCE(quarantined, 0) = 0" if has_q else "1=1"
+
+        live = _count(conn, f"SELECT COUNT(*) FROM atomic_facts WHERE {live_clause}")
+        withheld = (
+            _count(conn, "SELECT COUNT(*) FROM atomic_facts WHERE quarantined = 1")
+            if has_q else 0
+        )
+        missing_vec = _count(
+            conn,
+            f"SELECT COUNT(*) FROM atomic_facts "
+            f"WHERE embedding IS NULL AND {live_clause}",
+        )
+
+        if _table_exists(conn, "embedding_metadata"):
+            findable = _count(
+                conn,
+                "SELECT COUNT(*) FROM embedding_metadata em "
+                "JOIN atomic_facts af ON af.fact_id = em.fact_id "
+                f"WHERE {_prefixed(live_clause, 'af')}",
+            )
+        else:
+            unavailable.append("embedding_metadata")
+            findable = 0
+
+        display = (
+            _count(conn, "SELECT COUNT(*) FROM consolidated_summaries")
+            if _table_exists(conn, "consolidated_summaries") else 0
+        )
+        if not _table_exists(conn, "consolidated_summaries"):
+            unavailable.append("consolidated_summaries")
+
+        hidden = inconsistent = 0
+        if _table_exists(conn, "fact_retention"):
+            hidden = _count(
+                conn,
+                "SELECT COUNT(*) FROM fact_retention r "
+                "JOIN atomic_facts af ON af.fact_id = r.fact_id "
+                "WHERE r.lifecycle_zone IN ('archive', 'forgotten') "
+                f"  AND {_prefixed(live_clause, 'af')}",
+            )
+            # The contradiction M043 repairs: hidden, yet scored to keep.
+            inconsistent = _count(
+                conn,
+                "SELECT COUNT(*) FROM fact_retention r "
+                "JOIN atomic_facts af ON af.fact_id = r.fact_id "
+                "WHERE r.lifecycle_zone IN ('archive', 'forgotten') "
+                "  AND r.retention_score > 0.8 "
+                f"  AND {_prefixed(live_clause, 'af')}",
+            )
+        else:
+            unavailable.append("fact_retention")
+
+        return MemoryHealth(
+            live_facts=live,
+            findable_by_meaning=findable,
+            missing_vector=missing_vec,
+            withheld_summaries=withheld,
+            display_summaries=display,
+            hidden_by_forgetting=hidden,
+            inconsistently_hidden=inconsistent,
+            unavailable=tuple(unavailable),
+        )
+    except sqlite3.Error as exc:
+        logger.debug("memory health measurement failed: %s", exc)
+        return MemoryHealth(unavailable=(*unavailable, "query_failed"))
+    finally:
+        conn.close()
+
+
+def describe(health: MemoryHealth) -> list[str]:
+    """Plain-language lines for a reader who does not write SQL.
+
+    No percentages without the counts behind them, and no jargon: "findable by
+    asking a question" rather than "vector coverage", because the person who
+    needs this line is the one who would not know what a vector is.
+    """
+    lines: list[str] = []
+    if "atomic_facts" in health.unavailable or "database" in health.unavailable:
+        return ["Memory store not readable yet."]
+
+    lines.append(f"You have {health.live_facts:,} memories.")
+
+    if "embedding_metadata" in health.unavailable:
+        lines.append(
+            "Whether they can be found by asking a question is not known yet — "
+            "the search index has not been built."
+        )
+    elif health.live_facts:
+        pct = 100.0 * health.reachability
+        if health.findable_by_meaning >= health.live_facts:
+            # "All" only when the counts actually agree. The threshold used to
+            # be reachability >= 0.99, which printed "All of them can be found
+            # by asking a question (5,199 indexed)" on a store of 5,205 — a
+            # claim of all, contradicted by the number beside it. This module
+            # exists to be believed; it cannot round in its own favour.
+            lines.append(
+                f"All {health.live_facts:,} of them can be found by asking a "
+                f"question."
+            )
+        elif health.reachability >= 0.99:
+            gap = health.live_facts - health.findable_by_meaning
+            lines.append(
+                f"{health.findable_by_meaning:,} of them can be found by asking "
+                f"a question. The other {gap:,} can only be found by matching "
+                f"words. That is a small enough share to be normal — a memory "
+                f"written moments ago, or one the model could not read."
+            )
+        else:
+            gap = health.live_facts - health.findable_by_meaning
+            lines.append(
+                f"{health.findable_by_meaning:,} of them ({pct:.0f}%) can be "
+                f"found by asking a question. The other {gap:,} can only be "
+                f"found by matching words, so a question phrased differently "
+                f"will miss them. This repairs itself as the service runs; if "
+                f"it does not, the embedding model is unavailable."
+            )
+
+    if health.withheld_summaries:
+        lines.append(
+            f"{health.withheld_summaries:,} machine-written summaries are kept "
+            f"out of your answers and shown on the dashboard instead. They were "
+            f"written by the summarizer, not by you, and they used to be "
+            f"returned as if they were your own notes."
+        )
+
+    if health.inconsistently_hidden:
+        lines.append(
+            f"{health.inconsistently_hidden:,} memories are hidden even though "
+            f"they are marked worth keeping. This is a fault and it is repaired "
+            f"automatically the next time the service starts."
+        )
+
+    if health.hidden_by_forgetting:
+        lines.append(
+            f"{health.hidden_by_forgetting:,} older memories are set aside by "
+            f"the forgetting curve. They are not deleted and a deep search "
+            f"still reaches them."
+        )
+
+    return lines
+
+
+def _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    return conn.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,),
+    ).fetchone() is not None
+
+
+def _has_column(conn: sqlite3.Connection, table: str, column: str) -> bool:
+    return any(
+        row[1] == column for row in conn.execute(f"PRAGMA table_info({table})")
+    )
+
+
+def _prefixed(clause: str, prefix: str) -> str:
+    """Qualify a bare column reference for use in a joined query.
+
+    Word-bounded, so a future column named ``quarantined_at`` is not silently
+    rewritten to ``af.quarantined_at`` by a substring match. No such column
+    exists today; the point is that the failure would be a wrong count rather
+    than an error, and a wrong count in a health report is the one thing this
+    module must not produce.
+    """
+    return re.sub(r"\bquarantined\b", f"{prefix}.quarantined", clause)
+
+
+def _count(conn: sqlite3.Connection, sql: str) -> int:
+    row = conn.execute(sql).fetchone()
+    return int(row[0]) if row else 0

package/src/superlocalmemory/core/mode_capability.py

@@ -0,0 +1,111 @@
+# 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
+
+"""What the running mode can do with a model, in words a user can act on.
+
+WHY THIS EXISTS
+
+Mode A runs with no language model at all. That is the point of it: nothing on
+the store or recall path calls out to anything, and a summary is assembled
+directly from the user's own notes rather than written.
+
+The surfaces already reported *what* they did -- a summary came back labelled
+"assembled directly from your own notes" -- but never *why*, and never what to do
+about it. Someone looking at a plainer summary than they expected had no way to
+learn that a written one needs a model and which modes have one. They would
+reasonably conclude the feature was broken.
+
+So this returns the mode, whether a model is available, and one sentence naming
+the next step. Every model-backed surface returns the same block, so the
+explanation is identical wherever it appears rather than reworded per pane.
+
+WHAT IT IS NOT
+
+It is not a capability gate. Nothing here decides whether a call is made; the
+mode's configuration does that. This only describes the decision to the person
+looking at the result.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+#: Named so the message can say which modes to consider without hard-coding the
+#: sentence at each call site.
+_MODE_WITH_LOCAL_MODEL = "B"
+_MODE_WITH_CLOUD_MODEL = "C"
+
+_NO_MODEL_MESSAGE = (
+    "This mode runs entirely on your machine with no language model, so "
+    "summaries are assembled from your own notes rather than written. For "
+    f"written summaries and the other model-backed features, switch to Mode "
+    f"{_MODE_WITH_LOCAL_MODEL} (a local model) or Mode {_MODE_WITH_CLOUD_MODEL} "
+    "(your own cloud model) in Settings and connect one."
+)
+
+_MODEL_CONFIGURED_BUT_ABSENT = (
+    "This mode uses a language model, but none is reachable right now, so "
+    "results fall back to being assembled from your own notes. Check the model "
+    "settings, and that the local model server is running if you are using one."
+)
+
+_CLOUD_MODEL_HAS_NO_KEY = (
+    "This mode uses a hosted language model and no key has been set for it, so "
+    "summaries are assembled from your own notes rather than written. Run "
+    "`slm provider set` and supply your key, or switch to Mode "
+    f"{_MODE_WITH_LOCAL_MODEL} to use a model on this machine."
+)
+
+#: Providers that run on the machine and need no credential. Anything else is
+#: a hosted service, and naming one without a key is not a configured model --
+#: which is what this used to report, so the surfaces said everything was fine
+#: while every model-backed feature was about to fall back.
+_LOCAL_PROVIDERS = frozenset({
+    "ollama", "lmstudio", "llamacpp", "llama.cpp", "local", "vllm", "none", "",
+})
+
+
+def llm_capability(config: Any, *, llm_reachable: bool | None = None) -> dict:
+    """Describe this mode's model support for a user-facing surface.
+
+    ``llm_reachable`` lets a caller that already knows the answer pass it in --
+    a summary route has just tried and knows whether it worked, and asking again
+    would mean a second connection attempt to say something it already knows.
+    Left as None, availability is taken from configuration alone.
+    """
+    mode = ""
+    provider = ""
+    api_key = ""
+    try:
+        mode = str(getattr(getattr(config, "mode", None), "value", "") or "").upper()
+        llm = getattr(config, "llm", None)
+        provider = str(getattr(llm, "provider", "") or "")
+        api_key = str(getattr(llm, "api_key", "") or "").strip()
+    except Exception as exc:  # noqa: BLE001 -- a description must not raise
+        logger.debug("mode capability: cannot read config: %s", exc)
+
+    mode_has_model = mode in (_MODE_WITH_LOCAL_MODEL, _MODE_WITH_CLOUD_MODEL)
+    needs_a_key = provider.lower() not in _LOCAL_PROVIDERS
+    missing_key = mode_has_model and bool(provider) and needs_a_key and not api_key
+    configured = bool(provider) and mode_has_model and not missing_key
+    available = configured if llm_reachable is None else bool(llm_reachable)
+
+    if not mode_has_model:
+        message = _NO_MODEL_MESSAGE
+    elif missing_key and llm_reachable is not True:
+        message = _CLOUD_MODEL_HAS_NO_KEY
+    elif not available:
+        message = _MODEL_CONFIGURED_BUT_ABSENT
+    else:
+        message = ""
+
+    return {
+        "mode": mode or "?",
+        "llm_available": bool(available),
+        "llm_provider": provider,
+        "message": message,
+    }

package/src/superlocalmemory/core/ollama_validator.py

@@ -0,0 +1,315 @@
+# 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
+
+"""Ask the local model server whether a model exists, before trusting it.
+
+Mode B runs on Ollama, and a user picking a model there picks it by typing a
+name. Two things then go wrong silently.
+
+**The name is wrong.** Nothing happens at the moment of the mistake; the config
+saves, the daemon starts, and every write quietly falls back to a worse path.
+The error a user eventually sees is unrelated to what they did.
+
+**The name is right and the shape is different.** Every embedding model emits a
+vector of a fixed width. `nomic-embed-text` emits 768 numbers,
+`mxbai-embed-large` emits 1024. Vectors of different widths cannot be compared,
+so a store holding both answers similarity questions with noise — and it does so
+without failing, because nothing in a similarity search knows the difference
+between a bad answer and a good one. **This is the single silent-and-catastrophic
+change a user can make**, so it is refused rather than warned about, and the
+refusal says the one command that would make it safe.
+
+There are two Ollama roles and they are separate models with separate names:
+the embedding model (`embedding.ollama_model`) turns text into vectors, and the
+generation model (`llm.model` when the provider is Ollama) writes summaries.
+They are validated independently because a machine can perfectly well have one
+and not the other.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = [
+    "EMBEDDING",
+    "GENERATION",
+    "OllamaProbe",
+    "DimensionChange",
+    "validate_ollama_model",
+    "stored_embedding_dimension",
+    "check_embedding_model_change",
+    "same_embedding_model",
+]
+
+logger = logging.getLogger(__name__)
+
+EMBEDDING = "embedding"
+GENERATION = "generation"
+
+DEFAULT_BASE_URL = "http://localhost:11434"
+
+#: Long enough for a cold model load, short enough that a wedged server is not
+#: mistaken for a slow one.
+_CONNECT_TIMEOUT = 3.0
+_RESPONSE_TIMEOUT = 60.0
+
+_PROBE_TEXT = "superlocalmemory model probe"
+_PROBE_PROMPT = "Reply with the single word: ok"
+
+
+@dataclass(frozen=True)
+class OllamaProbe:
+    """What the server said when asked about one model."""
+
+    ok: bool
+    message: str
+    dimension: int | None = None
+
+    def __bool__(self) -> bool:  # pragma: no cover - convenience only
+        return self.ok
+
+
+@dataclass(frozen=True)
+class DimensionChange:
+    """A model change that would put two vector widths in one store."""
+
+    allowed: bool
+    message: str
+    stored_dimension: int | None = None
+    new_dimension: int | None = None
+
+
+def same_embedding_model(left: str, right: str) -> bool:
+    """True when two names are two spellings of one model.
+
+    ``nomic-ai/nomic-embed-text-v1.5`` is the HuggingFace name and
+    ``nomic-embed-text`` is the Ollama pull name for the same weights. Warning
+    about a dimension change between them would be a false alarm, and a false
+    alarm about the one thing that is genuinely dangerous is how a real warning
+    gets ignored.
+    """
+    def base(name: str) -> str:
+        stem = name.strip().lower().rsplit("/", 1)[-1]
+        # An Ollama tag is PART OF THE IDENTITY, not packaging.
+        # ``qwen3-embedding:0.6b`` emits 1024 numbers and ``qwen3-embedding:8b``
+        # emits 4096, and stripping the tag made this function call them the
+        # same model — which then skipped the width check that exists to stop
+        # exactly that swap. Only ``:latest`` means "whatever the bare name
+        # means", so only that one is dropped.
+        if stem.endswith(":latest"):
+            stem = stem[: -len(":latest")]
+        # A HuggingFace revision suffix on an otherwise identical name is
+        # packaging; ``nomic-embed-text-v1.5`` and ``nomic-embed-text`` are the
+        # same weights under two registries' conventions.
+        if ":" not in stem:
+            for suffix in ("-v1.5", "-v1", "-v2"):
+                if stem.endswith(suffix):
+                    stem = stem[: -len(suffix)]
+        return stem
+
+    return base(left) == base(right)
+
+
+def validate_ollama_model(
+    model_name: str,
+    role: str = EMBEDDING,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: float = _RESPONSE_TIMEOUT,
+) -> OllamaProbe:
+    """Ask the server to actually use the model, and report what happened.
+
+    Listing the installed models is not enough: a name can be present and the
+    model still fail to load. So this runs the smallest real request for the
+    role and reads the answer, which is also the only way to learn an embedding
+    model's width.
+    """
+    if role not in (EMBEDDING, GENERATION):
+        raise ValueError(f"role must be {EMBEDDING!r} or {GENERATION!r}, got {role!r}")
+    name = (model_name or "").strip()
+    if not name:
+        return OllamaProbe(False, "No model name given.")
+
+    try:
+        import httpx
+    except ImportError:  # pragma: no cover - httpx is a hard dependency
+        return OllamaProbe(False, "httpx is not installed, so Ollama cannot be reached.")
+
+    url = base_url.rstrip("/")
+    request_timeout = httpx.Timeout(timeout, connect=_CONNECT_TIMEOUT)
+
+    try:
+        if role == EMBEDDING:
+            response = httpx.post(
+                f"{url}/api/embed",
+                json={"model": name, "input": [_PROBE_TEXT]},
+                timeout=request_timeout,
+            )
+        else:
+            response = httpx.post(
+                f"{url}/api/generate",
+                json={"model": name, "prompt": _PROBE_PROMPT, "stream": False},
+                timeout=request_timeout,
+            )
+    except httpx.ConnectError:
+        return OllamaProbe(
+            False,
+            f"Ollama is not running at {url}. Start it with: ollama serve",
+        )
+    except httpx.TimeoutException:
+        return OllamaProbe(
+            False,
+            f"Ollama did not answer within {timeout:.0f}s. The model may still be "
+            f"downloading — check with: ollama list",
+        )
+    except Exception as exc:  # noqa: BLE001 - the message is the product here
+        return OllamaProbe(False, f"Could not reach Ollama at {url}: {exc}")
+
+    if response.status_code == 404 or _looks_missing(response):
+        return OllamaProbe(
+            False,
+            f"Ollama has no model called {name!r}. Run: ollama pull {name}",
+        )
+    if role == EMBEDDING and _refuses_embeddings(response):
+        return OllamaProbe(
+            False,
+            f"{name!r} is not an embedding model — the server refused the "
+            f"request. Pick a model built for embeddings, such as "
+            f"nomic-embed-text.",
+        )
+    if response.status_code != 200:
+        return OllamaProbe(
+            False,
+            f"Ollama answered {response.status_code} for {name!r}: "
+            f"{response.text[:200]}",
+        )
+
+    try:
+        payload = response.json()
+    except ValueError:
+        return OllamaProbe(False, f"Ollama returned something that is not JSON for {name!r}.")
+
+    if role == EMBEDDING:
+        vectors = payload.get("embeddings") or []
+        if not vectors or not isinstance(vectors[0], list) or not vectors[0]:
+            return OllamaProbe(
+                False,
+                f"{name!r} answered but returned no vector, so it is not an "
+                f"embedding model. Pick one built for embeddings, such as "
+                f"nomic-embed-text.",
+            )
+        width = len(vectors[0])
+        return OllamaProbe(True, f"{name} emits {width}-dimensional vectors.", width)
+
+    text = str(payload.get("response") or "").strip()
+    if not text:
+        return OllamaProbe(
+            False,
+            f"{name!r} answered but wrote nothing, so it cannot be used to "
+            f"generate summaries.",
+        )
+    return OllamaProbe(True, f"{name} answered a probe prompt.")
+
+
+def _refuses_embeddings(response: object) -> bool:
+    """A generation-only model answers an embedding request with a refusal.
+
+    The server's own wording is about its build flags and means nothing to
+    somebody who typed a chat model's name into an embedding field.
+    """
+    status = getattr(response, "status_code", 0)
+    try:
+        lowered = response.text.lower()  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover - defensive
+        lowered = ""
+    if status == 501:
+        return True
+    return "does not support embed" in lowered or "not support embeddings" in lowered
+
+
+def _looks_missing(response: object) -> bool:
+    """Ollama reports an unknown model as a 400 with a body that says so."""
+    try:
+        body = response.text  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover - defensive
+        return False
+    lowered = body.lower()
+    return "not found" in lowered and "model" in lowered
+
+
+def stored_embedding_dimension(db_path: str | Path) -> int | None:
+    """The vector width this store already holds, or None if it holds none."""
+    path = Path(db_path)
+    if not path.exists():
+        return None
+    try:
+        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    except sqlite3.Error:
+        return None
+    try:
+        row = conn.execute(
+            "SELECT dimension FROM embedding_metadata "
+            "WHERE dimension IS NOT NULL AND dimension > 0 LIMIT 1"
+        ).fetchone()
+    except sqlite3.Error:
+        return None
+    finally:
+        conn.close()
+    return int(row[0]) if row else None
+
+
+def check_embedding_model_change(
+    new_model: str,
+    *,
+    db_path: str | Path,
+    current_model: str = "",
+    base_url: str = DEFAULT_BASE_URL,
+) -> DimensionChange:
+    """Decide whether switching the embedding model is safe for this store.
+
+    Refuses rather than warns. A warning printed into a log is not a decision,
+    and the outcome of getting this wrong is a store whose similarity search is
+    quietly meaningless.
+    """
+    # The width is asked for FIRST, always. Recognising two names as the same
+    # model may soften the message, but it must never stand in for measuring —
+    # a name that merely looks familiar is exactly how a different-width model
+    # would get through.
+    probe = validate_ollama_model(new_model, EMBEDDING, base_url=base_url)
+    if not probe.ok:
+        return DimensionChange(False, probe.message)
+
+    familiar = bool(current_model) and same_embedding_model(current_model, new_model)
+    stored = stored_embedding_dimension(db_path)
+    if familiar and (stored is None or stored == probe.dimension):
+        return DimensionChange(
+            True,
+            f"{new_model} is another name for the model already in use, and it "
+            f"emits the same {probe.dimension}-dimensional vectors.",
+            stored,
+            probe.dimension,
+        )
+    if stored is None:
+        return DimensionChange(
+            True,
+            f"{probe.message} This store holds no vectors yet, so nothing has to "
+            f"be rebuilt.",
+            None,
+            probe.dimension,
+        )
+    if stored == probe.dimension:
+        return DimensionChange(True, probe.message, stored, probe.dimension)
+
+    return DimensionChange(
+        False,
+        f"{new_model} emits {probe.dimension}-dimensional vectors and this store "
+        f"holds {stored}-dimensional ones. Vectors of different widths cannot be "
+        f"compared, so every memory already stored would become unfindable by "
+        f"meaning. Rebuild them first with: slm db migrate",
+        stored,
+        probe.dimension,
+    )