superlocalmemory 2.7.6 → 2.8.0

package/src/lifecycle/retention_policy.py

@@ -0,0 +1,285 @@
+# 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/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tests for lifecycle engine.
+"""

package/src/lifecycle/tests/test_bounded_growth.py

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

package/src/lifecycle/tests/test_compaction.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
+"""Tests for compaction engine — content archival and restoration.
+"""
+import sqlite3
+import tempfile
+import os
+import sys
+import json
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+
+
+class TestCompactionEngine:
+    """Test memory compaction and restoration."""
+
+    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',
+                tags TEXT DEFAULT '[]',
+                summary TEXT
+            )
+        """)
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS memory_archive (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                memory_id INTEGER UNIQUE NOT NULL,
+                full_content TEXT NOT NULL,
+                archived_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+            )
+        """)
+        conn.execute("CREATE INDEX IF NOT EXISTS idx_archive_memory ON memory_archive(memory_id)")
+
+        # Memory 1: Long content suitable for compaction
+        long_content = (
+            "The Python programming language is widely used for machine learning and data science. "
+            "It provides libraries like scikit-learn, TensorFlow, and PyTorch for building models. "
+            "Python's simplicity and readability make it ideal for rapid prototyping. "
+            "The ecosystem includes tools for data preprocessing, visualization, and deployment. "
+            "Many enterprise applications use Python for backend services and API development."
+        )
+        conn.execute(
+            "INSERT INTO memories (content, importance, lifecycle_state, tags) VALUES (?, ?, ?, ?)",
+            (long_content, 5, "cold", '["python","ml"]'),
+        )
+        # Memory 2: Short content
+        conn.execute(
+            "INSERT INTO memories (content, importance, lifecycle_state) VALUES (?, ?, ?)",
+            ("brief note about testing", 3, "cold"),
+        )
+        # Memory 3: Already archived
+        conn.execute(
+            "INSERT INTO memories (content, importance, lifecycle_state) VALUES (?, ?, ?)",
+            ("[COMPACTED] Key entities: database, SQL", 5, "archived"),
+        )
+        conn.execute(
+            "INSERT INTO memory_archive (memory_id, full_content) VALUES (?, ?)",
+            (3, "The database management system uses SQL for querying and PostgreSQL for storage."),
+        )
+        conn.commit()
+        conn.close()
+
+    def teardown_method(self):
+        import shutil
+        shutil.rmtree(self.tmp_dir, ignore_errors=True)
+
+    def test_compact_memory_archives_content(self):
+        """Compaction stores full content in memory_archive."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        result = engine.compact_memory(1)
+        assert result["success"] is True
+        # Verify archive has full content
+        conn = sqlite3.connect(self.db_path)
+        row = conn.execute("SELECT full_content FROM memory_archive WHERE memory_id=1").fetchone()
+        conn.close()
+        assert row is not None
+        assert "Python programming" in row[0]
+
+    def test_compact_memory_replaces_content(self):
+        """Compacted memory content is replaced with summary + entities."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        engine.compact_memory(1)
+        conn = sqlite3.connect(self.db_path)
+        row = conn.execute("SELECT content FROM memories WHERE id=1").fetchone()
+        conn.close()
+        # Content should be shorter than original
+        assert len(row[0]) < 300
+        assert "[COMPACTED]" in row[0]
+
+    def test_compact_preserves_key_entities(self):
+        """Compacted content preserves key entities/terms."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        result = engine.compact_memory(1)
+        assert "entities" in result
+        assert len(result["entities"]) >= 3
+        # Should extract key terms like "python", "learning", "data"
+        entities_lower = [e.lower() for e in result["entities"]]
+        assert any("python" in e for e in entities_lower)
+
+    def test_compact_preserves_tags(self):
+        """Compaction does NOT remove tags from the memory."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        engine.compact_memory(1)
+        conn = sqlite3.connect(self.db_path)
+        row = conn.execute("SELECT tags FROM memories WHERE id=1").fetchone()
+        conn.close()
+        assert row[0] is not None
+        tags = json.loads(row[0])
+        assert "python" in tags
+
+    def test_restore_memory_from_archive(self):
+        """Restoring a compacted memory brings back full content."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        result = engine.restore_memory(3)  # Already archived memory
+        assert result["success"] is True
+        conn = sqlite3.connect(self.db_path)
+        row = conn.execute("SELECT content FROM memories WHERE id=3").fetchone()
+        conn.close()
+        assert "database management" in row[0]
+
+    def test_restore_cleans_archive(self):
+        """After restoration, the archive entry is removed."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        engine.restore_memory(3)
+        conn = sqlite3.connect(self.db_path)
+        row = conn.execute("SELECT * FROM memory_archive WHERE memory_id=3").fetchone()
+        conn.close()
+        assert row is None
+
+    def test_dry_run_no_changes(self):
+        """dry_run mode shows what would happen without modifying DB."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        result = engine.compact_memory(1, dry_run=True)
+        assert result["success"] is True
+        assert result["dry_run"] is True
+        # Verify DB was NOT modified
+        conn = sqlite3.connect(self.db_path)
+        row = conn.execute("SELECT content FROM memories WHERE id=1").fetchone()
+        archive = conn.execute("SELECT * FROM memory_archive WHERE memory_id=1").fetchone()
+        conn.close()
+        assert "Python programming" in row[0]  # Original content still there
+        assert archive is None  # No archive entry created
+
+    def test_compact_nonexistent_memory(self):
+        """Compacting nonexistent memory returns failure."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        result = engine.compact_memory(999)
+        assert result["success"] is False
+
+    def test_restore_nonexistent_archive(self):
+        """Restoring memory without archive entry returns failure."""
+        from lifecycle.compaction_engine import CompactionEngine
+        engine = CompactionEngine(self.db_path)
+        result = engine.restore_memory(1)  # Memory 1 has no archive
+        assert result["success"] is False