superlocalmemory 3.2.1 → 3.2.3

package/src/superlocalmemory/storage/access_log.py

@@ -0,0 +1,169 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3
+
+"""Access log for fact retrieval events.
+
+Tracks when facts are accessed (recall, auto_invoke, search).
+Used by Phase 2 auto-invoke for recency scoring (H1 fix).
+All SQL parameterized (Rule 11). Silent errors (Rule 19).
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.storage.database import DatabaseManager
+
+logger = logging.getLogger(__name__)
+
+
+def _new_log_id() -> str:
+    """Generate a short unique log ID."""
+    return uuid.uuid4().hex[:16]
+
+
+class AccessLog:
+    """CRUD operations for fact_access_log table."""
+
+    def __init__(self, db: DatabaseManager) -> None:
+        self._db = db
+
+    def store_access(
+        self,
+        fact_id: str,
+        profile_id: str,
+        access_type: str = "recall",
+        session_id: str = "",
+    ) -> str:
+        """Record a fact access event. Returns log_id.
+
+        Validates access_type against allowed values.
+        Returns empty string on failure (Rule 19).
+        """
+        allowed = ("recall", "auto_invoke", "search", "consolidation")
+        if access_type not in allowed:
+            access_type = "recall"
+
+        log_id = _new_log_id()
+        try:
+            self._db.execute(
+                "INSERT INTO fact_access_log "
+                "(log_id, fact_id, profile_id, access_type, session_id) "
+                "VALUES (?, ?, ?, ?, ?)",
+                (log_id, fact_id, profile_id, access_type, session_id),
+            )
+            return log_id
+        except Exception as exc:
+            logger.debug("store_access failed for fact_id=%s: %s", fact_id, exc)
+            return ""
+
+    def store_access_batch(
+        self,
+        fact_ids: list[str],
+        profile_id: str,
+        access_type: str = "recall",
+        session_id: str = "",
+    ) -> int:
+        """Record access events for multiple facts. Returns count stored.
+
+        Catches exceptions per-fact (Rule 19: silent errors).
+        """
+        count = 0
+        for fact_id in fact_ids:
+            result = self.store_access(
+                fact_id, profile_id, access_type, session_id,
+            )
+            if result:
+                count += 1
+        return count
+
+    def get_latest_access_time(
+        self, fact_id: str, profile_id: str,
+    ) -> str | None:
+        """Most recent access timestamp for a fact.
+
+        Returns ISO datetime string or None if never accessed.
+        """
+        try:
+            rows = self._db.execute(
+                "SELECT MAX(accessed_at) AS latest "
+                "FROM fact_access_log "
+                "WHERE fact_id = ? AND profile_id = ?",
+                (fact_id, profile_id),
+            )
+            if rows and rows[0]["latest"] is not None:
+                return str(rows[0]["latest"])
+            return None
+        except Exception as exc:
+            logger.debug("get_latest_access_time failed: %s", exc)
+            return None
+
+    def get_access_count(
+        self, fact_id: str, profile_id: str,
+    ) -> int:
+        """Total access count for a fact."""
+        try:
+            rows = self._db.execute(
+                "SELECT COUNT(*) AS c "
+                "FROM fact_access_log "
+                "WHERE fact_id = ? AND profile_id = ?",
+                (fact_id, profile_id),
+            )
+            if rows:
+                return int(rows[0]["c"])
+            return 0
+        except Exception as exc:
+            logger.debug("get_access_count failed: %s", exc)
+            return 0
+
+    def get_all_access_times(
+        self, profile_id: str, limit: int = 1000,
+    ) -> dict[str, str]:
+        """Latest access time for all facts in a profile.
+
+        Returns {fact_id: latest_accessed_at} dict.
+        """
+        try:
+            rows = self._db.execute(
+                "SELECT fact_id, MAX(accessed_at) AS latest "
+                "FROM fact_access_log "
+                "WHERE profile_id = ? "
+                "GROUP BY fact_id "
+                "ORDER BY latest DESC "
+                "LIMIT ?",
+                (profile_id, limit),
+            )
+            return {str(r["fact_id"]): str(r["latest"]) for r in rows}
+        except Exception as exc:
+            logger.debug("get_all_access_times failed: %s", exc)
+            return {}
+
+    def get_frequently_accessed(
+        self, profile_id: str, min_count: int = 3, limit: int = 100,
+    ) -> list[tuple[str, int]]:
+        """Facts accessed at least min_count times.
+
+        Returns [(fact_id, access_count)] sorted by count desc.
+        """
+        try:
+            rows = self._db.execute(
+                "SELECT fact_id, COUNT(*) AS cnt "
+                "FROM fact_access_log "
+                "WHERE profile_id = ? "
+                "GROUP BY fact_id "
+                "HAVING cnt >= ? "
+                "ORDER BY cnt DESC "
+                "LIMIT ?",
+                (profile_id, min_count, limit),
+            )
+            return [(str(r["fact_id"]), int(r["cnt"])) for r in rows]
+        except Exception as exc:
+            logger.debug("get_frequently_accessed failed: %s", exc)
+            return []

package/src/superlocalmemory/storage/database.py

@@ -674,3 +674,291 @@ class DatabaseManager:
             )
             for r in rows
         ]
+
+    # ------------------------------------------------------------------
+    # Phase 2: fact_context CRUD (Auto-Invoke Engine)
+    # ------------------------------------------------------------------
+
+    def store_fact_context(
+        self,
+        fact_id: str,
+        profile_id: str,
+        contextual_description: str,
+        keywords: str,
+        generated_by: str = "rules",
+    ) -> None:
+        """Store or replace contextual description for a fact."""
+        self.execute(
+            "INSERT OR REPLACE INTO fact_context "
+            "(fact_id, profile_id, contextual_description, keywords, generated_by) "
+            "VALUES (?, ?, ?, ?, ?)",
+            (fact_id, profile_id, contextual_description, keywords, generated_by),
+        )
+
+    def get_fact_context(self, fact_id: str) -> dict | None:
+        """Get contextual description for a fact."""
+        rows = self.execute(
+            "SELECT * FROM fact_context WHERE fact_id = ?", (fact_id,),
+        )
+        return dict(rows[0]) if rows else None
+
+    def get_all_fact_contexts(self, profile_id: str) -> list[dict]:
+        """Get all contextual descriptions for a profile."""
+        rows = self.execute(
+            "SELECT * FROM fact_context WHERE profile_id = ?", (profile_id,),
+        )
+        return [dict(r) for r in rows]
+
+    def delete_fact_context(self, fact_id: str) -> None:
+        """Delete contextual description for a fact."""
+        self.execute("DELETE FROM fact_context WHERE fact_id = ?", (fact_id,))
+
+    # ------------------------------------------------------------------
+    # Phase 3: Association Graph CRUD (Rule 15)
+    # ------------------------------------------------------------------
+
+    def store_association_edge(self, edge: dict) -> None:
+        """Persist an association edge."""
+        self.execute(
+            "INSERT OR IGNORE INTO association_edges "
+            "(edge_id, profile_id, source_fact_id, target_fact_id, "
+            " association_type, weight, co_access_count, created_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))",
+            (edge["edge_id"], edge["profile_id"],
+             edge["source_fact_id"], edge["target_fact_id"],
+             edge["association_type"], edge["weight"],
+             edge.get("co_access_count", 0)),
+        )
+
+    def get_association_edges(
+        self, fact_id: str, profile_id: str,
+    ) -> list[dict]:
+        """All association edges where fact_id is source or target."""
+        rows = self.execute(
+            "SELECT * FROM association_edges WHERE profile_id = ? "
+            "AND (source_fact_id = ? OR target_fact_id = ?)",
+            (profile_id, fact_id, fact_id),
+        )
+        return [dict(r) for r in rows]
+
+    def get_all_association_edges(self, profile_id: str) -> list[dict]:
+        """All association edges for a profile."""
+        rows = self.execute(
+            "SELECT * FROM association_edges WHERE profile_id = ?",
+            (profile_id,),
+        )
+        return [dict(r) for r in rows]
+
+    def delete_association_edges(self, profile_id: str) -> int:
+        """Delete all association edges for a profile. Returns count."""
+        before = self.execute(
+            "SELECT COUNT(*) AS c FROM association_edges WHERE profile_id = ?",
+            (profile_id,),
+        )
+        count = int(before[0]["c"]) if before else 0
+        self.execute(
+            "DELETE FROM association_edges WHERE profile_id = ?",
+            (profile_id,),
+        )
+        return count
+
+    def store_activation_cache(self, entry: dict) -> None:
+        """Persist an activation cache entry."""
+        self.execute(
+            "INSERT OR REPLACE INTO activation_cache "
+            "(cache_id, profile_id, query_hash, node_id, activation_value, "
+            " iteration, created_at, expires_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, datetime('now'), datetime('now', '+1 hour'))",
+            (entry["cache_id"], entry["profile_id"],
+             entry["query_hash"], entry["node_id"],
+             entry["activation_value"], entry["iteration"]),
+        )
+
+    def get_activation_cache(
+        self, query_hash: str, profile_id: str,
+    ) -> list[dict]:
+        """Get cached activation results (non-expired)."""
+        rows = self.execute(
+            "SELECT node_id, activation_value FROM activation_cache "
+            "WHERE profile_id = ? AND query_hash = ? "
+            "AND expires_at > datetime('now') "
+            "ORDER BY activation_value DESC",
+            (profile_id, query_hash),
+        )
+        return [dict(r) for r in rows]
+
+    def cleanup_activation_cache(self) -> int:
+        """Delete expired cache entries. Returns count deleted."""
+        before = self.execute(
+            "SELECT COUNT(*) AS c FROM activation_cache "
+            "WHERE expires_at < datetime('now')"
+        )
+        count = int(before[0]["c"]) if before else 0
+        self.execute(
+            "DELETE FROM activation_cache WHERE expires_at < datetime('now')"
+        )
+        return count
+
+    def store_fact_importance(self, entry: dict) -> None:
+        """Persist fact importance scores."""
+        self.execute(
+            "INSERT OR REPLACE INTO fact_importance "
+            "(fact_id, profile_id, pagerank_score, community_id, "
+            " degree_centrality, computed_at) "
+            "VALUES (?, ?, ?, ?, ?, datetime('now'))",
+            (entry["fact_id"], entry["profile_id"],
+             entry["pagerank_score"], entry.get("community_id"),
+             entry.get("degree_centrality", 0.0)),
+        )
+
+    def get_fact_importance(
+        self, fact_id: str, profile_id: str,
+    ) -> dict | None:
+        """Get importance scores for a fact."""
+        rows = self.execute(
+            "SELECT * FROM fact_importance "
+            "WHERE fact_id = ? AND profile_id = ?",
+            (fact_id, profile_id),
+        )
+        return dict(rows[0]) if rows else None
+
+    def get_top_facts_by_pagerank(
+        self, profile_id: str, top_k: int = 20,
+    ) -> list[dict]:
+        """Top facts by PageRank score."""
+        rows = self.execute(
+            "SELECT * FROM fact_importance "
+            "WHERE profile_id = ? "
+            "ORDER BY pagerank_score DESC LIMIT ?",
+            (profile_id, top_k),
+        )
+        return [dict(r) for r in rows]
+
+    # ------------------------------------------------------------------
+    # Phase 4: Temporal Intelligence CRUD (Rule 15)
+    # ------------------------------------------------------------------
+
+    def store_temporal_validity(
+        self, fact_id: str, profile_id: str,
+        valid_from: str | None = None,
+        valid_until: str | None = None,
+    ) -> None:
+        """Create temporal validity record for a fact."""
+        self.execute(
+            "INSERT OR IGNORE INTO fact_temporal_validity "
+            "(fact_id, profile_id, valid_from, valid_until) "
+            "VALUES (?, ?, ?, ?)",
+            (fact_id, profile_id, valid_from, valid_until),
+        )
+
+    def get_temporal_validity(self, fact_id: str) -> dict | None:
+        """Get temporal validity record for a fact."""
+        rows = self.execute(
+            "SELECT * FROM fact_temporal_validity WHERE fact_id = ?",
+            (fact_id,),
+        )
+        return dict(rows[0]) if rows else None
+
+    def get_all_temporal_validity(self, profile_id: str) -> list[dict]:
+        """Get all temporal validity records for a profile."""
+        rows = self.execute(
+            "SELECT * FROM fact_temporal_validity WHERE profile_id = ?",
+            (profile_id,),
+        )
+        return [dict(r) for r in rows]
+
+    def invalidate_fact_temporal(
+        self, fact_id: str, invalidated_by: str,
+        invalidation_reason: str,
+    ) -> None:
+        """Set valid_until and system_expired_at for a fact.
+
+        BOTH timestamps set atomically (BI-TEMPORAL INTEGRITY).
+        Never deletes the fact (Rule 17: immutability).
+        """
+        from datetime import UTC, datetime as _dt
+        now = _dt.now(UTC).isoformat()
+        self.execute(
+            "UPDATE fact_temporal_validity "
+            "SET valid_until = ?, system_expired_at = ?, "
+            "    invalidated_by = ?, invalidation_reason = ? "
+            "WHERE fact_id = ?",
+            (now, now, invalidated_by, invalidation_reason, fact_id),
+        )
+
+    def get_valid_facts(self, profile_id: str) -> list[str]:
+        """Get fact_ids that are currently valid (not expired).
+
+        Returns facts that either have no temporal record (assumed valid)
+        or have valid_until IS NULL and system_expired_at IS NULL.
+        """
+        rows = self.execute(
+            "SELECT f.fact_id FROM atomic_facts f "
+            "LEFT JOIN fact_temporal_validity tv ON f.fact_id = tv.fact_id "
+            "WHERE f.profile_id = ? "
+            "  AND (tv.fact_id IS NULL OR tv.valid_until IS NULL) "
+            "  AND (tv.fact_id IS NULL OR tv.system_expired_at IS NULL)",
+            (profile_id,),
+        )
+        return [dict(r)["fact_id"] for r in rows]
+
+    def delete_temporal_validity(self, fact_id: str) -> None:
+        """Delete temporal validity record (for testing/rollback only)."""
+        self.execute(
+            "DELETE FROM fact_temporal_validity WHERE fact_id = ?",
+            (fact_id,),
+        )
+
+    # ------------------------------------------------------------------
+    # Phase 5: Core Memory Blocks CRUD (Rule 15)
+    # ------------------------------------------------------------------
+
+    def store_core_block(
+        self,
+        block_id: str,
+        profile_id: str,
+        block_type: str,
+        content: str,
+        source_fact_ids: str = "[]",
+        char_count: int = 0,
+        version: int = 1,
+        compiled_by: str = "rules",
+    ) -> None:
+        """Store or replace a Core Memory block.
+
+        Uses INSERT OR REPLACE on UNIQUE(profile_id, block_type)
+        to guarantee idempotency (L18).
+        """
+        self.execute(
+            "INSERT OR REPLACE INTO core_memory_blocks "
+            "(block_id, profile_id, block_type, content, source_fact_ids, "
+            " char_count, version, compiled_by, created_at, updated_at) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))",
+            (block_id, profile_id, block_type, content,
+             source_fact_ids, char_count, version, compiled_by),
+        )
+
+    def get_core_blocks(self, profile_id: str) -> list[dict]:
+        """Get all Core Memory blocks for a profile."""
+        rows = self.execute(
+            "SELECT * FROM core_memory_blocks "
+            "WHERE profile_id = ? ORDER BY block_type",
+            (profile_id,),
+        )
+        return [dict(r) for r in rows]
+
+    def get_core_block(self, profile_id: str, block_type: str) -> dict | None:
+        """Get a single Core Memory block by profile and type."""
+        rows = self.execute(
+            "SELECT * FROM core_memory_blocks "
+            "WHERE profile_id = ? AND block_type = ?",
+            (profile_id, block_type),
+        )
+        return dict(rows[0]) if rows else None
+
+    def delete_core_blocks(self, profile_id: str) -> None:
+        """Delete all Core Memory blocks for a profile."""
+        self.execute(
+            "DELETE FROM core_memory_blocks WHERE profile_id = ?",
+            (profile_id,),
+        )

package/src/superlocalmemory/storage/schema.py

@@ -705,6 +705,11 @@ def create_all_tables(conn: sqlite3.Connection) -> None:
     for ddl in _DDL_ORDERED:
         conn.executescript(ddl)
 
+    # --- V3.2 schema extension (additive only) ---
+    from superlocalmemory.storage.schema_v32 import V32_DDL
+    for ddl in V32_DDL:
+        conn.executescript(ddl)
+
     # Seed schema version on first run.
     existing = conn.execute(
         "SELECT COUNT(*) AS n FROM schema_version"
@@ -728,6 +733,11 @@ def drop_all_tables(conn: sqlite3.Connection) -> None:
     Args:
         conn: An open SQLite connection. Caller manages commit.
     """
+    # V32 tables first (they may FK to base tables)
+    from superlocalmemory.storage.schema_v32 import V32_ROLLBACK
+    for sql in V32_ROLLBACK:
+        conn.execute(sql)
+
     # FTS + triggers first (depend on atomic_facts).
     for fts in _FTS_TABLES:
         conn.execute(f"DROP TABLE IF EXISTS {fts}")