superlocalmemory 2.8.6 → 3.0.1

package/src/superlocalmemory/core/registry.py

@@ -0,0 +1,117 @@
+# 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
+
+"""Agent registry — multi-agent profile isolation.
+
+Tracks which agents are using which profiles and prevents
+two agents from writing to the same profile simultaneously
+via an advisory lock mechanism. Persisted as JSON for
+survival across process restarts.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ProfileLockError(Exception):
+    """Raised when an agent tries to write-lock an already-locked profile."""
+
+
+class AgentRegistry:
+    """In-memory agent registry with JSON file persistence.
+
+    Each agent registers with an ID and a target profile.
+    Advisory write locks prevent two agents from mutating
+    the same profile at the same time.
+    """
+
+    def __init__(self, persist_path: Path | None = None) -> None:
+        self._agents: dict[str, dict[str, Any]] = {}
+        self._write_locks: dict[str, str] = {}  # profile_id -> agent_id
+        self._path = persist_path
+        if self._path and self._path.exists():
+            self._load()
+
+    # -- Public API ---------------------------------------------------------
+
+    def register_agent(self, agent_id: str, profile_id: str) -> None:
+        """Register an agent for a profile. Acquires advisory write lock."""
+        if agent_id in self._agents:
+            self.unregister_agent(agent_id)
+
+        holder = self._write_locks.get(profile_id)
+        if holder and holder != agent_id:
+            raise ProfileLockError(
+                f"Profile '{profile_id}' is locked by agent '{holder}'."
+            )
+
+        self._agents[agent_id] = {
+            "profile_id": profile_id,
+            "registered_at": time.time(),
+        }
+        self._write_locks[profile_id] = agent_id
+        self._save()
+        logger.info("Agent '%s' registered for profile '%s'", agent_id, profile_id)
+
+    def unregister_agent(self, agent_id: str) -> None:
+        """Remove an agent and release its write lock."""
+        entry = self._agents.pop(agent_id, None)
+        if entry:
+            profile_id = entry["profile_id"]
+            if self._write_locks.get(profile_id) == agent_id:
+                del self._write_locks[profile_id]
+            self._save()
+            logger.info("Agent '%s' unregistered", agent_id)
+
+    def get_agent_profile(self, agent_id: str) -> str:
+        """Return the profile ID for a registered agent.
+
+        Raises KeyError if the agent is not registered.
+        """
+        entry = self._agents.get(agent_id)
+        if entry is None:
+            raise KeyError(f"Agent '{agent_id}' is not registered.")
+        return entry["profile_id"]
+
+    def list_agents(self) -> list[dict[str, Any]]:
+        """Return a snapshot of all registered agents."""
+        return [
+            {
+                "agent_id": aid,
+                "profile_id": info["profile_id"],
+                "registered_at": info["registered_at"],
+            }
+            for aid, info in self._agents.items()
+        ]
+
+    # -- Persistence --------------------------------------------------------
+
+    def _save(self) -> None:
+        if not self._path:
+            return
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        data = {"agents": self._agents, "write_locks": self._write_locks}
+        self._path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+    def _load(self) -> None:
+        if not self._path or not self._path.exists():
+            return
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+            self._agents = data.get("agents", {})
+            self._write_locks = data.get("write_locks", {})
+        except (json.JSONDecodeError, KeyError):
+            logger.warning("Corrupt registry file at %s — starting fresh.", self._path)
+            self._agents = {}
+            self._write_locks = {}

package/src/superlocalmemory/dynamics/fisher_langevin_coupling.py

@@ -0,0 +1,223 @@
+# 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-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: MIT
+"""
+
+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)
+
+        # 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)
+        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
+        ]