superlocalmemory 3.7.8 → 3.8.1

package/src/superlocalmemory/server/recall_health.py

@@ -124,15 +124,36 @@ def run_health_tick(engine, state: RecallHealth, *, probe: str = DEFAULT_PROBE,
 
     Mutates and returns ``state``. Never raises — a timed-out / failing recall
     marks the path unhealthy instead of propagating.
+
+    Uses ``operation_nowait()`` when a runtime is supplied so that a pending
+    profile switch is not blocked by the health-probe recall.  If a transition
+    is in progress the tick is skipped entirely — the next scheduled tick will
+    re-warm once the switch has committed.
     """
     state.checks += 1
 
     # Tier 1: re-warm. A real full-fusion recall keeps the graph page cache hot
     # and the embedder resident.
+    # Cooperative preemption: use operation_nowait() so a pending profile switch
+    # is not held hostage by a slow full-fusion recall (2–10s with fast=False).
     try:
-        lease = runtime.operation() if runtime is not None else nullcontext()
-        with lease:
-            resp = engine.recall(probe, limit=3, fast=False)
+        if runtime is not None:
+            lease = runtime.operation_nowait()
+        else:
+            lease = nullcontext()
+        with lease as _snap:
+            if runtime is not None and _snap is None:
+                # A profile transition is in progress — skip this tick so we
+                # do not hold the drain window.  Health state is unchanged;
+                # the next tick fires after the switch commits.
+                log.debug(
+                    "recall-health: tick skipped — profile transition in progress"
+                )
+                return state
+            # fast=True: a health probe must release its operation lease well
+            # within the 5s profile-switch drain window (fast=False is 2-10s and
+            # would make every profile switch time out while a tick is in flight).
+            resp = engine.recall(probe, limit=3, fast=True)
     except Exception as exc:
         state.healthy = False
         state.consecutive_failures += 1

package/src/superlocalmemory/server/recall_serializer.py

@@ -24,6 +24,7 @@ import re
 from typing import Any
 
 from superlocalmemory.core.config import CANONICAL_RECALL_LIMIT
+from superlocalmemory.retrieval.temporal_frame import relative_age, temporal_frame
 
 
 # ---------------------------------------------------------------------------
@@ -190,9 +191,13 @@ def serialize_recall_response(
         is the evidence-floor signal lifted from the response (additive).
     """
     memory_map = memory_map or {}
+    # T-inject: one shared "now" so every result's age label is consistent.
+    from datetime import datetime as _dt, timezone as _tz
+    _now = _dt.now(_tz.utc)
     raw: list[dict] = []
     for r in (response.results or [])[:limit]:
         fact = r.fact
+        _created = getattr(fact, "created_at", "") or ""
         fact_type = getattr(fact, "fact_type", None)
         lifecycle = getattr(fact, "lifecycle", None)
         raw.append({
@@ -225,7 +230,10 @@ def serialize_recall_response(
                 if lifecycle is not None and hasattr(lifecycle, "value")
                 else (lifecycle or ""),
             "access_count": getattr(fact, "access_count", 0),
-            "created_at": getattr(fact, "created_at", "") or "",
+            "created_at": _created,
+            # T-inject: human-relative age so consumers (and the LLM) can
+            # weigh recency without doing date math. "" when undated.
+            "age_label": relative_age(_created, _now),
             "evidence_chain": list(getattr(r, "evidence_chain", []) or []),
         })
 
@@ -241,6 +249,12 @@ def serialize_recall_response(
 
 def recall_response_metadata(response: Any) -> dict:
     """Return Score Contract v2 response metadata for transport envelopes."""
+    # T-inject: a one-line temporal frame anchoring the result set to "now"
+    # and its age span, so time-blind LLMs get an explicit recency signal.
+    _timestamps = [
+        getattr(getattr(r, "fact", None), "created_at", "") or ""
+        for r in (getattr(response, "results", None) or [])
+    ]
     return {
         "score_contract_version": getattr(response, "score_contract_version", "2"),
         "calibration_status": getattr(response, "calibration_status", "uncalibrated"),
@@ -248,4 +262,8 @@ def recall_response_metadata(response: Any) -> dict:
         "answer_confidence": getattr(response, "answer_confidence", None),
         "abstained": bool(getattr(response, "abstained", False)),
         "abstention_reason": getattr(response, "abstention_reason", None),
+        "temporal_frame": temporal_frame(_timestamps),
+        # Q2b: thematic community summary (pure pass-through; computed upstream
+        # in the engine where DB access is available). None on most recalls.
+        "thematic_context": getattr(response, "community_context", None),
     }

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

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later — see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com
+
+"""Progressive-abstraction read API (Wave Q3).
+
+Exposes the abstraction hierarchy so the dashboard can browse it and drill
+down to source atoms:
+
+  GET /api/v3/abstraction/persona      — the per-profile persona roll-up
+  GET /api/v3/abstraction/communities  — community summaries (Q2)
+  GET /api/v3/abstraction/sources      — drill-down (node -> source atoms)
+
+Read-only, profile-scoped (Rule 01), direct sqlite3 (Rule 06). All handlers
+fail-soft: a missing DB or table returns an empty payload, never a 500.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import Any
+
+from fastapi import APIRouter, Query
+from fastapi.responses import JSONResponse
+
+from superlocalmemory.server.routes.helpers import DB_PATH, get_active_profile
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v3/abstraction", tags=["abstraction"])
+
+
+class _ReadDB:
+    """Adapt a raw sqlite3 connection to the .execute(...) -> list contract
+    the read-only builder methods expect (matches DatabaseManager.execute)."""
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def execute(self, sql: str, params: tuple = ()) -> list:
+        return self._conn.execute(sql, params).fetchall()
+
+
+def _conn() -> sqlite3.Connection | None:
+    if not DB_PATH.exists():
+        return None
+    conn = sqlite3.connect(str(DB_PATH))
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+@router.get("/persona")
+def get_persona(profile: str = Query("")) -> JSONResponse:
+    pid = profile or get_active_profile()
+    conn = _conn()
+    if conn is None:
+        return JSONResponse({"profile": pid, "persona": None})
+    try:
+        from superlocalmemory.core.progressive_abstraction import ProgressiveAbstraction
+
+        persona = ProgressiveAbstraction(_ReadDB(conn)).get_persona(pid)
+        return JSONResponse({"profile": pid, "persona": persona})
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("persona read failed: %s", exc)
+        return JSONResponse({"profile": pid, "persona": None})
+    finally:
+        conn.close()
+
+
+@router.get("/communities")
+def get_communities(profile: str = Query("")) -> JSONResponse:
+    pid = profile or get_active_profile()
+    conn = _conn()
+    if conn is None:
+        return JSONResponse({"profile": pid, "communities": []})
+    try:
+        from superlocalmemory.core.community_summary import CommunitySummaryBuilder
+
+        summaries = CommunitySummaryBuilder(_ReadDB(conn)).get_summaries(pid)
+        return JSONResponse({"profile": pid, "communities": summaries})
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("communities read failed: %s", exc)
+        return JSONResponse({"profile": pid, "communities": []})
+    finally:
+        conn.close()
+
+
+@router.get("/sources")
+def get_sources(
+    profile: str = Query(""), node: str = Query("persona"),
+) -> JSONResponse:
+    pid = profile or get_active_profile()
+    conn = _conn()
+    empty: dict[str, Any] = {
+        "node_id": node, "node_type": "unknown", "communities": [], "fact_ids": [],
+    }
+    if conn is None:
+        return JSONResponse({"profile": pid, "sources": empty})
+    try:
+        from superlocalmemory.core.progressive_abstraction import ProgressiveAbstraction
+
+        node_val: Any = node
+        if node != "persona":
+            try:
+                node_val = int(node)
+            except (ValueError, TypeError):
+                node_val = node
+        sources = ProgressiveAbstraction(_ReadDB(conn)).get_sources(pid, node_val)
+        return JSONResponse({"profile": pid, "sources": sources})
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("sources read failed: %s", exc)
+        return JSONResponse({"profile": pid, "sources": empty})
+    finally:
+        conn.close()

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

@@ -19,6 +19,12 @@ from .helpers import DB_PATH
 logger = logging.getLogger("superlocalmemory.routes.agents")
 router = APIRouter()
 
+
+def _internal_error(detail: str = "Internal server error") -> HTTPException:
+    """SEC-H-02: log full traceback server-side; return a generic message to the client."""
+    logger.exception("agents route error")
+    return HTTPException(status_code=500, detail=detail)
+
 # Feature flag: V3 trust scorer
 TRUST_AVAILABLE = False
 try:
@@ -56,8 +62,8 @@ async def get_agents(
             "count": len(agents),
             "stats": {"total_agents": len(agents)},
         }
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Agent registry error: {str(e)}")
+    except Exception:
+        raise _internal_error("Agent registry error")
 
 
 @router.get("/api/agents/stats")
@@ -69,8 +75,91 @@ async def get_agent_stats(request: Request):
         registry = AgentRegistry(persist_path=_registry_path())
         agents = registry.list_agents()
         return {"total_agents": len(agents)}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Agent stats error: {str(e)}")
+    except Exception:
+        raise _internal_error("Agent stats error")
+
+
+@router.get("/api/agents/memory-activity")
+async def get_agent_memory_activity(
+    request: Request,
+    limit: int = Query(20, ge=1, le=100),
+):
+    """Per-agent memory attribution for the multi-agent memory view.
+
+    Reports how many memories each writing agent contributed, when each was
+    last active, which ingestion sources they used, and the most recent
+    entries — grouped by ``ingestion_operations.trusted_actor_id`` (the agent
+    that wrote the memory). Profile-scoped. Uses a direct DB read because the
+    dashboard runs without the engine subprocess. Never raises to the client;
+    returns empty structures if the operations table is absent.
+    """
+    import sqlite3
+
+    from .helpers import get_active_profile
+
+    pid = get_active_profile()
+    agents: list[dict] = []
+    recent: list[dict] = []
+    total = 0
+
+    if DB_PATH.exists():
+        conn = sqlite3.connect(str(DB_PATH))
+        conn.row_factory = sqlite3.Row
+        try:
+            try:
+                rows = conn.execute(
+                    "SELECT CASE WHEN trusted_actor_id='' THEN 'unknown' "
+                    "ELSE trusted_actor_id END AS agent_id, "
+                    "COUNT(*) AS cnt, MAX(created_at) AS last_active, "
+                    "GROUP_CONCAT(DISTINCT source_type) AS sources "
+                    "FROM ingestion_operations WHERE profile_id=? "
+                    "GROUP BY agent_id ORDER BY cnt DESC, agent_id ASC "
+                    "LIMIT 500",
+                    (pid,),
+                ).fetchall()
+                for r in rows:
+                    agents.append({
+                        "agent_id": r["agent_id"],
+                        "count": r["cnt"],
+                        "last_active": r["last_active"],
+                        "source_types": (
+                            [s for s in (r["sources"] or "").split(",") if s]
+                        ),
+                    })
+                    total += r["cnt"]
+            except sqlite3.OperationalError:
+                pass
+
+            try:
+                rows = conn.execute(
+                    "SELECT CASE WHEN trusted_actor_id='' THEN 'unknown' "
+                    "ELSE trusted_actor_id END AS agent_id, "
+                    "substr(raw_content, 1, 160) AS snippet, "
+                    "created_at, source_type, session_id "
+                    "FROM ingestion_operations WHERE profile_id=? "
+                    "ORDER BY created_at DESC, rowid DESC LIMIT ?",
+                    (pid, int(limit)),
+                ).fetchall()
+                recent = [{
+                    "agent_id": r["agent_id"],
+                    "content": r["snippet"],
+                    "created_at": r["created_at"],
+                    "source_type": r["source_type"],
+                    "session_id": r["session_id"],
+                } for r in rows]
+            except sqlite3.OperationalError:
+                pass
+        finally:
+            conn.close()
+
+    return {
+        "ok": True,
+        "profile_id": pid,
+        "total_memories": total,
+        "agent_count": len(agents),
+        "agents": agents,
+        "recent": recent,
+    }
 
 
 @router.get("/api/trust/stats")
@@ -102,38 +191,39 @@ async def get_trust_stats(request: Request):
             conn = sqlite3.connect(str(DB_PATH))
             conn.row_factory = sqlite3.Row
             try:
-                # Count trust signals
-                row = conn.execute(
-                    "SELECT COUNT(*) AS cnt FROM trust_signals "
-                    "WHERE profile_id = ?", (pid,),
-                ).fetchone()
-                total_signals = row["cnt"] if row else 0
-            except sqlite3.OperationalError:
-                pass
-
-            try:
-                # Average trust score
-                row = conn.execute(
-                    "SELECT AVG(trust_score) AS avg_ts FROM trust_scores "
-                    "WHERE profile_id = ?", (pid,),
-                ).fetchone()
-                if row and row["avg_ts"] is not None:
-                    avg_trust_score = round(float(row["avg_ts"]), 3)
-            except sqlite3.OperationalError:
-                pass
+                try:
+                    # Count trust signals
+                    row = conn.execute(
+                        "SELECT COUNT(*) AS cnt FROM trust_signals "
+                        "WHERE profile_id = ?", (pid,),
+                    ).fetchone()
+                    total_signals = row["cnt"] if row else 0
+                except sqlite3.OperationalError:
+                    pass
 
-            try:
-                # Signal breakdown by type
-                rows = conn.execute(
-                    "SELECT signal_type, COUNT(*) AS cnt "
-                    "FROM trust_signals WHERE profile_id = ? "
-                    "GROUP BY signal_type", (pid,),
-                ).fetchall()
-                by_signal_type = {r["signal_type"]: r["cnt"] for r in rows}
-            except sqlite3.OperationalError:
-                pass
+                try:
+                    # Average trust score
+                    row = conn.execute(
+                        "SELECT AVG(trust_score) AS avg_ts FROM trust_scores "
+                        "WHERE profile_id = ?", (pid,),
+                    ).fetchone()
+                    if row and row["avg_ts"] is not None:
+                        avg_trust_score = round(float(row["avg_ts"]), 3)
+                except sqlite3.OperationalError:
+                    pass
 
-            conn.close()
+                try:
+                    # Signal breakdown by type
+                    rows = conn.execute(
+                        "SELECT signal_type, COUNT(*) AS cnt "
+                        "FROM trust_signals WHERE profile_id = ? "
+                        "GROUP BY signal_type", (pid,),
+                    ).fetchall()
+                    by_signal_type = {r["signal_type"]: r["cnt"] for r in rows}
+                except sqlite3.OperationalError:
+                    pass
+            finally:
+                conn.close()
 
         # Enforcement status: SLM uses "Silent Collection" by default
         enforcement = "Silent Collection"
@@ -144,8 +234,8 @@ async def get_trust_stats(request: Request):
             "enforcement": enforcement,
             "by_signal_type": by_signal_type,
         }
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Trust stats error: {str(e)}")
+    except Exception:
+        raise _internal_error("Trust stats error")
 
 
 @router.get("/api/trust/signals/{agent_id}")
@@ -167,5 +257,5 @@ async def get_agent_trust_signals(
                 "signals": signals, "count": len(signals),
             }
         return {"agent_id": agent_id, "signals": [], "count": 0}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Trust signals error: {str(e)}")
+    except Exception:
+        raise _internal_error("Trust signals error")