superlocalmemory 2.7.6 → 2.8.0

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",
+        }

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.
+"""