superlocalmemory 3.3.20 → 3.3.22

package/src/superlocalmemory/code_graph/bridge/fact_enricher.py

@@ -0,0 +1,159 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory v3.4 — CodeGraph Bridge Module
+
+"""Fact Enricher — append code metadata to fact descriptions.
+
+For MVP: builds enrichment strings from matched nodes but does NOT
+write to memory.db.  Returns the enriched description so callers
+(MCP tools, event listeners) can decide what to do with it.
+
+This keeps the bridge completely isolated from memory.db writes
+per the MVP constraint.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from superlocalmemory.code_graph.models import EdgeKind
+
+if TYPE_CHECKING:
+    from superlocalmemory.code_graph.database import CodeGraphDatabase
+    from superlocalmemory.code_graph.bridge.entity_resolver import MatchedNode
+
+logger = logging.getLogger(__name__)
+
+MAX_ENRICHMENT_LEN = 500
+MAX_NODES_PER_ENRICHMENT = 3
+
+
+@dataclass(frozen=True)
+class EnrichmentResult:
+    """Result of enriching a fact description."""
+    fact_id: str
+    original_description: str
+    enriched_description: str
+    nodes_used: int
+
+
+class FactEnricher:
+    """Enriches SLM fact descriptions with code graph metadata.
+
+    For MVP, this only constructs enrichment strings from code_graph.db.
+    It does NOT read from or write to memory.db.
+    """
+
+    def __init__(self, code_graph_db: CodeGraphDatabase) -> None:
+        self._db = code_graph_db
+
+    def enrich(
+        self,
+        fact_id: str,
+        matched_nodes: list[MatchedNode],
+        original_description: str = "",
+    ) -> str:
+        """Enrich a fact description with code metadata.
+
+        Args:
+            fact_id: SLM fact ID.
+            matched_nodes: Nodes matched by EntityResolver.
+            original_description: Original fact text to enrich.
+
+        Returns:
+            Enriched description string. If no matches, returns
+            original_description unchanged.
+        """
+        if not matched_nodes:
+            return original_description
+
+        # Sort by confidence descending, limit to top N
+        sorted_nodes = sorted(
+            matched_nodes,
+            key=lambda n: n.confidence,
+            reverse=True,
+        )[:MAX_NODES_PER_ENRICHMENT]
+
+        suffix_parts: list[str] = []
+        for node in sorted_nodes:
+            suffix_part = self._build_node_suffix(node)
+            if suffix_part:
+                suffix_parts.append(suffix_part)
+
+        if not suffix_parts:
+            return original_description
+
+        enrichment_suffix = " ".join(suffix_parts)
+
+        if original_description:
+            enriched = f"{original_description} {enrichment_suffix}"
+        else:
+            enriched = enrichment_suffix
+
+        # Truncate to MAX_ENRICHMENT_LEN
+        if len(enriched) > MAX_ENRICHMENT_LEN:
+            enriched = enriched[:MAX_ENRICHMENT_LEN - 3] + "..."
+
+        return enriched
+
+    def bulk_enrich(
+        self,
+        fact_node_pairs: list[tuple[str, list[MatchedNode], str]],
+    ) -> list[EnrichmentResult]:
+        """Enrich multiple facts. Returns list of EnrichmentResult."""
+        results: list[EnrichmentResult] = []
+        for fact_id, nodes, description in fact_node_pairs:
+            enriched = self.enrich(fact_id, nodes, description)
+            results.append(EnrichmentResult(
+                fact_id=fact_id,
+                original_description=description,
+                enriched_description=enriched,
+                nodes_used=min(len(nodes), MAX_NODES_PER_ENRICHMENT),
+            ))
+        return results
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _build_node_suffix(self, node: MatchedNode) -> str:
+        """Build enrichment suffix for a single matched node."""
+        try:
+            # Get callers count
+            callers_count = self._count_edges_to(node.node_id, EdgeKind.CALLS)
+            # Get callees count
+            callees_count = self._count_edges_from(node.node_id, EdgeKind.CALLS)
+
+            suffix = f"[{node.kind}: {node.file_path}::{node.qualified_name.split('::')[-1] if '::' in node.qualified_name else node.qualified_name}"
+            if callers_count > 0:
+                suffix += f"; {callers_count} callers"
+            if callees_count > 0:
+                suffix += f"; calls {callees_count}"
+            suffix += "]"
+            return suffix
+        except Exception:
+            logger.debug(
+                "Failed to build suffix for node %s", node.node_id,
+                exc_info=True,
+            )
+            return ""
+
+    def _count_edges_to(self, node_id: str, kind: EdgeKind) -> int:
+        """Count incoming edges of a specific kind."""
+        rows = self._db.execute(
+            "SELECT COUNT(*) as cnt FROM graph_edges "
+            "WHERE target_node_id = ? AND kind = ?",
+            (node_id, kind.value),
+        )
+        return rows[0]["cnt"] if rows else 0
+
+    def _count_edges_from(self, node_id: str, kind: EdgeKind) -> int:
+        """Count outgoing edges of a specific kind."""
+        rows = self._db.execute(
+            "SELECT COUNT(*) as cnt FROM graph_edges "
+            "WHERE source_node_id = ? AND kind = ?",
+            (node_id, kind.value),
+        )
+        return rows[0]["cnt"] if rows else 0

package/src/superlocalmemory/code_graph/bridge/hebbian_linker.py

@@ -0,0 +1,170 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory v3.4 — CodeGraph Bridge Module
+
+"""Hebbian Linker — code-aware association edge creation.
+
+When two SLM facts mention functions in the same call subgraph,
+creates code_memory_links entries to record the relationship.
+
+For MVP: creates code_memory_links entries ONLY.  Does NOT write
+to memory.db association_edges — that's Phase 4b (future).
+This keeps the bridge completely isolated from memory.db writes.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from superlocalmemory.code_graph.models import EdgeKind
+
+if TYPE_CHECKING:
+    from superlocalmemory.code_graph.database import CodeGraphDatabase
+    from superlocalmemory.code_graph.graph_engine import GraphEngine
+
+logger = logging.getLogger(__name__)
+
+WEIGHT_BASE = 0.3
+WEIGHT_PER_SHARED = 0.1
+WEIGHT_CAP = 0.8
+
+
+@dataclass(frozen=True)
+class HebbianEdge:
+    """A code-aware Hebbian association found between two facts."""
+    source_fact_id: str
+    target_fact_id: str
+    weight: float
+    shared_node_count: int
+
+
+class HebbianLinker:
+    """Finds facts sharing code subgraphs via code_memory_links in code_graph.db.
+
+    For MVP: read-only analysis + returns results.  Does NOT write
+    association_edges to memory.db.
+    """
+
+    def __init__(
+        self,
+        code_graph_db: CodeGraphDatabase,
+        graph_engine: GraphEngine,
+    ) -> None:
+        self._db = code_graph_db
+        self._engine = graph_engine
+
+    def link(
+        self,
+        fact_id: str,
+        linked_node_ids: list[str],
+    ) -> list[HebbianEdge]:
+        """Find facts sharing code subgraph and return Hebbian edges.
+
+        Args:
+            fact_id: The SLM fact that was just linked to code.
+            linked_node_ids: Code node IDs the fact was linked to.
+
+        Returns:
+            List of HebbianEdge objects describing discovered associations.
+        """
+        if not linked_node_ids:
+            return []
+
+        # Step 1: Compute 1-hop call neighborhood for all linked nodes
+        neighborhood_ids: set[str] = set(linked_node_ids)
+        for node_id in linked_node_ids:
+            neighbors = self._get_call_neighborhood(node_id)
+            neighborhood_ids.update(neighbors)
+
+        # Step 2: Find other facts linked to the same neighborhood
+        other_facts = self._find_facts_in_neighborhood(
+            neighborhood_ids, exclude_fact_id=fact_id,
+        )
+
+        if not other_facts:
+            return []
+
+        # Step 3: For each other fact, count shared nodes and compute weight
+        edges: list[HebbianEdge] = []
+        for other_fact_id, other_node_ids in other_facts.items():
+            shared_count = len(neighborhood_ids & other_node_ids)
+            if shared_count == 0:
+                continue
+
+            weight = min(
+                WEIGHT_BASE + (shared_count * WEIGHT_PER_SHARED),
+                WEIGHT_CAP,
+            )
+            edges.append(HebbianEdge(
+                source_fact_id=fact_id,
+                target_fact_id=other_fact_id,
+                weight=weight,
+                shared_node_count=shared_count,
+            ))
+
+        logger.debug(
+            "Found %d Hebbian associations for fact %s",
+            len(edges), fact_id,
+        )
+        return edges
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _get_call_neighborhood(self, node_id: str) -> set[str]:
+        """Get 1-hop CALLS neighbors (both directions) for a node."""
+        neighbors: set[str] = set()
+        try:
+            # Outgoing CALLS
+            callees = self._engine.get_callees(
+                node_id, edge_kinds={EdgeKind.CALLS.value},
+            )
+            for item in callees:
+                nid = item["node"]["node_id"]
+                neighbors.add(nid)
+
+            # Incoming CALLS
+            callers = self._engine.get_callers(
+                node_id, edge_kinds={EdgeKind.CALLS.value},
+            )
+            for item in callers:
+                nid = item["node"]["node_id"]
+                neighbors.add(nid)
+        except KeyError:
+            # Node not in graph — skip
+            logger.debug("Node %s not in graph, skipping neighborhood", node_id)
+
+        return neighbors
+
+    def _find_facts_in_neighborhood(
+        self,
+        neighborhood_ids: set[str],
+        exclude_fact_id: str,
+    ) -> dict[str, set[str]]:
+        """Find other facts linked to nodes in the neighborhood.
+
+        Returns dict of fact_id -> set of linked node_ids.
+        """
+        if not neighborhood_ids:
+            return {}
+
+        placeholders = ",".join("?" for _ in neighborhood_ids)
+        rows = self._db.execute(
+            f"SELECT DISTINCT slm_fact_id, code_node_id "
+            f"FROM code_memory_links "
+            f"WHERE code_node_id IN ({placeholders}) "
+            f"AND slm_fact_id != ? "
+            f"AND is_stale = 0",
+            tuple(neighborhood_ids) + (exclude_fact_id,),
+        )
+
+        result: dict[str, set[str]] = {}
+        for row in rows:
+            fid = row["slm_fact_id"]
+            nid = row["code_node_id"]
+            result.setdefault(fid, set()).add(nid)
+
+        return result

package/src/superlocalmemory/code_graph/bridge/temporal_checker.py

@@ -0,0 +1,152 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory v3.4 — CodeGraph Bridge Module
+
+"""Temporal Checker — invalidate memories about deleted/renamed code.
+
+For MVP: operates entirely on code_graph.db (code_memory_links table).
+Does NOT write to memory.db fact_temporal_validity — that's Phase 4b.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superlocalmemory.code_graph.database import CodeGraphDatabase
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class StaleLink:
+    """A code_memory_link that has been marked stale."""
+    link_id: str
+    code_node_id: str
+    slm_fact_id: str
+    qualified_name: str
+
+
+@dataclass(frozen=True)
+class DeletedCodeMemory:
+    """A fact linked to a code node that no longer exists in the graph."""
+    fact_id: str
+    node_id: str
+    node_qualified_name: str
+    link_id: str
+
+
+class TemporalChecker:
+    """Checks and invalidates memories about deleted/renamed code.
+
+    Operates on code_graph.db only (MVP constraint).
+    """
+
+    def __init__(self, code_graph_db: CodeGraphDatabase) -> None:
+        self._db = code_graph_db
+
+    def mark_links_stale(self, node_id: str) -> int:
+        """Mark all non-stale links for a node as stale.
+
+        Returns the count of links marked stale.
+        """
+        count = self._db.execute_write(
+            "UPDATE code_memory_links SET is_stale = 1, "
+            "last_verified = datetime('now') "
+            "WHERE code_node_id = ? AND is_stale = 0",
+            (node_id,),
+        )
+        if count > 0:
+            logger.info(
+                "Marked %d links stale for node %s", count, node_id,
+            )
+        return count
+
+    def check_stale_links(self) -> list[StaleLink]:
+        """Get all stale code_memory_links.
+
+        Returns list of StaleLink with node metadata.
+        """
+        rows = self._db.execute(
+            "SELECT cml.link_id, cml.code_node_id, cml.slm_fact_id, "
+            "COALESCE(gn.qualified_name, 'deleted') as qualified_name "
+            "FROM code_memory_links cml "
+            "LEFT JOIN graph_nodes gn ON cml.code_node_id = gn.node_id "
+            "WHERE cml.is_stale = 1",
+            (),
+        )
+        return [
+            StaleLink(
+                link_id=row["link_id"],
+                code_node_id=row["code_node_id"],
+                slm_fact_id=row["slm_fact_id"],
+                qualified_name=row["qualified_name"],
+            )
+            for row in rows
+        ]
+
+    def get_memories_for_deleted_code(self) -> list[DeletedCodeMemory]:
+        """Find facts linked to code nodes that no longer exist in the graph.
+
+        These are code_memory_links whose code_node_id has no matching
+        graph_nodes row — the code was deleted.
+        """
+        rows = self._db.execute(
+            "SELECT cml.slm_fact_id, cml.code_node_id, cml.link_id "
+            "FROM code_memory_links cml "
+            "LEFT JOIN graph_nodes gn ON cml.code_node_id = gn.node_id "
+            "WHERE gn.node_id IS NULL",
+            (),
+        )
+        return [
+            DeletedCodeMemory(
+                fact_id=row["slm_fact_id"],
+                node_id=row["code_node_id"],
+                node_qualified_name="deleted",
+                link_id=row["link_id"],
+            )
+            for row in rows
+        ]
+
+    def bulk_verify(self) -> dict[str, int]:
+        """Re-verify ALL code_memory_links against current graph state.
+
+        - Links whose code_node_id still exists: mark verified
+        - Links whose code_node_id is gone: mark stale
+
+        Returns {"verified": int, "marked_stale": int, "already_stale": int}
+        """
+        # Count already stale
+        already_rows = self._db.execute(
+            "SELECT COUNT(*) as cnt FROM code_memory_links WHERE is_stale = 1",
+            (),
+        )
+        already_stale = already_rows[0]["cnt"] if already_rows else 0
+
+        # Mark stale: links to deleted nodes
+        marked_stale = self._db.execute_write(
+            "UPDATE code_memory_links SET is_stale = 1, "
+            "last_verified = datetime('now') "
+            "WHERE is_stale = 0 AND code_node_id NOT IN "
+            "(SELECT node_id FROM graph_nodes)",
+            (),
+        )
+
+        # Verify: links to existing nodes
+        verified = self._db.execute_write(
+            "UPDATE code_memory_links SET "
+            "last_verified = datetime('now') "
+            "WHERE is_stale = 0 AND code_node_id IN "
+            "(SELECT node_id FROM graph_nodes)",
+            (),
+        )
+
+        result = {
+            "verified": verified,
+            "marked_stale": marked_stale,
+            "already_stale": already_stale,
+        }
+        logger.info("Bulk verify complete: %s", result)
+        return result