superlocalmemory 2.8.6 → 3.0.0

package/src/lifecycle/lifecycle_engine.py

@@ -1,355 +0,0 @@
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""Memory lifecycle state machine with formal transition rules.
-
-State Machine:
-    ACTIVE -> WARM -> COLD -> ARCHIVED -> TOMBSTONED
-
-Reactivation allowed from WARM, COLD, ARCHIVED back to ACTIVE.
-TOMBSTONED is terminal (deletion only).
-
-Each transition is recorded in lifecycle_history (JSON array) for auditability.
-Thread-safe via threading.Lock() around read-modify-write operations.
-"""
-import sqlite3
-import json
-import threading
-from datetime import datetime
-from pathlib import Path
-from typing import Optional, Dict, Any, List
-
-
-class LifecycleEngine:
-    """Manages memory lifecycle states: ACTIVE -> WARM -> COLD -> ARCHIVED -> TOMBSTONED."""
-
-    STATES = ("active", "warm", "cold", "archived", "tombstoned")
-
-    TRANSITIONS = {
-        "active": ["warm"],
-        "warm": ["active", "cold"],
-        "cold": ["active", "archived"],
-        "archived": ["active", "tombstoned"],
-        "tombstoned": [],  # Terminal state
-    }
-
-    def __init__(self, db_path: Optional[str] = None, config_path: Optional[str] = None):
-        if db_path is None:
-            db_path = Path.home() / ".claude-memory" / "memory.db"
-        self._db_path = str(db_path)
-        self._config_path = config_path
-        self._lock = threading.Lock()
-        self._ensure_columns()
-
-    def _get_connection(self) -> sqlite3.Connection:
-        """Get a SQLite connection to memory.db."""
-        conn = sqlite3.connect(self._db_path)
-        conn.row_factory = sqlite3.Row
-        return conn
-
-    def _ensure_columns(self) -> None:
-        """Ensure v2.8 lifecycle columns exist in memories table."""
-        try:
-            conn = self._get_connection()
-            try:
-                cursor = conn.cursor()
-                cursor.execute("PRAGMA table_info(memories)")
-                existing = {row[1] for row in cursor.fetchall()}
-                v28_cols = [
-                    ("lifecycle_state", "TEXT DEFAULT 'active'"),
-                    ("lifecycle_updated_at", "TIMESTAMP"),
-                    ("lifecycle_history", "TEXT DEFAULT '[]'"),
-                    ("access_level", "TEXT DEFAULT 'public'"),
-                ]
-                for col_name, col_type in v28_cols:
-                    if col_name not in existing:
-                        try:
-                            cursor.execute(
-                                f"ALTER TABLE memories ADD COLUMN {col_name} {col_type}"
-                            )
-                        except sqlite3.OperationalError:
-                            pass
-                conn.commit()
-            finally:
-                conn.close()
-        except Exception:
-            pass  # Graceful degradation — don't block engine init
-
-    def is_valid_transition(self, from_state: str, to_state: str) -> bool:
-        """Check if a state transition is valid per the state machine.
-
-        Args:
-            from_state: Current lifecycle state
-            to_state: Target lifecycle state
-
-        Returns:
-            True if the transition is allowed, False otherwise
-        """
-        if from_state not in self.TRANSITIONS:
-            return False
-        return to_state in self.TRANSITIONS[from_state]
-
-    def get_memory_state(self, memory_id: int) -> Optional[str]:
-        """Get the current lifecycle state of a memory.
-
-        Args:
-            memory_id: The memory's database ID
-
-        Returns:
-            The lifecycle state string, or None if memory not found
-        """
-        conn = self._get_connection()
-        try:
-            try:
-                row = conn.execute(
-                    "SELECT lifecycle_state FROM memories WHERE id = ?",
-                    (memory_id,),
-                ).fetchone()
-            except sqlite3.OperationalError as e:
-                if "no such column" in str(e):
-                    conn.close()
-                    self._ensure_columns()
-                    conn = self._get_connection()
-                    row = conn.execute(
-                        "SELECT lifecycle_state FROM memories WHERE id = ?",
-                        (memory_id,),
-                    ).fetchone()
-                else:
-                    raise
-            if row is None:
-                return None
-            return row["lifecycle_state"] or "active"
-        finally:
-            conn.close()
-
-    def transition_memory(
-        self,
-        memory_id: int,
-        to_state: str,
-        reason: str = "",
-    ) -> Dict[str, Any]:
-        """Transition a memory to a new lifecycle state.
-
-        Validates the transition against the state machine, updates the database,
-        and appends to the lifecycle_history JSON array.
-
-        Args:
-            memory_id: The memory's database ID
-            to_state: Target lifecycle state
-            reason: Human-readable reason for the transition
-
-        Returns:
-            Dict with success/failure status, from_state, to_state, etc.
-        """
-        with self._lock:
-            conn = self._get_connection()
-            try:
-                row = conn.execute(
-                    "SELECT lifecycle_state, lifecycle_history FROM memories WHERE id = ?",
-                    (memory_id,),
-                ).fetchone()
-
-                if row is None:
-                    return {"success": False, "error": f"Memory {memory_id} not found"}
-
-                from_state = row["lifecycle_state"] or "active"
-
-                if not self.is_valid_transition(from_state, to_state):
-                    return {
-                        "success": False,
-                        "error": f"Invalid transition from '{from_state}' to '{to_state}'",
-                    }
-
-                now = datetime.now().isoformat()
-                history = json.loads(row["lifecycle_history"] or "[]")
-                history.append({
-                    "from": from_state,
-                    "to": to_state,
-                    "reason": reason,
-                    "timestamp": now,
-                })
-
-                conn.execute(
-                    """UPDATE memories
-                       SET lifecycle_state = ?,
-                           lifecycle_updated_at = ?,
-                           lifecycle_history = ?
-                       WHERE id = ?""",
-                    (to_state, now, json.dumps(history), memory_id),
-                )
-                conn.commit()
-
-                self._try_emit_event("lifecycle.transitioned", memory_id, {
-                    "from_state": from_state,
-                    "to_state": to_state,
-                    "reason": reason,
-                })
-
-                return {
-                    "success": True,
-                    "from_state": from_state,
-                    "to_state": to_state,
-                    "memory_id": memory_id,
-                    "reason": reason,
-                    "timestamp": now,
-                }
-            finally:
-                conn.close()
-
-    def batch_transition(
-        self,
-        memory_ids: List[int],
-        to_state: str,
-        reasons: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """Transition multiple memories in a single connection + commit.
-
-        Validates each transition individually, skips invalid ones.
-        Much faster than calling transition_memory() in a loop because
-        it opens only one connection and commits once.
-
-        Args:
-            memory_ids: List of memory IDs to transition
-            to_state: Target lifecycle state for all
-            reasons: Per-memory reasons (defaults to empty string)
-
-        Returns:
-            Dict with succeeded (list), failed (list), and counts
-        """
-        if reasons is None:
-            reasons = [""] * len(memory_ids)
-
-        succeeded: List[Dict[str, Any]] = []
-        failed: List[Dict[str, Any]] = []
-
-        with self._lock:
-            conn = self._get_connection()
-            try:
-                now = datetime.now().isoformat()
-
-                for mem_id, reason in zip(memory_ids, reasons):
-                    row = conn.execute(
-                        "SELECT lifecycle_state, lifecycle_history "
-                        "FROM memories WHERE id = ?",
-                        (mem_id,),
-                    ).fetchone()
-
-                    if row is None:
-                        failed.append({"memory_id": mem_id, "error": "not_found"})
-                        continue
-
-                    from_state = row["lifecycle_state"] or "active"
-                    if not self.is_valid_transition(from_state, to_state):
-                        failed.append({
-                            "memory_id": mem_id,
-                            "error": f"invalid_{from_state}_to_{to_state}",
-                        })
-                        continue
-
-                    history = json.loads(row["lifecycle_history"] or "[]")
-                    history.append({
-                        "from": from_state,
-                        "to": to_state,
-                        "reason": reason,
-                        "timestamp": now,
-                    })
-
-                    conn.execute(
-                        """UPDATE memories
-                           SET lifecycle_state = ?,
-                               lifecycle_updated_at = ?,
-                               lifecycle_history = ?
-                           WHERE id = ?""",
-                        (to_state, now, json.dumps(history), mem_id),
-                    )
-                    succeeded.append({
-                        "memory_id": mem_id,
-                        "from_state": from_state,
-                        "to_state": to_state,
-                    })
-
-                conn.commit()
-
-                # Best-effort event emission for each transitioned memory
-                for entry in succeeded:
-                    self._try_emit_event(
-                        "lifecycle.transitioned", entry["memory_id"], {
-                            "from_state": entry["from_state"],
-                            "to_state": entry["to_state"],
-                            "reason": "batch",
-                        },
-                    )
-
-                return {
-                    "succeeded": succeeded,
-                    "failed": failed,
-                    "total": len(memory_ids),
-                    "success_count": len(succeeded),
-                    "fail_count": len(failed),
-                }
-            finally:
-                conn.close()
-
-    def reactivate_memory(
-        self,
-        memory_id: int,
-        trigger: str = "",
-    ) -> Dict[str, Any]:
-        """Reactivate a non-active memory back to ACTIVE state.
-
-        Convenience wrapper around transition_memory for reactivation.
-        Valid from WARM, COLD, or ARCHIVED states.
-
-        Args:
-            memory_id: The memory's database ID
-            trigger: What triggered reactivation (e.g., "recall", "explicit")
-
-        Returns:
-            Dict with success/failure status
-        """
-        return self.transition_memory(
-            memory_id, "active", reason=f"reactivated:{trigger}"
-        )
-
-    def get_state_distribution(self) -> Dict[str, int]:
-        """Get count of memories in each lifecycle state.
-
-        Returns:
-            Dict mapping state names to counts (all STATES keys present)
-        """
-        conn = self._get_connection()
-        try:
-            dist = {state: 0 for state in self.STATES}
-            try:
-                rows = conn.execute(
-                    "SELECT lifecycle_state, COUNT(*) as cnt "
-                    "FROM memories GROUP BY lifecycle_state"
-                ).fetchall()
-            except sqlite3.OperationalError as e:
-                if "no such column" in str(e):
-                    conn.close()
-                    self._ensure_columns()
-                    conn = self._get_connection()
-                    rows = conn.execute(
-                        "SELECT lifecycle_state, COUNT(*) as cnt "
-                        "FROM memories GROUP BY lifecycle_state"
-                    ).fetchall()
-                else:
-                    raise
-            for row in rows:
-                state = row["lifecycle_state"] if row["lifecycle_state"] else "active"
-                if state in dist:
-                    dist[state] = row["cnt"]
-            return dist
-        finally:
-            conn.close()
-
-    def _try_emit_event(
-        self, event_type: str, memory_id: int, payload: dict
-    ) -> None:
-        """Best-effort EventBus emission. Fails silently if unavailable."""
-        try:
-            from event_bus import EventBus
-            bus = EventBus.get_instance(Path(self._db_path))
-            bus.emit(event_type, payload=payload, memory_id=memory_id)
-        except Exception:
-            pass

package/src/lifecycle/lifecycle_evaluator.py

@@ -1,257 +0,0 @@
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""Lifecycle evaluation rules — determines which memories should transition.
-
-Evaluates memories against configurable thresholds based on:
-- Time since last access (staleness)
-- Importance score
-- Current lifecycle state
-
-Default rules:
-    ACTIVE -> WARM:  no access >= 30 days AND importance <= 6
-    WARM -> COLD:    no access >= 90 days AND importance <= 4
-    COLD -> ARCHIVED: no access >= 180 days (any importance)
-
-Thresholds configurable via lifecycle_config.json.
-"""
-import sqlite3
-import json
-from datetime import datetime
-from pathlib import Path
-from typing import Optional, Dict, Any, List, Set
-
-
-# Default evaluation thresholds
-DEFAULT_EVAL_CONFIG: Dict[str, Dict[str, Any]] = {
-    "active_to_warm": {
-        "no_access_days": 30,
-        "max_importance": 6,
-    },
-    "warm_to_cold": {
-        "no_access_days": 90,
-        "max_importance": 4,
-    },
-    "cold_to_archived": {
-        "no_access_days": 180,
-    },
-}
-
-
-class LifecycleEvaluator:
-    """Evaluates memories for lifecycle state transitions.
-
-    Scans memories and recommends transitions based on staleness and importance.
-    Does NOT execute transitions — returns recommendations for the engine or
-    scheduler to act on.
-    """
-
-    def __init__(
-        self, db_path: Optional[str] = None, config_path: Optional[str] = None
-    ):
-        if db_path is None:
-            db_path = str(Path.home() / ".claude-memory" / "memory.db")
-        self._db_path = str(db_path)
-        self._config_path = config_path
-
-    def _get_connection(self) -> sqlite3.Connection:
-        """Get a SQLite connection to memory.db."""
-        conn = sqlite3.connect(self._db_path)
-        conn.row_factory = sqlite3.Row
-        return conn
-
-    def _ensure_lifecycle_columns(self) -> None:
-        """Ensure v2.8 lifecycle columns exist via LifecycleEngine."""
-        try:
-            from lifecycle.lifecycle_engine import LifecycleEngine
-            engine = LifecycleEngine(db_path=self._db_path)
-            engine._ensure_columns()
-        except Exception:
-            pass  # Best effort — don't block evaluation
-
-    def evaluate_memories(
-        self,
-        profile: Optional[str] = None,
-        retention_overrides: Optional[Set[int]] = None,
-    ) -> List[Dict[str, Any]]:
-        """Scan all memories and return recommended transitions.
-
-        Args:
-            profile: Filter by profile (None = all profiles)
-            retention_overrides: Set of memory IDs to skip (retention-protected)
-
-        Returns:
-            List of recommendation dicts with memory_id, from_state, to_state, reason
-        """
-        config = self._load_config()
-        overrides = retention_overrides or set()
-
-        conn = self._get_connection()
-        try:
-            query = (
-                "SELECT id, lifecycle_state, importance, last_accessed, created_at "
-                "FROM memories WHERE lifecycle_state IN ('active', 'warm', 'cold')"
-            )
-            params: list = []
-            if profile:
-                query += " AND profile = ?"
-                params.append(profile)
-
-            try:
-                rows = conn.execute(query, params).fetchall()
-            except sqlite3.OperationalError as e:
-                if "no such column" in str(e):
-                    conn.close()
-                    self._ensure_lifecycle_columns()
-                    conn = self._get_connection()
-                    rows = conn.execute(query, params).fetchall()
-                else:
-                    raise
-
-            recommendations = []
-            now = datetime.now()
-
-            for row in rows:
-                if row["id"] in overrides:
-                    continue
-                rec = self._evaluate_row(row, config, now)
-                if rec:
-                    recommendations.append(rec)
-
-            return recommendations
-        finally:
-            conn.close()
-
-    def evaluate_single(
-        self,
-        memory_id: int,
-        retention_overrides: Optional[Set[int]] = None,
-    ) -> Optional[Dict[str, Any]]:
-        """Evaluate a single memory for potential transition.
-
-        Args:
-            memory_id: The memory's database ID
-            retention_overrides: Set of memory IDs to skip
-
-        Returns:
-            Recommendation dict, or None if no transition recommended
-        """
-        overrides = retention_overrides or set()
-        if memory_id in overrides:
-            return None
-
-        config = self._load_config()
-        conn = self._get_connection()
-        try:
-            try:
-                row = conn.execute(
-                    "SELECT id, lifecycle_state, importance, last_accessed, created_at "
-                    "FROM memories WHERE id = ?",
-                    (memory_id,),
-                ).fetchone()
-            except sqlite3.OperationalError as e:
-                if "no such column" in str(e):
-                    conn.close()
-                    self._ensure_lifecycle_columns()
-                    conn = self._get_connection()
-                    row = conn.execute(
-                        "SELECT id, lifecycle_state, importance, last_accessed, created_at "
-                        "FROM memories WHERE id = ?",
-                        (memory_id,),
-                    ).fetchone()
-                else:
-                    raise
-            if row is None:
-                return None
-            return self._evaluate_row(row, config, datetime.now())
-        finally:
-            conn.close()
-
-    def _evaluate_row(
-        self, row: sqlite3.Row, config: Dict, now: datetime
-    ) -> Optional[Dict[str, Any]]:
-        """Evaluate a single memory row against transition rules."""
-        state = row["lifecycle_state"] or "active"
-        importance = row["importance"] or 5
-
-        # Determine staleness: prefer last_accessed, fall back to created_at
-        last_access_str = row["last_accessed"] or row["created_at"]
-        if last_access_str:
-            try:
-                last_access = datetime.fromisoformat(str(last_access_str))
-            except (ValueError, TypeError):
-                last_access = now  # Unparseable -> treat as recent (safe default)
-        else:
-            last_access = now
-
-        days_stale = (now - last_access).days
-
-        if state == "active":
-            rules = config.get("active_to_warm", {})
-            threshold_days = rules.get("no_access_days", 30)
-            max_importance = rules.get("max_importance", 6)
-            if days_stale >= threshold_days and importance <= max_importance:
-                return self._build_recommendation(
-                    row["id"], "active", "warm", days_stale, importance
-                )
-        elif state == "warm":
-            rules = config.get("warm_to_cold", {})
-            threshold_days = rules.get("no_access_days", 90)
-            max_importance = rules.get("max_importance", 4)
-            if days_stale >= threshold_days and importance <= max_importance:
-                return self._build_recommendation(
-                    row["id"], "warm", "cold", days_stale, importance
-                )
-        elif state == "cold":
-            rules = config.get("cold_to_archived", {})
-            threshold_days = rules.get("no_access_days", 180)
-            if days_stale >= threshold_days:
-                return self._build_recommendation(
-                    row["id"], "cold", "archived", days_stale, importance
-                )
-
-        return None
-
-    def _build_recommendation(
-        self,
-        memory_id: int,
-        from_state: str,
-        to_state: str,
-        days_stale: int,
-        importance: int,
-    ) -> Dict[str, Any]:
-        """Build a standardized recommendation dict."""
-        reason = f"no_access_{days_stale}d"
-        if to_state != "archived":
-            reason += f"_importance_{importance}"
-        return {
-            "memory_id": memory_id,
-            "from_state": from_state,
-            "to_state": to_state,
-            "reason": reason,
-            "days_stale": days_stale,
-            "importance": importance,
-        }
-
-    def _load_config(self) -> Dict[str, Any]:
-        """Load lifecycle evaluation config from JSON. Returns defaults if missing."""
-        try:
-            if self._config_path:
-                config_path = Path(self._config_path)
-            else:
-                config_path = Path(self._db_path).parent / "lifecycle_config.json"
-            if config_path.exists():
-                with open(config_path) as f:
-                    user_config = json.load(f)
-                merged: Dict[str, Any] = {}
-                for key in DEFAULT_EVAL_CONFIG:
-                    if key in user_config and isinstance(user_config[key], dict):
-                        merged[key] = {**DEFAULT_EVAL_CONFIG[key], **user_config[key]}
-                    else:
-                        merged[key] = dict(DEFAULT_EVAL_CONFIG[key])
-                for key in user_config:
-                    if key not in merged:
-                        merged[key] = user_config[key]
-                return merged
-        except Exception:
-            pass
-        return {k: dict(v) for k, v in DEFAULT_EVAL_CONFIG.items()}