superlocalmemory 3.4.9 → 3.4.11

package/src/superlocalmemory/core/graph_pruner.py

@@ -0,0 +1,290 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3.4.11 "Scale-Ready" — Graph Pruning Engine.
+
+Reduces graph_edges count without losing meaningful connections:
+  1. Orphan removal: edges where source/target no longer exists
+  2. Self-loop removal: edges where source == target
+  3. Duplicate removal: keeps highest-weight edge per (source, target, type)
+  4. Supersedes chain collapse: A→B→C becomes A→B + A→C (B→C removed)
+
+CRITICAL: Never deletes facts. Only prunes graph EDGES.
+All operations are profile-scoped and idempotent.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import time
+import uuid
+from datetime import datetime, UTC
+from pathlib import Path
+
+logger = logging.getLogger("superlocalmemory.graph_pruner")
+
+_CHAIN_BATCH_LIMIT = 10_000
+
+
+def prune_graph(
+    db_path: str | Path,
+    profile_id: str = "default",
+    dry_run: bool = False,
+) -> dict:
+    """Run all graph pruning strategies for a specific profile.
+
+    Returns stats dict with counts for each strategy.
+    """
+    conn = sqlite3.connect(str(db_path))
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=10000")
+    conn.row_factory = sqlite3.Row
+
+    stats = {
+        "orphans_removed": 0,
+        "supersedes_collapsed": 0,
+        "self_loops_removed": 0,
+        "duplicates_removed": 0,
+        "total_before": 0,
+        "total_after": 0,
+    }
+
+    try:
+        c = conn.cursor()
+        c.execute(
+            "SELECT COUNT(*) as cnt FROM graph_edges WHERE profile_id = ?",
+            (profile_id,),
+        )
+        stats["total_before"] = c.fetchone()["cnt"]
+
+        start = time.time()
+
+        # Explicit transaction for atomicity
+        c.execute("BEGIN")
+
+        stats["orphans_removed"] = _remove_orphan_edges(c, profile_id, dry_run)
+        stats["self_loops_removed"] = _remove_self_loops(c, profile_id, dry_run)
+        stats["duplicates_removed"] = _remove_duplicate_edges(c, profile_id, dry_run)
+        stats["supersedes_collapsed"] = _collapse_supersedes_chains(
+            c, profile_id, dry_run,
+        )
+
+        if dry_run:
+            c.execute("ROLLBACK")
+        else:
+            c.execute("COMMIT")
+
+        c.execute(
+            "SELECT COUNT(*) as cnt FROM graph_edges WHERE profile_id = ?",
+            (profile_id,),
+        )
+        stats["total_after"] = c.fetchone()["cnt"]
+
+        elapsed = time.time() - start
+        total_removed = stats["total_before"] - stats["total_after"]
+        pct = round(total_removed / max(stats["total_before"], 1) * 100, 1)
+
+        prefix = "(dry-run) " if dry_run else ""
+        logger.info(
+            "%sGraph pruning: removed %d edges (%.1f%%) in %.1fs — "
+            "orphans=%d, supersedes=%d, self_loops=%d, duplicates=%d",
+            prefix, total_removed, pct, elapsed,
+            stats["orphans_removed"], stats["supersedes_collapsed"],
+            stats["self_loops_removed"], stats["duplicates_removed"],
+        )
+
+    except Exception as exc:
+        logger.error("Graph pruning failed: %s", exc, exc_info=True)
+        stats["error"] = str(exc)
+        try:
+            c.execute("ROLLBACK")
+        except Exception:
+            pass
+    finally:
+        conn.close()
+
+    return stats
+
+
+def _remove_orphan_edges(
+    c: sqlite3.Cursor,
+    profile_id: str,
+    dry_run: bool,
+) -> int:
+    """Remove edges where source OR target no longer exists in facts/entities.
+
+    Scoped to profile_id. Checks both source_id and target_id.
+    """
+    orphan_sql = """
+        SELECT COUNT(*) as cnt FROM graph_edges
+        WHERE profile_id = ?
+          AND (
+            (source_id NOT IN (SELECT fact_id FROM atomic_facts)
+             AND source_id NOT IN (SELECT entity_id FROM canonical_entities))
+            OR
+            (target_id NOT IN (SELECT fact_id FROM atomic_facts)
+             AND target_id NOT IN (SELECT entity_id FROM canonical_entities))
+          )
+    """
+
+    if dry_run:
+        c.execute(orphan_sql, (profile_id,))
+        return c.fetchone()["cnt"]
+
+    c.execute("""
+        DELETE FROM graph_edges
+        WHERE profile_id = ?
+          AND (
+            (source_id NOT IN (SELECT fact_id FROM atomic_facts)
+             AND source_id NOT IN (SELECT entity_id FROM canonical_entities))
+            OR
+            (target_id NOT IN (SELECT fact_id FROM atomic_facts)
+             AND target_id NOT IN (SELECT entity_id FROM canonical_entities))
+          )
+    """, (profile_id,))
+    return c.rowcount
+
+
+def _remove_self_loops(
+    c: sqlite3.Cursor,
+    profile_id: str,
+    dry_run: bool,
+) -> int:
+    """Remove edges where source equals target. Scoped to profile_id."""
+    if dry_run:
+        c.execute(
+            "SELECT COUNT(*) as cnt FROM graph_edges "
+            "WHERE source_id = target_id AND profile_id = ?",
+            (profile_id,),
+        )
+        return c.fetchone()["cnt"]
+
+    c.execute(
+        "DELETE FROM graph_edges WHERE source_id = target_id AND profile_id = ?",
+        (profile_id,),
+    )
+    return c.rowcount
+
+
+def _remove_duplicate_edges(
+    c: sqlite3.Cursor,
+    profile_id: str,
+    dry_run: bool,
+) -> int:
+    """Remove duplicate edges (same source+target+type), keeping highest weight.
+
+    Uses correlated subquery for SQLite 3.22+ compatibility (no window functions).
+    """
+    if dry_run:
+        # Count actual edges to be deleted (total - groups = excess edges)
+        c.execute("""
+            SELECT
+                (SELECT COUNT(*) FROM graph_edges WHERE profile_id = ?) -
+                (SELECT COUNT(*) FROM (
+                    SELECT source_id, target_id, edge_type
+                    FROM graph_edges WHERE profile_id = ?
+                    GROUP BY source_id, target_id, edge_type
+                )) as cnt
+        """, (profile_id, profile_id))
+        return max(c.fetchone()["cnt"], 0)
+
+    # Keep the edge with highest weight per (source, target, type).
+    # Portable: no ROW_NUMBER() OVER, works on SQLite 3.22+.
+    c.execute("""
+        DELETE FROM graph_edges
+        WHERE profile_id = ?
+          AND edge_id NOT IN (
+            SELECT edge_id FROM graph_edges ge1
+            WHERE profile_id = ?
+              AND weight = (
+                SELECT MAX(weight) FROM graph_edges ge2
+                WHERE ge2.source_id = ge1.source_id
+                  AND ge2.target_id = ge1.target_id
+                  AND ge2.edge_type = ge1.edge_type
+                  AND ge2.profile_id = ge1.profile_id
+              )
+            GROUP BY source_id, target_id, edge_type
+          )
+    """, (profile_id, profile_id))
+    return c.rowcount
+
+
+def _collapse_supersedes_chains(
+    c: sqlite3.Cursor,
+    profile_id: str,
+    dry_run: bool,
+) -> int:
+    """Collapse supersedes chains: if A supersedes B and B supersedes C,
+    remove B→C edge AND create A→C shortcut edge.
+
+    Preserves reachability: A can still reach C via the new direct edge.
+    """
+    c.execute("""
+        SELECT e1.edge_id as e1_id, e1.source_id as a, e1.target_id as b,
+               e1.weight as e1_weight,
+               e2.edge_id as e2_id, e2.target_id as c
+        FROM graph_edges e1
+        JOIN graph_edges e2 ON e1.target_id = e2.source_id
+        WHERE e1.edge_type = 'supersedes'
+          AND e2.edge_type = 'supersedes'
+          AND e1.profile_id = ?
+          AND e2.profile_id = ?
+        LIMIT ?
+    """, (profile_id, profile_id, _CHAIN_BATCH_LIMIT))
+
+    chains = c.fetchall()
+    if not chains:
+        return 0
+
+    if len(chains) >= _CHAIN_BATCH_LIMIT:
+        logger.warning(
+            "Supersedes chain collapse hit limit (%d). "
+            "More chains may exist — will process in next cycle.",
+            _CHAIN_BATCH_LIMIT,
+        )
+
+    if dry_run:
+        return len(chains)
+
+    # Collect IDs for batch operations
+    delete_ids: list[str] = []
+    insert_rows: list[tuple] = []
+    now = datetime.now(UTC).isoformat()
+
+    for chain in chains:
+        a_id = chain["a"]
+        c_id = chain["c"]
+        e2_id = chain["e2_id"]
+        weight = chain["e1_weight"] or 1.0
+
+        delete_ids.append(e2_id)
+
+        # Create A→C shortcut edge (preserves reachability)
+        new_edge_id = uuid.uuid4().hex[:16]
+        insert_rows.append((
+            new_edge_id, profile_id, a_id, c_id,
+            "supersedes", weight, now,
+        ))
+
+    # Batch DELETE: remove all B→C intermediate edges
+    for i in range(0, len(delete_ids), 500):
+        batch = delete_ids[i:i + 500]
+        placeholders = ",".join("?" * len(batch))
+        c.execute(
+            f"DELETE FROM graph_edges WHERE edge_id IN ({placeholders})",
+            batch,
+        )
+
+    # Batch INSERT: add all A→C shortcut edges
+    c.executemany(
+        "INSERT OR IGNORE INTO graph_edges "
+        "(edge_id, profile_id, source_id, target_id, edge_type, weight, created_at) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+        insert_rows,
+    )
+
+    return len(delete_ids)

package/src/superlocalmemory/core/maintenance_scheduler.py

@@ -75,7 +75,7 @@ class MaintenanceScheduler:
         self._timer.start()
 
     def _run(self) -> None:
-        """Execute maintenance and schedule next run."""
+        """Execute maintenance + auto-backup check, then schedule next run."""
         if not self._running:
             return
         try:
@@ -84,8 +84,49 @@ class MaintenanceScheduler:
             logger.info("Scheduled maintenance complete: %s", counts)
         except Exception as exc:
             logger.warning("Scheduled maintenance failed: %s", exc)
-        finally:
-            self._schedule_next()
+
+        # V3.4.11: Graph pruning (remove orphan edges)
+        try:
+            from superlocalmemory.core.graph_pruner import prune_graph
+            prune_stats = prune_graph(self._db.db_path, self._profile_id)
+            removed = prune_stats["total_before"] - prune_stats["total_after"]
+            if removed > 0:
+                logger.info("Graph pruning: %d edges removed", removed)
+        except Exception as exc:
+            logger.debug("Graph pruning skipped: %s", exc)
+
+        # V3.4.11: Run tier evaluation (demote old facts)
+        try:
+            from superlocalmemory.core.tier_manager import evaluate_tiers
+            stats = evaluate_tiers(self._db, self._profile_id)
+            demoted = stats["demoted_to_warm"] + stats["demoted_to_cold"] + stats["demoted_to_archive"]
+            if demoted > 0:
+                logger.info("Tier evaluation: %d facts demoted", demoted)
+        except Exception as exc:
+            logger.debug("Tier evaluation skipped: %s", exc)
+
+        # V3.4.10: Check if auto-backup is due
+        try:
+            from superlocalmemory.infra.backup import BackupManager
+            manager = BackupManager(db_path=self._db.db_path)
+            filename = manager.check_and_backup()
+            if filename:
+                logger.info("Auto-backup created: %s", filename)
+                self._sync_cloud_destinations(manager)
+        except Exception as exc:
+            logger.debug("Auto-backup check skipped: %s", exc)
+
+        self._schedule_next()
+
+    def _sync_cloud_destinations(self, manager: object) -> None:
+        """Push latest backup to configured cloud destinations."""
+        try:
+            from superlocalmemory.infra.cloud_backup import sync_all_destinations
+            sync_all_destinations(self._db.db_path)
+        except ImportError:
+            pass  # cloud_backup module not available yet
+        except Exception as exc:
+            logger.warning("Cloud sync failed (non-critical): %s", exc)
 
     def __del__(self) -> None:
         try:

package/src/superlocalmemory/core/recall_pipeline.py

@@ -226,6 +226,15 @@ def run_recall(
         except Exception as exc:
             logger.debug("Access log batch store failed: %s", exc)
 
+    # V3.4.11: Promote recalled facts back to active tier (single batch UPDATE)
+    if response.results:
+        try:
+            from superlocalmemory.core.tier_manager import promote_on_access_batch
+            fact_ids = [r.fact.fact_id for r in response.results[:10]]
+            promote_on_access_batch(db, fact_ids)
+        except Exception:
+            pass  # tier_manager not available yet — graceful
+
     # V3.3.16: Behavioral tracking + spaced repetition use module-level
     # singletons to avoid creating new objects per recall (was causing
     # object accumulation across 304 benchmark recalls).

package/src/superlocalmemory/core/tier_manager.py

@@ -0,0 +1,325 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3.4.11 "Scale-Ready" — Tier Manager.
+
+Manages the lifecycle tiers of atomic facts:
+  - active (hot): Recent, frequently accessed. Full retrieval priority.
+  - warm: Consolidated or aging. Reduced retrieval weight (0.7x).
+  - cold: Old, rarely accessed. Low retrieval weight (0.3x).
+  - archived: Superseded or consolidated. Excluded from default retrieval,
+              but searchable via deep recall.
+
+CRITICAL RULE: Facts are NEVER deleted. Only moved between tiers.
+The forgetting curve affects RETRIEVAL RANKING, not data existence.
+
+Demotion logic: A fact is demoted based on time since last access
+(via fact_retention.last_accessed_at), NOT total age from created_at.
+If no access record exists, created_at is used as fallback.
+
+Runs on the maintenance scheduler alongside Ebbinghaus/Langevin.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, UTC
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.storage.database import DatabaseManager
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Tier thresholds (configurable via SLMConfig in future)
+# ---------------------------------------------------------------------------
+
+WARM_AFTER_DAYS = 30       # active → warm after 30 days without access
+COLD_AFTER_DAYS = 180      # warm → cold after 180 days without access
+ARCHIVE_AFTER_DAYS = 365   # cold → archived after 365 days without access
+
+ACCESS_BOOST_THRESHOLD = 5    # 5+ accesses: boost demotion timer
+ACCESS_BOOST_MULTIPLIER = 2.0
+
+IMPORTANCE_RESIST_THRESHOLD = 0.8  # importance >= 0.8: boost demotion timer
+IMPORTANCE_RESIST_MULTIPLIER = 3.0
+
+# Cap: when both boosts apply, use max (not multiplicative) to prevent
+# 6x suppression (which would delay archival for 6+ years).
+MAX_COMBINED_MULTIPLIER = 3.0
+
+_BATCH_SIZE = 1000  # Process facts in batches to prevent OOM at scale
+
+
+def evaluate_tiers(
+    db: DatabaseManager,
+    profile_id: str = "default",
+    dry_run: bool = False,
+) -> dict[str, int]:
+    """Evaluate and update lifecycle tiers for all facts in a profile.
+
+    Rules:
+      1. Pinned facts ALWAYS stay 'active' regardless of age/access.
+      2. Recently accessed facts resist demotion (access_count boost).
+      3. High-importance facts resist demotion (importance boost).
+      4. Boosts cap at MAX_COMBINED_MULTIPLIER (3x), not multiplicative.
+      5. NEVER delete facts. NEVER.
+    """
+    stats = {
+        "demoted_to_warm": 0,
+        "demoted_to_cold": 0,
+        "demoted_to_archive": 0,
+        "pinned_protected": 0,
+        "total_evaluated": 0,
+    }
+
+    now = datetime.now(UTC)
+    pinned_ids = _get_pinned_fact_ids(db, profile_id)
+
+    stats["demoted_to_warm"] = _demote_tier(
+        db, profile_id, "active", "warm",
+        WARM_AFTER_DAYS, pinned_ids, now, dry_run,
+    )
+    stats["demoted_to_cold"] = _demote_tier(
+        db, profile_id, "warm", "cold",
+        COLD_AFTER_DAYS, pinned_ids, now, dry_run,
+    )
+    stats["demoted_to_archive"] = _demote_tier(
+        db, profile_id, "cold", "archived",
+        ARCHIVE_AFTER_DAYS, pinned_ids, now, dry_run,
+    )
+
+    stats["pinned_protected"] = len(pinned_ids)
+
+    # Count only non-archived facts (archived are not inspected by _demote_tier)
+    rows = db.execute(
+        "SELECT COUNT(*) as c FROM atomic_facts "
+        "WHERE profile_id = ? AND lifecycle != 'archived'",
+        (profile_id,),
+    )
+    stats["total_evaluated"] = rows[0]["c"] if rows else 0
+
+    total_demoted = (
+        stats["demoted_to_warm"]
+        + stats["demoted_to_cold"]
+        + stats["demoted_to_archive"]
+    )
+    if total_demoted > 0:
+        logger.info(
+            "Tier evaluation: %d demoted (warm=%d, cold=%d, archive=%d), %d pinned",
+            total_demoted, stats["demoted_to_warm"],
+            stats["demoted_to_cold"], stats["demoted_to_archive"],
+            stats["pinned_protected"],
+        )
+
+    return stats
+
+
+def promote_on_access_batch(db: DatabaseManager, fact_ids: list[str]) -> int:
+    """Batch-promote facts back to 'active' when accessed during recall.
+
+    Single UPDATE for all fact IDs — avoids N sequential writes on hot path.
+    """
+    if not fact_ids:
+        return 0
+    placeholders = ",".join("?" * len(fact_ids))
+    db.execute(
+        f"UPDATE atomic_facts SET lifecycle = 'active' "
+        f"WHERE fact_id IN ({placeholders}) AND lifecycle IN ('warm', 'cold')",
+        tuple(fact_ids),
+    )
+    return len(fact_ids)
+
+
+def promote_on_access(db: DatabaseManager, fact_id: str) -> None:
+    """Promote a single fact back to 'active' when accessed during recall.
+
+    Kept for backward compatibility. Prefer promote_on_access_batch.
+    """
+    db.execute(
+        "UPDATE atomic_facts SET lifecycle = 'active' "
+        "WHERE fact_id = ? AND lifecycle IN ('warm', 'cold')",
+        (fact_id,),
+    )
+
+
+def pin_fact(
+    db: DatabaseManager,
+    fact_id: str,
+    profile_id: str,
+    reason: str = "",
+) -> bool:
+    """Pin a fact to stay in active tier forever.
+
+    Both the pin record and lifecycle update are scoped to profile_id.
+    """
+    now = datetime.now(UTC).isoformat()
+    try:
+        db.execute(
+            "INSERT OR REPLACE INTO pinned_facts "
+            "(fact_id, profile_id, pinned_at, reason) VALUES (?, ?, ?, ?)",
+            (fact_id, profile_id, now, reason),
+        )
+        db.execute(
+            "UPDATE atomic_facts SET lifecycle = 'active' "
+            "WHERE fact_id = ? AND profile_id = ?",
+            (fact_id, profile_id),
+        )
+        return True
+    except Exception as exc:
+        logger.warning("Failed to pin fact %s: %s", fact_id, exc, exc_info=True)
+        return False
+
+
+def unpin_fact(db: DatabaseManager, fact_id: str) -> bool:
+    """Unpin a fact, allowing normal tier demotion to resume."""
+    try:
+        db.execute("DELETE FROM pinned_facts WHERE fact_id = ?", (fact_id,))
+        return True
+    except Exception as exc:
+        logger.warning("Failed to unpin fact %s: %s", fact_id, exc, exc_info=True)
+        return False
+
+
+def get_tier_stats(db: DatabaseManager, profile_id: str = "default") -> dict:
+    """Get tier distribution stats for the dashboard."""
+    rows = db.execute(
+        "SELECT lifecycle, COUNT(*) as cnt FROM atomic_facts "
+        "WHERE profile_id = ? GROUP BY lifecycle",
+        (profile_id,),
+    )
+    dist = {r["lifecycle"]: r["cnt"] for r in rows}
+
+    pinned_rows = db.execute(
+        "SELECT COUNT(*) as c FROM pinned_facts WHERE profile_id = ?",
+        (profile_id,),
+    )
+    pinned = pinned_rows[0]["c"] if pinned_rows else 0
+
+    total = sum(dist.values())
+    return {
+        "active": dist.get("active", 0),
+        "warm": dist.get("warm", 0),
+        "cold": dist.get("cold", 0),
+        "archived": dist.get("archived", 0),
+        "total": total,
+        "pinned": pinned,
+        "active_pct": round(dist.get("active", 0) / max(total, 1) * 100, 1),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _get_pinned_fact_ids(db: DatabaseManager, profile_id: str) -> frozenset[str]:
+    """Load all pinned fact IDs for a profile."""
+    try:
+        rows = db.execute(
+            "SELECT fact_id FROM pinned_facts WHERE profile_id = ?",
+            (profile_id,),
+        )
+        return frozenset(r["fact_id"] for r in rows)
+    except Exception as exc:
+        logger.warning(
+            "Failed to load pinned facts for profile %s: %s",
+            profile_id, exc, exc_info=True,
+        )
+        return frozenset()
+
+
+def _demote_tier(
+    db: DatabaseManager,
+    profile_id: str,
+    from_tier: str,
+    to_tier: str,
+    base_days: int,
+    pinned_ids: frozenset[str],
+    now: datetime,
+    dry_run: bool,
+) -> int:
+    """Demote facts from one tier to the next based on idle time.
+
+    Uses last_accessed_at from fact_retention as the reference date
+    (time since last access). Falls back to created_at if no access record.
+    Processes in batches of _BATCH_SIZE to prevent OOM at scale.
+    """
+    demoted_ids: list[str] = []
+    offset = 0
+
+    while True:
+        rows = db.execute(
+            "SELECT af.fact_id, af.access_count, af.importance, "
+            "       af.created_at, fr.last_accessed_at "
+            "FROM atomic_facts af "
+            "LEFT JOIN fact_retention fr ON af.fact_id = fr.fact_id "
+            "WHERE af.profile_id = ? AND af.lifecycle = ? "
+            "LIMIT ? OFFSET ?",
+            (profile_id, from_tier, _BATCH_SIZE, offset),
+        )
+
+        if not rows:
+            break
+
+        for row in rows:
+            fid = row["fact_id"]
+
+            if fid in pinned_ids:
+                continue
+
+            effective_days = float(base_days)
+
+            access_count = row["access_count"] or 0
+            access_mult = (
+                ACCESS_BOOST_MULTIPLIER
+                if access_count >= ACCESS_BOOST_THRESHOLD
+                else 1.0
+            )
+
+            importance = row["importance"] or 0.5
+            importance_mult = (
+                IMPORTANCE_RESIST_MULTIPLIER
+                if importance >= IMPORTANCE_RESIST_THRESHOLD
+                else 1.0
+            )
+
+            # Cap: use max of the two boosts, not multiplicative
+            effective_days *= min(max(access_mult, importance_mult), MAX_COMBINED_MULTIPLIER)
+
+            # Reference: last access time, fallback to created_at
+            ref_str = row["last_accessed_at"] or row["created_at"] or ""
+            if not ref_str:
+                continue
+
+            try:
+                ref_date = datetime.fromisoformat(ref_str.replace("Z", "+00:00"))
+                if ref_date.tzinfo is None:
+                    ref_date = ref_date.replace(tzinfo=UTC)
+                idle_time = now - ref_date
+                if idle_time < timedelta(days=effective_days):
+                    continue
+            except (ValueError, TypeError):
+                continue
+
+            demoted_ids.append(fid)
+
+        if len(rows) < _BATCH_SIZE:
+            break
+        offset += _BATCH_SIZE
+
+    if demoted_ids and not dry_run:
+        # Batch UPDATE in chunks of 500
+        for i in range(0, len(demoted_ids), 500):
+            batch = demoted_ids[i:i + 500]
+            placeholders = ",".join("?" * len(batch))
+            db.execute(
+                f"UPDATE atomic_facts SET lifecycle = ? "
+                f"WHERE fact_id IN ({placeholders}) AND lifecycle = ?",
+                (to_tier, *batch, from_tier),
+            )
+
+    return len(demoted_ids)