superlocalmemory 3.4.19 → 3.4.22

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

@@ -11,7 +11,7 @@ import gzip
 import json
 import logging
 from typing import Optional
-from datetime import datetime
+from datetime import datetime, timezone
 
 from fastapi import APIRouter, HTTPException, Query, Request, UploadFile, File
 from fastapi.responses import StreamingResponse
@@ -79,14 +79,14 @@ async def export_memories(
         else:
             content = json.dumps({
                 "version": "3.0.0",
-                "exported_at": datetime.now().isoformat(),
+                "exported_at": datetime.now(timezone.utc).isoformat(),
                 "total_memories": len(memories),
                 "filters": {"category": category, "project_name": project_name},
                 "memories": memories,
             }, indent=2)
             media_type = "application/json"
 
-        ts = datetime.now().strftime('%Y%m%d_%H%M%S')
+        ts = datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')
         if len(content) > 10000:
             compressed = gzip.compress(content.encode())
             return StreamingResponse(
@@ -167,7 +167,7 @@ async def import_memories(request: Request, file: UploadFile = File(...)):
                 if ws_manager:
                     await ws_manager.broadcast({
                         "type": "memory_added", "memory_id": imported,
-                        "timestamp": datetime.now().isoformat(),
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
                     })
 
             except Exception as e:

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

@@ -12,7 +12,7 @@ import threading
 import queue as _queue
 import logging
 from typing import Optional, Set
-from datetime import datetime
+from datetime import datetime, timezone
 
 from fastapi import APIRouter, HTTPException, Query
 from fastapi.responses import StreamingResponse
@@ -136,7 +136,7 @@ async def event_stream(
 
                 # 3. Keepalive + sleep
                 if not drained:
-                    yield f": keepalive {datetime.now().isoformat()}\n\n"
+                    yield f": keepalive {datetime.now(timezone.utc).isoformat()}\n\n"
                 await asyncio.sleep(1)
         finally:
             with _sse_queues_lock:

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

@@ -257,7 +257,7 @@ def ensure_profile_in_json(name: str, description: str = "") -> None:
         profiles[name] = {
             'name': name,
             'description': description or f'Memory profile: {name}',
-            'created_at': datetime.now().isoformat(),
+            'created_at': datetime.now(timezone.utc).isoformat(),
             'last_used': None,
         }
         config['profiles'] = profiles

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

@@ -11,7 +11,7 @@ Uses V3 learning modules: FeedbackCollector, EngagementTracker, AdaptiveLearner.
 """
 import shutil
 import logging
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 
 from fastapi import APIRouter
@@ -23,6 +23,84 @@ router = APIRouter()
 
 LEARNING_DB = MEMORY_DIR / "learning.db"
 
+
+# ---------------------------------------------------------------------------
+# LLD-02 §4.10 — Dashboard phase truth
+# ---------------------------------------------------------------------------
+
+
+def _compute_ranker_phase(
+    profile_id: str,
+    *,
+    learning_db_path: Path | None = None,
+) -> dict:
+    """Return {phase, label, model_active, signals} — LLD-02 §4.10.
+
+    Phase 3 requires BOTH an active (is_active=1) row AND a successful
+    SHA-256 verification on the model_cache load. Tampered bytes fall
+    back to phase 2.
+    """
+    from superlocalmemory.learning.database import LearningDatabase
+    from superlocalmemory.learning.model_cache import load_active, invalidate
+
+    db_path = Path(learning_db_path) if learning_db_path else LEARNING_DB
+    if not db_path.exists():
+        return {
+            "phase": 1,
+            "label": "Cold start (cross-encoder only)",
+            "model_active": False,
+            "signals": 0,
+        }
+
+    db = LearningDatabase(db_path)
+    try:
+        signals = db.count_signals(profile_id)
+    except Exception as exc:
+        logger.warning("count_signals failed: %s", exc)
+        signals = 0
+
+    # Force a cache-bypass load — the dashboard read is rare and we want
+    # tamper detection to surface immediately.
+    invalidate(profile_id)
+    try:
+        model = load_active(db, profile_id, use_cache=False)
+    except Exception as exc:
+        logger.warning("load_active failed: %s", exc)
+        model = None
+
+    active = model is not None
+
+    if active and signals >= 200:
+        return {
+            "phase": 3,
+            "label": "LightGBM ranker active",
+            "model_active": True,
+            "signals": signals,
+        }
+    if signals >= 50:
+        return {
+            "phase": 2,
+            "label": "Contextual bandit",
+            "model_active": False,
+            "signals": signals,
+        }
+    return {
+        "phase": 1,
+        "label": "Cold start (cross-encoder only)",
+        "model_active": False,
+        "signals": signals,
+    }
+
+
+@router.get("/api/learning/ranker_phase")
+async def ranker_phase():
+    """Dashboard endpoint — LLD-02 §4.10 phase truth."""
+    try:
+        profile = get_active_profile()
+    except Exception:
+        profile = "default"
+    return _compute_ranker_phase(profile)
+
 # Feature detection
 LEARNING_AVAILABLE = False
 BEHAVIORAL_AVAILABLE = False
@@ -341,6 +419,42 @@ async def feedback_stats():
 # PATTERNS ENDPOINT (v3.4.1 — CRITICAL FIX: frontend calls /api/patterns)
 # ============================================================================
 
+
+@router.delete("/api/patterns/delete")
+async def delete_pattern(data: dict) -> dict:
+    """S9-DASH-04: delete a single auto-detected pattern by key.
+
+    Body: ``{pattern_type: str, pattern_key: str}``
+
+    Returns ``{success: bool, deleted: int}``. The pattern is scoped
+    to the active profile so cross-profile deletion is impossible.
+    """
+    if not BEHAVIORAL_AVAILABLE:
+        return {"success": False, "error": "Behavioral engine not available"}
+    ptype = (data or {}).get("pattern_type", "")
+    pkey = (data or {}).get("pattern_key", "")
+    if not ptype or not pkey:
+        return {
+            "success": False,
+            "error": "pattern_type and pattern_key are required",
+        }
+    try:
+        profile = get_active_profile()
+        store = BehavioralPatternStore(str(LEARNING_DB))
+        deleted = store.delete_pattern_by_key(
+            profile_id=profile,
+            pattern_type=ptype,
+            pattern_key=pkey,
+        )
+        return {
+            "success": True, "deleted": int(deleted),
+            "active_profile": profile,
+        }
+    except Exception as exc:  # noqa: BLE001
+        logger.error("delete_pattern failed: %s", exc)
+        return {"success": False, "error": str(exc)}
+
+
 @router.get("/api/patterns")
 async def get_patterns():
     """Get learned behavioral patterns for the Patterns dashboard tab.
@@ -434,7 +548,7 @@ async def learning_backup():
         if not LEARNING_DB.exists():
             return {"success": False, "error": "No learning.db found"}
 
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
         backup_name = f"learning.db.backup_{timestamp}"
         backup_path = MEMORY_DIR / backup_name
         shutil.copy2(str(LEARNING_DB), str(backup_path))
@@ -451,15 +565,86 @@ async def learning_backup():
 
 @router.post("/api/learning/reset")
 async def learning_reset():
-    """Reset all learning data. Memories preserved."""
+    """Reset all learning data for the active profile. Memories preserved."""
     if not LEARNING_AVAILABLE:
         return {"success": False, "error": "Learning system not available"}
-    return {"status": "not_implemented", "message": "Coming soon"}
+    try:
+        from superlocalmemory.learning.database import LearningDatabase
+        db = LearningDatabase(LEARNING_DB)
+        profile_id = get_active_profile() or "default"
+        db.reset(profile_id=profile_id)
+        return {
+            "success": True,
+            "message": "Learning data reset. Memories preserved.",
+            "profile_id": profile_id,
+        }
+    except Exception as exc:  # noqa: BLE001
+        logger.error("learning_reset failed: %s", exc)
+        return {"success": False, "error": str(exc)}
 
 
 @router.post("/api/learning/retrain")
-async def learning_retrain():
-    """Force retrain the ranking model."""
+async def learning_retrain(data: dict | None = None):
+    """Force a retrain of the LightGBM ranker.
+
+    Body (optional, JSON):
+        ``{"include_synthetic": bool}`` — when True, migrated legacy rows
+        (``is_synthetic=1``) participate in training. Default False.
+    """
     if not LEARNING_AVAILABLE:
         return {"success": False, "error": "Learning system not available"}
-    return {"status": "not_implemented", "message": "Coming soon"}
+    include_synthetic = bool(
+        data and data.get("include_synthetic")
+    ) if isinstance(data, dict) else False
+    try:
+        from superlocalmemory.learning.consolidation_worker import (
+            _retrain_ranker_impl,
+        )
+        profile_id = get_active_profile() or "default"
+        trained = _retrain_ranker_impl(
+            LEARNING_DB,
+            profile_id,
+            include_synthetic=include_synthetic,
+        )
+        if trained:
+            return {
+                "success": True,
+                "trained": True,
+                "profile_id": profile_id,
+                "include_synthetic": include_synthetic,
+            }
+        return {
+            "success": True,
+            "trained": False,
+            "profile_id": profile_id,
+            "include_synthetic": include_synthetic,
+            "message": (
+                "Not enough training rows yet. Keep using SLM, or run "
+                "legacy migration + retry with include_synthetic=true."
+            ),
+        }
+    except Exception as exc:  # noqa: BLE001
+        logger.error("learning_retrain failed: %s", exc)
+        return {"success": False, "error": str(exc)}
+
+
+@router.post("/api/learning/migrate-legacy")
+async def learning_migrate_legacy():
+    """Copy ``learning_feedback`` rows into LLD-02 tables for training.
+
+    Idempotent: subsequent calls detect the migration_log sentinel and
+    return ``already_done=True`` without re-copying. The rows are written
+    with ``is_synthetic=1`` to preserve provenance; the trainer must be
+    invoked with ``include_synthetic=True`` to use them.
+    """
+    if not LEARNING_AVAILABLE:
+        return {"success": False, "error": "Learning system not available"}
+    try:
+        from superlocalmemory.learning.legacy_migration import (
+            migrate_legacy_feedback,
+        )
+        stats = migrate_legacy_feedback(LEARNING_DB)
+        return {"success": True, **stats}
+    except Exception as exc:  # noqa: BLE001
+        logger.error("learning_migrate_legacy failed: %s", exc)
+        return {"success": False, "error": str(exc)}

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

@@ -211,8 +211,22 @@ async def get_memories(
     tags: Optional[str] = None,
     limit: int = Query(50, ge=1, le=200),
     offset: int = Query(0, ge=0),
+    filter: Optional[str] = Query(
+        None,
+        description="Named filter: 'high_reward' | 'being_forgotten'",
+    ),
 ):
-    """List memories with optional filtering and pagination."""
+    """List memories with optional filtering and pagination.
+
+    S9-DASH-07: ``filter`` enables dashboard "learning-visible" views:
+
+    * ``high_reward``: facts cited by ``action_outcomes`` with
+      ``reward >= 0.7`` in the last 30 days. Surfaces what the ranker
+      is actually learning from.
+    * ``being_forgotten``: facts in ``archive_status='archived'`` OR
+      with ``lifecycle='cold'`` AND no positive reward in 60 days.
+      Makes "memory decay" tangible to the operator.
+    """
     try:
         conn = get_db_connection()
         conn.row_factory = dict_factory
@@ -277,6 +291,56 @@ async def get_memories(
                 query += " AND tags LIKE ?"
                 params.append(f'%{tag}%')
 
+        # S9-DASH-07: named filters — "high_reward" and "being_forgotten".
+        # Only supported on the v3 (atomic_facts) path — v2 fallback
+        # ignores the flag silently.
+        if filter and use_v3:
+            if filter == "high_reward":
+                query += (
+                    " AND fact_id IN ("
+                    "  SELECT DISTINCT json_each.value"
+                    "  FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
+                    "  WHERE action_outcomes.reward >= 0.7"
+                    "    AND datetime(action_outcomes.settled_at) >= "
+                    "        datetime('now', '-30 day')"
+                    ")"
+                )
+                count_base += (
+                    " AND fact_id IN ("
+                    "  SELECT DISTINCT json_each.value"
+                    "  FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
+                    "  WHERE action_outcomes.reward >= 0.7"
+                    "    AND datetime(action_outcomes.settled_at) >= "
+                    "        datetime('now', '-30 day')"
+                    ")"
+                )
+            elif filter == "being_forgotten":
+                # Cold / archived + no recent positive reward.
+                query += (
+                    " AND ("
+                    "  archive_status = 'archived' OR "
+                    "  (lifecycle = 'cold' AND fact_id NOT IN ("
+                    "    SELECT DISTINCT json_each.value"
+                    "    FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
+                    "    WHERE action_outcomes.reward >= 0.5"
+                    "      AND datetime(action_outcomes.settled_at) >= "
+                    "          datetime('now', '-60 day')"
+                    "  ))"
+                    ")"
+                )
+                count_base += (
+                    " AND ("
+                    "  archive_status = 'archived' OR "
+                    "  (lifecycle = 'cold' AND fact_id NOT IN ("
+                    "    SELECT DISTINCT json_each.value"
+                    "    FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
+                    "    WHERE action_outcomes.reward >= 0.5"
+                    "      AND datetime(action_outcomes.settled_at) >= "
+                    "          datetime('now', '-60 day')"
+                    "  ))"
+                    ")"
+                )
+
         query += " ORDER BY created_at DESC LIMIT ? OFFSET ?"
         params.extend([limit, offset])
 
@@ -569,6 +633,130 @@ async def delete_memory(request: Request, fact_id: str):
         raise HTTPException(status_code=500, detail=f"Delete error: {str(e)}")
 
 
+@router.post("/api/memories/{fact_id}/forget")
+async def forget_memory(request: Request, fact_id: str):
+    """S9-DASH-08: soft-forget a fact — flip archive_status='archived'.
+
+    Non-destructive: the row stays in ``atomic_facts`` for audit and
+    can be un-archived later. Default recall paths filter it out.
+    The fact's payload is ALSO copied into ``memory_archive`` so a
+    future ``slm restore`` can bring it back.
+    """
+    import json as _json
+    try:
+        conn = get_db_connection()
+        conn.row_factory = dict_factory
+        cursor = conn.cursor()
+        active_profile = get_active_profile()
+        cursor.execute(
+            "SELECT fact_id, content, importance, confidence, "
+            "       canonical_entities_json, embedding, created_at "
+            "FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
+            (fact_id, active_profile),
+        )
+        row = cursor.fetchone()
+        if not row:
+            conn.close()
+            raise HTTPException(status_code=404, detail="Memory not found")
+        # Archive copy — payload_json small enough for the canonical row.
+        payload = {
+            "fact_id": row["fact_id"],
+            "content": row["content"],
+            "canonical_entities_json": row.get("canonical_entities_json"),
+            "importance": row.get("importance"),
+            "confidence": row.get("confidence"),
+            "created_at": row.get("created_at"),
+        }
+        from datetime import datetime, timezone
+        archived_at = datetime.now(timezone.utc).isoformat()
+        import uuid as _uuid
+        cursor.execute(
+            "INSERT INTO memory_archive "
+            "(archive_id, fact_id, profile_id, payload_json, archived_at, reason) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (str(_uuid.uuid4()), fact_id, active_profile,
+             _json.dumps(payload), archived_at, "user_forget_dashboard"),
+        )
+        cursor.execute(
+            "UPDATE atomic_facts SET archive_status = 'archived' "
+            "WHERE fact_id = ?",
+            (fact_id,),
+        )
+        conn.commit()
+        conn.close()
+        return {"success": True, "fact_id": fact_id, "archived_at": archived_at}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Forget error: {str(e)}")
+
+
+@router.post("/api/memories/{fact_id}/merge")
+async def merge_memory(request: Request, fact_id: str):
+    """S9-DASH-08: merge this fact into another (keep the other).
+
+    Body: ``{into: <kept_fact_id>}``.
+
+    Writes a ``memory_merge_log`` row (M011) for provenance and marks
+    the loser's ``merged_into`` column. The loser is archived so it
+    no longer appears in default recall. The winner is untouched.
+    """
+    try:
+        body = await request.json()
+        kept = str((body or {}).get("into", "")).strip()
+        if not kept:
+            raise HTTPException(400, "Body field 'into' is required")
+        # S9-AUDIT: cap length defensively — fact_ids are UUID-v4 36 chars.
+        if len(kept) > 200:
+            raise HTTPException(400, "'into' exceeds 200-char limit")
+        if kept == fact_id:
+            raise HTTPException(400, "Cannot merge a fact into itself")
+        conn = get_db_connection()
+        conn.row_factory = dict_factory
+        cursor = conn.cursor()
+        active_profile = get_active_profile()
+        # Both must belong to the active profile.
+        cursor.execute(
+            "SELECT fact_id FROM atomic_facts "
+            "WHERE fact_id IN (?, ?) AND profile_id = ?",
+            (fact_id, kept, active_profile),
+        )
+        found = {r["fact_id"] for r in cursor.fetchall()}
+        if fact_id not in found or kept not in found:
+            conn.close()
+            raise HTTPException(
+                404,
+                "Both fact_ids must exist in the active profile",
+            )
+        from datetime import datetime, timezone
+        merged_at = datetime.now(timezone.utc).isoformat()
+        cursor.execute(
+            "INSERT INTO memory_merge_log "
+            "(kept_fact_id, merged_fact_id, profile_id, reason, merged_at) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (kept, fact_id, active_profile,
+             "user_merge_dashboard", merged_at),
+        )
+        cursor.execute(
+            "UPDATE atomic_facts "
+            "SET merged_into = ?, archive_status = 'archived' "
+            "WHERE fact_id = ?",
+            (kept, fact_id),
+        )
+        conn.commit()
+        conn.close()
+        return {
+            "success": True,
+            "merged": fact_id,
+            "into": kept,
+            "merged_at": merged_at,
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Merge error: {str(e)}")
+
+
 @router.patch("/api/memories/{fact_id}")
 async def edit_memory(request: Request, fact_id: str):
     """Edit the content of a specific memory (atomic fact)."""

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

@@ -0,0 +1,171 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.22 — LLD-01 §4.4 / §4.5
+
+"""POST /internal/prewarm — populates the context cache for a session.
+
+S8-SK-02 fix: Wave 2A shipped ``hooks/prewarm_auth.authorize`` (gates
+loopback → origin → install-token → body-size) and unit-tested it, but
+no FastAPI route mounted it. The hot-path ``post_tool_async_hook`` POSTs
+to ``/internal/prewarm`` after every tool call to refresh the
+``active_brain_cache`` row for the current session/topic. Without a
+route registered here, those POSTs 404'd silently, the cache never
+populated, and every ``UserPromptSubmit`` ended up a structural miss.
+
+Design notes
+------------
+* All 4 gates from LLD-01 §4.4 run before any engine work: loopback
+  peer, absence of browser ``Origin`` header, valid install-token, body
+  <= ``MAX_BODY_BYTES``. On any gate failure we return the decision's
+  status code with ``application/json`` error envelope and do not touch
+  the engine. This is LLD-07 SEC-HR-03 applied at the edge.
+* The route is async; the actual cache write (``ContextCache.upsert``)
+  is synchronous SQLite and runs on the default executor via
+  ``asyncio.to_thread`` so we never block the event loop.
+* Body schema is intentionally narrow: ``{"session_id": str,
+  "prompt": str, "content": str, "fact_ids": list[str]}``. Missing or
+  wrong-type fields produce 400.
+* Never raises past this function. Any unexpected exception is caught,
+  logged at ``debug`` to avoid log flooding under a hostile peer, and
+  returned as 500 JSON. The hot path ``post_tool_async_hook`` treats
+  any non-2xx as "fire-and-forget, try again later", so degradation is
+  graceful.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["internal"])
+
+
+_ALLOWED_BODY_KEYS = frozenset({"session_id", "prompt", "content", "fact_ids"})
+
+
+@router.post("/internal/prewarm")
+async def prewarm(request: Request) -> JSONResponse:
+    """Write (or refresh) a context-cache entry for the caller's session.
+
+    Gates (LLD-01 §4.4):
+      1. Loopback-only client (127.0.0.1 / ::1 / localhost).
+      2. Reject browser-originated calls (any ``Origin`` header).
+      3. Install-token present and constant-time-verified.
+      4. Body <= ``MAX_BODY_BYTES``.
+
+    On success, returns ``{"ok": true}``. On any failure, returns the
+    AuthDecision's status with a terse JSON body. Never exposes engine
+    error detail to the caller.
+    """
+    # Gates 1-3 first (cheap; reject hostile peers before reading body).
+    try:
+        from superlocalmemory.hooks.prewarm_auth import (
+            MAX_BODY_BYTES,
+            authorize,
+            check_body_size,
+        )
+    except Exception as exc:  # pragma: no cover — primitives always present
+        logger.debug("prewarm: auth primitives unimportable: %s", exc)
+        return JSONResponse({"error": "server_error"}, status_code=500)
+
+    client_host = request.client.host if request.client else ""
+    headers = {k.lower(): v for k, v in request.headers.items()}
+
+    decision = authorize(client_host=client_host, headers=headers)
+    if not decision.allowed:
+        return JSONResponse(
+            {"error": decision.reason}, status_code=decision.status,
+        )
+
+    # Gate 4 — read body with a hard size cap. FastAPI/Starlette has no
+    # cheap way to check the Content-Length up front in all servers, so
+    # we read at most MAX_BODY_BYTES+1 and reject if we got more.
+    try:
+        body_bytes = await request.body()
+    except Exception as exc:  # pragma: no cover
+        logger.debug("prewarm: body read failed: %s", exc)
+        return JSONResponse({"error": "bad_body"}, status_code=400)
+    ok, reason = check_body_size(body_bytes)
+    if not ok:
+        return JSONResponse({"error": reason}, status_code=413)
+
+    try:
+        import json as _json
+        payload = _json.loads(body_bytes or b"{}")
+    except Exception:
+        return JSONResponse({"error": "invalid_json"}, status_code=400)
+
+    if not isinstance(payload, dict):
+        return JSONResponse({"error": "invalid_json"}, status_code=400)
+
+    # Narrow contract: reject unknown keys to keep the surface small.
+    # S10-SEC-N-02: fixed error tag, never echo attacker-supplied keys.
+    unknown = set(payload.keys()) - _ALLOWED_BODY_KEYS
+    if unknown:
+        return JSONResponse(
+            {"error": "unknown_keys"}, status_code=400,
+        )
+
+    session_id = payload.get("session_id")
+    prompt = payload.get("prompt")
+    content = payload.get("content")
+    fact_ids = payload.get("fact_ids") or []
+    if not isinstance(session_id, str) or not session_id:
+        return JSONResponse({"error": "session_id_required"}, status_code=400)
+    if not isinstance(prompt, str) or not prompt:
+        return JSONResponse({"error": "prompt_required"}, status_code=400)
+    if not isinstance(content, str) or not content:
+        return JSONResponse({"error": "content_required"}, status_code=400)
+    if not isinstance(fact_ids, list) or not all(
+        isinstance(f, str) for f in fact_ids
+    ):
+        return JSONResponse({"error": "fact_ids_list"}, status_code=400)
+
+    try:
+        topic_sig = await asyncio.to_thread(_compute_topic_sig, prompt)
+        await asyncio.to_thread(
+            _upsert_cache,
+            session_id=session_id,
+            topic_sig=topic_sig,
+            content=content,
+            fact_ids=fact_ids,
+        )
+    except Exception as exc:  # pragma: no cover — defensive
+        logger.debug("prewarm: upsert failed: %s", exc)
+        return JSONResponse({"error": "upsert_failed"}, status_code=500)
+
+    return JSONResponse({"ok": True})
+
+
+def _compute_topic_sig(prompt: str) -> str:
+    """Lazy import so module import is free of hot-path SLM modules."""
+    from superlocalmemory.core.topic_signature import compute_topic_signature
+    return compute_topic_signature(prompt)
+
+
+def _upsert_cache(
+    *, session_id: str, topic_sig: str,
+    content: str, fact_ids: list[str],
+) -> None:
+    from superlocalmemory.core.context_cache import CacheEntry, ContextCache
+    cache = ContextCache()
+    try:
+        cache.upsert(CacheEntry(
+            session_id=session_id,
+            topic_sig=topic_sig,
+            content=content,
+            fact_ids=tuple(fact_ids),
+            provenance="prewarm_post_tool",
+            computed_at=int(time.time()),
+        ))
+    finally:
+        cache.close()
+
+
+__all__ = ("router",)