superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/dynamics/ebbinghaus_langevin_coupling.py

@@ -1,171 +0,0 @@
-# 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
-
-"""Ebbinghaus-Langevin coupling — forgetting drift in dynamics.
-
-Combines the Ebbinghaus forgetting curve with Fisher-Langevin coupling
-to create a three-way information-dynamic lifecycle:
-
-  1. Fisher confidence  -> Langevin temperature (existing)
-  2. Ebbinghaus retention -> forgetting drift coefficient (new)
-  3. Combined temperature = T_fisher * (1 + lambda_forget)
-
-The forgetting drift pushes low-retention memories toward the Langevin
-boundary faster, while high-retention memories resist drift. This creates
-a thermodynamically grounded forgetting process.
-
-Mathematical formulation:
-  lambda_forget = (1 - R) * forgetting_drift_scale
-  T_combined = T_fisher * (1 + lambda_forget)
-  weight_combined = w_fisher * w_ebbinghaus
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-
-import numpy as np
-
-from superlocalmemory.core.config import ForgettingConfig
-from superlocalmemory.dynamics.fisher_langevin_coupling import (
-    FisherLangevinCoupling,
-)
-from superlocalmemory.math.ebbinghaus import EbbinghausCurve
-from superlocalmemory.math.langevin import LangevinDynamics
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Coupling state
-# ---------------------------------------------------------------------------
-
-@dataclass(frozen=True)
-class EbbinghausCouplingState:
-    """State of the Ebbinghaus-Langevin coupling for a single memory.
-
-    Attributes:
-        fact_id: Fact identifier.
-        retention_score: R(t) in [0, 1].
-        memory_strength: S(m) in [S_MIN, S_MAX].
-        lifecycle_zone: One of active/warm/cold/archive/forgotten.
-        effective_temperature: Combined T (Fisher + forgetting).
-        lifecycle_weight: Combined weight [0, 1].
-        forgetting_drift: lambda_forget coefficient.
-        is_forgotten: Below forget_threshold.
-        consolidation_signal: From Fisher coupling.
-    """
-
-    fact_id: str
-    retention_score: float
-    memory_strength: float
-    lifecycle_zone: str
-    effective_temperature: float
-    lifecycle_weight: float
-    forgetting_drift: float
-    is_forgotten: bool
-    consolidation_signal: bool
-
-
-# ---------------------------------------------------------------------------
-# Coupling class
-# ---------------------------------------------------------------------------
-
-class EbbinghausLangevinCoupling:
-    """Couples Ebbinghaus forgetting to Fisher-Langevin dynamics.
-
-    Creates a three-way feedback loop:
-    1. Fisher confidence modulates Langevin temperature (existing).
-    2. Ebbinghaus retention adds forgetting drift.
-    3. Combined effect determines lifecycle zone and weight.
-    """
-
-    __slots__ = ("_ebbinghaus", "_langevin", "_fisher_coupling", "_config")
-
-    def __init__(
-        self,
-        ebbinghaus: EbbinghausCurve,
-        langevin: LangevinDynamics,
-        fisher_coupling: FisherLangevinCoupling,
-        config: ForgettingConfig,
-    ) -> None:
-        self._ebbinghaus = ebbinghaus
-        self._langevin = langevin
-        self._fisher_coupling = fisher_coupling
-        self._config = config
-
-    def compute_coupled_state(
-        self,
-        fact_id: str,
-        fisher_variance: np.ndarray,
-        langevin_radius: float,
-        access_count: int,
-        importance: float,
-        confirmation_count: int,
-        emotional_salience: float,
-        hours_since_last_access: float,
-    ) -> EbbinghausCouplingState:
-        """Compute the full coupled state for a single memory.
-
-        Combines Fisher-Langevin coupling with Ebbinghaus forgetting
-        to produce a unified lifecycle state.
-
-        Args:
-            fact_id: Fact identifier.
-            fisher_variance: Fisher variance vector (diagonal).
-            langevin_radius: Current Langevin position radius [0, 1).
-            access_count: Total access count.
-            importance: PageRank importance score.
-            confirmation_count: Evidence/confirmation count.
-            emotional_salience: Emotional strength.
-            hours_since_last_access: Hours since last access.
-
-        Returns:
-            EbbinghausCouplingState with all computed fields.
-        """
-        # Step 1: Fisher-Langevin coupling (existing system)
-        fl_state = self._fisher_coupling.compute_coupling(
-            fisher_variance, langevin_radius, access_count,
-        )
-
-        # Step 2: Ebbinghaus strength
-        strength = self._ebbinghaus.memory_strength(
-            access_count, importance, confirmation_count, emotional_salience,
-        )
-
-        # Step 3: Ebbinghaus retention
-        retention = self._ebbinghaus.retention(hours_since_last_access, strength)
-
-        # Step 4: Lifecycle zone
-        zone = self._ebbinghaus.lifecycle_zone(retention)
-
-        # Step 5: Forgetting drift coefficient
-        # Higher forgetting (lower R) -> stronger drift toward boundary
-        lambda_forget = (1.0 - retention) * self._config.forgetting_drift_scale
-
-        # Step 6: Combined temperature
-        # Forgetting increases effective temperature -> more noise -> faster drift
-        t_combined = fl_state.langevin_temperature * (1.0 + lambda_forget)
-
-        # Step 7: Combined weight
-        weight = fl_state.lifecycle_weight * self._ebbinghaus.lifecycle_weight(zone)
-
-        # Step 8: Is forgotten?
-        is_forgotten = zone == "forgotten"
-
-        return EbbinghausCouplingState(
-            fact_id=fact_id,
-            retention_score=retention,
-            memory_strength=strength,
-            lifecycle_zone=zone,
-            effective_temperature=t_combined,
-            lifecycle_weight=weight,
-            forgetting_drift=lambda_forget,
-            is_forgotten=is_forgotten,
-            consolidation_signal=fl_state.consolidation_signal,
-        )

package/src/superlocalmemory/dynamics/fisher_langevin_coupling.py

@@ -1,227 +0,0 @@
-# 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
-
-"""Fisher-Langevin Coupling: information-dynamic lifecycle for memory.
-
-THE CORE INVENTION — Paper Headline 2 (STRONGEST NOVELTY):
-Fisher information confidence directly drives Langevin dynamics,
-creating self-organizing memory where:
-
-  - High Fisher confidence (low variance) -> memory stabilizes
-    (Langevin drift toward origin -> ACTIVE state)
-  - Low Fisher confidence (high variance) -> memory fades
-    (Langevin drift toward boundary -> ARCHIVED state)
-  - Evidence accumulation -> Fisher variance decreases -> consolidation
-
-Mathematical formulation:
-  Coupled SDE with information-modulated temperature:
-    T_eff = T_0 / (fisher_confidence + epsilon)
-
-  High confidence -> low T_eff -> less noise -> position stabilizes.
-  Low confidence  -> high T_eff -> more noise -> position drifts to boundary.
-
-  This produces a provable Fokker-Planck steady-state distribution where
-  the memory system self-organizes without external scheduling.
-
-Adapted: uses Langevin position radius for lifecycle zone classification.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-import logging
-import math
-from dataclasses import dataclass, field
-from typing import Any
-
-import numpy as np
-
-logger = logging.getLogger(__name__)
-
-# Default coupling parameters
-DEFAULT_CONFIDENCE_SCALE = 1.0
-DEFAULT_BASE_TEMPERATURE = 0.3    # Matches Langevin MathConfig default
-DEFAULT_EPSILON = 0.1
-DEFAULT_CONSOLIDATION_THRESHOLD = 0.8
-
-
-@dataclass
-class CouplingState:
-    """State of the Fisher-Langevin coupling for a single memory.
-
-    Attributes:
-        fact_id: Fact identifier.
-        fisher_confidence: Current Fisher confidence [0, 1].
-        langevin_temperature: Derived effective temperature.
-        drift_direction: "stabilize" | "neutral" | "fade".
-        lifecycle_weight: Score multiplier from coupling [0.3, 1.0].
-        consolidation_signal: Whether to consolidate this memory.
-    """
-
-    fact_id: str = ""
-    fisher_confidence: float = 0.5
-    langevin_temperature: float = 0.3
-    drift_direction: str = "neutral"
-    lifecycle_weight: float = 1.0
-    consolidation_signal: bool = False
-
-
-class FisherLangevinCoupling:
-    """Couples Fisher information to Langevin dynamics for self-organizing memory.
-
-    The coupling creates a feedback loop:
-    1. Fisher confidence measures how CERTAIN a memory's embedding is.
-    2. Confidence drives Langevin TEMPERATURE (high conf -> low noise).
-    3. Low noise -> memory position stabilizes near origin (ACTIVE).
-    4. High noise -> memory drifts toward boundary (ARCHIVED).
-    5. Evidence accumulation -> Fisher variance decreases -> confidence rises.
-
-    This is a provable self-organizing system with Fokker-Planck steady state.
-    """
-
-    def __init__(
-        self,
-        confidence_scale: float = DEFAULT_CONFIDENCE_SCALE,
-        base_temperature: float = DEFAULT_BASE_TEMPERATURE,
-        epsilon: float = DEFAULT_EPSILON,
-        consolidation_threshold: float = DEFAULT_CONSOLIDATION_THRESHOLD,
-    ) -> None:
-        self._scale = confidence_scale
-        self._base_temp = base_temperature
-        self._epsilon = epsilon
-        self._consolidation_threshold = consolidation_threshold
-
-    def compute_coupling(
-        self,
-        fisher_variance: np.ndarray | list[float],
-        langevin_radius: float,
-        access_count: int = 0,
-    ) -> CouplingState:
-        """Compute the coupled state for a single memory.
-
-        Args:
-            fisher_variance: Fisher variance vector (diagonal).
-            langevin_radius: Current Langevin position radius [0, 1).
-            access_count: Number of times memory has been accessed.
-
-        Returns:
-            CouplingState with derived temperature, direction, and weight.
-        """
-        var_arr = np.asarray(fisher_variance, dtype=np.float64)
-        if var_arr.size == 0:
-            return CouplingState()
-
-        # Step 1: Fisher confidence from variance
-        # Low variance = high confidence (memory is well-characterized)
-        avg_var = float(np.mean(np.clip(var_arr, 1e-8, None)))
-        fisher_conf = 1.0 / (1.0 + avg_var)
-
-        # Evidence reinforcement from repeated access
-        evidence_boost = min(access_count * 0.02, 0.2)
-        fisher_conf = min(1.0, fisher_conf + evidence_boost)
-
-        # Step 2: Derive Langevin effective temperature
-        # T_eff = T_0 / (confidence + epsilon)
-        # High confidence -> low temperature -> less noise -> stabilizes
-        temperature = self._base_temp / (fisher_conf + self._epsilon)
-
-        # Step 3: Determine drift direction and lifecycle weight
-        if fisher_conf >= self._consolidation_threshold:
-            direction = "stabilize"
-            weight = 0.9 + 0.1 * fisher_conf
-        elif fisher_conf >= 0.5:
-            direction = "neutral"
-            weight = 0.7 + 0.3 * fisher_conf
-        elif fisher_conf >= 0.3:
-            direction = "fade"
-            weight = 0.4 + 0.6 * fisher_conf
-        else:
-            direction = "fade"
-            weight = max(0.3, fisher_conf)
-
-        # Step 4: Langevin radius modulates (near-boundary penalty)
-        if langevin_radius > 0.85:
-            weight *= 0.8
-
-        return CouplingState(
-            fisher_confidence=fisher_conf,
-            langevin_temperature=temperature,
-            drift_direction=direction,
-            lifecycle_weight=weight,
-            consolidation_signal=fisher_conf >= self._consolidation_threshold,
-        )
-
-    def apply_to_facts(
-        self,
-        facts: list[dict[str, Any]],
-    ) -> list[CouplingState]:
-        """Apply Fisher-Langevin coupling to a list of fact dicts.
-
-        Each dict must have: fact_id, fisher_variance (or None),
-        langevin_position (or None), access_count.
-
-        Returns:
-            List of CouplingState for each fact.
-        """
-        states: list[CouplingState] = []
-
-        for fact in facts:
-            fid = fact.get("fact_id", "")
-            f_var = fact.get("fisher_variance")
-            l_pos = fact.get("langevin_position")
-            access = fact.get("access_count", 0)
-
-            if f_var is None:
-                # No Fisher data — use default coupling
-                states.append(CouplingState(fact_id=fid))
-                continue
-
-            # Compute Langevin radius from position vector
-            radius = 0.5
-            if l_pos is not None:
-                pos = np.asarray(l_pos, dtype=np.float64)
-                radius = float(np.linalg.norm(pos))
-
-            state = self.compute_coupling(f_var, radius, access)
-            state.fact_id = fid
-            states.append(state)
-
-        return states
-
-    def get_effective_temperature(
-        self,
-        fisher_variance: np.ndarray | list[float] | None,
-        access_count: int = 0,
-    ) -> float:
-        """Quick helper: get effective Langevin temperature from Fisher variance.
-
-        Used by maintenance.py when running Langevin batch_step with
-        Fisher-coupled temperature.
-        """
-        if fisher_variance is None:
-            return self._base_temp
-
-        var_arr = np.asarray(fisher_variance, dtype=np.float64)
-        if var_arr.size == 0:
-            return self._base_temp
-        avg_var = float(np.mean(np.clip(var_arr, 1e-8, None)))
-        fisher_conf = min(1.0, 1.0 / (1.0 + avg_var) + min(access_count * 0.02, 0.2))
-        return self._base_temp / (fisher_conf + self._epsilon)
-
-    def get_consolidation_candidates(
-        self, states: list[CouplingState],
-    ) -> list[str]:
-        """Return fact IDs that should be consolidated (high confidence)."""
-        return [s.fact_id for s in states if s.consolidation_signal]
-
-    def get_decay_candidates(
-        self, states: list[CouplingState],
-    ) -> list[str]:
-        """Return fact IDs that are fading (low confidence + drifting)."""
-        return [
-            s.fact_id for s in states
-            if s.drift_direction == "fade" and s.fisher_confidence < 0.3
-        ]