superlocalmemory 4.0.5 → 4.0.6

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

@@ -260,6 +260,131 @@ async def set_mode(request: Request):
         return _internal_error()
 
 
+def apply_settings_update(config: "SLMConfig", payload: dict) -> "SLMConfig":
+    """Credential-safe LLM config update for the settings dashboard (fixes #119).
+
+    This is the SINGLE authoritative place where incoming dashboard save payloads
+    are merged onto the stored config.  The POST /api/v3/mode/set handler calls
+    this function after its HTTP-layer concerns (SSRF guard, auth) are settled,
+    so the acceptance gate (test_wave2_acceptance.py::P3) tests real product
+    behaviour — not a reimplementation.
+
+    SEC-L-01 PRESERVED:
+      The GET /mode route returns only ``urlparse(api_base).netloc`` (the host),
+      never the full URL.  When the UI echoes that value back on save,
+      apply_settings_update detects the scheme-less netloc and silently restores
+      the stored full URL (scheme + path).  This means the server-side logic
+      internally reads the stored URL but NEVER returns it to callers — viewer
+      users remain unable to discover the full endpoint topology.
+
+    Credential semantics:
+      api_key  blank/omitted   →  UNCHANGED  (browsers never repopulate pw fields)
+      api_key  non-blank       →  applied
+      clear_api_key = True     →  explicit "" (deliberate wipe — only way to clear)
+
+      endpoint  absent/empty   →  UNCHANGED
+      endpoint  == stored netloc (no scheme "://")  →  UNCHANGED (redacted echo)
+      endpoint  with "://"     →  applied
+      clear_base_url = True    →  explicit "" (deliberate wipe)
+
+    Security rule:  if the destination provider or endpoint genuinely changes AND
+    no new key was supplied, the stored key is cleared to prevent accidental
+    credential reuse across providers.  An explicit clear_api_key=True is
+    always honoured regardless.
+
+    NEVER logs api_key.
+    """
+    import dataclasses as _dc
+    from urllib.parse import urlparse, urlsplit, urlunsplit
+
+    stored = config.llm
+    stored_key: str = stored.api_key
+    stored_base: str = stored.api_base or ""
+
+    # ── endpoint ─────────────────────────────────────────────────────────────
+    raw_endpoint: str = (payload.get("endpoint") or payload.get("base_url") or "").strip()
+    clear_endpoint: bool = payload.get("clear_base_url") is True
+
+    if clear_endpoint:
+        new_base = ""
+        endpoint_changed = bool(stored_base)
+    elif not raw_endpoint:
+        # Nothing supplied — keep stored URL intact.
+        new_base = stored_base
+        endpoint_changed = False
+    else:
+        # Detect the SEC-L-01 redacted echo: GET /mode returns
+        # urlparse(api_base).netloc (host only, no scheme, no path).  If the
+        # client sent that exact string back, it did NOT change the endpoint —
+        # restore the full stored URL.  We compare the raw string directly to
+        # stored_netloc so that hosts with ports ("api.host.com:443") also match.
+        stored_netloc: str = urlparse(stored_base).netloc if stored_base else ""
+        is_redacted_echo: bool = bool(stored_netloc) and (raw_endpoint == stored_netloc)
+
+        if is_redacted_echo:
+            new_base = stored_base
+            endpoint_changed = False
+        else:
+            new_base = raw_endpoint
+            # Canonical comparison (strip trailing slash, normalise scheme/host
+            # case) so a harmless trailing-slash difference does not clear the key.
+            def _canonical(u: str) -> str:
+                p = urlsplit(u)
+                return urlunsplit((
+                    p.scheme.lower(), p.netloc.lower(),
+                    p.path.rstrip("/"), p.query, "",
+                ))
+            endpoint_changed = _canonical(new_base) != _canonical(stored_base)
+
+    # ── provider ─────────────────────────────────────────────────────────────
+    raw_provider: str = (payload.get("provider") or "").strip()
+    if raw_provider == "none":
+        new_provider = ""      # "none" sentinel means "clear provider"
+    elif raw_provider:
+        new_provider = raw_provider
+    else:
+        new_provider = stored.provider or ""
+
+    provider_changed: bool = new_provider != (stored.provider or "")
+
+    # ── api_key ───────────────────────────────────────────────────────────────
+    # Evaluated AFTER endpoint/provider so we know whether the destination changed.
+    raw_key: str = (payload.get("api_key") or "").strip()
+    clear_key: bool = payload.get("clear_api_key") is True
+    destination_changed: bool = provider_changed or endpoint_changed
+
+    if clear_key:
+        new_key = ""           # explicit user wipe
+    elif raw_key:
+        new_key = raw_key      # user supplied a replacement key
+    elif destination_changed:
+        # Security: destination changed but no new key → clear to prevent
+        # the stored credential from being silently redirected to a new
+        # provider or endpoint the user may not own.
+        new_key = ""
+    else:
+        # Blank key + same destination = browser did not repopulate the
+        # password field.  Preserve the stored key verbatim.
+        new_key = stored_key
+
+    # ── model ────────────────────────────────────────────────────────────────
+    raw_model: str = (payload.get("model") or "").strip()
+    new_model: str = raw_model if raw_model else (stored.model or "")
+
+    # ── apply ─────────────────────────────────────────────────────────────────
+    # dataclasses.replace preserves temperature / max_tokens / timeout_seconds.
+    # Assigning to config.llm works because SLMConfig is not frozen.
+    # NEVER include new_key in any log call.
+    config.llm = _dc.replace(
+        stored,
+        provider=new_provider,
+        model=new_model,
+        api_key=new_key,
+        api_base=new_base,
+    )
+    return config
+
+
 @router.post("/mode/set")
 async def set_full_config(request: Request):
     """Save mode + provider + model + API key together.
@@ -273,7 +398,7 @@ async def set_full_config(request: Request):
         body = await request.json()
         if not isinstance(body, dict):
             return JSONResponse({"error": "Request body must be a JSON object"}, status_code=400)
-        from superlocalmemory.core.config import SLMConfig, EmbeddingConfig, LLMConfig
+        from superlocalmemory.core.config import SLMConfig, EmbeddingConfig
         from superlocalmemory.storage.models import Mode
         from superlocalmemory.server.routes.helpers import log_mode_change
 
@@ -316,68 +441,54 @@ async def set_full_config(request: Request):
         if new_mode not in ("a", "b", "c"):
             return JSONResponse({"error": "Invalid mode"}, status_code=400)
 
-        # Field presence, not form defaults, is the persistence contract. A
-        # dashboard panel may update embeddings without sending mode/provider,
-        # and password fields deliberately reload blank. In both cases saved
-        # LLM state must remain intact unless the user supplies a replacement
-        # or explicit clear flag.
-        provider = provider_input or config.llm.provider or "none"
-        model = model_input or config.llm.model
-        _endpoint = "" if clear_base_url else (base_url_input or endpoint_input or "")
+        # Resolve the effective endpoint value before SSRF validation.
+        # Only the Ollama default injection happens here; the fallback to the
+        # stored URL (and redacted-echo detection) live inside
+        # apply_settings_update so that the P3 acceptance gate exercises
+        # the same code path as the HTTP handler — not a reimplementation.
+        _raw_ep: str = "" if clear_base_url else (base_url_input or endpoint_input or "")
         if (
-            not _endpoint and provider_input == "ollama"
+            not _raw_ep
+            and provider_input == "ollama"
             and config.llm.provider != "ollama"
             and not clear_base_url
         ):
-            _endpoint = "http://localhost:11434"
-        elif not _endpoint and not clear_base_url:
-            _endpoint = config.llm.api_base or ""
-
-        # Custom endpoints become runtime egress destinations.  Apply the
-        # same boundary policy as the connection-test route before persisting.
-        if base_url_input is not None or endpoint_input is not None:
-            client = getattr(request, "client", None)
-            endpoint_error = _validate_provider_url(
-                _endpoint, getattr(client, "host", "") if client else ""
-            )
-            if endpoint_error:
-                return JSONResponse({"error": endpoint_error}, status_code=400)
-
-        # A retained cloud credential must never be redirected to a caller's
-        # newly supplied provider or endpoint.  Compare canonical URL identity
-        # after validation so a harmless host-case or trailing-slash rewrite
-        # does not unexpectedly clear the key.
-        from urllib.parse import urlsplit, urlunsplit
-
-        def _endpoint_identity(url: str) -> str:
-            parsed = urlsplit(url)
-            return urlunsplit((
-                parsed.scheme.lower(), parsed.netloc.lower(),
-                parsed.path.rstrip("/"), parsed.query, "",
-            ))
-
-        destination_changed = (
-            (provider_input is not None and provider_input != config.llm.provider)
-            or (
-                (base_url_input is not None or endpoint_input is not None)
-                and _endpoint_identity(_endpoint)
-                != _endpoint_identity(config.llm.api_base or "")
-            )
-        )
-        api_key = "" if (clear_api_key or (destination_changed and not api_key_input)) else (
-            api_key_input or config.llm.api_key
-        )
-
-        # Mutate only the fields the dashboard sent — all other config blocks
-        # (forgetting, injection, retrieval, math, consolidation, scope, …) are
-        # preserved because we loaded the full existing config above.
+            _raw_ep = "http://localhost:11434"
+
+        # SSRF guard — fires only for genuinely new egress destinations.
+        # Redacted echoes (the netloc-only string GET /mode returns per
+        # SEC-L-01) are NOT outbound targets; they will be silently replaced
+        # with the stored full URL by apply_settings_update.
+        if _raw_ep and (base_url_input is not None or endpoint_input is not None):
+            from urllib.parse import urlparse as _up
+            _stored_nl: str = _up(config.llm.api_base or "").netloc
+            _is_redacted_echo: bool = bool(_stored_nl) and (_raw_ep == _stored_nl)
+            if not _is_redacted_echo:
+                client = getattr(request, "client", None)
+                endpoint_error = _validate_provider_url(
+                    _raw_ep, getattr(client, "host", "") if client else ""
+                )
+                if endpoint_error:
+                    return JSONResponse({"error": endpoint_error}, status_code=400)
+
+        # Build the normalised body for apply_settings_update.  Inject the
+        # resolved endpoint (Ollama default when applicable) so that the
+        # credential-safe logic sees the approved value.  Consolidate
+        # base_url → endpoint to keep apply_settings_update's lookup simple.
+        _apply_body: dict = dict(body)
+        if _raw_ep or clear_base_url:
+            _apply_body["endpoint"] = _raw_ep
+            _apply_body.pop("base_url", None)
+
+        # Credential-safe LLM update.  All field presence, preservation, and
+        # security-clearing rules live here.  Other config blocks (forgetting,
+        # injection, retrieval, math, consolidation, scope, …) are preserved
+        # because we loaded the full existing config at the top of this handler.
+        config = apply_settings_update(config, _apply_body)
+
+        # Mode switch — happens after LLM update so the correct provider/key
+        # is already in place when the runtime engine is reconfigured.
         config.mode = Mode(new_mode)
-        config.llm = LLMConfig(
-            provider=provider if provider != "none" else "",
-            model=model,
-            api_key=api_key,
-            api_base=_endpoint,
-        )
 
         # Update embedding only when the dashboard explicitly sent those fields;
         # absence means "leave it alone" (AIDEV-86 / broader fix).
@@ -423,8 +534,8 @@ async def set_full_config(request: Request):
         return {
             "success": True,
             "mode": new_mode,
-            "provider": provider,
-            "model": model,
+            "provider": config.llm.provider or "none",
+            "model": config.llm.model,
             "embedding_provider": config.embedding.provider,
             "embedding_model": config.embedding.model_name,
             "embedding_dimension": config.embedding.dimension,

package/src/superlocalmemory/storage/database.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 import json
 import logging
 import os
+import platform
 import sqlite3
 import threading
 import time
@@ -85,6 +86,10 @@ _BUSY_TIMEOUT_MS = _env_int("SLM_DB_BUSY_TIMEOUT_MS", 10_000)   # wait for write
 _MAX_RETRIES = _env_int("SLM_DB_MAX_RETRIES", 5)                # retry on SQLITE_BUSY
 _RETRY_BASE_DELAY = _env_float("SLM_DB_RETRY_BASE_DELAY", 0.1)  # backoff base (s)
 
+# Warn once per process, not once per connection, when the WAL close-path
+# deadlock guard cannot be installed (Python < 3.12).
+_NO_CKPT_WARNED = False
+
 
 def _unbounded_facts_ceiling() -> int:
     """Hard upper bound applied when a fact fetch is called with limit=None, so
@@ -231,6 +236,37 @@ class DatabaseManager:
         conn.row_factory = sqlite3.Row
         conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")
         conn.execute("PRAGMA foreign_keys=ON")
+        # wal_autocheckpoint is a PER-CONNECTION pragma and is NOT persisted in
+        # the database file (unlike journal_mode=WAL).  Setting it only on the
+        # short-lived initialisation connection left every working connection
+        # on SQLite's default of 1000 frames.  With checkpoint-on-close
+        # disabled below, autocheckpoint is the ONLY remaining checkpoint path,
+        # so the intended value must be set where the writes actually happen.
+        conn.execute("PRAGMA wal_autocheckpoint=400")
+        # Deadlock hardening (postmortem 2026-08-13, Option B): WAL close
+        # triggers a checkpoint that can wait indefinitely on reader marks
+        # pinned by another process/thread — while holding SQLite's
+        # process-global VFS mutex, which convoys every later connect().
+        # busy_timeout does NOT apply to the close path. NO_CKPT_ON_CLOSE
+        # makes close() checkpoint-free so it can never block; normal
+        # checkpointing continues via the wal_autocheckpoint set above.
+        # Available since Python 3.12 / SQLite 3.31; guarded for portability.
+        try:
+            conn.setconfig(sqlite3.SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE, 1)  # type: ignore[attr-defined]
+        except (AttributeError, sqlite3.OperationalError):
+            # Silent degradation would hide an inactive deadlock guard on a
+            # supported interpreter (requires-python allows 3.11, which
+            # predates Connection.setconfig).  Warn once, not per connection.
+            global _NO_CKPT_WARNED
+            if not _NO_CKPT_WARNED:
+                _NO_CKPT_WARNED = True
+                logger.warning(
+                    "SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE unavailable (Python %s, "
+                    "SQLite %s); WAL close-path deadlock hardening is INACTIVE. "
+                    "Python 3.12+ is required for this protection.",
+                    platform.python_version(),
+                    sqlite3.sqlite_version,
+                )
         return conn
 
     @contextmanager

package/src/superlocalmemory/storage/models.py

@@ -73,11 +73,19 @@ class SignalType(str, Enum):
 
 
 class Mode(str, Enum):
-    """Operating modes — EU AI Act alignment."""
+    """Operating modes.
+
+    A — All data stays on this device. No AI language model runs anywhere.
+        Fastest and most private.
+    B — All data stays on this device. Uses a local Ollama AI model to
+        improve recall quality. Requires Ollama to be installed and running.
+    C — Uses a cloud AI provider (OpenAI, Anthropic, …) for the best recall
+        quality. Queries leave this device; an API key is required.
+    """
 
-    A = "a"  # Local Guardian: zero LLM, EU AI Act FULL
-    B = "b"  # Smart Local: local Ollama LLM, EU AI Act FULL
-    C = "c"  # Full Power: UNRESTRICTED, best models, 90%+ target
+    A = "a"  # Local Guardian — on-device only, no LLM
+    B = "b"  # Smart Local — on-device + local Ollama LLM, no cloud
+    C = "c"  # Cloud LLM — best accuracy, queries leave device, API key needed
 
 
 # ---------------------------------------------------------------------------

package/src/superlocalmemory/summaries/__init__.py

@@ -0,0 +1,37 @@
+# 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
+
+"""SuperLocalMemory issue #113 — Personal Memory Views.
+
+Three bounded, profile-scoped, traceable summaries:
+
+  Session Summary    — what happened in a specific session (data is sparse:
+                       only ~3.9% of facts carry a session_id on a real store;
+                       coverage is always disclosed explicitly).
+  Daily Reflection   — what was recorded on a specific date.
+  Project Work Log   — what tool events and facts belong to a project,
+                       scoped by tool_events.project_path (NOT by
+                       entity_profiles.project_name, which has one distinct
+                       value across 1,148 rows and is useless for scoping).
+
+Every SummaryResult carries:
+  - source_fact_ids  for traceability (maintainer's binding constraint)
+  - profile_id       — cross-profile access is not permitted
+  - coverage         — honest assessment; never silently partial
+
+Deferred to 4.0.7: prompt-driven custom views.  They are non-deterministic,
+hard to make traceable, and a prompt-injection surface.
+"""
+
+from .base import SummaryResult
+from .daily_reflection import generate_daily_reflection
+from .project_work_log import generate_project_work_log
+from .session_summary import generate_session_summary
+
+__all__ = [
+    "SummaryResult",
+    "generate_session_summary",
+    "generate_daily_reflection",
+    "generate_project_work_log",
+]

package/src/superlocalmemory/summaries/base.py

@@ -0,0 +1,108 @@
+# 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
+
+"""Base types for the #113 bounded summary layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class SummaryResult:
+    """A bounded, profile-scoped, traceable summary of user memories.
+
+    Maintainer's binding constraint (issue #113 reply):
+        "views must be customizable, profile-scoped, privacy-aware, and
+         traceable back to the underlying memories rather than becoming
+         opaque generic summaries"
+
+    This dataclass enforces three of those four constraints structurally:
+
+    Traceability
+        ``source_fact_ids`` carries the atomic_facts.fact_id for every fact
+        that contributed to this summary.  A user can always drill back to
+        the raw memories.
+
+    Profile scope
+        ``profile_id`` is mandatory; callers must never mix profiles.
+
+    Honesty / non-opaqueness
+        ``coverage`` must be set to an accurate value.  See the constants
+        below.  A summary over 3.9% of facts that presents itself as "your
+        session" is precisely the opaque generic summary the maintainer said
+        to avoid.
+
+    Generated-by
+        ``generated_by`` records whether the content is extractive
+        (deterministic, always available, Mode A default) or came from an
+        LLM (Mode B Ollama / Mode C cloud).
+
+    Attributes:
+        kind:            "session" | "daily" | "project"
+        profile_id:      Owning profile — never expose across profiles.
+        content:         Human-readable summary text.
+        source_fact_ids: IDs of the atomic_facts that contributed.
+                         Empty only when the underlying data does not exist.
+        coverage:        One of the COVERAGE_* constants below.
+        generated_by:    One of the GENERATED_BY_* constants below.
+        metadata:        Extra context: date, project_path, session_id, etc.
+    """
+
+    kind: str
+    profile_id: str
+    content: str
+    source_fact_ids: list[str]
+    coverage: str
+    generated_by: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+# ── coverage constants ──────────────────────────────────────────────────────
+#
+# Use these strings; the acceptance gate checks for their presence
+# and the values must be human-interpretable without this file.
+
+COVERAGE_FULL = "full"
+"""All relevant data was available and contributed to the summary."""
+
+COVERAGE_PARTIAL = "partial"
+"""Some data was available.  Session summaries are always at most partial
+because only ~3.9% of facts carry a session_id on a real store."""
+
+COVERAGE_INSUFFICIENT = "insufficient"
+"""Too few facts to produce a meaningful summary (below MIN_FACTS threshold)."""
+
+COVERAGE_NO_SESSION = "no_session"
+"""Session ID not found, or the session has no associated facts."""
+
+COVERAGE_UNAVAILABLE = "unavailable"
+"""Required data does not exist or a query error prevented access."""
+
+
+# ── generated_by constants ──────────────────────────────────────────────────
+#
+# extractive is the deterministic fallback, ALWAYS available.
+# Mode A users never get anything else.  Mode B/C users fall back when
+# Ollama or the cloud is down — silence is not an option.
+
+GENERATED_BY_EXTRACTIVE = "extractive"
+"""Deterministic extractive summary — no LLM.  Always available."""
+
+GENERATED_BY_LLM_B = "llm_b"
+"""Ollama local LLM (Mode B).  Falls back to extractive if unavailable."""
+
+GENERATED_BY_LLM_C = "llm_c"
+"""Cloud LLM (Mode C).  Falls back via llm_b to extractive."""
+
+
+def get_mode_str(config: object | None) -> str:
+    """Extract the operating mode string ('a', 'b', or 'c') from a config."""
+    if config is None:
+        return "a"
+    m = getattr(config, "mode", None)
+    if m is None:
+        return "a"
+    return getattr(m, "value", str(m)).lower()