superlocalmemory 4.0.0 → 4.0.2

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

@@ -61,6 +61,7 @@ from superlocalmemory.learning.database import LearningDatabase
 from superlocalmemory.learning.features import FEATURE_DIM
 from superlocalmemory.infra.data_root import canonical_data_root
 from superlocalmemory.storage.read_connection import ReadConnectionFactory
+from superlocalmemory.storage.agent_experience import get_profile_receipt_summary
 from .helpers import get_active_profile
 
 logger = logging.getLogger("superlocalmemory.routes.brain")
@@ -320,6 +321,15 @@ def _compute_learning_status(profile_id: str,
     }
 
 
+def _compute_agent_experience(profile_id: str) -> dict:
+    """Honest, profile-scoped receipt evidence for the Living Brain.
+
+    Receipt rows record observation and verification evidence only; this read
+    model never alters retrieval, ranking, or model routing.
+    """
+    return get_profile_receipt_summary(_learning_db_path(), profile_id)
+
+
 def _resolve_phase(signals: int, model_active: bool,
                    sha_present: bool) -> tuple[int, str]:
     """LLD-02 §4.10 — phase truth, U3 enforcement.
@@ -687,6 +697,161 @@ def _compute_cross_platform() -> dict:
     return out
 
 
+def _compute_active_clients(profile_id: str) -> dict:
+    """Return recent host presence without leaking session identifiers.
+
+    ``cross_platform`` describes configured integration targets.  This
+    separate read-model answers the different question users actually ask:
+    which host clients have recently interacted with this local brain?
+    """
+    try:
+        from superlocalmemory.hooks.session_registry import active_client_summary
+        clients = active_client_summary(profile_id, within_seconds=300)
+    except Exception:
+        clients = []
+    return {
+        "is_real": True,
+        "scope": "profile",
+        "window_seconds": 300,
+        "clients": clients,
+        "source": "session_registry (ephemeral, profile-scoped)",
+    }
+
+
+def _compute_feedback_loop(profile_id: str, lrn_db: LearningDatabase) -> dict:
+    """Expose only durable feedback evidence that already drives learning."""
+    empty = {
+        "is_real": True,
+        "signals_by_type": {},
+        "explicit_signals": 0,
+        "implicit_signals": 0,
+        "settled_outcomes": 0,
+        "mean_settled_reward": None,
+        "source": "learning_signals + memory.db:action_outcomes",
+    }
+    signal_rows: list[sqlite3.Row] = []
+    try:
+        learning_conn = lrn_db.ro_connection()
+        try:
+            signal_rows = learning_conn.execute(
+                "SELECT signal_type, COUNT(*) AS count FROM learning_signals "
+                "WHERE profile_id = ? GROUP BY signal_type ORDER BY signal_type",
+                (profile_id,),
+            ).fetchall()
+        finally:
+            learning_conn.close()
+    except sqlite3.Error:
+        return empty
+    by_type = {
+        str(row["signal_type"]): int(row["count"] or 0)
+        for row in signal_rows
+    }
+    explicit_types = {
+        "user_positive", "user_negative", "user_correction", "user_pin",
+        "legacy_feedback",
+    }
+    explicit = sum(count for kind, count in by_type.items() if kind in explicit_types)
+    implicit = sum(count for kind, count in by_type.items() if kind not in explicit_types)
+    settled, mean_reward = 0, None
+    db_path = _memory_db_path()
+    if db_path.exists():
+        try:
+            memory_conn = ReadConnectionFactory(db_path).open()
+            try:
+                row = memory_conn.execute(
+                    "SELECT COUNT(*) AS count, AVG(reward) AS mean_reward "
+                    "FROM action_outcomes WHERE profile_id = ? AND settled = 1 "
+                    "AND reward IS NOT NULL",
+                    (profile_id,),
+                ).fetchone()
+                if row:
+                    settled = int(row["count"] or 0)
+                    mean_reward = (
+                        float(row["mean_reward"])
+                        if row["mean_reward"] is not None else None
+                    )
+            finally:
+                memory_conn.close()
+        except sqlite3.Error:
+            pass
+    return {
+        **empty,
+        "signals_by_type": by_type,
+        "explicit_signals": explicit,
+        "implicit_signals": implicit,
+        "settled_outcomes": settled,
+        "mean_settled_reward": mean_reward,
+    }
+
+
+def _compute_source_quality(profile_id: str) -> dict:
+    """Summarize observed provenance quality; neutral priors are not evidence."""
+    empty = {
+        "is_real": True,
+        "observed_sources": 0,
+        "mean_quality": None,
+        "source": "learning.db:source_quality_observations",
+    }
+    db_path = _learning_db_path()
+    if not db_path.exists():
+        return empty
+    try:
+        conn = sqlite3.connect(db_path, timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        try:
+            row = conn.execute(
+                "SELECT COUNT(DISTINCT source_id) AS sources, AVG(reward) AS mean_quality "
+                "FROM source_quality_observations WHERE profile_id = ?",
+                (profile_id,),
+            ).fetchone()
+        finally:
+            conn.close()
+        if row is None:
+            return empty
+        return {
+            **empty,
+            "observed_sources": int(row["sources"] or 0),
+            "mean_quality": float(row["mean_quality"]) if row["mean_quality"] is not None else None,
+        }
+    except sqlite3.Error:
+        return empty
+
+
+def _compute_graph_summary(profile_id: str) -> dict:
+    """Return graph evidence counts, never a decorative graph surrogate."""
+    empty = {
+        "is_real": True,
+        "fact_nodes": 0,
+        "association_edges": 0,
+        "source": "memory.db:atomic_facts + association_edges",
+    }
+    db_path = _memory_db_path()
+    if not db_path.exists():
+        return empty
+    try:
+        conn = ReadConnectionFactory(db_path).open()
+        try:
+            facts = conn.execute(
+                "SELECT COUNT(*) AS count FROM atomic_facts "
+                "WHERE profile_id = ?",
+                (profile_id,),
+            ).fetchone()
+            edges = conn.execute(
+                "SELECT COUNT(*) AS count FROM association_edges "
+                "WHERE profile_id = ?",
+                (profile_id,),
+            ).fetchone()
+        finally:
+            conn.close()
+        return {
+            **empty,
+            "fact_nodes": int(facts["count"] or 0) if facts else 0,
+            "association_edges": int(edges["count"] or 0) if edges else 0,
+        }
+    except sqlite3.Error:
+        return empty
+
+
 def _meta_now() -> dict:
     return {
         "generated_at": datetime.now(timezone.utc)
@@ -963,7 +1128,8 @@ async def get_brain(request: Request, profile_id: str | None = None) -> dict:
 
     (
         preferences, learning, usage, bandit_snap, cache,
-        cross_platform, outcomes_preview, evolution,
+        cross_platform, outcomes_preview, evolution, active_clients,
+        feedback_loop, source_quality, graph_summary, agent_experience,
     ) = await asyncio.gather(
         asyncio.to_thread(_compute_preferences, profile_id),
         asyncio.to_thread(_compute_learning_status, profile_id, lrn_db),
@@ -976,6 +1142,11 @@ async def get_brain(request: Request, profile_id: str | None = None) -> dict:
             _compute_evolution_timeseries, profile_id, lrn_db,
             days=_EVOLUTION_DEFAULT_DAYS,
         ),
+        asyncio.to_thread(_compute_active_clients, profile_id),
+        asyncio.to_thread(_compute_feedback_loop, profile_id, lrn_db),
+        asyncio.to_thread(_compute_source_quality, profile_id),
+        asyncio.to_thread(_compute_graph_summary, profile_id),
+        asyncio.to_thread(_compute_agent_experience, profile_id),
         return_exceptions=True,
     )
 
@@ -986,6 +1157,26 @@ async def get_brain(request: Request, profile_id: str | None = None) -> dict:
             return fallback
         return value
 
+    active_clients = _ok(active_clients, {"is_real": True, "scope": "profile", "clients": [],
+                                          "window_seconds": 300,
+                                          "source": "session_registry unavailable"})
+    feedback_loop = _ok(feedback_loop, {"is_real": True, "signals_by_type": {},
+                                         "explicit_signals": 0, "implicit_signals": 0,
+                                         "settled_outcomes": 0, "mean_settled_reward": None,
+                                         "source": "feedback data unavailable"})
+    source_quality = _ok(source_quality, {"is_real": True, "observed_sources": 0,
+                                           "mean_quality": None,
+                                           "source": "source-quality data unavailable"})
+    graph_summary = _ok(graph_summary, {"is_real": True, "fact_nodes": 0,
+                                         "association_edges": 0,
+                                         "source": "graph data unavailable"})
+    agent_experience = _ok(agent_experience, {
+        "is_real": False, "availability": "unavailable",
+        "experiences_total": 0, "turns_total": 0,
+        "turns_by_state": {}, "claimed_evidence_experiences": 0,
+        "source": "receipt data unavailable",
+    })
+
     return {
         "profile_id": profile_id,
         "preferences":      _ok(preferences, {"is_real": True,
@@ -1005,6 +1196,20 @@ async def get_brain(request: Request, profile_id: str | None = None) -> dict:
                                         "db_size_bytes": 0,
                                         "entry_count": 0}),
         "cross_platform":   _ok(cross_platform, {}),
+        # One canonical, transport-neutral read model for the non-technical
+        # Living Brain.  Existing top-level sections stay intact for the CLI,
+        # MCP and older dashboard clients.  This is observation only: it never
+        # changes retrieval or model routing.
+        "living_brain": {
+            "is_real": True,
+            "control_plane": "observation_only",
+            "connected_clients": active_clients,
+            "feedback": feedback_loop,
+            "source_quality": source_quality,
+            "graph": graph_summary,
+            "agent_experience": agent_experience,
+            "source": "local durable stores + ephemeral session registry",
+        },
         "evolution_preview": _ok(evolution, {
             "is_real": True, "source": "learning_signals",
             "days": _EVOLUTION_DEFAULT_DAYS, "total_signals": 0, "points": [],

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

@@ -8,9 +8,10 @@ Shared utilities for all route modules: DB connection, dict factory,
 profile helper, validation, Pydantic models, config paths, and the
 shared lazy engine accessor used by every engine-dependent route.
 """
+
+import json
 import logging
 import re
-import json
 import sqlite3
 import threading
 import time
@@ -24,7 +25,6 @@ from pydantic import BaseModel, Field
 from superlocalmemory.infra.data_root import DynamicStatePath, canonical_data_root
 from superlocalmemory.storage.memory_write import memory_read, memory_write
 
-
 _engine_logger = logging.getLogger("superlocalmemory.engine")
 
 
@@ -32,6 +32,7 @@ _engine_logger = logging.getLogger("superlocalmemory.engine")
 # Version detection (shared — avoids circular import between ui.py ↔ v3_api.py)
 # ---------------------------------------------------------------------------
 
+
 def _get_version() -> str:
     """Read version from package.json / pyproject.toml / importlib.
 
@@ -43,6 +44,7 @@ def _get_version() -> str:
     for depth in (5, 4):
         try:
             import json as _json
+
             root = here
             for _ in range(depth):
                 root = root.parent
@@ -55,12 +57,14 @@ def _get_version() -> str:
             toml_path = root / "pyproject.toml"
             if toml_path.exists():
                 import tomllib
+
                 with open(toml_path, "rb") as f:
                     return tomllib.load(f)["project"]["version"]
         except Exception:
             continue
     try:
         from importlib.metadata import version
+
         return version("superlocalmemory")
     except Exception:
         pass
@@ -147,6 +151,7 @@ def get_engine_lazy(app_state):
         try:
             from superlocalmemory.core.config import SLMConfig
             from superlocalmemory.core.engine import MemoryEngine
+
             config = SLMConfig.load()
             new_engine = MemoryEngine(config)
             new_engine.initialize()
@@ -213,7 +218,11 @@ def log_mode_change(
 
     _engine_logger.info(
         "Mode change: %s→%s provider=%s model=%s (%s)",
-        old_mode, new_mode, provider, model, source,
+        old_mode,
+        new_mode,
+        provider,
+        model,
+        source,
     )
 
 
@@ -277,17 +286,17 @@ def get_active_profile() -> str:
     config_file = MEMORY_DIR / "profiles.json"
     if config_file.exists():
         try:
-            with open(config_file, 'r') as f:
+            with open(config_file, "r") as f:
                 pconfig = json.load(f)
-            return pconfig.get('active_profile', 'default')
+            return pconfig.get("active_profile", "default")
         except (json.JSONDecodeError, IOError):
             pass
-    return 'default'
+    return "default"
 
 
 def validate_profile_name(name: str) -> bool:
     """Validate profile name (alphanumeric, underscore, hyphen only)."""
-    return bool(re.match(r'^[a-zA-Z0-9_-]+$', name))
+    return bool(re.match(r"^[a-zA-Z0-9_-]+$", name))
 
 
 # ============================================================================
@@ -308,8 +317,7 @@ def ensure_profile_in_db(name: str, description: str = "") -> None:
     with memory_write(DB_PATH) as conn:
         conn.execute("PRAGMA foreign_keys=ON")
         conn.execute(
-            "INSERT OR IGNORE INTO profiles (profile_id, name, description) "
-            "VALUES (?, ?, ?)",
+            "INSERT OR IGNORE INTO profiles (profile_id, name, description) VALUES (?, ?, ?)",
             (name, name, description or f"Memory profile: {name}"),
         )
 
@@ -317,17 +325,17 @@ def ensure_profile_in_db(name: str, description: str = "") -> None:
 def ensure_profile_in_json(name: str, description: str = "") -> None:
     """Ensure a profile entry exists in profiles.json (idempotent)."""
     from datetime import datetime
-    config_file = MEMORY_DIR / "profiles.json"
+
     config = _load_profiles_json()
-    profiles = config.get('profiles', {})
+    profiles = config.get("profiles", {})
     if name not in profiles:
         profiles[name] = {
-            'name': name,
-            'description': description or f'Memory profile: {name}',
-            'created_at': datetime.now(timezone.utc).isoformat(),
-            'last_used': None,
+            "name": name,
+            "description": description or f"Memory profile: {name}",
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "last_used": None,
         }
-        config['profiles'] = profiles
+        config["profiles"] = profiles
         _save_profiles_json(config)
 
 
@@ -340,31 +348,31 @@ def sync_profiles() -> list[dict]:
     """
     db_profiles = _get_db_profiles()
     json_config = _load_profiles_json()
-    json_profiles = json_config.get('profiles', {})
+    json_profiles = json_config.get("profiles", {})
 
     # profile_id is the canonical key (PK in SQLite, FK target everywhere)
-    db_ids = {p['profile_id'] for p in db_profiles}
+    db_ids = {p["profile_id"] for p in db_profiles}
     json_keys = set(json_profiles.keys())
 
     changed = False
 
     # JSON-only → add to SQLite (fixes Dashboard-created profiles)
     for key in json_keys - db_ids:
-        ensure_profile_in_db(key, json_profiles[key].get('description', ''))
+        ensure_profile_in_db(key, json_profiles[key].get("description", ""))
 
     # SQLite-only → add to profiles.json (fixes CLI-created profiles)
     for pid in db_ids - json_keys:
-        db_entry = next(p for p in db_profiles if p['profile_id'] == pid)
+        db_entry = next(p for p in db_profiles if p["profile_id"] == pid)
         json_profiles[pid] = {
-            'name': pid,
-            'description': db_entry.get('description', ''),
-            'created_at': db_entry.get('created_at', ''),
-            'last_used': db_entry.get('last_used'),
+            "name": pid,
+            "description": db_entry.get("description", ""),
+            "created_at": db_entry.get("created_at", ""),
+            "last_used": db_entry.get("last_used"),
         }
         changed = True
 
     if changed:
-        json_config['profiles'] = json_profiles
+        json_config["profiles"] = json_profiles
         _save_profiles_json(json_config)
 
     # Return merged list from SQLite (now authoritative)
@@ -389,6 +397,12 @@ def delete_profile_from_db(name: str) -> None:
     """
     if not DB_PATH.exists():
         return
+    # Receipt evidence lives in learning.db, not recall's memory.db.  Purge it
+    # first: if this fails the profile row must survive for a retry rather than
+    # leaving profile-scoped learning evidence orphaned.
+    from superlocalmemory.storage.agent_experience import purge_profile_receipts
+
+    purge_profile_receipts(Path(DB_PATH).parent / "learning.db", name)
     with memory_write(DB_PATH) as conn:
         conn.execute("PRAGMA foreign_keys=ON")
         # Purge role grants for this workspace (no FK CASCADE covers these).
@@ -420,24 +434,24 @@ def _load_profiles_json() -> dict:
     config_file = MEMORY_DIR / "profiles.json"
     if config_file.exists():
         try:
-            with open(config_file, 'r') as f:
+            with open(config_file, "r") as f:
                 data = json.load(f)
             # Handle ProfileManager array format → convert to dict format
-            if isinstance(data.get('profiles'), list):
+            if isinstance(data.get("profiles"), list):
                 converted = {}
-                for p in data['profiles']:
-                    n = p.get('name', '')
+                for p in data["profiles"]:
+                    n = p.get("name", "")
                     if n:
                         converted[n] = p
-                data['profiles'] = converted
-                if 'active' in data and 'active_profile' not in data:
-                    data['active_profile'] = data.pop('active')
+                data["profiles"] = converted
+                if "active" in data and "active_profile" not in data:
+                    data["active_profile"] = data.pop("active")
             return data
         except (json.JSONDecodeError, IOError):
             pass
     return {
-        'profiles': {'default': {'name': 'default', 'description': 'Default memory profile'}},
-        'active_profile': 'default',
+        "profiles": {"default": {"name": "default", "description": "Default memory profile"}},
+        "active_profile": "default",
     }
 
 
@@ -445,7 +459,7 @@ def _save_profiles_json(config: dict) -> None:
     """Save profiles.json config."""
     MEMORY_DIR.mkdir(parents=True, exist_ok=True)
     config_file = MEMORY_DIR / "profiles.json"
-    with open(config_file, 'w') as f:
+    with open(config_file, "w") as f:
         json.dump(config, f, indent=2)
 
 
@@ -453,8 +467,10 @@ def _save_profiles_json(config: dict) -> None:
 # Pydantic Models (shared across routes)
 # ============================================================================
 
+
 class SearchRequest(BaseModel):
     """Advanced search request model."""
+
     query: str = Field(..., min_length=1, max_length=1000)
     limit: int = Field(default=10, ge=1, le=100)
     min_score: float = Field(default=0.3, ge=0.0, le=1.0)
@@ -471,11 +487,13 @@ class SearchRequest(BaseModel):
 
 class ProfileSwitch(BaseModel):
     """Profile switching request."""
+
     profile_name: str = Field(..., min_length=1, max_length=50)
 
 
 class BackupConfigRequest(BaseModel):
     """Backup configuration update request."""
+
     interval_hours: Optional[int] = Field(None, ge=1, le=8760)
     max_backups: Optional[int] = Field(None, ge=1, le=100)
     enabled: Optional[bool] = None

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

@@ -271,24 +271,102 @@ async def set_full_config(request: Request):
     require_manage(request)
     try:
         body = await request.json()
-        new_mode = body.get("mode", "a").lower()
-        provider = body.get("provider", "none")
-        model = body.get("model", "")
-        api_key = body.get("api_key", "")
-
-        if new_mode not in ("a", "b", "c"):
-            return JSONResponse({"error": "Invalid mode"}, status_code=400)
-
+        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.storage.models import Mode
         from superlocalmemory.server.routes.helpers import log_mode_change
+
         config = SLMConfig.load()
         old_mode = config.mode.value
 
-        # v3.6.12 (settings-2): honor a custom endpoint for ANY provider.
-        _endpoint = (body.get("base_url", "") or body.get("endpoint", "")).strip()
-        if not _endpoint and provider == "ollama":
+        def _nonblank(name: str) -> str | None:
+            value = body.get(name)
+            if value is None:
+                return None
+            if not isinstance(value, str):
+                raise ValueError(f"{name} must be a string")
+            return value.strip() or None
+
+        new_mode = (_nonblank("mode") or config.mode.value).lower()
+        provider_input = _nonblank("provider")
+        model_input = _nonblank("model")
+        api_key_input = _nonblank("api_key")
+        base_url_input = _nonblank("base_url")
+        endpoint_input = _nonblank("endpoint")
+        clear_api_key = body.get("clear_api_key") is True
+        clear_base_url = body.get("clear_base_url") is True
+
+        if clear_api_key and api_key_input:
+            return JSONResponse(
+                {"error": "api_key cannot be replaced and cleared together"},
+                status_code=400,
+            )
+        if clear_base_url and (base_url_input or endpoint_input):
+            return JSONResponse(
+                {"error": "base_url cannot be replaced and cleared together"},
+                status_code=400,
+            )
+        if base_url_input and endpoint_input and base_url_input != endpoint_input:
+            return JSONResponse(
+                {"error": "base_url and endpoint must match when both are supplied"},
+                status_code=400,
+            )
+
+        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 "")
+        if (
+            not _endpoint 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
@@ -351,6 +429,8 @@ async def set_full_config(request: Request):
             "embedding_model": config.embedding.model_name,
             "embedding_dimension": config.embedding.dimension,
         }
+    except ValueError as exc:
+        return JSONResponse({"error": str(exc)}, status_code=400)
     except Exception as e:
         return _internal_error()
 
@@ -830,6 +910,17 @@ async def recall_trace(request: Request):
         limit = body.get("limit", 10)
         window = body.get("window", "") or ""
         as_of_raw = (body.get("as_of", "") or "").strip()
+        raw_known_as_of = body.get("known_as_of", "")
+        raw_valid_at = body.get("valid_at", "")
+        if raw_known_as_of is not None and not isinstance(raw_known_as_of, str):
+            return JSONResponse({"error": "invalid_known_as_of"}, status_code=400)
+        if raw_valid_at is not None and not isinstance(raw_valid_at, str):
+            return JSONResponse({"error": "invalid_valid_at"}, status_code=400)
+        known_as_of_raw = (raw_known_as_of or "").strip()
+        valid_at_raw = (raw_valid_at or "").strip()
+        include_unknown = body.get("include_unknown", False)
+        if not isinstance(include_unknown, bool):
+            return JSONResponse({"error": "invalid_include_unknown"}, status_code=400)
 
         # Normalize as_of at HTTP boundary. Invalid → 400.
         _as_of: str | None = None
@@ -840,6 +931,20 @@ async def recall_trace(request: Request):
                 return JSONResponse(
                     {"error": "invalid_as_of", "raw": as_of_raw}, status_code=400
                 )
+        def _normalize_named_time(raw: str, error: str) -> str | None | JSONResponse:
+            if not raw:
+                return None
+            from superlocalmemory.retrieval.temporal_utils import normalize_as_of
+            normalized = normalize_as_of(raw)
+            if normalized is None:
+                return JSONResponse({"error": error, "raw": raw}, status_code=400)
+            return normalized
+        _known_as_of = _normalize_named_time(known_as_of_raw, "invalid_known_as_of")
+        if isinstance(_known_as_of, JSONResponse):
+            return _known_as_of
+        _valid_at = _normalize_named_time(valid_at_raw, "invalid_valid_at")
+        if isinstance(_valid_at, JSONResponse):
+            return _valid_at
 
         # Use daemon engine — already loaded, shares warm page cache.
         # run_in_executor keeps event loop alive so browser doesn't abort.
@@ -855,6 +960,8 @@ async def recall_trace(request: Request):
             lambda: engine.recall(
                 query, limit=limit, fast=False,
                 window=window or None, as_of=_as_of,
+                known_as_of=_known_as_of, valid_at=_valid_at,
+                include_unknown=include_unknown,
             ),
         )
         elapsed_ms = round((_time.monotonic() - t0) * 1000, 1)