superlocalmemory 2.8.6 → 3.0.0

package/src/trust/queries.py

@@ -1,157 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""
-Trust query and enforcement mixin for TrustScorer.
-
-Contains: get_trust_score, get_beta_params, check_trust, get_signals, get_trust_stats.
-"""
-
-import json
-import logging
-from typing import Dict, List
-
-from .constants import INITIAL_ALPHA, INITIAL_BETA
-
-logger = logging.getLogger("superlocalmemory.trust")
-
-
-class TrustQueryMixin:
-    """Mixin providing trust query, enforcement, and stats methods."""
-
-    def get_trust_score(self, agent_id: str) -> float:
-        """
-        Get current trust score for an agent.
-
-        Computes alpha/(alpha+beta) from cached or stored Beta params.
-        Returns INITIAL_ALPHA/(INITIAL_ALPHA+INITIAL_BETA) = 0.667 for
-        unknown agents.
-        """
-        alpha, beta = self._get_beta_params(agent_id)
-        if (alpha + beta) > 0:
-            return alpha / (alpha + beta)
-        return INITIAL_ALPHA / (INITIAL_ALPHA + INITIAL_BETA)
-
-    def get_beta_params(self, agent_id: str) -> Dict[str, float]:
-        """
-        Get the Beta distribution parameters for an agent.
-
-        Returns:
-            {"alpha": float, "beta": float, "trust_score": float}
-        """
-        alpha, beta = self._get_beta_params(agent_id)
-        score = alpha / (alpha + beta) if (alpha + beta) > 0 else 0.0
-        return {
-            "alpha": round(alpha, 4),
-            "beta": round(beta, 4),
-            "trust_score": round(score, 4),
-        }
-
-    def check_trust(self, agent_id: str, operation: str = "write") -> bool:
-        """
-        Check if agent is trusted enough for the given operation.
-
-        v2.6 enforcement: blocks write/delete for agents with trust < 0.3.
-
-        Args:
-            agent_id: The agent identifier
-            operation: One of "read", "write", "delete"
-
-        Returns:
-            True if operation is allowed, False if blocked
-        """
-        if operation == "read":
-            return True  # Reads are always allowed
-
-        score = self.get_trust_score(agent_id)
-
-        threshold = 0.3  # Block write/delete below this
-        if score < threshold:
-            logger.warning(
-                "Trust enforcement: agent '%s' blocked from '%s' (trust=%.4f < %.2f)",
-                agent_id, operation, score, threshold
-            )
-            return False
-
-        return True
-
-    def get_signals(self, agent_id: str, limit: int = 50) -> List[dict]:
-        """Get recent trust signals for an agent."""
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            with mgr.read_connection() as conn:
-                cursor = conn.cursor()
-                cursor.execute("""
-                    SELECT signal_type, delta, old_score, new_score, context, created_at
-                    FROM trust_signals
-                    WHERE agent_id = ?
-                    ORDER BY created_at DESC
-                    LIMIT ?
-                """, (agent_id, limit))
-
-                signals = []
-                for row in cursor.fetchall():
-                    ctx = {}
-                    try:
-                        ctx = json.loads(row[4]) if row[4] else {}
-                    except (json.JSONDecodeError, TypeError):
-                        pass
-                    signals.append({
-                        "signal_type": row[0],
-                        "delta": row[1],
-                        "old_score": row[2],
-                        "new_score": row[3],
-                        "context": ctx,
-                        "created_at": row[5],
-                    })
-                return signals
-
-        except Exception as e:
-            logger.error("Failed to get trust signals: %s", e)
-            return []
-
-    def get_trust_stats(self) -> dict:
-        """Get trust system statistics."""
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            with mgr.read_connection() as conn:
-                cursor = conn.cursor()
-
-                cursor.execute("SELECT COUNT(*) FROM trust_signals")
-                total_signals = cursor.fetchone()[0]
-
-                cursor.execute("""
-                    SELECT signal_type, COUNT(*) FROM trust_signals
-                    GROUP BY signal_type ORDER BY COUNT(*) DESC
-                """)
-                by_type = dict(cursor.fetchall())
-
-                cursor.execute("""
-                    SELECT agent_id, COUNT(*) FROM trust_signals
-                    GROUP BY agent_id ORDER BY COUNT(*) DESC LIMIT 10
-                """)
-                by_agent = dict(cursor.fetchall())
-
-                cursor.execute("""
-                    SELECT AVG(trust_score) FROM agent_registry
-                    WHERE trust_score IS NOT NULL
-                """)
-                avg = cursor.fetchone()[0]
-
-            return {
-                "total_signals": total_signals,
-                "by_signal_type": by_type,
-                "by_agent": by_agent,
-                "avg_trust_score": round(avg, 4) if avg else INITIAL_ALPHA / (INITIAL_ALPHA + INITIAL_BETA),
-                "scoring_model": "Beta-Binomial",
-                "prior": f"Beta({INITIAL_ALPHA}, {INITIAL_BETA})",
-                "enforcement": "enabled (v2.6 -- write/delete blocked below 0.3 trust)",
-            }
-
-        except Exception as e:
-            logger.error("Failed to get trust stats: %s", e)
-            return {"total_signals": 0, "error": str(e)}

package/src/trust/schema.py

@@ -1,95 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""
-Database schema initialization for the trust scoring system.
-
-Creates trust_signals table and adds alpha/beta columns to agent_registry.
-Extracted from TrustScorer._init_schema for modularity.
-"""
-
-from pathlib import Path
-
-from .constants import INITIAL_ALPHA, INITIAL_BETA
-
-
-def init_trust_schema(db_path: Path):
-    """
-    Create trust_signals table and add alpha/beta columns to agent_registry.
-
-    Handles both DbConnectionManager (preferred) and direct sqlite3 fallback.
-
-    Args:
-        db_path: Path to the SQLite database file.
-    """
-    try:
-        from db_connection_manager import DbConnectionManager
-        mgr = DbConnectionManager.get_instance(db_path)
-
-        def _create(conn):
-            # Trust signals audit trail
-            conn.execute('''
-                CREATE TABLE IF NOT EXISTS trust_signals (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT,
-                    agent_id TEXT NOT NULL,
-                    signal_type TEXT NOT NULL,
-                    delta REAL NOT NULL,
-                    old_score REAL,
-                    new_score REAL,
-                    context TEXT DEFAULT '{}',
-                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-                )
-            ''')
-            conn.execute('''
-                CREATE INDEX IF NOT EXISTS idx_trust_agent
-                ON trust_signals(agent_id)
-            ''')
-            conn.execute('''
-                CREATE INDEX IF NOT EXISTS idx_trust_created
-                ON trust_signals(created_at)
-            ''')
-
-            # Add trust_alpha and trust_beta columns to agent_registry
-            # (backward compatible -- old databases get these columns added)
-            for col_name, col_default in [("trust_alpha", INITIAL_ALPHA),
-                                           ("trust_beta", INITIAL_BETA)]:
-                try:
-                    conn.execute(
-                        f'ALTER TABLE agent_registry ADD COLUMN {col_name} REAL DEFAULT {col_default}'
-                    )
-                except Exception:
-                    pass  # Column already exists
-
-            conn.commit()
-
-        mgr.execute_write(_create)
-    except ImportError:
-        import sqlite3
-        conn = sqlite3.connect(str(db_path))
-        conn.execute('''
-            CREATE TABLE IF NOT EXISTS trust_signals (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                agent_id TEXT NOT NULL,
-                signal_type TEXT NOT NULL,
-                delta REAL NOT NULL,
-                old_score REAL,
-                new_score REAL,
-                context TEXT DEFAULT '{}',
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-            )
-        ''')
-        conn.execute('CREATE INDEX IF NOT EXISTS idx_trust_agent ON trust_signals(agent_id)')
-        conn.execute('CREATE INDEX IF NOT EXISTS idx_trust_created ON trust_signals(created_at)')
-
-        # Add trust_alpha and trust_beta columns (backward compatible)
-        for col_name, col_default in [("trust_alpha", INITIAL_ALPHA),
-                                       ("trust_beta", INITIAL_BETA)]:
-            try:
-                conn.execute(
-                    f'ALTER TABLE agent_registry ADD COLUMN {col_name} REAL DEFAULT {col_default}'
-                )
-            except sqlite3.OperationalError:
-                pass  # Column already exists
-
-        conn.commit()
-        conn.close()

package/src/trust/scorer.py

@@ -1,299 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""SuperLocalMemory V2 - Trust Scorer (core class)
-. MIT License.
-
-Bayesian Beta-Binomial trust scoring for AI agents.
-Core class with Beta parameter management and signal recording.
-Query/stats via TrustQueryMixin; signal helpers via TrustSignalsMixin.
-"""
-import json
-import logging
-import threading
-from pathlib import Path
-from typing import Optional, Dict
-
-from .constants import (
-    SIGNAL_WEIGHTS,
-    INITIAL_ALPHA,
-    INITIAL_BETA,
-    DECAY_FACTOR,
-    DECAY_INTERVAL,
-    ALPHA_FLOOR,
-    BETA_FLOOR,
-)
-from .schema import init_trust_schema
-from .signals import TrustSignalsMixin
-from .queries import TrustQueryMixin
-
-logger = logging.getLogger("superlocalmemory.trust")
-
-
-class TrustScorer(TrustSignalsMixin, TrustQueryMixin):
-    """
-    Bayesian Beta-Binomial trust scorer for AI agents.
-
-    Each agent is modeled as Beta(alpha, beta). Positive signals
-    increment alpha, negative signals increment beta. The trust
-    score is the posterior mean: alpha / (alpha + beta).
-
-    Thread-safe singleton per database path.
-    """
-
-    _instances: Dict[str, "TrustScorer"] = {}
-    _instances_lock = threading.Lock()
-
-    @classmethod
-    def get_instance(cls, db_path: Optional[Path] = None) -> "TrustScorer":
-        """Get or create the singleton TrustScorer."""
-        if db_path is None:
-            db_path = Path.home() / ".claude-memory" / "memory.db"
-        key = str(db_path)
-        with cls._instances_lock:
-            if key not in cls._instances:
-                cls._instances[key] = cls(db_path)
-            return cls._instances[key]
-
-    @classmethod
-    def reset_instance(cls, db_path: Optional[Path] = None):
-        """Remove singleton. Used for testing."""
-        with cls._instances_lock:
-            if db_path is None:
-                cls._instances.clear()
-            else:
-                key = str(db_path)
-                if key in cls._instances:
-                    del cls._instances[key]
-
-    def __init__(self, db_path: Path):
-        self.db_path = Path(db_path)
-
-        # In-memory signal log for burst detection (agent_id -> list of timestamps)
-        self._write_timestamps: Dict[str, list] = {}
-        self._timestamps_lock = threading.Lock()
-
-        # Signal count per agent (for decay interval tracking)
-        self._signal_counts: Dict[str, int] = {}
-
-        # In-memory cache of Beta parameters per agent
-        # Key: agent_id, Value: (alpha, beta)
-        self._beta_params: Dict[str, tuple] = {}
-        self._beta_lock = threading.Lock()
-
-        self._init_schema()
-        logger.info("TrustScorer initialized (Beta-Binomial -- alpha=%.1f, beta=%.1f prior)",
-                     INITIAL_ALPHA, INITIAL_BETA)
-
-    def _init_schema(self):
-        """Create trust_signals table and add alpha/beta columns to agent_registry."""
-        init_trust_schema(self.db_path)
-
-    # =========================================================================
-    # Beta Parameter Management
-    # =========================================================================
-
-    def _get_beta_params(self, agent_id: str) -> tuple:
-        """
-        Get (alpha, beta) for an agent. Checks in-memory cache first,
-        then database, then falls back to prior defaults.
-
-        Returns:
-            (alpha, beta) tuple
-        """
-        with self._beta_lock:
-            if agent_id in self._beta_params:
-                return self._beta_params[agent_id]
-
-        # Not in cache -- read from database
-        alpha, beta = None, None
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            with mgr.read_connection() as conn:
-                cursor = conn.cursor()
-                cursor.execute(
-                    "SELECT trust_alpha, trust_beta FROM agent_registry WHERE agent_id = ?",
-                    (agent_id,)
-                )
-                row = cursor.fetchone()
-                if row:
-                    alpha = row[0]
-                    beta = row[1]
-        except Exception:
-            pass
-
-        # Fall back to defaults if NULL or missing
-        if alpha is None or beta is None:
-            alpha = INITIAL_ALPHA
-            beta = INITIAL_BETA
-
-        with self._beta_lock:
-            self._beta_params[agent_id] = (alpha, beta)
-
-        return (alpha, beta)
-
-    def _set_beta_params(self, agent_id: str, alpha: float, beta: float):
-        """
-        Update (alpha, beta) in cache and persist to agent_registry.
-        Also computes and stores the derived trust_score = alpha/(alpha+beta).
-        """
-        trust_score = alpha / (alpha + beta) if (alpha + beta) > 0 else 0.0
-
-        with self._beta_lock:
-            self._beta_params[agent_id] = (alpha, beta)
-
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            def _update(conn):
-                conn.execute(
-                    """UPDATE agent_registry
-                       SET trust_score = ?, trust_alpha = ?, trust_beta = ?
-                       WHERE agent_id = ?""",
-                    (round(trust_score, 4), round(alpha, 4), round(beta, 4), agent_id)
-                )
-                conn.commit()
-
-            mgr.execute_write(_update)
-        except Exception as e:
-            logger.error("Failed to persist Beta params for %s: %s", agent_id, e)
-
-    def _apply_decay(self, agent_id: str, alpha: float, beta: float) -> tuple:
-        """
-        Apply periodic decay to alpha and beta to forget very old signals.
-
-        Called every DECAY_INTERVAL signals per agent.
-        Multiplies both by DECAY_FACTOR with floor constraints.
-
-        Returns:
-            (decayed_alpha, decayed_beta)
-        """
-        new_alpha = max(ALPHA_FLOOR, alpha * DECAY_FACTOR)
-        new_beta = max(BETA_FLOOR, beta * DECAY_FACTOR)
-        return (new_alpha, new_beta)
-
-    # =========================================================================
-    # Signal Recording (Beta-Binomial Update)
-    # =========================================================================
-
-    def record_signal(
-        self,
-        agent_id: str,
-        signal_type: str,
-        context: Optional[dict] = None,
-    ) -> bool:
-        """
-        Record a trust signal for an agent using Beta-Binomial update.
-
-        Args:
-            agent_id: Agent that generated the signal
-            signal_type: One of SIGNAL_WEIGHTS keys
-            context: Additional context (memory_id, etc.)
-
-        Returns:
-            True if signal was recorded successfully
-        """
-        if signal_type not in SIGNAL_WEIGHTS:
-            logger.warning("Unknown trust signal: %s", signal_type)
-            return False
-
-        direction, weight = SIGNAL_WEIGHTS[signal_type]
-
-        # Get current Beta parameters
-        alpha, beta = self._get_beta_params(agent_id)
-        old_score = alpha / (alpha + beta) if (alpha + beta) > 0 else 0.0
-
-        # Apply Beta-Binomial update
-        if direction == "positive":
-            alpha += weight
-        elif direction == "negative":
-            beta += weight
-        else:  # neutral -- tiny alpha nudge
-            alpha += weight
-
-        # Apply periodic decay
-        count = self._signal_counts.get(agent_id, 0) + 1
-        self._signal_counts[agent_id] = count
-
-        if count % DECAY_INTERVAL == 0:
-            alpha, beta = self._apply_decay(agent_id, alpha, beta)
-
-        # Compute new trust score (posterior mean)
-        new_score = alpha / (alpha + beta) if (alpha + beta) > 0 else 0.0
-
-        # Compute delta for audit trail
-        delta = new_score - old_score
-
-        # Persist signal to audit trail
-        self._persist_signal(agent_id, signal_type, delta, old_score, new_score, context)
-
-        # Persist updated Beta parameters and derived trust_score
-        self._set_beta_params(agent_id, alpha, beta)
-
-        logger.debug(
-            "Trust signal: agent=%s, type=%s (%s, w=%.2f), "
-            "alpha=%.2f, beta=%.2f, score=%.4f->%.4f",
-            agent_id, signal_type, direction, weight,
-            alpha, beta, old_score, new_score
-        )
-
-        return True
-
-    def _persist_signal(self, agent_id, signal_type, delta, old_score, new_score, context):
-        """Save signal to trust_signals table."""
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            def _insert(conn):
-                conn.execute('''
-                    INSERT INTO trust_signals (agent_id, signal_type, delta, old_score, new_score, context)
-                    VALUES (?, ?, ?, ?, ?, ?)
-                ''', (agent_id, signal_type, delta, old_score, new_score, json.dumps(context or {})))
-                conn.commit()
-
-            mgr.execute_write(_insert)
-        except Exception as e:
-            logger.error("Failed to persist trust signal: %s", e)
-
-    def _get_agent_trust(self, agent_id: str) -> Optional[float]:
-        """Get current trust score from agent_registry."""
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            with mgr.read_connection() as conn:
-                cursor = conn.cursor()
-                cursor.execute(
-                    "SELECT trust_score FROM agent_registry WHERE agent_id = ?",
-                    (agent_id,)
-                )
-                row = cursor.fetchone()
-                return row[0] if row else None
-        except Exception:
-            return None
-
-    def _update_agent_trust(self, agent_id: str, new_score: float):
-        """
-        Update trust score in agent_registry (legacy compatibility method).
-
-        In Beta-Binomial mode, _set_beta_params already updates trust_score
-        alongside alpha and beta. Kept for backward compatibility.
-        """
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            def _update(conn):
-                conn.execute(
-                    "UPDATE agent_registry SET trust_score = ? WHERE agent_id = ?",
-                    (round(new_score, 4), agent_id)
-                )
-                conn.commit()
-
-            mgr.execute_write(_update)
-        except Exception as e:
-            logger.error("Failed to update agent trust: %s", e)

package/src/trust/signals.py

@@ -1,95 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""
-High-level signal helpers and burst detection mixin for TrustScorer.
-
-Contains: on_memory_created, on_memory_deleted, on_memory_recalled,
-          _track_write, _is_burst.
-"""
-
-import logging
-from datetime import datetime, timedelta
-from typing import Optional
-
-from .constants import (
-    QUICK_DELETE_HOURS,
-    BURST_THRESHOLD,
-    BURST_WINDOW_MINUTES,
-)
-
-logger = logging.getLogger("superlocalmemory.trust")
-
-
-class TrustSignalsMixin:
-    """Mixin providing high-level signal helpers and burst detection."""
-
-    # =========================================================================
-    # High-Level Signal Helpers (called from memory_store_v2 / mcp_server)
-    # =========================================================================
-
-    def on_memory_created(self, agent_id: str, memory_id: int, importance: int = 5):
-        """Record signals when a memory is created."""
-        # Track write timestamp for burst detection
-        self._track_write(agent_id)
-
-        if importance >= 7:
-            self.record_signal(agent_id, "high_importance_write",
-                             context={"memory_id": memory_id, "importance": importance})
-        else:
-            self.record_signal(agent_id, "normal_write",
-                             context={"memory_id": memory_id})
-
-        # Check for burst pattern
-        if self._is_burst(agent_id):
-            self.record_signal(agent_id, "high_volume_burst",
-                             context={"memory_id": memory_id})
-
-    def on_memory_deleted(self, agent_id: str, memory_id: int, created_at: Optional[str] = None):
-        """Record signals when a memory is deleted."""
-        if created_at:
-            try:
-                created = datetime.fromisoformat(created_at)
-                age_hours = (datetime.now() - created).total_seconds() / 3600
-                if age_hours < QUICK_DELETE_HOURS:
-                    self.record_signal(agent_id, "quick_delete",
-                                     context={"memory_id": memory_id, "age_hours": round(age_hours, 2)})
-                    return
-            except (ValueError, TypeError):
-                pass
-
-        # Normal delete (no negative signal)
-        self.record_signal(agent_id, "normal_write",
-                         context={"memory_id": memory_id, "action": "delete"})
-
-    def on_memory_recalled(self, agent_id: str, memory_id: int, created_by: Optional[str] = None):
-        """Record signals when a memory is recalled."""
-        if created_by and created_by != agent_id:
-            # Cross-agent validation: another agent found this memory useful
-            self.record_signal(created_by, "memory_recalled_by_others",
-                             context={"memory_id": memory_id, "recalled_by": agent_id})
-
-        self.record_signal(agent_id, "normal_recall",
-                         context={"memory_id": memory_id})
-
-    # =========================================================================
-    # Burst Detection
-    # =========================================================================
-
-    def _track_write(self, agent_id: str):
-        """Track a write timestamp for burst detection."""
-        now = datetime.now()
-        with self._timestamps_lock:
-            if agent_id not in self._write_timestamps:
-                self._write_timestamps[agent_id] = []
-            timestamps = self._write_timestamps[agent_id]
-            timestamps.append(now)
-            # Keep only recent timestamps (within burst window)
-            cutoff = now - timedelta(minutes=BURST_WINDOW_MINUTES)
-            self._write_timestamps[agent_id] = [t for t in timestamps if t > cutoff]
-
-    def _is_burst(self, agent_id: str) -> bool:
-        """Check if agent is in a burst write pattern."""
-        with self._timestamps_lock:
-            timestamps = self._write_timestamps.get(agent_id, [])
-            return len(timestamps) > BURST_THRESHOLD

package/src/trust_scorer.py

@@ -1,44 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""
-Backward-compatible shim -- delegates to src/trust/ package.
-
-All public symbols are re-exported so existing imports like
-``from trust_scorer import TrustScorer`` continue to work unchanged.
-"""
-
-# Re-export everything from the trust package
-from trust.constants import (  # noqa: F401
-    SIGNAL_WEIGHTS,
-    SIGNAL_DELTAS,
-    INITIAL_ALPHA,
-    INITIAL_BETA,
-    DECAY_FACTOR,
-    DECAY_INTERVAL,
-    ALPHA_FLOOR,
-    BETA_FLOOR,
-    QUICK_DELETE_HOURS,
-    BURST_THRESHOLD,
-    BURST_WINDOW_MINUTES,
-)
-
-from trust.schema import init_trust_schema  # noqa: F401
-
-from trust.scorer import TrustScorer  # noqa: F401
-
-__all__ = [
-    "TrustScorer",
-    "SIGNAL_WEIGHTS",
-    "SIGNAL_DELTAS",
-    "INITIAL_ALPHA",
-    "INITIAL_BETA",
-    "DECAY_FACTOR",
-    "DECAY_INTERVAL",
-    "ALPHA_FLOOR",
-    "BETA_FLOOR",
-    "QUICK_DELETE_HOURS",
-    "BURST_THRESHOLD",
-    "BURST_WINDOW_MINUTES",
-    "init_trust_schema",
-]