superlocalmemory 2.7.6 → 2.8.0

package/src/lifecycle/lifecycle_engine.py

@@ -0,0 +1,302 @@
+# 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()
+
+    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 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:
+            row = conn.execute(
+                "SELECT lifecycle_state FROM memories WHERE id = ?",
+                (memory_id,),
+            ).fetchone()
+            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}
+            rows = conn.execute(
+                "SELECT lifecycle_state, COUNT(*) as cnt "
+                "FROM memories GROUP BY lifecycle_state"
+            ).fetchall()
+            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

@@ -0,0 +1,225 @@
+# 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 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)
+
+            rows = conn.execute(query, params).fetchall()
+            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:
+            row = conn.execute(
+                "SELECT id, lifecycle_state, importance, last_accessed, created_at "
+                "FROM memories WHERE id = ?",
+                (memory_id,),
+            ).fetchone()
+            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()}

package/src/lifecycle/lifecycle_scheduler.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Background scheduler for periodic lifecycle evaluation and enforcement.
+
+Runs on a configurable interval (default: 6 hours) to:
+1. Evaluate all memories for lifecycle transitions
+2. Execute recommended transitions
+3. Enforce bounded growth limits
+
+Uses daemon threading — does not prevent process exit.
+"""
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+
+from .lifecycle_engine import LifecycleEngine
+from .lifecycle_evaluator import LifecycleEvaluator
+from .bounded_growth import BoundedGrowthEnforcer
+
+# Default interval: 6 hours
+DEFAULT_INTERVAL_SECONDS = 21600
+
+
+class LifecycleScheduler:
+    """Background scheduler for periodic lifecycle evaluation.
+
+    Orchestrates the evaluator, engine, and bounded growth enforcer
+    on a configurable timer interval.
+    """
+
+    def __init__(
+        self,
+        db_path: Optional[str] = None,
+        config_path: Optional[str] = None,
+        interval_seconds: int = DEFAULT_INTERVAL_SECONDS,
+    ):
+        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
+        self.interval_seconds = interval_seconds
+
+        self._engine = LifecycleEngine(self._db_path, config_path=config_path)
+        self._evaluator = LifecycleEvaluator(self._db_path, config_path=config_path)
+        self._enforcer = BoundedGrowthEnforcer(self._db_path, config_path=config_path)
+
+        self._timer: Optional[threading.Timer] = None
+        self._running = False
+        self._lock = threading.Lock()
+
+    @property
+    def is_running(self) -> bool:
+        """Whether the scheduler is currently running."""
+        return self._running
+
+    def start(self) -> None:
+        """Start the background scheduler."""
+        with self._lock:
+            if self._running:
+                return
+            self._running = True
+            self._schedule_next()
+
+    def stop(self) -> None:
+        """Stop the background scheduler."""
+        with self._lock:
+            self._running = False
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+
+    def run_now(self) -> Dict[str, Any]:
+        """Execute a lifecycle evaluation cycle immediately.
+
+        Returns:
+            Dict with evaluation results, enforcement results, and timestamp
+        """
+        return self._execute_cycle()
+
+    def _schedule_next(self) -> None:
+        """Schedule the next evaluation cycle."""
+        self._timer = threading.Timer(self.interval_seconds, self._run_cycle)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _run_cycle(self) -> None:
+        """Run one evaluation cycle, then schedule the next."""
+        try:
+            self._execute_cycle()
+        except Exception:
+            pass  # Scheduler must not crash
+        finally:
+            with self._lock:
+                if self._running:
+                    self._schedule_next()
+
+    def _execute_cycle(self) -> Dict[str, Any]:
+        """Core evaluation + enforcement logic.
+
+        1. Evaluate all memories for potential transitions
+        2. Execute recommended transitions via the engine
+        3. Enforce bounded growth limits
+        """
+        # Step 1: Evaluate
+        recommendations = self._evaluator.evaluate_memories()
+
+        # Step 2: Execute transitions
+        transitioned = 0
+        transition_results: List[Dict] = []
+        for rec in recommendations:
+            result = self._engine.transition_memory(
+                rec["memory_id"], rec["to_state"], reason=rec["reason"]
+            )
+            if result.get("success"):
+                transitioned += 1
+                transition_results.append(result)
+
+        # Step 3: Enforce bounds
+        enforcement = self._enforcer.enforce_bounds()
+
+        return {
+            "timestamp": datetime.now().isoformat(),
+            "evaluation": {
+                "recommendations": recommendations,
+                "transitioned": transitioned,
+                "transition_results": transition_results,
+            },
+            "enforcement": enforcement,
+        }