superlocalmemory 2.4.2 → 2.5.0

package/src/trust_scorer.py

@@ -0,0 +1,456 @@
+#!/usr/bin/env python3
+"""
+SuperLocalMemory V2 - Trust Scorer
+Copyright (c) 2026 Varun Pratap Bhardwaj
+Licensed under MIT License
+
+Repository: https://github.com/varun369/SuperLocalMemoryV2
+Author: Varun Pratap Bhardwaj (Solution Architect)
+
+NOTICE: This software is protected by MIT License.
+Attribution must be preserved in all copies or derivatives.
+"""
+
+"""
+TrustScorer — Silent trust signal collection for AI agents.
+
+v2.5 BEHAVIOR (this version):
+    - All agents start at trust 1.0
+    - Signals are collected silently (no enforcement, no ranking, no blocking)
+    - Trust scores are updated in agent_registry.trust_score
+    - Dashboard shows scores but they don't affect recall ordering yet
+
+v2.6 BEHAVIOR (future):
+    - Trust scores visible in dashboard
+    - Recall results ranked by trust (higher trust = higher in results)
+
+v3.0 BEHAVIOR (future):
+    - Active enforcement: quarantine low-trust memories, rate limiting
+    - Admin approval for untrusted agents
+
+Trust Signals (all silently collected):
+    POSITIVE (increase trust):
+        - Memory recalled by other agents (cross-agent validation)
+        - Memory updated (shows ongoing relevance)
+        - High importance memories (agent writes valuable content)
+        - Consistent write patterns (not spam-like)
+
+    NEGATIVE (decrease trust):
+        - Memory deleted shortly after creation (low quality)
+        - Very high write volume in short time (potential spam/poisoning)
+        - Content flagged or overwritten by user
+
+    NEUTRAL:
+        - Normal read/write patterns
+        - Agent disconnects/reconnects
+
+Scoring Algorithm:
+    Bayesian-inspired moving average. Each signal adjusts the score
+    by a small delta. Score is clamped to [0.0, 1.0].
+
+    new_score = old_score + (delta * decay_factor)
+    decay_factor = 1 / (1 + signal_count * 0.01)  # Stabilizes over time
+
+    This means early signals have more impact, and the score converges
+    as more data is collected. Similar to MACLA Beta-Binomial approach
+    (arXiv:2512.18950) but simplified for local computation.
+
+Security (OWASP for Agentic AI):
+    - Memory poisoning (#1 threat): Trust scoring is the first defense layer
+    - Over-permissioning: Trust scores inform future access control (v3.0)
+    - Agent impersonation: Agent ID + protocol tracking detects anomalies
+"""
+
+import json
+import logging
+import math
+import threading
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional, Dict, List
+
+logger = logging.getLogger("superlocalmemory.trust")
+
+# Signal deltas (how much each signal moves the trust score)
+SIGNAL_DELTAS = {
+    # Positive signals
+    "memory_recalled_by_others": +0.02,
+    "memory_updated": +0.01,
+    "high_importance_write": +0.015,   # importance >= 7
+    "consistent_pattern": +0.01,
+
+    # Negative signals
+    "quick_delete": -0.03,             # deleted within 1 hour of creation
+    "high_volume_burst": -0.02,        # >20 writes in 5 minutes
+    "content_overwritten_by_user": -0.01,
+
+    # Neutral (logged but no score change)
+    "normal_write": 0.0,
+    "normal_recall": 0.0,
+}
+
+# Thresholds
+QUICK_DELETE_HOURS = 1       # Delete within 1 hour = negative signal
+BURST_THRESHOLD = 20         # >20 writes in burst window = negative
+BURST_WINDOW_MINUTES = 5     # Burst detection window
+
+
+class TrustScorer:
+    """
+    Silent trust signal collector for AI agents.
+
+    v2.5: Collection only, no enforcement. All agents start at 1.0.
+    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 factor calculation)
+        self._signal_counts: Dict[str, int] = {}
+
+        self._init_schema()
+        logger.info("TrustScorer initialized (v2.5 — silent collection, no enforcement)")
+
+    def _init_schema(self):
+        """Create trust_signals table for audit trail."""
+        try:
+            from db_connection_manager import DbConnectionManager
+            mgr = DbConnectionManager.get_instance(self.db_path)
+
+            def _create(conn):
+                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)
+                ''')
+                conn.commit()
+
+            mgr.execute_write(_create)
+        except ImportError:
+            import sqlite3
+            conn = sqlite3.connect(str(self.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)')
+            conn.commit()
+            conn.close()
+
+    # =========================================================================
+    # Signal Recording
+    # =========================================================================
+
+    def record_signal(
+        self,
+        agent_id: str,
+        signal_type: str,
+        context: Optional[dict] = None,
+    ):
+        """
+        Record a trust signal for an agent.
+
+        Silently adjusts the agent's trust score based on the signal type.
+        The signal and score change are logged to trust_signals table.
+
+        Args:
+            agent_id: Agent that generated the signal
+            signal_type: One of SIGNAL_DELTAS keys
+            context: Additional context (memory_id, etc.)
+        """
+        if signal_type not in SIGNAL_DELTAS:
+            logger.warning("Unknown trust signal: %s", signal_type)
+            return
+
+        delta = SIGNAL_DELTAS[signal_type]
+
+        # Get current trust score from agent registry
+        old_score = self._get_agent_trust(agent_id)
+        if old_score is None:
+            old_score = 1.0  # Default for unknown agents
+
+        # Apply decay factor (score stabilizes over time)
+        count = self._signal_counts.get(agent_id, 0)
+        decay = 1.0 / (1.0 + count * 0.01)
+        adjusted_delta = delta * decay
+
+        # Calculate new score (clamped to [0.0, 1.0])
+        new_score = max(0.0, min(1.0, old_score + adjusted_delta))
+
+        # Update signal count
+        self._signal_counts[agent_id] = count + 1
+
+        # Persist signal to audit trail
+        self._persist_signal(agent_id, signal_type, adjusted_delta, old_score, new_score, context)
+
+        # Update agent trust score (if score actually changed)
+        if abs(new_score - old_score) > 0.0001:
+            self._update_agent_trust(agent_id, new_score)
+
+        logger.debug(
+            "Trust signal: agent=%s, type=%s, delta=%.4f, score=%.4f→%.4f",
+            agent_id, signal_type, adjusted_delta, old_score, new_score
+        )
+
+    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."""
+        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)
+
+    # =========================================================================
+    # 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
+
+    # =========================================================================
+    # Query Trust Data
+    # =========================================================================
+
+    def get_trust_score(self, agent_id: str) -> float:
+        """Get current trust score for an agent. Returns 1.0 if unknown."""
+        score = self._get_agent_trust(agent_id)
+        return score if score is not None else 1.0
+
+    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 1.0,
+                "enforcement": "disabled (v2.5 — silent collection only)",
+            }
+
+        except Exception as e:
+            logger.error("Failed to get trust stats: %s", e)
+            return {"total_signals": 0, "error": str(e)}

package/src/webhook_dispatcher.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+SuperLocalMemory V2 - Webhook Dispatcher
+Copyright (c) 2026 Varun Pratap Bhardwaj
+Licensed under MIT License
+
+Repository: https://github.com/varun369/SuperLocalMemoryV2
+Author: Varun Pratap Bhardwaj (Solution Architect)
+
+NOTICE: This software is protected by MIT License.
+Attribution must be preserved in all copies or derivatives.
+"""
+
+"""
+WebhookDispatcher — Delivers events via HTTP POST to configured webhook URLs.
+
+Runs on a background thread so webhook delivery never blocks the main event flow.
+Retries failed deliveries with exponential backoff (3 attempts).
+
+Security:
+    - Only allows http:// and https:// URLs
+    - Validates URL format before dispatch
+    - 10-second timeout per request
+    - No private/internal IP blocking in v2.5 (added in v2.6 with trust enforcement)
+"""
+
+import json
+import logging
+import threading
+import time
+from queue import Queue, Empty
+from typing import Optional, Dict
+from datetime import datetime
+
+logger = logging.getLogger("superlocalmemory.webhooks")
+
+# Configuration
+MAX_RETRIES = 3
+RETRY_BACKOFF_BASE = 2  # seconds: 2, 4, 8
+REQUEST_TIMEOUT = 10    # seconds
+MAX_QUEUE_SIZE = 1000
+
+# Optional: urllib3/requests for HTTP POST
+try:
+    from urllib.request import Request, urlopen
+    from urllib.error import URLError, HTTPError
+    HTTP_AVAILABLE = True
+except ImportError:
+    HTTP_AVAILABLE = False
+
+
+class WebhookDispatcher:
+    """
+    Background webhook delivery with retry logic.
+
+    Thread-safe. Enqueues webhook deliveries and processes them on a
+    dedicated background thread. Failed deliveries are retried with
+    exponential backoff.
+    """
+
+    _instances: Dict[str, "WebhookDispatcher"] = {}
+    _instances_lock = threading.Lock()
+
+    @classmethod
+    def get_instance(cls, name: str = "default") -> "WebhookDispatcher":
+        """Get or create a singleton WebhookDispatcher."""
+        with cls._instances_lock:
+            if name not in cls._instances:
+                cls._instances[name] = cls()
+            return cls._instances[name]
+
+    @classmethod
+    def reset_instance(cls, name: Optional[str] = None):
+        """Remove singleton(s). Used for testing."""
+        with cls._instances_lock:
+            if name is None:
+                for inst in cls._instances.values():
+                    inst.close()
+                cls._instances.clear()
+            elif name in cls._instances:
+                cls._instances[name].close()
+                del cls._instances[name]
+
+    def __init__(self):
+        self._queue: Queue = Queue(maxsize=MAX_QUEUE_SIZE)
+        self._closed = False
+        self._stats = {
+            "dispatched": 0,
+            "succeeded": 0,
+            "failed": 0,
+            "retries": 0,
+        }
+        self._stats_lock = threading.Lock()
+
+        # Background worker thread
+        self._worker = threading.Thread(
+            target=self._worker_loop,
+            name="slm-webhook-worker",
+            daemon=True,
+        )
+        self._worker.start()
+        logger.info("WebhookDispatcher started")
+
+    def dispatch(self, event: dict, webhook_url: str):
+        """
+        Enqueue a webhook delivery.
+
+        Args:
+            event: Event dict to send as JSON POST body
+            webhook_url: URL to POST to
+
+        Raises:
+            ValueError: If webhook_url is invalid
+            RuntimeError: If dispatcher is closed
+        """
+        if self._closed:
+            raise RuntimeError("WebhookDispatcher is closed")
+
+        if not webhook_url or not (webhook_url.startswith("http://") or webhook_url.startswith("https://")):
+            raise ValueError(f"Invalid webhook URL: {webhook_url}")
+
+        try:
+            self._queue.put_nowait({
+                "event": event,
+                "url": webhook_url,
+                "attempt": 0,
+                "enqueued_at": datetime.now().isoformat(),
+            })
+            with self._stats_lock:
+                self._stats["dispatched"] += 1
+        except Exception:
+            logger.warning("Webhook queue full, dropping event for %s", webhook_url)
+
+    def _worker_loop(self):
+        """Background worker: processes webhook deliveries sequentially."""
+        while not self._closed:
+            try:
+                item = self._queue.get(timeout=1.0)
+            except Empty:
+                continue
+
+            if item is None:  # Shutdown sentinel
+                self._queue.task_done()
+                break
+
+            self._deliver(item)
+            self._queue.task_done()
+
+    def _deliver(self, item: dict):
+        """Attempt to deliver a webhook. Retry on failure."""
+        event = item["event"]
+        url = item["url"]
+        attempt = item["attempt"]
+
+        if not HTTP_AVAILABLE:
+            logger.error("HTTP library not available, cannot deliver webhook to %s", url)
+            with self._stats_lock:
+                self._stats["failed"] += 1
+            return
+
+        try:
+            payload = json.dumps({
+                "event": event,
+                "delivered_at": datetime.now().isoformat(),
+                "attempt": attempt + 1,
+                "source": "superlocalmemory",
+                "version": "2.5.0",
+            }).encode("utf-8")
+
+            req = Request(
+                url,
+                data=payload,
+                headers={
+                    "Content-Type": "application/json",
+                    "User-Agent": "SuperLocalMemory/2.5.0",
+                    "X-SLM-Event-Type": event.get("event_type", "unknown"),
+                },
+                method="POST",
+            )
+
+            with urlopen(req, timeout=REQUEST_TIMEOUT) as resp:
+                status = resp.status
+                if 200 <= status < 300:
+                    with self._stats_lock:
+                        self._stats["succeeded"] += 1
+                    logger.debug("Webhook delivered: url=%s, status=%d", url, status)
+                    return
+                else:
+                    raise HTTPError(url, status, f"HTTP {status}", {}, None)
+
+        except Exception as e:
+            logger.warning("Webhook delivery failed (attempt %d/%d): url=%s, error=%s",
+                          attempt + 1, MAX_RETRIES, url, e)
+
+            if attempt + 1 < MAX_RETRIES:
+                # Retry with exponential backoff
+                backoff = RETRY_BACKOFF_BASE ** (attempt + 1)
+                time.sleep(backoff)
+                with self._stats_lock:
+                    self._stats["retries"] += 1
+                item["attempt"] = attempt + 1
+                self._deliver(item)  # Recursive retry
+            else:
+                with self._stats_lock:
+                    self._stats["failed"] += 1
+                logger.error("Webhook permanently failed after %d attempts: url=%s", MAX_RETRIES, url)
+
+    def get_stats(self) -> dict:
+        """Get webhook delivery statistics."""
+        with self._stats_lock:
+            return dict(self._stats)
+
+    def close(self):
+        """Shut down the dispatcher. Drains remaining items."""
+        if self._closed:
+            return
+        self._closed = True
+        self._queue.put(None)  # Shutdown sentinel
+        if self._worker.is_alive():
+            self._worker.join(timeout=5)
+        logger.info("WebhookDispatcher closed: stats=%s", self._stats)
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    @property
+    def queue_size(self) -> int:
+        return self._queue.qsize()