superlocalmemory 2.8.6 → 3.0.0

package/src/lifecycle/lifecycle_scheduler.py

@@ -1,130 +0,0 @@
-# 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,
-        }

package/src/lifecycle/retention_policy.py

@@ -1,285 +0,0 @@
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""Retention policy loading, evaluation, and enforcement.
-
-Manages retention policies that determine how long memories must be kept
-in specific states. Supports GDPR (right to erasure), EU AI Act (audit
-retention), and HIPAA (medical record retention) compliance frameworks.
-
-Policies are stored in a `retention_policies` table alongside the memories
-database. Each policy specifies criteria (tags, project_name) for matching
-memories and an action (retain, archive, tombstone) with a retention period.
-"""
-import json
-import logging
-import sqlite3
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Set
-
-logger = logging.getLogger(__name__)
-
-_POLICIES_TABLE_SQL = """
-CREATE TABLE IF NOT EXISTS retention_policies (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    retention_days INTEGER NOT NULL,
-    framework TEXT NOT NULL,
-    action TEXT NOT NULL,
-    applies_to TEXT NOT NULL,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-)
-"""
-
-
-class RetentionPolicyManager:
-    """Manages retention policies for lifecycle enforcement.
-
-    Evaluates which compliance policies apply to each memory based on
-    tag and project_name matching. When multiple policies match, the
-    strictest (shortest retention_days) wins.
-    """
-
-    def __init__(self, db_path: Optional[str] = None):
-        self._db_path = db_path
-        if db_path:
-            self._ensure_table()
-
-    # ------------------------------------------------------------------
-    # Internal helpers
-    # ------------------------------------------------------------------
-
-    def _connect(self) -> sqlite3.Connection:
-        """Open a connection to the database."""
-        conn = sqlite3.connect(self._db_path)
-        conn.row_factory = sqlite3.Row
-        return conn
-
-    def _ensure_table(self) -> None:
-        """Create the retention_policies table if it doesn't exist."""
-        conn = self._connect()
-        try:
-            conn.execute(_POLICIES_TABLE_SQL)
-            conn.commit()
-        finally:
-            conn.close()
-
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
-
-    def create_policy(
-        self,
-        name: str,
-        retention_days: int,
-        framework: str,
-        action: str,
-        applies_to: Dict[str, Any],
-    ) -> int:
-        """Create a new retention policy.
-
-        Args:
-            name: Human-readable policy name.
-            retention_days: Minimum days to retain (0 = immediate action).
-            framework: Compliance framework (gdpr, hipaa, eu_ai_act, internal).
-            action: What to do (retain, archive, tombstone).
-            applies_to: Criteria dict with optional keys: tags, project_name.
-
-        Returns:
-            The auto-generated policy ID.
-        """
-        conn = self._connect()
-        try:
-            cursor = conn.execute(
-                "INSERT INTO retention_policies (name, retention_days, framework, action, applies_to) "
-                "VALUES (?, ?, ?, ?, ?)",
-                (name, retention_days, framework, action, json.dumps(applies_to)),
-            )
-            conn.commit()
-            return cursor.lastrowid
-        finally:
-            conn.close()
-
-    def list_policies(self) -> List[Dict[str, Any]]:
-        """Return all retention policies as a list of dicts."""
-        conn = self._connect()
-        try:
-            rows = conn.execute("SELECT * FROM retention_policies ORDER BY id").fetchall()
-            return [self._row_to_dict(r) for r in rows]
-        finally:
-            conn.close()
-
-    def load_policies(self, path: str) -> int:
-        """Load retention policies from a JSON file.
-
-        The file must contain a JSON array of policy objects, each with
-        keys: name, retention_days, framework, action, applies_to.
-
-        Args:
-            path: Absolute or relative path to the JSON policy file.
-
-        Returns:
-            Number of policies loaded. Returns 0 if file is missing or
-            contains invalid data, without raising an exception.
-        """
-        policy_path = Path(path)
-        if not policy_path.exists():
-            logger.debug("Policy file not found: %s", path)
-            return 0
-
-        try:
-            data = json.loads(policy_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError) as exc:
-            logger.warning("Failed to read policy file %s: %s", path, exc)
-            return 0
-
-        if not isinstance(data, list):
-            logger.warning("Policy file must contain a JSON array: %s", path)
-            return 0
-
-        count = 0
-        for entry in data:
-            try:
-                self.create_policy(
-                    name=entry["name"],
-                    retention_days=entry["retention_days"],
-                    framework=entry["framework"],
-                    action=entry["action"],
-                    applies_to=entry.get("applies_to", {}),
-                )
-                count += 1
-            except (KeyError, TypeError) as exc:
-                logger.warning("Skipping invalid policy entry: %s", exc)
-
-        return count
-
-    def evaluate_memory(self, memory_id: int) -> Optional[Dict[str, Any]]:
-        """Determine which retention policy applies to a memory.
-
-        Loads the memory's tags and project_name, then checks every
-        policy's ``applies_to`` criteria. If multiple policies match,
-        the **strictest** one wins (lowest ``retention_days``).
-
-        Args:
-            memory_id: The memory row ID.
-
-        Returns:
-            A dict with ``policy_name``, ``action``, ``retention_days``,
-            and ``framework``; or ``None`` if no policy matches.
-        """
-        conn = self._connect()
-        try:
-            mem_row = conn.execute(
-                "SELECT tags, project_name FROM memories WHERE id = ?",
-                (memory_id,),
-            ).fetchone()
-            if mem_row is None:
-                return None
-
-            mem_tags = self._parse_json_field(mem_row["tags"])
-            mem_project = mem_row["project_name"]
-
-            policies = conn.execute(
-                "SELECT * FROM retention_policies ORDER BY retention_days ASC"
-            ).fetchall()
-
-            for policy in policies:
-                criteria = self._parse_json_field(policy["applies_to"])
-                if self._policy_matches(criteria, mem_tags, mem_project):
-                    return {
-                        "policy_name": policy["name"],
-                        "action": policy["action"],
-                        "retention_days": policy["retention_days"],
-                        "framework": policy["framework"],
-                    }
-
-            return None
-        finally:
-            conn.close()
-
-    def get_protected_memory_ids(self) -> Set[int]:
-        """Return the set of memory IDs protected by any ``retain`` policy.
-
-        A memory is protected if at least one policy with
-        ``action='retain'`` matches its tags or project_name.
-        """
-        conn = self._connect()
-        try:
-            retain_policies = conn.execute(
-                "SELECT * FROM retention_policies WHERE action = 'retain'"
-            ).fetchall()
-            if not retain_policies:
-                return set()
-
-            memories = conn.execute(
-                "SELECT id, tags, project_name FROM memories"
-            ).fetchall()
-
-            protected: Set[int] = set()
-            for mem in memories:
-                mem_tags = self._parse_json_field(mem["tags"])
-                mem_project = mem["project_name"]
-                for policy in retain_policies:
-                    criteria = self._parse_json_field(policy["applies_to"])
-                    if self._policy_matches(criteria, mem_tags, mem_project):
-                        protected.add(mem["id"])
-                        break  # One matching retain policy is enough
-
-            return protected
-        finally:
-            conn.close()
-
-    # ------------------------------------------------------------------
-    # Private helpers
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _row_to_dict(row: sqlite3.Row) -> Dict[str, Any]:
-        """Convert a sqlite3.Row to a plain dict with parsed applies_to."""
-        d = dict(row)
-        if "applies_to" in d and isinstance(d["applies_to"], str):
-            try:
-                d["applies_to"] = json.loads(d["applies_to"])
-            except (json.JSONDecodeError, TypeError):
-                d["applies_to"] = {}
-        return d
-
-    @staticmethod
-    def _parse_json_field(value: Any) -> Any:
-        """Parse a JSON string field; return as-is if already parsed."""
-        if isinstance(value, str):
-            try:
-                return json.loads(value)
-            except (json.JSONDecodeError, TypeError):
-                return value
-        return value if value is not None else []
-
-    @staticmethod
-    def _policy_matches(
-        criteria: Any, mem_tags: Any, mem_project: Optional[str]
-    ) -> bool:
-        """Check if a policy's applies_to criteria match a memory.
-
-        Matching rules:
-        - If criteria has ``tags``: memory must have at least one
-          overlapping tag.
-        - If criteria has ``project_name``: memory's project_name
-          must equal the criteria value.
-        - If criteria is empty (``{}``): the policy does NOT match
-          any memory (opt-in only).
-        """
-        if not isinstance(criteria, dict) or not criteria:
-            return False
-
-        matched = True  # Assume match; any failing criterion flips to False
-
-        if "tags" in criteria:
-            policy_tags = set(criteria["tags"]) if criteria["tags"] else set()
-            memory_tags = set(mem_tags) if isinstance(mem_tags, list) else set()
-            if not policy_tags & memory_tags:
-                matched = False
-
-        if "project_name" in criteria:
-            if mem_project != criteria["project_name"]:
-                matched = False
-
-        return matched

package/src/lifecycle/tests/test_bounded_growth.py

@@ -1,193 +0,0 @@
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""Tests for bounded growth enforcement — memory count limits.
-"""
-import sqlite3
-import tempfile
-import os
-import sys
-import json
-from datetime import datetime, timedelta
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
-
-
-class TestBoundedGrowth:
-    """Test bounded growth enforcement and memory scoring."""
-
-    def setup_method(self):
-        self.tmp_dir = tempfile.mkdtemp()
-        self.db_path = os.path.join(self.tmp_dir, "test.db")
-        conn = sqlite3.connect(self.db_path)
-        conn.execute("""
-            CREATE TABLE memories (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                content TEXT NOT NULL,
-                importance INTEGER DEFAULT 5,
-                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                last_accessed TIMESTAMP,
-                access_count INTEGER DEFAULT 0,
-                lifecycle_state TEXT DEFAULT 'active',
-                lifecycle_updated_at TIMESTAMP,
-                lifecycle_history TEXT DEFAULT '[]',
-                access_level TEXT DEFAULT 'public',
-                profile TEXT DEFAULT 'default'
-            )
-        """)
-        now = datetime.now()
-
-        # Memory 1: HIGH value — importance 9, accessed today, frequently used
-        conn.execute(
-            "INSERT INTO memories (content, importance, lifecycle_state, last_accessed, created_at, access_count) VALUES (?, ?, ?, ?, ?, ?)",
-            ("high value memory", 9, "active", now.isoformat(), (now - timedelta(days=30)).isoformat(), 20),
-        )
-        # Memory 2: MEDIUM-HIGH — importance 7, accessed 5d ago
-        conn.execute(
-            "INSERT INTO memories (content, importance, lifecycle_state, last_accessed, created_at, access_count) VALUES (?, ?, ?, ?, ?, ?)",
-            ("medium high memory", 7, "active", (now - timedelta(days=5)).isoformat(), (now - timedelta(days=60)).isoformat(), 10),
-        )
-        # Memory 3: MEDIUM — importance 5, accessed 10d ago
-        conn.execute(
-            "INSERT INTO memories (content, importance, lifecycle_state, last_accessed, created_at, access_count) VALUES (?, ?, ?, ?, ?, ?)",
-            ("medium memory", 5, "active", (now - timedelta(days=10)).isoformat(), (now - timedelta(days=90)).isoformat(), 5),
-        )
-        # Memory 4: LOW — importance 3, accessed 20d ago, rarely used
-        conn.execute(
-            "INSERT INTO memories (content, importance, lifecycle_state, last_accessed, created_at, access_count) VALUES (?, ?, ?, ?, ?, ?)",
-            ("low value memory", 3, "active", (now - timedelta(days=20)).isoformat(), (now - timedelta(days=120)).isoformat(), 2),
-        )
-        # Memory 5: LOWEST — importance 1, accessed 40d ago, never reused
-        conn.execute(
-            "INSERT INTO memories (content, importance, lifecycle_state, last_accessed, created_at, access_count) VALUES (?, ?, ?, ?, ?, ?)",
-            ("lowest value memory", 1, "active", (now - timedelta(days=40)).isoformat(), (now - timedelta(days=150)).isoformat(), 0),
-        )
-        # Memory 6: Warm state (for warm bounds test) — importance 2, stale
-        conn.execute(
-            "INSERT INTO memories (content, importance, lifecycle_state, last_accessed, created_at, access_count) VALUES (?, ?, ?, ?, ?, ?)",
-            ("warm memory A", 2, "warm", (now - timedelta(days=50)).isoformat(), (now - timedelta(days=200)).isoformat(), 1),
-        )
-        # Memory 7: Warm state — importance 4
-        conn.execute(
-            "INSERT INTO memories (content, importance, lifecycle_state, last_accessed, created_at, access_count) VALUES (?, ?, ?, ?, ?, ?)",
-            ("warm memory B", 4, "warm", (now - timedelta(days=30)).isoformat(), (now - timedelta(days=100)).isoformat(), 3),
-        )
-        conn.commit()
-        conn.close()
-
-    def teardown_method(self):
-        import shutil
-        shutil.rmtree(self.tmp_dir, ignore_errors=True)
-
-    def test_no_action_under_limit(self):
-        """No transitions when counts are within bounds."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        enforcer = BoundedGrowthEnforcer(self.db_path)
-        result = enforcer.enforce_bounds()
-        assert result["enforced"] is False
-        assert len(result["transitions"]) == 0
-
-    def test_enforce_active_limit(self):
-        """When active_count > max_active, excess memories transition to warm."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        config_path = os.path.join(self.tmp_dir, "lifecycle_config.json")
-        with open(config_path, "w") as f:
-            json.dump({"bounds": {"max_active": 3, "max_warm": 100}}, f)
-        enforcer = BoundedGrowthEnforcer(self.db_path, config_path=config_path)
-        result = enforcer.enforce_bounds()
-        assert result["enforced"] is True
-        # 5 active, limit 3 -> 2 should transition
-        assert len(result["transitions"]) == 2
-
-    def test_lowest_scoring_evicted_first(self):
-        """The lowest-scoring memories should be the ones transitioned."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        config_path = os.path.join(self.tmp_dir, "lifecycle_config.json")
-        with open(config_path, "w") as f:
-            json.dump({"bounds": {"max_active": 3, "max_warm": 100}}, f)
-        enforcer = BoundedGrowthEnforcer(self.db_path, config_path=config_path)
-        result = enforcer.enforce_bounds()
-        evicted_ids = {t["memory_id"] for t in result["transitions"]}
-        # Memory 5 (importance 1, stale 40d) and Memory 4 (importance 3, stale 20d)
-        # should be evicted — lowest scores
-        assert 5 in evicted_ids
-        assert 4 in evicted_ids
-        # Top 3 memories (1, 2, 3) should survive
-        assert 1 not in evicted_ids
-        assert 2 not in evicted_ids
-        assert 3 not in evicted_ids
-
-    def test_evicted_memories_now_warm(self):
-        """Evicted memories should now be in 'warm' state in the database."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        config_path = os.path.join(self.tmp_dir, "lifecycle_config.json")
-        with open(config_path, "w") as f:
-            json.dump({"bounds": {"max_active": 3, "max_warm": 100}}, f)
-        enforcer = BoundedGrowthEnforcer(self.db_path, config_path=config_path)
-        enforcer.enforce_bounds()
-        conn = sqlite3.connect(self.db_path)
-        row4 = conn.execute("SELECT lifecycle_state FROM memories WHERE id=4").fetchone()
-        row5 = conn.execute("SELECT lifecycle_state FROM memories WHERE id=5").fetchone()
-        conn.close()
-        assert row4[0] == "warm"
-        assert row5[0] == "warm"
-
-    def test_enforce_warm_limit(self):
-        """When warm_count > max_warm, excess warm memories transition to cold."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        config_path = os.path.join(self.tmp_dir, "lifecycle_config.json")
-        with open(config_path, "w") as f:
-            json.dump({"bounds": {"max_active": 100, "max_warm": 1}}, f)
-        enforcer = BoundedGrowthEnforcer(self.db_path, config_path=config_path)
-        result = enforcer.enforce_bounds()
-        assert result["enforced"] is True
-        # 2 warm (ids 6, 7), limit 1 -> 1 transition
-        warm_transitions = [t for t in result["transitions"] if t["from_state"] == "warm"]
-        assert len(warm_transitions) == 1
-        # Memory 6 (importance 2, stale 50d) should be evicted before Memory 7 (importance 4, stale 30d)
-        assert warm_transitions[0]["memory_id"] == 6
-
-    def test_score_memory_importance_matters(self):
-        """Higher importance -> higher score, all else equal."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        enforcer = BoundedGrowthEnforcer(self.db_path)
-        scores = enforcer.score_all_memories()
-        # Memory 1 (importance 9) should score higher than Memory 5 (importance 1)
-        score_map = {s["memory_id"]: s["score"] for s in scores}
-        assert score_map[1] > score_map[5]
-
-    def test_score_memory_recency_matters(self):
-        """More recently accessed -> higher score."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        enforcer = BoundedGrowthEnforcer(self.db_path)
-        scores = enforcer.score_all_memories()
-        score_map = {s["memory_id"]: s["score"] for s in scores}
-        # Memory 1 (accessed today) should score higher than Memory 3 (accessed 10d ago)
-        # (both active, Memory 1 also has higher importance, so this should hold)
-        assert score_map[1] > score_map[3]
-
-    def test_score_all_returns_all_active(self):
-        """score_all_memories returns scores for all memories in given state."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        enforcer = BoundedGrowthEnforcer(self.db_path)
-        scores = enforcer.score_all_memories(state="active")
-        assert len(scores) == 5  # 5 active memories
-
-    def test_result_structure(self):
-        """enforce_bounds returns properly structured result dict."""
-        from lifecycle.bounded_growth import BoundedGrowthEnforcer
-        enforcer = BoundedGrowthEnforcer(self.db_path)
-        result = enforcer.enforce_bounds()
-        assert "enforced" in result
-        assert "active_count" in result
-        assert "active_limit" in result
-        assert "warm_count" in result
-        assert "warm_limit" in result
-        assert "transitions" in result
-        assert isinstance(result["transitions"], list)
-
-    def test_default_bounds(self):
-        """Default bounds should be max_active=10000, max_warm=5000."""
-        from lifecycle.bounded_growth import DEFAULT_BOUNDS
-        assert DEFAULT_BOUNDS["max_active"] == 10000
-        assert DEFAULT_BOUNDS["max_warm"] == 5000