superlocalmemory 2.7.5 → 2.8.0

package/src/behavioral/outcome_inference.py

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Implicit outcome detection from recall behavior patterns.
+
+Pure logic module — no database, no I/O. Takes recall events and
+returns inference results. The caller (EventBus integration) passes
+these to OutcomeTracker for persistence.
+
+Inference rules (checked in priority order, first match wins per recall):
+1. Deletion of recalled memory within 60 min  -> failure,  confidence 0.0
+2. Usage signal "mcp_used_high" within 5 min   -> success,  confidence 0.8
+3. Usage signal cross-tool within 5 min        -> success,  confidence 0.7
+4. Rapid-fire: 3+ recalls in 2 min window      -> failure,  confidence 0.1
+5. Different-query recall within 2 min          -> failure,  confidence 0.2
+6. No re-query for 10+ min elapsed             -> success,  confidence 0.6
+7. Otherwise                                   -> not yet inferrable (keep)
+"""
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional
+
+
+# ── Thresholds (seconds) ─────────────────────────────────────────────
+_DELETION_WINDOW = 60 * 60      # 60 min
+_USAGE_WINDOW = 5 * 60          # 5 min
+_RAPID_FIRE_WINDOW = 2 * 60     # 2 min
+_RAPID_FIRE_COUNT = 3
+_REQUERY_WINDOW = 2 * 60        # 2 min
+_QUIET_WINDOW = 10 * 60         # 10 min
+
+
+class OutcomeInference:
+    """Infer implicit success/failure from post-recall user behavior."""
+
+    def __init__(self) -> None:
+        self._recalls: List[Dict] = []      # {query, memory_ids, ts}
+        self._usages: List[Dict] = []       # {query, signal, ts}
+        self._deletions: List[Dict] = []    # {memory_id, ts}
+
+    # ── Recording API ────────────────────────────────────────────────
+
+    def record_recall(
+        self,
+        query: str,
+        memory_ids: List[int],
+        timestamp: Optional[datetime] = None,
+    ) -> None:
+        """Buffer a recall event."""
+        self._recalls.append({
+            "query": query,
+            "memory_ids": list(memory_ids),
+            "ts": timestamp or datetime.now(),
+        })
+
+    def record_usage(
+        self,
+        query: str,
+        signal: str,
+        timestamp: Optional[datetime] = None,
+    ) -> None:
+        """Buffer a post-recall usage signal."""
+        self._usages.append({
+            "query": query,
+            "signal": signal,
+            "ts": timestamp or datetime.now(),
+        })
+
+    def record_deletion(
+        self,
+        memory_id: int,
+        timestamp: Optional[datetime] = None,
+    ) -> None:
+        """Buffer a memory deletion event."""
+        self._deletions.append({
+            "memory_id": memory_id,
+            "ts": timestamp or datetime.now(),
+        })
+
+    # ── Inference engine ─────────────────────────────────────────────
+
+    def infer_outcomes(self, now: Optional[datetime] = None) -> List[Dict]:
+        """Process buffered events, apply rules, return inferences.
+
+        Processed recall events are removed from the buffer.
+        Events that are not yet inferrable remain for later.
+
+        Returns:
+            List of dicts with keys: outcome, confidence, memory_ids, reason
+        """
+        now = now or datetime.now()
+        results: List[Dict] = []
+        remaining: List[Dict] = []
+
+        for recall in self._recalls:
+            result = self._evaluate(recall, now)
+            if result is not None:
+                results.append(result)
+            else:
+                remaining.append(recall)
+
+        # Clear processed; keep un-inferrable recalls
+        self._recalls = remaining
+        # Consumed usages and deletions are cleared entirely
+        self._usages.clear()
+        self._deletions.clear()
+
+        return results
+
+    # ── Private rule evaluation ──────────────────────────────────────
+
+    def _evaluate(self, recall: Dict, now: datetime) -> Optional[Dict]:
+        """Apply rules in priority order. First match wins."""
+        query = recall["query"]
+        mem_ids = recall["memory_ids"]
+        ts = recall["ts"]
+        elapsed = (now - ts).total_seconds()
+
+        # Rule 1: Deletion of recalled memory within 60 min
+        for d in self._deletions:
+            if d["memory_id"] in mem_ids:
+                delta = (d["ts"] - ts).total_seconds()
+                if 0 <= delta <= _DELETION_WINDOW:
+                    return self._result(
+                        "failure", 0.0, mem_ids,
+                        "memory_deleted_after_recall",
+                    )
+
+        # Rule 2: Usage signal "mcp_used_high" within 5 min
+        for u in self._usages:
+            if u["query"] == query and u["signal"] == "mcp_used_high":
+                delta = (u["ts"] - ts).total_seconds()
+                if 0 <= delta <= _USAGE_WINDOW:
+                    return self._result(
+                        "success", 0.8, mem_ids,
+                        "mcp_used_high_after_recall",
+                    )
+
+        # Rule 3: Cross-tool usage within 5 min
+        for u in self._usages:
+            if u["query"] == query and u["signal"] == "implicit_positive_cross_tool":
+                delta = (u["ts"] - ts).total_seconds()
+                if 0 <= delta <= _USAGE_WINDOW:
+                    return self._result(
+                        "success", 0.7, mem_ids,
+                        "cross_tool_access_after_recall",
+                    )
+
+        # Rule 4: Rapid-fire — 3+ recalls within 2 min window
+        window_start = ts - timedelta(seconds=_RAPID_FIRE_WINDOW)
+        nearby = [
+            r for r in self._recalls
+            if r is not recall and window_start <= r["ts"] <= ts + timedelta(seconds=_RAPID_FIRE_WINDOW)
+        ]
+        # Count total including this recall
+        if len(nearby) + 1 >= _RAPID_FIRE_COUNT:
+            return self._result(
+                "failure", 0.1, mem_ids,
+                "rapid_fire_queries",
+            )
+
+        # Rule 5: Different-query recall within 2 min
+        for r in self._recalls:
+            if r is recall:
+                continue
+            if r["query"] != query:
+                delta = abs((r["ts"] - ts).total_seconds())
+                if delta <= _REQUERY_WINDOW:
+                    return self._result(
+                        "failure", 0.2, mem_ids,
+                        "immediate_requery_different_terms",
+                    )
+
+        # Rule 6: 10+ min elapsed with no subsequent activity
+        if elapsed >= _QUIET_WINDOW:
+            return self._result(
+                "success", 0.6, mem_ids,
+                "no_requery_after_recall",
+            )
+
+        # Rule 7: Not yet inferrable
+        return None
+
+    @staticmethod
+    def _result(
+        outcome: str,
+        confidence: float,
+        memory_ids: List[int],
+        reason: str,
+    ) -> Dict:
+        return {
+            "outcome": outcome,
+            "confidence": confidence,
+            "memory_ids": memory_ids,
+            "reason": reason,
+        }

package/src/behavioral/outcome_tracker.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Explicit + implicit action outcome recording.
+
+Records what happens AFTER memories are recalled — success, failure,
+or partial outcomes. 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 typing import Dict, List, Optional, Any
+
+
+class OutcomeTracker:
+    """Records action outcomes for behavioral learning.
+
+    Each outcome links one or more memory IDs to an outcome label
+    (success / failure / partial) with optional context metadata.
+    Confidence defaults to 0.9 for explicit (user-reported) outcomes.
+    """
+
+    OUTCOMES = ("success", "failure", "partial")
+
+    ACTION_TYPES = (
+        "code_written",
+        "decision_made",
+        "debug_resolved",
+        "architecture_chosen",
+        "other",
+    )
+
+    _CREATE_TABLE = """
+        CREATE TABLE IF NOT EXISTS action_outcomes (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            memory_ids TEXT NOT NULL,
+            outcome TEXT NOT NULL,
+            action_type TEXT DEFAULT 'other',
+            context TEXT DEFAULT '{}',
+            confidence REAL DEFAULT 0.9,
+            agent_id TEXT DEFAULT 'user',
+            project TEXT,
+            profile TEXT DEFAULT 'default',
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        )
+    """
+
+    def __init__(self, db_path: Optional[str] = None):
+        self._db_path = db_path
+        self._lock = threading.Lock()
+        if db_path:
+            self._ensure_table()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def record_outcome(
+        self,
+        memory_ids: List[int],
+        outcome: str,
+        action_type: str = "other",
+        context: Optional[Dict[str, Any]] = None,
+        confidence: float = 0.9,
+        agent_id: str = "user",
+        project: Optional[str] = None,
+    ) -> Optional[int]:
+        """Record an action outcome against one or more memories.
+
+        Args:
+            memory_ids: List of memory IDs involved in this outcome.
+            outcome: One of OUTCOMES ("success", "failure", "partial").
+            action_type: Category of the action taken.
+            context: Arbitrary metadata dict (stored as JSON).
+            confidence: Confidence in the outcome label (default 0.9).
+            agent_id: Identifier for the reporting agent.
+            project: Optional project scope.
+
+        Returns:
+            The row ID of the inserted outcome, or None if validation fails.
+        """
+        if outcome not in self.OUTCOMES:
+            return None
+
+        context_json = json.dumps(context or {})
+        memory_ids_json = json.dumps(memory_ids)
+
+        with self._lock:
+            conn = self._connect()
+            try:
+                cur = conn.execute(
+                    """INSERT INTO action_outcomes
+                       (memory_ids, outcome, action_type, context,
+                        confidence, agent_id, project)
+                       VALUES (?, ?, ?, ?, ?, ?, ?)""",
+                    (
+                        memory_ids_json,
+                        outcome,
+                        action_type,
+                        context_json,
+                        confidence,
+                        agent_id,
+                        project,
+                    ),
+                )
+                conn.commit()
+                return cur.lastrowid
+            finally:
+                conn.close()
+
+    def get_outcomes(
+        self,
+        memory_id: Optional[int] = None,
+        project: Optional[str] = None,
+        limit: int = 100,
+    ) -> List[Dict[str, Any]]:
+        """Query recorded outcomes with optional filters.
+
+        Args:
+            memory_id: If given, return only outcomes that include this
+                       memory ID in their memory_ids list.
+            project: If given, filter by project scope.
+            limit: Maximum rows to return (default 100).
+
+        Returns:
+            List of outcome dicts with deserialized memory_ids and context.
+        """
+        with self._lock:
+            conn = self._connect()
+            try:
+                query = "SELECT * FROM action_outcomes WHERE 1=1"
+                params: List[Any] = []
+
+                if project is not None:
+                    query += " AND project = ?"
+                    params.append(project)
+
+                query += " ORDER BY created_at DESC LIMIT ?"
+                params.append(limit)
+
+                rows = conn.execute(query, params).fetchall()
+                results = [self._row_to_dict(r) for r in rows]
+
+                if memory_id is not None:
+                    results = [
+                        r for r in results if memory_id in r["memory_ids"]
+                    ]
+
+                return results
+            finally:
+                conn.close()
+
+    def get_success_rate(self, memory_id: int) -> float:
+        """Calculate success rate for a specific memory.
+
+        Counts outcomes where memory_id appears in memory_ids.
+        Returns success count / total count, or 0.0 if no outcomes.
+        """
+        outcomes = self.get_outcomes(memory_id=memory_id)
+        if not outcomes:
+            return 0.0
+        successes = sum(1 for o in outcomes if o["outcome"] == "success")
+        return round(successes / len(outcomes), 3)
+
+    # ------------------------------------------------------------------
+    # 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_table(self) -> None:
+        """Create the action_outcomes 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 fields."""
+        d = dict(row)
+        d["memory_ids"] = json.loads(d.get("memory_ids", "[]"))
+        ctx = d.get("context", "{}")
+        d["context"] = json.loads(ctx) if isinstance(ctx, str) else ctx
+        return d

package/src/behavioral/tests/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tests for behavioral learning engine.
+"""

package/src/behavioral/tests/test_behavioral_integration.py

@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tests for behavioral engine EventBus integration.
+"""
+import sqlite3
+import tempfile
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+
+
+class TestBehavioralIntegration:
+    """Test behavioral engine wiring with EventBus."""
+
+    def setup_method(self):
+        self.tmp_dir = tempfile.mkdtemp()
+        self.db_path = os.path.join(self.tmp_dir, "learning.db")
+
+    def teardown_method(self):
+        import shutil
+        shutil.rmtree(self.tmp_dir, ignore_errors=True)
+
+    def test_create_behavioral_listener(self):
+        """BehavioralListener can be instantiated."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path)
+        assert listener is not None
+
+    def test_listener_handles_recall_event(self):
+        """Listener processes memory.recalled events."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path)
+        event = {
+            "event_type": "memory.recalled",
+            "memory_id": 1,
+            "payload": {"query": "test query", "memory_ids": [1, 2]},
+            "timestamp": datetime.now().isoformat(),
+        }
+        # Should not raise
+        listener.handle_event(event)
+        assert listener.events_processed >= 1
+
+    def test_listener_ignores_irrelevant_events(self):
+        """Listener ignores non-recall events."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path)
+        event = {
+            "event_type": "memory.created",
+            "memory_id": 1,
+            "payload": {},
+            "timestamp": datetime.now().isoformat(),
+        }
+        listener.handle_event(event)
+        assert listener.recall_events_processed == 0
+
+    def test_listener_handles_deletion_event(self):
+        """Listener records deletion events for inference."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path)
+        event = {
+            "event_type": "memory.deleted",
+            "memory_id": 5,
+            "payload": {},
+            "timestamp": datetime.now().isoformat(),
+        }
+        listener.handle_event(event)
+        assert listener.deletion_events_processed >= 1
+
+    def test_listener_tracks_usage_signals(self):
+        """Listener records usage signals (memory_used) for inference."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path)
+        event = {
+            "event_type": "memory.recalled",
+            "memory_id": 1,
+            "payload": {"query": "test", "memory_ids": [1], "signal": "mcp_used_high"},
+            "timestamp": datetime.now().isoformat(),
+        }
+        listener.handle_event(event)
+        assert listener.events_processed >= 1
+
+    def test_graceful_degradation_no_eventbus(self):
+        """If EventBus unavailable, behavioral engine still works."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path)
+        # register_with_eventbus should not crash even if EventBus fails
+        result = listener.register_with_eventbus()
+        # Result depends on whether EventBus is importable in test env
+        assert isinstance(result, bool)
+
+    def test_pattern_extraction_threshold(self):
+        """Pattern extraction triggers after outcome count threshold."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path, extraction_threshold=5)
+        assert listener.extraction_threshold == 5
+
+    def test_get_status(self):
+        """Listener reports its status."""
+        from behavioral.behavioral_listener import BehavioralListener
+        listener = BehavioralListener(self.db_path)
+        status = listener.get_status()
+        assert "events_processed" in status
+        assert "recall_events_processed" in status
+        assert "registered" in status

package/src/behavioral/tests/test_behavioral_patterns.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tests for behavioral pattern extraction from outcomes.
+"""
+import sqlite3
+import tempfile
+import os
+import sys
+import json
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+
+
+class TestBehavioralPatterns:
+    """Test pattern extraction from action outcomes."""
+
+    def setup_method(self):
+        self.tmp_dir = tempfile.mkdtemp()
+        self.db_path = os.path.join(self.tmp_dir, "learning.db")
+        conn = sqlite3.connect(self.db_path)
+        # Create action_outcomes table (populated by OutcomeTracker)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS action_outcomes (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                memory_ids TEXT NOT NULL,
+                outcome TEXT NOT NULL,
+                action_type TEXT DEFAULT 'other',
+                context TEXT DEFAULT '{}',
+                confidence REAL DEFAULT 0.9,
+                agent_id TEXT DEFAULT 'user',
+                project TEXT,
+                profile TEXT DEFAULT 'default',
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        # Create behavioral_patterns table
+        conn.execute("""
+            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
+            )
+        """)
+        # Insert sample outcomes for pattern extraction
+        # Project A: 8 success, 2 failure -> 80% success
+        for i in range(8):
+            conn.execute("INSERT INTO action_outcomes (memory_ids, outcome, project, action_type) VALUES (?, ?, ?, ?)",
+                (json.dumps([i+1]), "success", "project_a", "code_written"))
+        for i in range(2):
+            conn.execute("INSERT INTO action_outcomes (memory_ids, outcome, project, action_type) VALUES (?, ?, ?, ?)",
+                (json.dumps([i+20]), "failure", "project_a", "code_written"))
+        # Project B: 2 success, 8 failure -> 20% success
+        for i in range(2):
+            conn.execute("INSERT INTO action_outcomes (memory_ids, outcome, project, action_type) VALUES (?, ?, ?, ?)",
+                (json.dumps([i+30]), "success", "project_b", "debug_resolved"))
+        for i in range(8):
+            conn.execute("INSERT INTO action_outcomes (memory_ids, outcome, project, action_type) VALUES (?, ?, ?, ?)",
+                (json.dumps([i+40]), "failure", "project_b", "debug_resolved"))
+        conn.commit()
+        conn.close()
+
+    def teardown_method(self):
+        import shutil
+        shutil.rmtree(self.tmp_dir, ignore_errors=True)
+
+    def test_extract_patterns(self):
+        """extract_patterns returns list of discovered patterns."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        patterns = extractor.extract_patterns()
+        assert isinstance(patterns, list)
+        assert len(patterns) >= 2  # At least project_a and project_b patterns
+
+    def test_project_success_rate(self):
+        """Patterns should reflect actual success rates per project."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        patterns = extractor.extract_patterns()
+        proj_a = [p for p in patterns if p["pattern_key"] == "project_a" and p["pattern_type"] == "project_success"]
+        assert len(proj_a) == 1
+        assert abs(proj_a[0]["success_rate"] - 0.8) < 0.01
+
+    def test_success_pattern_high_rate(self):
+        """Projects with >70% success and 5+ evidence -> success pattern."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        patterns = extractor.extract_patterns()
+        proj_a = [p for p in patterns if p["pattern_key"] == "project_a" and p["pattern_type"] == "project_success"]
+        assert proj_a[0]["success_rate"] > 0.7
+        assert proj_a[0]["evidence_count"] >= 5
+
+    def test_failure_pattern_low_rate(self):
+        """Projects with <30% success and 5+ evidence -> failure pattern."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        patterns = extractor.extract_patterns()
+        proj_b = [p for p in patterns if p["pattern_key"] == "project_b" and p["pattern_type"] == "project_success"]
+        assert proj_b[0]["success_rate"] < 0.3
+
+    def test_action_type_patterns(self):
+        """Should extract patterns grouped by action_type."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        patterns = extractor.extract_patterns()
+        action_patterns = [p for p in patterns if p["pattern_type"] == "action_type_success"]
+        assert len(action_patterns) >= 1
+
+    def test_get_patterns_with_min_confidence(self):
+        """get_patterns filters by minimum confidence."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        extractor.extract_patterns()
+        # Store patterns to DB first
+        extractor.save_patterns()
+        high_conf = extractor.get_patterns(min_confidence=0.5)
+        all_patterns = extractor.get_patterns(min_confidence=0.0)
+        assert len(high_conf) <= len(all_patterns)
+
+    def test_pattern_confidence_scoring(self):
+        """Patterns with more evidence should have higher confidence."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        patterns = extractor.extract_patterns()
+        for p in patterns:
+            assert 0.0 <= p["confidence"] <= 1.0
+            # Confidence should increase with evidence
+            if p["evidence_count"] >= 10:
+                assert p["confidence"] >= 0.5
+
+    def test_save_patterns_to_db(self):
+        """save_patterns stores extracted patterns in behavioral_patterns table."""
+        from behavioral.behavioral_patterns import BehavioralPatternExtractor
+        extractor = BehavioralPatternExtractor(self.db_path)
+        extractor.extract_patterns()
+        count = extractor.save_patterns()
+        assert count >= 2
+        # Verify in DB
+        conn = sqlite3.connect(self.db_path)
+        rows = conn.execute("SELECT COUNT(*) FROM behavioral_patterns").fetchone()
+        conn.close()
+        assert rows[0] >= 2