superlocalmemory 2.7.6 → 2.8.0

package/skills/slm-recall/SKILL.md

@@ -320,7 +320,7 @@ slm recall "query" --format csv
 
 **Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
 **Project:** SuperLocalMemory V2
-**License:** MIT with attribution requirements (see [ATTRIBUTION.md](../../ATTRIBUTION.md))
+**License:** MIT (see [LICENSE](../../LICENSE))
 **Repository:** https://github.com/varun369/SuperLocalMemoryV2
 
 *Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*

package/skills/slm-remember/SKILL.md

@@ -188,7 +188,7 @@ slm remember "Commit: $commit_msg (${commit_hash:0:7})" \
 
 **Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
 **Project:** SuperLocalMemory V2
-**License:** MIT with attribution requirements (see [ATTRIBUTION.md](../../ATTRIBUTION.md))
+**License:** MIT (see [LICENSE](../../LICENSE))
 **Repository:** https://github.com/varun369/SuperLocalMemoryV2
 
 *Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*

package/skills/slm-show-patterns/SKILL.md

@@ -218,7 +218,7 @@ slm engagement
 
 **Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
 **Project:** SuperLocalMemory V2
-**License:** MIT with attribution requirements (see [ATTRIBUTION.md](../../ATTRIBUTION.md))
+**License:** MIT (see [LICENSE](../../LICENSE))
 **Repository:** https://github.com/varun369/SuperLocalMemoryV2
 
 *Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*

package/skills/slm-status/SKILL.md

@@ -357,7 +357,7 @@ slm build-graph
 
 **Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
 **Project:** SuperLocalMemory V2
-**License:** MIT with attribution requirements (see [ATTRIBUTION.md](../../ATTRIBUTION.md))
+**License:** MIT (see [LICENSE](../../LICENSE))
 **Repository:** https://github.com/varun369/SuperLocalMemoryV2
 
 *Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*

package/skills/slm-switch-profile/SKILL.md

@@ -436,7 +436,7 @@ slm list-profiles
 
 **Created by:** [Varun Pratap Bhardwaj](https://github.com/varun369) (Solution Architect)
 **Project:** SuperLocalMemory V2
-**License:** MIT with attribution requirements (see [ATTRIBUTION.md](../../ATTRIBUTION.md))
+**License:** MIT (see [LICENSE](../../LICENSE))
 **Repository:** https://github.com/varun369/SuperLocalMemoryV2
 
 *Open source doesn't mean removing credit. Attribution must be preserved per MIT License terms.*

package/src/agent_registry.py

@@ -1,22 +1,12 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Agent Registry
-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.
-"""
-
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
 """
 AgentRegistry — Tracks which AI agents connect to SuperLocalMemory,
 what they write, when, and via which protocol.
 
-Every MCP client (Claude, Cursor, Windsurf), CLI call, REST API request,
-and future A2A agent gets registered here. This powers:
+Every MCP client (Claude, Cursor, Windsurf), CLI call, and REST API request
+gets registered here. This powers:
     - Dashboard "Connected Agents" panel
     - Trust scoring input (v2.5 silent collection)
     - Provenance tracking (who created which memory)
@@ -31,7 +21,6 @@ Protocols:
     cli     — Command-line interface (slm command, bin/ scripts)
     rest    — REST API (api_server.py)
     python  — Direct Python import
-    a2a     — Agent-to-Agent Protocol (v2.7+)
 """
 
 import json
@@ -155,7 +144,7 @@ class AgentRegistry:
         Args:
             agent_id: Unique identifier (e.g., "mcp:claude-desktop")
             agent_name: Human-readable name (e.g., "Claude Desktop")
-            protocol: Connection protocol (mcp, cli, rest, python, a2a)
+            protocol: Connection protocol (mcp, cli, rest, python)
             metadata: Additional agent info (version, capabilities, etc.)
 
         Returns:
@@ -164,7 +153,7 @@ class AgentRegistry:
         if not agent_id or not isinstance(agent_id, str):
             raise ValueError("agent_id must be a non-empty string")
 
-        valid_protocols = ("mcp", "cli", "rest", "python", "a2a")
+        valid_protocols = ("mcp", "cli", "rest", "python")
         if protocol not in valid_protocols:
             raise ValueError(f"Invalid protocol: {protocol}. Must be one of {valid_protocols}")
 
@@ -283,7 +272,7 @@ class AgentRegistry:
         List registered agents with optional filtering.
 
         Args:
-            protocol: Filter by protocol (mcp, cli, rest, python, a2a)
+            protocol: Filter by protocol (mcp, cli, rest, python)
             limit: Max agents to return
             active_since_hours: Only agents seen within N hours
 

package/src/auth_middleware.py

@@ -1,14 +1,12 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Optional API Key Authentication
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""SuperLocalMemory V2 - Optional API Key Authentication
 
 Opt-in API key authentication for dashboard and API endpoints.
 When ~/.claude-memory/api_key file exists, write endpoints require
 X-SLM-API-Key header. Read endpoints remain open for backward compatibility.
 """
-
 import os
 import hashlib
 import logging

package/src/auto_backup.py

@@ -1,10 +1,7 @@
 #!/usr/bin/env python3
-"""
-SuperLocalMemory V2 - Auto Backup System
-Copyright (c) 2026 Varun Pratap Bhardwaj
-Licensed under MIT License
-
-Repository: https://github.com/varun369/SuperLocalMemoryV2
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""SuperLocalMemory V2 - Auto Backup System
 
 Automated backup system for memory.db:
 - Configurable interval: 24h (daily) or 7 days (weekly, default)
@@ -13,7 +10,6 @@ Automated backup system for memory.db:
 - Auto-triggers on memory operations when backup is due
 - Manual backup via CLI
 """
-
 import sqlite3
 import shutil
 import json

package/src/behavioral/__init__.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""SLM v2.8 Behavioral Learning Engine — Action Outcome Learning.
+
+Tracks what happens AFTER memories are recalled (success/failure/partial).
+Extracts behavioral patterns. Transfers across projects (privacy-safe).
+All local, zero-LLM.
+
+Graceful degradation: if this module fails to import,
+adaptive ranking continues with v2.7 features only.
+"""
+import threading
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+BEHAVIORAL_AVAILABLE = False
+_init_error = None
+
+try:
+    from .outcome_tracker import OutcomeTracker
+    from .behavioral_patterns import BehavioralPatternExtractor
+    BEHAVIORAL_AVAILABLE = True
+except ImportError as e:
+    _init_error = str(e)
+
+_outcome_tracker: Optional["OutcomeTracker"] = None
+_tracker_lock = threading.Lock()
+
+
+def get_outcome_tracker(db_path: Optional[Path] = None) -> Optional["OutcomeTracker"]:
+    """Get or create the outcome tracker singleton."""
+    global _outcome_tracker
+    if not BEHAVIORAL_AVAILABLE:
+        return None
+    with _tracker_lock:
+        if _outcome_tracker is None:
+            try:
+                _outcome_tracker = OutcomeTracker(db_path)
+            except Exception:
+                return None
+        return _outcome_tracker
+
+
+def get_status() -> Dict[str, Any]:
+    return {
+        "behavioral_available": BEHAVIORAL_AVAILABLE,
+        "init_error": _init_error,
+        "tracker_active": _outcome_tracker is not None,
+    }

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