superlocalmemory 3.2.2 → 3.3.0

package/src/superlocalmemory/math/ebbinghaus.py

@@ -0,0 +1,309 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Ebbinghaus forgetting curve — memory strength and retention.
+
+Implements the classic Ebbinghaus retention formula:
+
+    R(t) = e^(-t/S)
+
+where:
+    R = retention score in [0, 1]
+    t = hours since last access
+    S = memory strength (composite of access, importance, confirmations, emotion)
+
+Memory strength formula (ACT-R inspired):
+
+    S = alpha * log(1 + access_count)
+      + beta  * importance
+      + gamma * confirmation_count
+      + delta * emotional_salience
+
+Lifecycle zones are derived from retention score:
+    active   (R > 0.8)  -> weight 1.0
+    warm     (R > 0.5)  -> weight 0.7
+    cold     (R > 0.2)  -> weight 0.3
+    archive  (R > 0.05) -> weight 0.0
+    forgotten (R <= 0.05) -> weight 0.0
+
+References:
+    Ebbinghaus H (1885). Memory: A Contribution to Experimental Psychology.
+    Anderson J R & Lebiere C (1998). The Atomic Components of Thought. ACT-R.
+    Zhong W et al. (2024). MemoryBank: Enhancing Large Language Models with
+        Long-Term Memory. AAAI 2024.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, TypedDict
+
+if TYPE_CHECKING:
+    from superlocalmemory.storage.database import DatabaseManager
+
+from superlocalmemory.core.config import ForgettingConfig
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class MemoryStrength:
+    """Computed strength for a single memory."""
+
+    fact_id: str
+    strength: float             # S(m) in [S_MIN, S_MAX]
+    access_component: float     # alpha * log(1 + access_count)
+    importance_component: float  # beta * importance
+    confirmation_component: float  # gamma * confirmation_count
+    emotional_component: float    # delta * emotional_salience
+
+
+class FactRetentionInput(TypedDict):
+    """Input dict for batch retention computation. All keys are required."""
+
+    fact_id: str
+    access_count: int
+    importance: float              # PageRank score from fact_importance
+    confirmation_count: int        # Mapped from atomic_facts.evidence_count
+    emotional_salience: float      # Mapped from atomic_facts.emotional_valence
+    last_accessed_at: str          # ISO 8601 datetime string
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle zone weights
+# ---------------------------------------------------------------------------
+
+_ZONE_WEIGHTS: dict[str, float] = {
+    "active": 1.0,
+    "warm": 0.7,
+    "cold": 0.3,
+    "archive": 0.0,
+    "forgotten": 0.0,
+}
+
+
+# ---------------------------------------------------------------------------
+# EbbinghausCurve
+# ---------------------------------------------------------------------------
+
+class EbbinghausCurve:
+    """Ebbinghaus forgetting curve with configurable strength formula.
+
+    Provides retention computation, memory strength calculation,
+    spaced repetition updates, lifecycle zone classification, and
+    batch processing for the forgetting scheduler.
+    """
+
+    __slots__ = ("_config",)
+
+    def __init__(self, config: ForgettingConfig) -> None:
+        self._config = config
+
+    def retention(self, hours_since_access: float, strength: float) -> float:
+        """Compute Ebbinghaus retention R(t) = e^(-t/S).
+
+        Args:
+            hours_since_access: Hours since last access. Negative treated as fresh.
+            strength: Memory strength S. Floored at min_strength.
+
+        Returns:
+            Retention score in [0.0, 1.0]. Never NaN, never Inf.
+        """
+        # HR-02: Validate negative time
+        if hours_since_access < 0:
+            return 1.0
+
+        # HR-03: Floor strength
+        s = max(self._config.min_strength, strength)
+
+        # Compute decay rate and retention
+        lambda_ = 1.0 / s
+        r = math.exp(-lambda_ * hours_since_access)
+
+        # NaN/Inf guard (A-MED-02) — MUST come before clamp
+        if math.isnan(r) or math.isinf(r):
+            logger.warning(
+                "retention(): NaN/Inf detected (lambda_=%f, t=%f), returning 0.0",
+                lambda_, hours_since_access,
+            )
+            return 0.0
+
+        # HR-02: Clamp to [0.0, 1.0]
+        return max(0.0, min(1.0, r))
+
+    def memory_strength(
+        self,
+        access_count: int,
+        importance: float,
+        confirmation_count: int,
+        emotional_salience: float,
+    ) -> float:
+        """Compute composite memory strength S(m).
+
+        S = alpha * log(1 + access_count)
+          + beta  * importance
+          + gamma * confirmation_count
+          + delta * emotional_salience
+
+        Args:
+            access_count: Number of times memory was accessed.
+            importance: PageRank importance score.
+            confirmation_count: Number of confirmations/evidence.
+            emotional_salience: Emotional strength [-1, 1].
+
+        Returns:
+            Clamped strength in [min_strength, max_strength].
+        """
+        cfg = self._config
+        a = cfg.alpha * math.log(1.0 + access_count)
+        b = cfg.beta * importance
+        c = cfg.gamma * confirmation_count
+        d = cfg.delta * emotional_salience
+        s = a + b + c + d
+
+        # HR-03: Clamp to bounds
+        return max(cfg.min_strength, min(cfg.max_strength, s))
+
+    def compute_strength(
+        self,
+        fact_id: str,
+        access_count: int,
+        importance: float,
+        confirmation_count: int,
+        emotional_salience: float,
+    ) -> MemoryStrength:
+        """Compute MemoryStrength dataclass for a single fact.
+
+        Returns:
+            MemoryStrength with all component scores.
+        """
+        cfg = self._config
+        a = cfg.alpha * math.log(1.0 + access_count)
+        b = cfg.beta * importance
+        c = cfg.gamma * confirmation_count
+        d = cfg.delta * emotional_salience
+        s = a + b + c + d
+        s = max(cfg.min_strength, min(cfg.max_strength, s))
+
+        return MemoryStrength(
+            fact_id=fact_id,
+            strength=s,
+            access_component=a,
+            importance_component=b,
+            confirmation_component=c,
+            emotional_component=d,
+        )
+
+    def spaced_repetition_update(
+        self, current_strength: float, hours_since_last_access: float,
+    ) -> float:
+        """Boost strength on re-access (spaced repetition effect).
+
+        Longer gaps between accesses produce larger boosts — this is the
+        spacing effect from cognitive science.
+
+        HR-07: Only INCREASES strength, never decreases.
+
+        Args:
+            current_strength: Current memory strength.
+            hours_since_last_access: Hours since last access.
+
+        Returns:
+            Updated strength, clamped to [min_strength, max_strength].
+        """
+        cfg = self._config
+        interval = math.log(1.0 + hours_since_last_access / 24.0)
+        boost = cfg.learning_rate * interval
+        s_new = current_strength + boost
+
+        # HR-03: Clamp
+        return max(cfg.min_strength, min(cfg.max_strength, s_new))
+
+    def lifecycle_zone(self, retention_score: float) -> str:
+        """Classify retention score into lifecycle zone.
+
+        Args:
+            retention_score: R in [0, 1].
+
+        Returns:
+            One of: 'active', 'warm', 'cold', 'archive', 'forgotten'.
+        """
+        if retention_score > 0.8:
+            return "active"
+        if retention_score > 0.5:
+            return "warm"
+        if retention_score > self._config.archive_threshold:
+            return "cold"
+        if retention_score > self._config.forget_threshold:
+            return "archive"
+        return "forgotten"
+
+    def lifecycle_weight(self, zone: str) -> float:
+        """Get retrieval weight for a lifecycle zone.
+
+        Args:
+            zone: Lifecycle zone name.
+
+        Returns:
+            Weight in [0.0, 1.0].
+        """
+        return _ZONE_WEIGHTS.get(zone, 0.0)
+
+    def batch_compute_retention(
+        self, facts: list[FactRetentionInput],
+    ) -> list[dict]:
+        """Compute retention for a batch of facts.
+
+        Args:
+            facts: List of FactRetentionInput dicts.
+
+        Returns:
+            List of dicts with fact_id, retention, strength, zone.
+        """
+        now = datetime.now(UTC)
+        results: list[dict] = []
+
+        for fact in facts:
+            access_count = fact["access_count"]
+            importance = fact["importance"]
+            confirmation_count = fact["confirmation_count"]
+            emotional_salience = fact["emotional_salience"]
+            last_accessed_at = fact["last_accessed_at"]
+
+            # Compute hours since last access
+            try:
+                last_dt = datetime.fromisoformat(last_accessed_at)
+                # Ensure timezone-aware
+                if last_dt.tzinfo is None:
+                    last_dt = last_dt.replace(tzinfo=UTC)
+                hours_since = (now - last_dt).total_seconds() / 3600.0
+            except (ValueError, TypeError):
+                hours_since = 0.0
+
+            strength = self.memory_strength(
+                access_count, importance, confirmation_count, emotional_salience,
+            )
+            ret = self.retention(hours_since, strength)
+            zone = self.lifecycle_zone(ret)
+
+            results.append({
+                "fact_id": fact["fact_id"],
+                "retention": ret,
+                "strength": strength,
+                "zone": zone,
+                "access_count": access_count,
+                "last_accessed_at": last_accessed_at,
+            })
+
+        return results

package/src/superlocalmemory/math/fisher_quantized.py

@@ -0,0 +1,251 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Fisher-Rao Quantization-Aware Distance (FRQAD).
+
+Novel contribution (98% IP confidence): Fisher-Rao geodesic distance on
+mixed-precision embeddings.  Quantized memories naturally rank lower because
+their variance is inflated to model quantization uncertainty.
+
+    sigma_quant = sigma_base * (32 / bit_width) ^ kappa
+
+When both embeddings are float32, FRQAD degrades exactly to standard
+Fisher-Rao --- no regression, pure extension.
+
+Mathematical basis:
+  - Fisher-Rao geodesic (Atkinson & Mitchell 1981, Pinele et al. 2020)
+  - Variance inflation models quantization noise as additional uncertainty
+    on the statistical manifold of diagonal Gaussians
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+from superlocalmemory.math.fisher import FisherRaoMetric
+
+logger = logging.getLogger(__name__)
+
+# Valid bit-widths aligned with Phase B/D (no 16-bit format exists).
+_VALID_BIT_WIDTHS: frozenset[int] = frozenset({2, 4, 8, 32})
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class FRQADConfig:
+    """Configuration for FRQAD metric.
+
+    Attributes:
+        kappa:            Scaling exponent for variance inflation.
+                          sigma_quant = sigma_base * (32/bw)^kappa.
+        temperature:      Softmax temperature for similarity conversion.
+        enabled:          When False, fall back to base Fisher-Rao.
+        variance_floor:   Minimum per-dimension variance after inflation.
+        variance_ceiling: Maximum per-dimension variance after inflation.
+    """
+
+    kappa: float = 0.5
+    temperature: float = 15.0
+    enabled: bool = True
+    variance_floor: float = 0.05
+    variance_ceiling: float = 10.0
+
+
+# ---------------------------------------------------------------------------
+# FRQAD Metric
+# ---------------------------------------------------------------------------
+
+
+class FRQADMetric:
+    """Fisher-Rao Quantization-Aware Distance metric.
+
+    Wraps an existing FisherRaoMetric and inflates variance vectors based
+    on each embedding's bit-width before computing geodesic distance.
+
+    Self-consistency property:
+        FRQAD(32bit, 32bit) == FisherRao(same pair) within float epsilon.
+    """
+
+    __slots__ = ("_base", "_config")
+
+    def __init__(
+        self,
+        base_metric: FisherRaoMetric,
+        config: FRQADConfig,
+    ) -> None:
+        """Construct FRQAD metric.
+
+        Args:
+            base_metric: Existing Fisher-Rao metric instance.
+            config:      FRQAD configuration.
+
+        Raises:
+            ValueError: On invalid configuration values.
+        """
+        # Validate config ranges (HR-04)
+        if not 0.0 <= config.kappa <= 2.0:
+            raise ValueError(
+                f"kappa must be in [0.0, 2.0], got {config.kappa}"
+            )
+        if not 1.0 <= config.temperature <= 100.0:
+            raise ValueError(
+                f"temperature must be in [1.0, 100.0], got {config.temperature}"
+            )
+        if not 0.001 <= config.variance_floor <= 1.0:
+            raise ValueError(
+                f"variance_floor must be in [0.001, 1.0], got {config.variance_floor}"
+            )
+        if not 1.0 <= config.variance_ceiling <= 100.0:
+            raise ValueError(
+                f"variance_ceiling must be in [1.0, 100.0], got {config.variance_ceiling}"
+            )
+
+        self._base = base_metric
+        self._config = config
+
+    # ------------------------------------------------------------------
+    # Quantization variance inflation
+    # ------------------------------------------------------------------
+
+    def quantization_variance(
+        self,
+        base_variance: NDArray[np.floating],
+        bit_width: int,
+    ) -> NDArray[np.floating]:
+        """Inflate variance to model quantization uncertainty.
+
+        HR-02: NEVER decreases base variance (scale >= 1.0 since bw <= 32).
+
+        Args:
+            base_variance: Per-dimension variance vector (strictly positive).
+            bit_width:     Embedding precision in bits.
+
+        Returns:
+            Quantization-aware variance, clamped to [floor, ceiling].
+        """
+        if bit_width not in _VALID_BIT_WIDTHS:
+            logger.warning(
+                "Unknown bit_width %d, treating as 32 (no penalty)", bit_width,
+            )
+            return np.array(base_variance, dtype=np.float64)
+
+        if bit_width >= 32:
+            return np.array(base_variance, dtype=np.float64)
+
+        scale = (32.0 / bit_width) ** self._config.kappa
+        sigma_q = np.asarray(base_variance, dtype=np.float64) * scale
+
+        return np.clip(sigma_q, self._config.variance_floor, self._config.variance_ceiling)
+
+    # ------------------------------------------------------------------
+    # Core distance (THE novel contribution)
+    # ------------------------------------------------------------------
+
+    def distance(
+        self,
+        mu_a: NDArray[np.floating],
+        var_a: NDArray[np.floating],
+        bw_a: int,
+        mu_b: NDArray[np.floating],
+        var_b: NDArray[np.floating],
+        bw_b: int,
+    ) -> float:
+        """FRQAD distance between mixed-precision embeddings.
+
+        Inflates variance based on bit-width, then delegates to the
+        standard Fisher-Rao geodesic.
+
+        Args:
+            mu_a:  Mean of embedding A.
+            var_a: Per-dimension variance of A.
+            bw_a:  Bit-width of A.
+            mu_b:  Mean of embedding B.
+            var_b: Per-dimension variance of B.
+            bw_b:  Bit-width of B.
+
+        Returns:
+            Non-negative geodesic distance.
+        """
+        if not self._config.enabled:
+            return self._base.distance(
+                np.asarray(mu_a, dtype=np.float64).tolist(),
+                np.asarray(var_a, dtype=np.float64).tolist(),
+                np.asarray(mu_b, dtype=np.float64).tolist(),
+                np.asarray(var_b, dtype=np.float64).tolist(),
+            )
+
+        var_a_q = self.quantization_variance(var_a, bw_a)
+        var_b_q = self.quantization_variance(var_b, bw_b)
+
+        return self._base.distance(
+            np.asarray(mu_a, dtype=np.float64).tolist(),
+            var_a_q.tolist(),
+            np.asarray(mu_b, dtype=np.float64).tolist(),
+            var_b_q.tolist(),
+        )
+
+    # ------------------------------------------------------------------
+    # Similarity (exponential kernel)
+    # ------------------------------------------------------------------
+
+    def similarity(
+        self,
+        mu_a: NDArray[np.floating],
+        var_a: NDArray[np.floating],
+        bw_a: int,
+        mu_b: NDArray[np.floating],
+        var_b: NDArray[np.floating],
+        bw_b: int,
+    ) -> float:
+        """Convert FRQAD distance to similarity in [0, 1].
+
+        sim = clamp(exp(-distance / temperature), 0, 1)
+
+        HR-03: No NaN, no negative, no > 1.
+        """
+        d = self.distance(mu_a, var_a, bw_a, mu_b, var_b, bw_b)
+        sim = math.exp(-d / self._config.temperature)
+        return max(0.0, min(1.0, sim))
+
+    # ------------------------------------------------------------------
+    # Batch similarity
+    # ------------------------------------------------------------------
+
+    def batch_similarity(
+        self,
+        query_mu: NDArray[np.floating],
+        query_var: NDArray[np.floating],
+        query_bw: int,
+        candidates: list[tuple[str, NDArray[np.floating], NDArray[np.floating], int]],
+    ) -> list[tuple[str, float]]:
+        """Score a batch of candidate memories against a query.
+
+        Args:
+            query_mu:   Query embedding mean.
+            query_var:  Query embedding variance.
+            query_bw:   Query bit-width (typically 32).
+            candidates: List of (fact_id, mu, var, bit_width) tuples.
+
+        Returns:
+            List of (fact_id, similarity) sorted descending by score.
+        """
+        results: list[tuple[str, float]] = []
+        for fact_id, mu, var, bw in candidates:
+            sim = self.similarity(query_mu, query_var, query_bw, mu, var, bw)
+            results.append((fact_id, sim))
+
+        results.sort(key=lambda x: x[1], reverse=True)
+        return results