superlocalmemory 2.7.5 → 2.8.0

package/src/behavioral/behavioral_listener.py

@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""EventBus listener that bridges events to the behavioral learning engine.
+
+Listens for memory.recalled, memory.deleted, and usage events.
+Feeds recall events to OutcomeInference for implicit outcome detection.
+Triggers pattern extraction after configurable outcome count threshold.
+
+Part of SLM v2.8 Behavioral Learning Engine.
+"""
+import logging
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+
+from .outcome_tracker import OutcomeTracker
+from .outcome_inference import OutcomeInference
+
+logger = logging.getLogger("superlocalmemory.behavioral.listener")
+
+# Default: extract patterns every 100 new outcomes
+DEFAULT_EXTRACTION_THRESHOLD = 100
+
+
+class BehavioralListener:
+    """EventBus listener that feeds events to the behavioral learning engine.
+
+    Processes:
+    - memory.recalled  -> feeds to OutcomeInference (implicit outcome detection)
+    - memory.deleted   -> records deletion for inference (Rule 1 signal)
+    - Usage signals    -> records for inference (Rule 2/3 signals)
+
+    Thread-safe: handle_event can be called from any thread.
+    Listener callbacks run on the emitter's thread -- must be fast.
+    """
+
+    # Event types this listener cares about
+    _RECALL_EVENT = "memory.recalled"
+    _DELETION_EVENT = "memory.deleted"
+
+    def __init__(
+        self,
+        db_path: Optional[str] = None,
+        extraction_threshold: int = DEFAULT_EXTRACTION_THRESHOLD,
+    ):
+        if db_path is None:
+            db_path = str(Path.home() / ".claude-memory" / "learning.db")
+        self._db_path = str(db_path)
+        self.extraction_threshold = extraction_threshold
+
+        # Core components
+        self._tracker = OutcomeTracker(self._db_path)
+        self._inference = OutcomeInference()
+
+        # Thread safety
+        self._lock = threading.Lock()
+
+        # Counters
+        self.events_processed = 0
+        self.recall_events_processed = 0
+        self.deletion_events_processed = 0
+        self._outcome_count_since_extraction = 0
+        self._registered = False
+
+    # ------------------------------------------------------------------
+    # Event handling (called on emitter's thread — must be fast)
+    # ------------------------------------------------------------------
+
+    def handle_event(self, event: Dict[str, Any]) -> None:
+        """Process an EventBus event.
+
+        Called on the emitter's thread — must be fast and non-blocking.
+        Filters by event_type and dispatches to the appropriate handler.
+        """
+        event_type = event.get("event_type", "")
+        payload = event.get("payload", {})
+        memory_id = event.get("memory_id")
+        timestamp_str = event.get("timestamp")
+
+        try:
+            timestamp = (
+                datetime.fromisoformat(timestamp_str)
+                if timestamp_str
+                else datetime.now()
+            )
+        except (ValueError, TypeError):
+            timestamp = datetime.now()
+
+        with self._lock:
+            self.events_processed += 1
+
+            if event_type == self._RECALL_EVENT:
+                self._handle_recall(payload, memory_id, timestamp)
+
+            elif event_type == self._DELETION_EVENT:
+                self._handle_deletion(memory_id, timestamp)
+            # All other event types are silently ignored
+
+    def _handle_recall(
+        self,
+        payload: Dict[str, Any],
+        memory_id: Optional[int],
+        timestamp: datetime,
+    ) -> None:
+        """Process a memory.recalled event. Must be called under self._lock."""
+        query = payload.get("query", "")
+        memory_ids = payload.get(
+            "memory_ids", [memory_id] if memory_id else []
+        )
+        signal = payload.get("signal")
+
+        self._inference.record_recall(query, memory_ids, timestamp)
+        if signal:
+            self._inference.record_usage(
+                query, signal=signal, timestamp=timestamp
+            )
+        self.recall_events_processed += 1
+
+        # Periodically run inference (every 10 recall events)
+        if self.recall_events_processed % 10 == 0:
+            self._run_inference_cycle()
+
+    def _handle_deletion(
+        self, memory_id: Optional[int], timestamp: datetime
+    ) -> None:
+        """Process a memory.deleted event. Must be called under self._lock."""
+        if memory_id is not None:
+            self._inference.record_deletion(memory_id, timestamp)
+            self.deletion_events_processed += 1
+
+    # ------------------------------------------------------------------
+    # Inference + pattern extraction
+    # ------------------------------------------------------------------
+
+    def _run_inference_cycle(self) -> None:
+        """Run outcome inference and optionally trigger pattern extraction."""
+        inferences: List[Dict] = self._inference.infer_outcomes(
+            datetime.now()
+        )
+        for inf in inferences:
+            self._tracker.record_outcome(
+                memory_ids=inf["memory_ids"],
+                outcome=inf["outcome"],
+                action_type="inferred",
+                confidence=inf["confidence"],
+                context={"reason": inf.get("reason", "")},
+            )
+            self._outcome_count_since_extraction += 1
+
+        if self._outcome_count_since_extraction >= self.extraction_threshold:
+            self._trigger_extraction()
+
+    def _trigger_extraction(self) -> None:
+        """Trigger behavioral pattern extraction. Best-effort."""
+        try:
+            from .behavioral_patterns import BehavioralPatternExtractor
+
+            extractor = BehavioralPatternExtractor(self._db_path)
+            extractor.extract_patterns()
+            extractor.save_patterns()
+            self._outcome_count_since_extraction = 0
+        except Exception as exc:
+            logger.warning("Pattern extraction failed: %s", exc)
+
+    # ------------------------------------------------------------------
+    # EventBus registration
+    # ------------------------------------------------------------------
+
+    def register_with_eventbus(self) -> bool:
+        """Register this listener with the EventBus singleton.
+
+        Returns True if registration succeeds, False otherwise.
+        Graceful degradation: failure here does NOT break the engine.
+        """
+        try:
+            from event_bus import EventBus
+
+            bus = EventBus.get_instance(Path(self._db_path))
+            bus.add_listener(self.handle_event)
+            self._registered = True
+            return True
+        except Exception as exc:
+            logger.info(
+                "EventBus registration skipped (not available): %s", exc
+            )
+            self._registered = False
+            return False
+
+    # ------------------------------------------------------------------
+    # Status / introspection
+    # ------------------------------------------------------------------
+
+    def get_status(self) -> Dict[str, Any]:
+        """Return listener status for diagnostics."""
+        return {
+            "events_processed": self.events_processed,
+            "recall_events_processed": self.recall_events_processed,
+            "deletion_events_processed": self.deletion_events_processed,
+            "registered": self._registered,
+            "outcome_count_since_extraction": self._outcome_count_since_extraction,
+            "extraction_threshold": self.extraction_threshold,
+        }

package/src/behavioral/behavioral_patterns.py

@@ -0,0 +1,275 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Pattern extraction from action outcome histories.
+
+Scans the action_outcomes table, groups by project and action_type,
+calculates success rates, and stores discovered patterns in the
+behavioral_patterns table. Self-contained: creates its own table via
+CREATE TABLE IF NOT EXISTS so no external migration is needed.
+
+Part of SLM v2.8 Behavioral Learning Engine.
+"""
+import json
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Any
+
+
+class BehavioralPatternExtractor:
+    """Extracts success/failure patterns from outcome data.
+
+    Analyzes action_outcomes rows to discover:
+      - project_success: success rate per project
+      - action_type_success: success rate per action_type
+
+    Confidence formula:
+        min(evidence_count / 10, 1.0) * abs(success_rate - 0.5) * 2
+    This yields high confidence only when there is enough evidence AND the
+    success rate is far from the 50/50 coin-flip baseline.
+    """
+
+    PATTERN_TYPES = ("project_success", "action_type_success")
+
+    _CREATE_TABLE = """
+        CREATE TABLE IF NOT EXISTS behavioral_patterns (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            pattern_type TEXT NOT NULL,
+            pattern_key TEXT NOT NULL,
+            success_rate REAL DEFAULT 0.0,
+            evidence_count INTEGER DEFAULT 0,
+            confidence REAL DEFAULT 0.0,
+            metadata TEXT DEFAULT '{}',
+            project TEXT,
+            profile TEXT DEFAULT 'default',
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+    """
+
+    # Minimum outcomes required before we emit a pattern at all.
+    MIN_EVIDENCE = 3
+
+    def __init__(self, db_path: Optional[str] = None):
+        self._db_path = db_path
+        self._lock = threading.Lock()
+        self._patterns: List[Dict[str, Any]] = []
+        if db_path:
+            self._ensure_table()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def extract_patterns(self) -> List[Dict[str, Any]]:
+        """Scan action_outcomes and extract success/failure patterns.
+
+        Groups outcomes by project and by action_type, calculates
+        success rates, and returns a list of pattern dicts. Also stores
+        the result internally so a subsequent ``save_patterns()`` call
+        can persist them.
+
+        Returns:
+            List of pattern dicts with keys: pattern_type, pattern_key,
+            success_rate, evidence_count, confidence, metadata, project.
+        """
+        patterns: List[Dict[str, Any]] = []
+        with self._lock:
+            conn = self._connect()
+            try:
+                patterns.extend(self._extract_project_patterns(conn))
+                patterns.extend(self._extract_action_type_patterns(conn))
+            finally:
+                conn.close()
+        self._patterns = patterns
+        return patterns
+
+    def save_patterns(self) -> int:
+        """Persist the most recently extracted patterns to the DB.
+
+        Inserts (or replaces) rows in the behavioral_patterns table.
+
+        Returns:
+            Number of patterns saved.
+        """
+        if not self._patterns:
+            return 0
+
+        now = datetime.now(timezone.utc).isoformat()
+        with self._lock:
+            conn = self._connect()
+            try:
+                for p in self._patterns:
+                    # Upsert: delete any existing row for the same
+                    # (pattern_type, pattern_key, project) then insert.
+                    conn.execute(
+                        """DELETE FROM behavioral_patterns
+                           WHERE pattern_type = ? AND pattern_key = ?
+                                 AND COALESCE(project, '') = COALESCE(?, '')""",
+                        (p["pattern_type"], p["pattern_key"], p.get("project")),
+                    )
+                    conn.execute(
+                        """INSERT INTO behavioral_patterns
+                           (pattern_type, pattern_key, success_rate,
+                            evidence_count, confidence, metadata,
+                            project, created_at, updated_at)
+                           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                        (
+                            p["pattern_type"],
+                            p["pattern_key"],
+                            p["success_rate"],
+                            p["evidence_count"],
+                            p["confidence"],
+                            json.dumps(p.get("metadata", {})),
+                            p.get("project"),
+                            now,
+                            now,
+                        ),
+                    )
+                conn.commit()
+                return len(self._patterns)
+            finally:
+                conn.close()
+
+    def get_patterns(
+        self,
+        min_confidence: float = 0.0,
+        project: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Read stored patterns from the DB with optional filters.
+
+        Args:
+            min_confidence: Only return patterns with confidence >= this.
+            project: If given, filter by project scope.
+
+        Returns:
+            List of pattern dicts read from the database.
+        """
+        with self._lock:
+            conn = self._connect()
+            try:
+                query = (
+                    "SELECT * FROM behavioral_patterns "
+                    "WHERE confidence >= ?"
+                )
+                params: List[Any] = [min_confidence]
+                if project is not None:
+                    query += " AND project = ?"
+                    params.append(project)
+                query += " ORDER BY confidence DESC"
+                rows = conn.execute(query, params).fetchall()
+                return [self._row_to_dict(r) for r in rows]
+            finally:
+                conn.close()
+
+    # ------------------------------------------------------------------
+    # Internal extraction helpers
+    # ------------------------------------------------------------------
+
+    def _extract_project_patterns(
+        self, conn: sqlite3.Connection
+    ) -> List[Dict[str, Any]]:
+        """Group outcomes by project and compute success rates."""
+        rows = conn.execute(
+            """SELECT project,
+                      COUNT(*) AS total,
+                      SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS wins
+               FROM action_outcomes
+               WHERE project IS NOT NULL
+               GROUP BY project
+               HAVING total >= ?""",
+            (self.MIN_EVIDENCE,),
+        ).fetchall()
+
+        patterns = []
+        for row in rows:
+            project = row[0]
+            total = row[1]
+            wins = row[2]
+            rate = round(wins / total, 4) if total else 0.0
+            confidence = self._compute_confidence(total, rate)
+            patterns.append(
+                {
+                    "pattern_type": "project_success",
+                    "pattern_key": project,
+                    "success_rate": rate,
+                    "evidence_count": total,
+                    "confidence": confidence,
+                    "metadata": {"wins": wins, "losses": total - wins},
+                    "project": project,
+                }
+            )
+        return patterns
+
+    def _extract_action_type_patterns(
+        self, conn: sqlite3.Connection
+    ) -> List[Dict[str, Any]]:
+        """Group outcomes by action_type and compute success rates."""
+        rows = conn.execute(
+            """SELECT action_type,
+                      COUNT(*) AS total,
+                      SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) AS wins
+               FROM action_outcomes
+               WHERE action_type IS NOT NULL
+               GROUP BY action_type
+               HAVING total >= ?""",
+            (self.MIN_EVIDENCE,),
+        ).fetchall()
+
+        patterns = []
+        for row in rows:
+            action_type = row[0]
+            total = row[1]
+            wins = row[2]
+            rate = round(wins / total, 4) if total else 0.0
+            confidence = self._compute_confidence(total, rate)
+            patterns.append(
+                {
+                    "pattern_type": "action_type_success",
+                    "pattern_key": action_type,
+                    "success_rate": rate,
+                    "evidence_count": total,
+                    "confidence": confidence,
+                    "metadata": {"wins": wins, "losses": total - wins},
+                    "project": None,
+                }
+            )
+        return patterns
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _compute_confidence(evidence_count: int, success_rate: float) -> float:
+        """Confidence = min(evidence/10, 1.0) * abs(rate - 0.5) * 2.
+
+        High confidence requires both sufficient evidence AND a success
+        rate that deviates significantly from the 50% baseline.
+        """
+        evidence_factor = min(evidence_count / 10.0, 1.0)
+        deviation_factor = abs(success_rate - 0.5) * 2.0
+        return round(evidence_factor * deviation_factor, 4)
+
+    def _connect(self) -> sqlite3.Connection:
+        """Open a connection with row factory enabled."""
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _ensure_table(self) -> None:
+        """Create the behavioral_patterns table if it doesn't exist."""
+        conn = self._connect()
+        try:
+            conn.execute(self._CREATE_TABLE)
+            conn.commit()
+        finally:
+            conn.close()
+
+    @staticmethod
+    def _row_to_dict(row: sqlite3.Row) -> Dict[str, Any]:
+        """Convert a sqlite3.Row into a plain dict with parsed JSON."""
+        d = dict(row)
+        meta = d.get("metadata", "{}")
+        d["metadata"] = json.loads(meta) if isinstance(meta, str) else meta
+        return d

package/src/behavioral/cross_project_transfer.py

@@ -0,0 +1,206 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Privacy-safe cross-project behavioral pattern transfer.
+
+Transfers behavioral patterns between projects using ONLY metadata
+(pattern type, success rate, confidence). Never transfers memory
+content or content hashes.
+
+Eligibility criteria:
+  - confidence >= 0.7
+  - evidence_count >= 5
+  - source project != target project
+
+Part of SLM v2.8 Behavioral Learning Engine.
+"""
+import sqlite3
+import threading
+from typing import Dict, List, Optional, Any
+
+
+# Thresholds for transfer eligibility
+MIN_CONFIDENCE = 0.7
+MIN_EVIDENCE = 5
+
+
+class CrossProjectTransfer:
+    """Privacy-safe cross-project behavioral pattern transfer.
+
+    Only metadata (pattern_type, pattern_key, success_rate,
+    evidence_count, confidence) is transferred — never content
+    or content hashes.
+    """
+
+    _CREATE_CROSS_TABLE = """
+        CREATE TABLE IF NOT EXISTS cross_project_behaviors (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            source_project TEXT NOT NULL,
+            target_project TEXT NOT NULL,
+            pattern_id INTEGER NOT NULL,
+            transfer_type TEXT DEFAULT 'metadata',
+            confidence REAL DEFAULT 0.0,
+            profile TEXT DEFAULT 'default',
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (pattern_id) REFERENCES behavioral_patterns(id)
+        )
+    """
+
+    def __init__(self, db_path: Optional[str] = None, enabled: bool = True):
+        self._db_path = db_path
+        self._enabled = enabled
+        self._lock = threading.Lock()
+        if db_path:
+            self._ensure_tables()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def evaluate_transfers(
+        self, target_project: str
+    ) -> List[Dict[str, Any]]:
+        """Find patterns eligible for transfer to the target project.
+
+        Eligibility: confidence >= 0.7 AND evidence_count >= 5
+        AND source project != target project.
+
+        Returns:
+            List of dicts with metadata-only fields: pattern_id,
+            pattern_type, pattern_key, success_rate, evidence_count,
+            confidence, source_project, transfer_type.
+        """
+        if not self._enabled:
+            return []
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                rows = conn.execute(
+                    """SELECT id, pattern_type, pattern_key, success_rate,
+                              evidence_count, confidence, project
+                       FROM behavioral_patterns
+                       WHERE confidence >= ?
+                         AND evidence_count >= ?
+                         AND project IS NOT NULL
+                         AND project != ?
+                       ORDER BY confidence DESC""",
+                    (MIN_CONFIDENCE, MIN_EVIDENCE, target_project),
+                ).fetchall()
+
+                return [self._eligible_to_dict(row) for row in rows]
+            finally:
+                conn.close()
+
+    def apply_transfer(
+        self, pattern_id: int, target_project: str
+    ) -> Dict[str, Any]:
+        """Record a cross-project transfer in the database.
+
+        Looks up the source pattern to get its project and confidence,
+        then inserts a record into cross_project_behaviors.
+
+        Returns:
+            Dict with success status and transfer id.
+        """
+        with self._lock:
+            conn = self._connect()
+            try:
+                # Look up the source pattern
+                pattern = conn.execute(
+                    "SELECT project, confidence FROM behavioral_patterns WHERE id = ?",
+                    (pattern_id,),
+                ).fetchone()
+
+                if pattern is None:
+                    return {"success": False, "error": "pattern_not_found"}
+
+                source_project = pattern["project"]
+                confidence = pattern["confidence"]
+
+                cur = conn.execute(
+                    """INSERT INTO cross_project_behaviors
+                       (source_project, target_project, pattern_id,
+                        transfer_type, confidence)
+                       VALUES (?, ?, ?, 'metadata', ?)""",
+                    (source_project, target_project, pattern_id, confidence),
+                )
+                conn.commit()
+                return {
+                    "success": True,
+                    "transfer_id": cur.lastrowid,
+                    "source_project": source_project,
+                    "target_project": target_project,
+                }
+            finally:
+                conn.close()
+
+    def get_transfers(
+        self,
+        target_project: Optional[str] = None,
+        source_project: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Query recorded cross-project transfers.
+
+        Args:
+            target_project: Filter by target project.
+            source_project: Filter by source project.
+
+        Returns:
+            List of transfer record dicts.
+        """
+        with self._lock:
+            conn = self._connect()
+            try:
+                query = "SELECT * FROM cross_project_behaviors WHERE 1=1"
+                params: List[Any] = []
+
+                if target_project is not None:
+                    query += " AND target_project = ?"
+                    params.append(target_project)
+
+                if source_project is not None:
+                    query += " AND source_project = ?"
+                    params.append(source_project)
+
+                query += " ORDER BY created_at DESC"
+
+                rows = conn.execute(query, params).fetchall()
+                return [dict(row) for row in rows]
+            finally:
+                conn.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _connect(self) -> sqlite3.Connection:
+        """Open a connection with row factory enabled."""
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _ensure_tables(self) -> None:
+        """Create the cross_project_behaviors table if missing."""
+        conn = self._connect()
+        try:
+            conn.execute(self._CREATE_CROSS_TABLE)
+            conn.commit()
+        finally:
+            conn.close()
+
+    @staticmethod
+    def _eligible_to_dict(row: sqlite3.Row) -> Dict[str, Any]:
+        """Convert a pattern row to a privacy-safe transfer dict.
+
+        Only metadata fields are included. No content, no hashes.
+        """
+        return {
+            "pattern_id": row["id"],
+            "pattern_type": row["pattern_type"],
+            "pattern_key": row["pattern_key"],
+            "success_rate": row["success_rate"],
+            "evidence_count": row["evidence_count"],
+            "confidence": row["confidence"],
+            "source_project": row["project"],
+            "transfer_type": "metadata",
+        }