superlocalmemory 3.7.7 → 3.8.0

package/src/superlocalmemory/retrieval/temporal_channel.py

@@ -62,7 +62,14 @@ class TemporalChannel:
     def __init__(self, db: DatabaseManager) -> None:
         self._db = db
 
-    def search(self, query: str, profile_id: str, top_k: int = 30) -> list[tuple[str, float]]:
+    def search(
+        self,
+        query: str,
+        profile_id: str,
+        top_k: int = 30,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
+    ) -> list[tuple[str, float]]:
         """Search for temporally relevant facts.
 
         Two strategies:
@@ -72,7 +79,17 @@ class TemporalChannel:
 
         Returns empty only when query has no temporal signal AND no
         entity-temporal matches.
+
+        Args:
+            include_global: Include global-scope facts. Falls back to the
+                instance attribute when not supplied.
+            include_shared: Include shared-scope facts. Same fallback.
         """
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
+
         parser = TemporalParser()
         dates = parser.extract_dates_from_text(query)
         query_dt = _parse_iso(dates.get("referenced_date"))
@@ -81,13 +98,18 @@ class TemporalChannel:
 
         # Strategy 1: Entity-temporal metadata search
         # "When did Alice...?" → find all temporal events for Alice
-        entity_results = self._entity_temporal_search(query, profile_id)
+        entity_results = self._entity_temporal_search(
+            query, profile_id,
+            include_global=include_global, include_shared=include_shared,
+        )
 
         # Strategy 2: Date proximity search
         if query_dt is None and not entity_results:
             return []
 
-        events = self._load_events(profile_id)
+        events = self._load_events(
+            profile_id, include_global=include_global, include_shared=include_shared,
+        )
         scored: dict[str, float] = {}
 
         # Include entity-temporal results with high base score
@@ -124,13 +146,21 @@ class TemporalChannel:
         return results[:top_k]
 
     def _entity_temporal_search(
-        self, query: str, profile_id: str,
+        self,
+        query: str,
+        profile_id: str,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Metadata-first: find temporal events for entities mentioned in query.
 
         "When did Alice do X?" → SQL filter by entity_id for Alice → return
         all temporal facts about Alice. High precision for entity+time queries.
         """
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         import re
         _PROPER_RE = re.compile(r"\b([A-Z][a-z]+)\b")
         names = [m.group(1) for m in _PROPER_RE.finditer(query)]
@@ -151,8 +181,8 @@ class TemporalChannel:
         seen: set[str] = set()
         where, params = _scope_where(
             profile_id,
-            include_global=bool(getattr(self, "include_global", False)),
-            include_shared=bool(getattr(self, "include_shared", False)),
+            include_global=include_global,
+            include_shared=include_shared,
             prefix="af",
         )
 
@@ -179,11 +209,20 @@ class TemporalChannel:
 
         return results
 
-    def _load_events(self, profile_id: str) -> list[dict]:
+    def _load_events(
+        self,
+        profile_id: str,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
+    ) -> list[dict]:
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         where, params = _scope_where(
             profile_id,
-            include_global=bool(getattr(self, "include_global", False)),
-            include_shared=bool(getattr(self, "include_shared", False)),
+            include_global=include_global,
+            include_shared=include_shared,
             prefix="af",
         )
         rows = self._db.execute(

package/src/superlocalmemory/retrieval/temporal_frame.py

@@ -0,0 +1,102 @@
+# 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
+
+"""Temporal-context injection helpers (Phase 4, T-inject).
+
+LLMs have no innate sense of time — a recalled fact reads the same whether it
+was stored an hour ago or two years ago. These pure helpers give every recalled
+memory a human-relative age label and give the whole result set a "temporal
+frame" header anchoring it to *now*, so the model can weigh recency and treat
+aged facts as possibly stale.
+
+Reuses ``time_window.parse_timestamp`` for tolerant timestamp parsing (SQLite
+space form, ISO ``T``/``Z``, date-only) — comparisons are always on parsed
+datetimes, never strings.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: AGPL-3.0-or-later
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Iterable
+
+from superlocalmemory.retrieval.time_window import parse_timestamp
+
+__all__ = ["relative_age", "temporal_frame"]
+
+
+def _plural(n: int, unit: str) -> str:
+    return f"{n} {unit}" + ("" if n == 1 else "s")
+
+
+def relative_age(timestamp: str | None, now: datetime | None = None) -> str:
+    """Human-relative age of ``timestamp`` vs now, e.g. "3 days ago".
+
+    Returns "" when the timestamp is missing/unparseable. Future timestamps
+    (e.g. a referenced event date ahead of now) read as "in N …".
+    """
+    dt = parse_timestamp(timestamp)
+    if dt is None:
+        return ""
+    _now = now or datetime.now(timezone.utc)
+    if _now.tzinfo is None:
+        _now = _now.replace(tzinfo=timezone.utc)
+    secs = (_now - dt).total_seconds()
+    future = secs < 0
+    secs = abs(secs)
+
+    if secs < 45:
+        return "just now"
+    minutes = secs / 60.0
+    hours = minutes / 60.0
+    days = hours / 24.0
+    if minutes < 45:
+        phrase = _plural(round(minutes), "minute")
+    elif hours < 24:
+        phrase = _plural(round(hours), "hour")
+    elif days < 14:
+        phrase = _plural(round(days), "day")
+    elif days < 60:
+        phrase = _plural(round(days / 7.0), "week")
+    elif days < 365:
+        phrase = _plural(round(days / 30.0), "month")
+    else:
+        phrase = _plural(round(days / 365.0), "year")
+    return f"in {phrase}" if future else f"{phrase} ago"
+
+
+def temporal_frame(
+    timestamps: Iterable[str | None],
+    now: datetime | None = None,
+) -> str:
+    """A one-line "now" anchor + age span for a set of recalled timestamps.
+
+    Example: ``"Now: 2026-07-22T12:00:00+00:00. Recalled memories span 2 years
+    ago → just now. Treat undated or aged facts as possibly stale."``
+
+    With no dated timestamps, returns just the now-anchor + an undated note.
+    """
+    _now = now or datetime.now(timezone.utc)
+    if _now.tzinfo is None:
+        _now = _now.replace(tzinfo=timezone.utc)
+    now_iso = _now.replace(microsecond=0).isoformat()
+
+    dts = [d for d in (parse_timestamp(t) for t in timestamps) if d is not None]
+    if not dts:
+        return f"Now: {now_iso}. Recalled memories are undated."
+
+    oldest = min(dts)
+    newest = max(dts)
+    span = (
+        relative_age(oldest.isoformat(), _now)
+        if oldest == newest
+        else f"{relative_age(oldest.isoformat(), _now)} → "
+             f"{relative_age(newest.isoformat(), _now)}"
+    )
+    return (
+        f"Now: {now_iso}. Recalled memories span {span}. "
+        f"Treat undated or aged facts as possibly stale."
+    )

package/src/superlocalmemory/retrieval/temporal_validity_filter.py

@@ -0,0 +1,135 @@
+# 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
+
+"""Bi-temporal validity filter for the retrieval pipeline (Phase 4, T1).
+
+Post-retrieval filter for *system-invalidated* facts — a fact whose temporal
+record has ``system_expired_at`` set was superseded/contradicted by a newer
+fact (see ``invalidate_fact_temporal`` / conflict-resolution supersession).
+
+P5-INT-01 (non-destructive supersession): such a fact is DEMOTED, not hidden.
+Its per-channel score is multiplied by ``superseded_demotion_factor`` (default
+0.25) and the channel lists are re-sorted, so currently-valid facts rank above
+it — but nothing valid silently vanishes. This is the Mem0-2026 design that
+wins long-term-memory benchmarks: keep every fact recallable and let
+retrieval-time recency resolve conflicts, rather than destructively deleting on
+a write-time contradiction guess (which over-fires: two complementary facts
+about the same entity diverge past the coboundary threshold and one would be
+wrongly hidden). A factor of 0.0 restores the legacy hide behaviour (a demoted
+score of 0 is gated out by the evidence floor).
+
+The filter runs on the per-channel candidate dict BEFORE RRF fusion, so fused
+ranks reflect the demotion. It queries validity only for the bounded candidate
+set (never the full ``get_valid_facts`` set) — an indexed, O(candidates) lookup
+on the hot path, no full-table scan.
+
+Pure SQL, no LLM → safe in every mode including Mode A. A no-op when nothing is
+invalidated and when config.enabled is False.
+
+Integrates with ChannelRegistry.register_filter() using the FilterFn signature:
+    (all_channel_results, profile_id, context) -> filtered_results
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: AGPL-3.0-or-later
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from superlocalmemory.core.config import TemporalValidatorConfig
+    from superlocalmemory.retrieval.channel_registry import ChannelRegistry
+    from superlocalmemory.storage.database import DatabaseManager
+
+logger = logging.getLogger(__name__)
+
+
+class TemporalValidityFilter:
+    """Demotes system-invalidated (superseded) facts in retrieval candidates."""
+
+    __slots__ = ("_db", "_demotion_factor")
+
+    def __init__(self, db: DatabaseManager, demotion_factor: float = 0.25) -> None:
+        self._db = db
+        # Clamp to [0, 1]. 0.0 = legacy hide (evidence floor drops zero-score
+        # facts); 1.0 = no demotion.
+        self._demotion_factor = max(0.0, min(1.0, float(demotion_factor)))
+
+    def filter(
+        self,
+        all_results: dict[str, list[tuple[str, float]]],
+        profile_id: str,
+        context: Any,
+    ) -> dict[str, list[tuple[str, float]]]:
+        """Demote superseded fact_ids in every channel's candidate list.
+
+        Matches FilterFn signature from channel_registry.py.
+
+        Args:
+            all_results: Channel name -> [(fact_id, score)] dict.
+            profile_id: Current profile.
+            context: Optional context (unused).
+
+        Returns:
+            A new dict where system-invalidated facts keep their channel
+            presence but have their score scaled by the demotion factor and the
+            channel lists re-sorted (so valid facts rank above them). Inputs are
+            never mutated (immutability). Unchanged when nothing is invalidated.
+        """
+        # Collect all unique candidate fact_ids across every channel.
+        all_fact_ids: set[str] = set()
+        for channel_results in all_results.values():
+            for fact_id, _ in channel_results:
+                all_fact_ids.add(fact_id)
+
+        if not all_fact_ids:
+            return all_results
+
+        try:
+            invalid = self._db.get_invalidated_fact_ids(
+                list(all_fact_ids), profile_id,
+            )
+        except Exception as exc:
+            # Fail-open: a validity-lookup error must never break retrieval.
+            logger.warning("Temporal validity lookup failed: %s", exc)
+            return all_results
+
+        if not invalid:
+            return all_results
+
+        factor = self._demotion_factor
+        demoted: dict[str, list[tuple[str, float]]] = {}
+        for channel_name, channel_results in all_results.items():
+            new_list = [
+                (fact_id, score * factor if fact_id in invalid else score)
+                for fact_id, score in channel_results
+            ]
+            # Re-sort descending so demoted (superseded) facts fall below
+            # currently-valid facts in this channel's rank order.
+            new_list.sort(key=lambda pair: pair[1], reverse=True)
+            demoted[channel_name] = new_list
+        return demoted
+
+
+def register_temporal_validity_filter(
+    registry: ChannelRegistry,
+    db: DatabaseManager,
+    config: TemporalValidatorConfig,
+) -> None:
+    """Register the bi-temporal validity filter into the channel registry.
+
+    Does nothing if config.enabled is False.
+
+    Args:
+        registry: Channel registry to register with.
+        db: Database manager for validity queries.
+        config: Temporal-validator configuration.
+    """
+    if not getattr(config, "enabled", True):
+        return
+    factor = getattr(config, "superseded_demotion_factor", 0.25)
+    f = TemporalValidityFilter(db, demotion_factor=factor)
+    registry.register_filter(f.filter)

package/src/superlocalmemory/retrieval/time_window.py

@@ -0,0 +1,181 @@
+# 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
+
+"""Time-window parsing + membership for recall (Phase 4, T-window).
+
+Pure, dependency-free helpers so recall() can prune candidates to an
+event-time range. Two window forms are accepted:
+
+  * relative string — ``"1h" | "24h" | "7d" | "30d" | "90d" | "1y"`` etc.
+    (``<int><unit>`` where unit is h/d/w/m/y; m≈30d, y≈365d) → ``[now-Δ, now]``.
+  * explicit range — ``(start_iso, end_iso)`` two-tuple of timestamps.
+
+Timestamps are parsed tolerantly: SQLite ``datetime('now')`` form
+(``"YYYY-MM-DD HH:MM:SS"``), ISO-8601 with ``T`` and/or trailing ``Z``, and
+date-only ``"YYYY-MM-DD"`` are all accepted. Comparing the *strings* would be
+wrong (a space sorts before ``T``), so everything is parsed to tz-aware UTC
+datetimes before comparison — never lexicographic.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: AGPL-3.0-or-later
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+
+__all__ = [
+    "parse_timestamp",
+    "parse_window",
+    "in_window",
+    "infer_window_from_query",
+]
+
+_REL = re.compile(r"^\s*(\d+)\s*([hdwmy])\s*$", re.IGNORECASE)
+
+# Hours per unit. Month and year are documented approximations.
+_UNIT_HOURS: dict[str, int] = {
+    "h": 1,
+    "d": 24,
+    "w": 24 * 7,
+    "m": 24 * 30,
+    "y": 24 * 365,
+}
+
+
+def parse_timestamp(value: str | None) -> datetime | None:
+    """Parse a stored timestamp into a tz-aware UTC datetime, or None.
+
+    Accepts SQLite ``datetime('now')`` (space-separated), ISO-8601 (``T`` and
+    optional ``Z``), and date-only strings. Naive values are assumed UTC.
+    """
+    if not value or not isinstance(value, str):
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+    dt: datetime | None = None
+    try:
+        dt = datetime.fromisoformat(text)
+    except ValueError:
+        # Fall back to a date-only prefix (e.g. "2026-03-15 ...").
+        try:
+            dt = datetime.fromisoformat(text[:10])
+        except ValueError:
+            return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def parse_window(
+    window: str | tuple[str, str] | list | None,
+    now: datetime | None = None,
+) -> tuple[datetime, datetime] | None:
+    """Resolve a window spec to a ``(start, end)`` UTC datetime pair, or None.
+
+    Returns None when the spec is None or unparseable (caller then applies no
+    time filter — additive, fail-open).
+    """
+    if window is None:
+        return None
+    _now = now or datetime.now(timezone.utc)
+    if _now.tzinfo is None:
+        _now = _now.replace(tzinfo=timezone.utc)
+
+    # Explicit (start, end) range.
+    if isinstance(window, (tuple, list)):
+        if len(window) != 2:
+            return None
+        start = parse_timestamp(window[0])
+        end = parse_timestamp(window[1])
+        if start is None or end is None:
+            return None
+        return (start, end) if start <= end else (end, start)
+
+    # String forms: relative "<int><unit>" or an explicit range written as
+    # "start..end" / "start,end" (so it survives URL params, JSON, and CLI args
+    # as a single value — no tuple serialization needed on the wire).
+    if isinstance(window, str):
+        m = _REL.match(window)
+        if m:
+            n = int(m.group(1))
+            unit = m.group(2).lower()
+            hours = n * _UNIT_HOURS[unit]
+            return (_now - timedelta(hours=hours), _now)
+        for sep in ("..", ","):
+            if sep in window:
+                left, _, right = window.partition(sep)
+                start = parse_timestamp(left)
+                end = parse_timestamp(right)
+                if start is None or end is None:
+                    return None
+                return (start, end) if start <= end else (end, start)
+
+    return None
+
+
+# Natural-language temporal-scope patterns → relative window spec. Ordered:
+# more specific ("last 3 weeks") is matched before generic ("last week").
+_UNIT_TO_SPEC = {"day": "d", "week": "w", "month": "m", "year": "y"}
+_QUERY_N_UNIT = re.compile(
+    r"\b(?:last|past|previous|prior)\s+(\d{1,3})\s+(day|week|month|year)s?\b",
+    re.IGNORECASE,
+)
+_QUERY_PHRASES: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"\btoday\b", re.IGNORECASE), "1d"),
+    (re.compile(r"\byesterday\b", re.IGNORECASE), "2d"),
+    (re.compile(r"\b(?:this|last|past|previous)\s+week\b", re.IGNORECASE), "7d"),
+    (re.compile(r"\b(?:this|last|past|previous)\s+month\b", re.IGNORECASE), "30d"),
+    (re.compile(r"\b(?:this|last|past|previous)\s+year\b", re.IGNORECASE), "1y"),
+    (re.compile(r"\b(?:recent|recently|lately)\b", re.IGNORECASE), "30d"),
+)
+
+
+def infer_window_from_query(query: str | None) -> str | None:
+    """Infer a relative time window from natural-language scope in a query.
+
+    Recognises a small, unambiguous set of temporal-scope phrases ("yesterday",
+    "last week", "past 3 months", "recently") and maps them to a relative
+    window spec ("2d", "7d", "3m", …) that ``parse_window`` understands. Returns
+    None when no clear temporal scope is present, so recall applies no window.
+
+    Deliberately conservative — only fires on explicit scope words, never on
+    bare content — so it augments, never surprises. Callers use it only when the
+    user did not pass an explicit window.
+    """
+    if not query or not isinstance(query, str):
+        return None
+    m = _QUERY_N_UNIT.search(query)
+    if m:
+        n = int(m.group(1))
+        unit = _UNIT_TO_SPEC.get(m.group(2).lower())
+        if unit and n > 0:
+            return f"{n}{unit}"
+    for pattern, spec in _QUERY_PHRASES:
+        if pattern.search(query):
+            return spec
+    return None
+
+
+def in_window(
+    event_time: str | None,
+    bounds: tuple[datetime, datetime] | None,
+) -> bool:
+    """True if ``event_time`` falls within ``bounds`` (inclusive).
+
+    No bounds → always True (no filtering). An unparseable/missing event time
+    is excluded (conservative: a windowed query returns only datable facts in
+    range).
+    """
+    if bounds is None:
+        return True
+    dt = parse_timestamp(event_time)
+    if dt is None:
+        return False
+    start, end = bounds
+    return start <= dt <= end

package/src/superlocalmemory/server/api.py

@@ -6,6 +6,23 @@
 SuperLocalMemory V3 - FastAPI API Server
 Provides REST endpoints for memory visualization and exploration.
 Uses V3 MemoryEngine for all operations.
+
+v3.7.8 (WS3 F4): ``create_app()`` in this module is a standalone/legacy app
+factory. The running daemon serves ``superlocalmemory.server.unified_daemon:
+create_app`` (see ``unified_daemon.py``'s uvicorn config); THIS factory is
+reachable only via direct ``python -m superlocalmemory.server.api`` /
+programmatic use and the tests that exercise it directly
+(``tests/test_api/test_api_lifespan_contract.py``,
+``tests/test_security/test_rate_limit_e2e.py``). Its ``auth_middleware``
+below intentionally keeps the older, simpler ``check_api_key``-only gate
+(unconditional per-write check, no daemon-capability / install-token
+identity layer) because it predates and is independent of the unified
+daemon's richer ``write_identity.require_http_mutation_actor`` boundary and
+the ``SLM_REQUIRE_API_KEY_LOOPBACK`` opt-in (see
+``infra/auth_middleware.py``). Do not treat this module's auth posture as
+the production write boundary -- that is ``unified_daemon.py``'s
+``auth_middleware``. ``UI_DIR`` below is still imported by
+``unified_daemon.py`` and must not be removed.
 """
 
 import json
@@ -31,10 +48,10 @@ logger = logging.getLogger("superlocalmemory.api_server")
 # V3 paths
 MEMORY_DIR = DynamicStatePath()
 DB_PATH = DynamicStatePath("memory.db")
-# V3.3.21: UI shipped inside the package for pip/npm installs.
-_PKG_UI = Path(__file__).resolve().parent.parent / "ui"
-_REPO_UI = Path(__file__).resolve().parent.parent.parent.parent / "ui"
-UI_DIR = _PKG_UI if (_PKG_UI / "index.html").exists() else _REPO_UI
+# V3.3.21+: the dashboard ships inside the package (superlocalmemory/ui) for
+# every install path. The legacy repo-root ui/ dev fallback was retired in
+# v3.8.0 when that copy was deleted; the packaged directory is authoritative.
+UI_DIR = Path(__file__).resolve().parent.parent / "ui"
 
 
 # ============================================================================