superlocalmemory 3.3.20 → 3.3.22

package/src/superlocalmemory/cli/pending_store.py

@@ -0,0 +1,158 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""Pending memory store — zero-loss async remember (Option C).
+
+Problem: v3.3.20 async `slm remember` spawns a detached subprocess with
+stderr=DEVNULL. If the embedding worker crashes, the user's data is silently
+lost — they see "Queued for background processing" but the memory never stores.
+
+Solution: Store-first, embed-later (Netflix pattern).
+  1. INSERT raw content into pending_memories (synchronous, 0.1s, no engine init)
+  2. Spawn background subprocess to process (extract facts, embed, build graph)
+  3. If background crashes, content survives in pending table
+  4. Next engine.initialize() auto-retries pending items
+
+Uses a separate `pending.db` file — never touches memory.db directly.
+Stdlib only — no SLM imports (must be fast).
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+_DEFAULT_DIR = Path.home() / ".superlocalmemory"
+_PENDING_DB = "pending.db"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS pending_memories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    content TEXT NOT NULL,
+    tags TEXT DEFAULT '',
+    metadata TEXT DEFAULT '{}',
+    created_at TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    error TEXT DEFAULT NULL,
+    retry_count INTEGER DEFAULT 0
+);
+"""
+
+
+def _get_db(base_dir: Path | None = None) -> sqlite3.Connection:
+    """Open pending.db with WAL mode. Creates if needed."""
+    d = base_dir or _DEFAULT_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    db_path = d / _PENDING_DB
+    conn = sqlite3.connect(str(db_path), timeout=5)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(_SCHEMA)
+    return conn
+
+
+def store_pending(
+    content: str,
+    tags: str = "",
+    metadata: dict | None = None,
+    base_dir: Path | None = None,
+) -> int:
+    """Store content in pending table. Returns the row ID.
+
+    This is intentionally FAST — no engine init, no embedding, no model loading.
+    Just a raw SQLite INSERT (~0.1s).
+    """
+    conn = _get_db(base_dir)
+    try:
+        cur = conn.execute(
+            "INSERT INTO pending_memories (content, tags, metadata, created_at, status) "
+            "VALUES (?, ?, ?, ?, 'pending')",
+            (content, tags, json.dumps(metadata or {}), time.strftime("%Y-%m-%dT%H:%M:%S")),
+        )
+        conn.commit()
+        return cur.lastrowid or 0
+    finally:
+        conn.close()
+
+
+def get_pending(base_dir: Path | None = None, limit: int = 50) -> list[dict]:
+    """Get unprocessed pending memories."""
+    conn = _get_db(base_dir)
+    try:
+        rows = conn.execute(
+            "SELECT id, content, tags, metadata, created_at, retry_count "
+            "FROM pending_memories WHERE status = 'pending' "
+            "ORDER BY id ASC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [
+            {"id": r[0], "content": r[1], "tags": r[2], "metadata": r[3],
+             "created_at": r[4], "retry_count": r[5]}
+            for r in rows
+        ]
+    finally:
+        conn.close()
+
+
+def mark_done(row_id: int, base_dir: Path | None = None) -> None:
+    """Mark a pending memory as successfully processed."""
+    conn = _get_db(base_dir)
+    try:
+        conn.execute(
+            "UPDATE pending_memories SET status = 'done' WHERE id = ?",
+            (row_id,),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def mark_failed(row_id: int, error: str, base_dir: Path | None = None) -> None:
+    """Mark a pending memory as failed with error message."""
+    conn = _get_db(base_dir)
+    try:
+        conn.execute(
+            "UPDATE pending_memories SET status = 'failed', error = ?, "
+            "retry_count = retry_count + 1 WHERE id = ?",
+            (error, row_id),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def pending_count(base_dir: Path | None = None) -> int:
+    """Count unprocessed pending memories."""
+    d = base_dir or _DEFAULT_DIR
+    db_path = d / _PENDING_DB
+    if not db_path.exists():
+        return 0
+    conn = sqlite3.connect(str(db_path), timeout=5)
+    try:
+        return conn.execute(
+            "SELECT COUNT(*) FROM pending_memories WHERE status = 'pending'"
+        ).fetchone()[0]
+    except sqlite3.OperationalError:
+        return 0
+    finally:
+        conn.close()
+
+
+def cleanup_done(days: int = 7, base_dir: Path | None = None) -> int:
+    """Remove processed entries older than N days."""
+    conn = _get_db(base_dir)
+    try:
+        cur = conn.execute(
+            "DELETE FROM pending_memories WHERE status = 'done' "
+            "AND created_at < datetime('now', ?)",
+            (f"-{days} days",),
+        )
+        conn.commit()
+        return cur.rowcount
+    finally:
+        conn.close()

package/src/superlocalmemory/cli/setup_wizard.py

@@ -265,7 +265,7 @@ def run_wizard(auto: bool = False) -> None:
     print()
 
     # -- Step 1: System check --
-    print("─── Step 1/5: System Check ───")
+    print("─── Step 1/6: System Check ───")
     print()
     py_ver = platform.python_version()
     py_ok = sys.version_info >= (3, 11)
@@ -293,7 +293,7 @@ def run_wizard(auto: bool = False) -> None:
 
     # -- Step 2: Mode selection --
     print()
-    print("─── Step 2/5: Choose Operating Mode ───")
+    print("─── Step 2/6: Choose Operating Mode ───")
     print()
     print("  [A] Local Guardian (recommended)")
     print("      Zero cloud. Zero LLM. Full privacy.")
@@ -340,9 +340,42 @@ def run_wizard(auto: bool = False) -> None:
     mode_names = {"a": "Local Guardian", "b": "Smart Local", "c": "Full Power"}
     print(f"\n  ✓ Mode {choice.upper()} ({mode_names[choice]}) configured")
 
-    # -- Step 3: Download embedding model --
+    # -- Step 3: Code Knowledge Graph --
     print()
-    print("─── Step 3/5: Download Embedding Model ───")
+    print("─── Step 3/6: Code Knowledge Graph ───")
+    print()
+    print("  CodeGraph builds a structural map of your codebase using Tree-sitter.")
+    print("  It gives your AI assistant blast-radius analysis, call graphs,")
+    print("  and connects code structure to your session memories.")
+    print()
+    print("  [Y] Enable CodeGraph (recommended for developers)")
+    print("  [N] Disable CodeGraph (can enable later via config)")
+    print()
+
+    if interactive:
+        cg_choice = _prompt("  Enable Code Knowledge Graph? [Y/n] (default: Y): ", "y").lower()
+    else:
+        cg_choice = "y"
+        print("  Auto-enabling CodeGraph (non-interactive)")
+
+    code_graph_enabled = cg_choice in ("", "y", "yes")
+
+    # Write code graph config
+    _SLM_HOME.mkdir(parents=True, exist_ok=True)
+    cg_config_path = _SLM_HOME / "code_graph_config.json"
+    import json
+    cg_config_data = {"enabled": code_graph_enabled, "bridge_enabled": code_graph_enabled}
+    cg_config_path.write_text(json.dumps(cg_config_data, indent=2))
+
+    if code_graph_enabled:
+        print(f"\n  ✓ CodeGraph enabled")
+        print(f"    Run `slm code-graph build` in any repo to index it")
+    else:
+        print(f"\n  ✓ CodeGraph disabled (enable later in {cg_config_path})")
+
+    # -- Step 4: Download embedding model --
+    print()
+    print("─── Step 4/6: Download Embedding Model ───")
 
     if not st_ok:
         print("  ⚠ Skipped (sentence-transformers not installed)")
@@ -354,7 +387,7 @@ def run_wizard(auto: bool = False) -> None:
 
     # -- Step 4: Download reranker model --
     print()
-    print("─── Step 4/5: Download Reranker Model ───")
+    print("─── Step 5/6: Download Reranker Model ───")
 
     if not st_ok:
         print("  ⚠ Skipped (sentence-transformers not installed)")
@@ -363,7 +396,7 @@ def run_wizard(auto: bool = False) -> None:
 
     # -- Step 5: Verification --
     print()
-    print("─── Step 5/5: Verification ───")
+    print("─── Step 6/6: Verification ───")
 
     if st_ok:
         verified = _verify_installation()

package/src/superlocalmemory/code_graph/__init__.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory v3.4 — CodeGraph Module
+
+"""Code Knowledge Graph for SuperLocalMemory.
+
+Unifies AST-derived code structure with SLM's semantic memory.
+Separate code_graph.db — does not touch memory.db.
+
+Usage:
+    from superlocalmemory.code_graph import CodeGraphService, CodeGraphConfig
+
+    config = CodeGraphConfig(enabled=True, repo_root=Path("/my/repo"))
+    service = CodeGraphService(config)
+    stats = service.get_stats()
+"""
+
+from superlocalmemory.code_graph.config import CodeGraphConfig
+from superlocalmemory.code_graph.models import (
+    CodeMemoryLink,
+    EdgeKind,
+    FileRecord,
+    GraphEdge,
+    GraphNode,
+    LinkType,
+    NodeKind,
+    ParseResult,
+)
+from superlocalmemory.code_graph.service import (
+    CodeGraphNotEnabledError,
+    CodeGraphService,
+)
+
+__all__ = [
+    "CodeGraphConfig",
+    "CodeGraphService",
+    "CodeGraphNotEnabledError",
+    "GraphNode",
+    "GraphEdge",
+    "FileRecord",
+    "CodeMemoryLink",
+    "ParseResult",
+    "NodeKind",
+    "EdgeKind",
+    "LinkType",
+]

package/src/superlocalmemory/code_graph/blast_radius.py

@@ -0,0 +1,177 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory v3.4 — CodeGraph Module
+
+"""BlastRadius — bidirectional BFS impact analysis.
+
+Given changed files or node IDs, computes the transitive impact
+radius on the rustworkx graph with configurable depth and node caps.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from superlocalmemory.code_graph.graph_engine import GraphEngine
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Result dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class BlastRadiusResult:
+    """Impact analysis result."""
+
+    changed_nodes: frozenset[str] = field(default_factory=frozenset)
+    impacted_nodes: frozenset[str] = field(default_factory=frozenset)
+    impacted_files: frozenset[str] = field(default_factory=frozenset)
+    edges: tuple[tuple[str, str, dict[str, Any]], ...] = ()
+    depth_reached: int = 0
+    truncated: bool = False
+
+
+# ---------------------------------------------------------------------------
+# BlastRadius computer
+# ---------------------------------------------------------------------------
+
+class BlastRadius:
+    """Computes blast radius via bidirectional BFS on the in-memory graph.
+
+    Usage::
+
+        br = BlastRadius(engine)
+        result = br.compute(changed_files=["src/foo.py"], max_depth=2)
+    """
+
+    def __init__(self, engine: GraphEngine) -> None:
+        self._engine = engine
+
+    def compute(
+        self,
+        changed_files: list[str] | None = None,
+        seed_node_ids: list[str] | None = None,
+        max_depth: int = 2,
+        max_nodes: int = 500,
+        edge_kinds: set[str] | None = None,
+        direction: str = "both",
+    ) -> BlastRadiusResult:
+        """Compute the blast radius from changed files or explicit seed nodes.
+
+        Parameters
+        ----------
+        changed_files : list of relative file paths whose nodes are seeds
+        seed_node_ids : explicit node IDs to use as seeds (additive)
+        max_depth : maximum BFS hops
+        max_nodes : cap on total visited nodes (seeds + impacted)
+        edge_kinds : restrict traversal to these edge kinds (None = all)
+        direction : "forward" (out-edges), "reverse" (in-edges), "both"
+
+        Returns
+        -------
+        BlastRadiusResult with changed_nodes, impacted_nodes, etc.
+        """
+        graph = self._engine.graph
+        index = self._engine.index
+
+        # Collect seed rx indices
+        seed_rx: set[int] = set()
+
+        if changed_files:
+            for fp in changed_files:
+                for nid, rx_idx in index.id_to_rx.items():
+                    node_data = graph[rx_idx]
+                    if node_data["file_path"] == fp:
+                        seed_rx.add(rx_idx)
+
+        if seed_node_ids:
+            for nid in seed_node_ids:
+                rx_idx = index.id_to_rx.get(nid)
+                if rx_idx is not None:
+                    seed_rx.add(rx_idx)
+
+        if not seed_rx:
+            return BlastRadiusResult()
+
+        # BFS
+        visited: set[int] = set(seed_rx)
+        frontier: set[int] = set(seed_rx)
+        impacted_rx: set[int] = set()
+        collected_edges: list[tuple[str, str, dict[str, Any]]] = []
+        depth = 0
+        truncated = False
+
+        while frontier and depth < max_depth:
+            next_frontier: set[int] = set()
+            should_break = False
+
+            for rx_idx in frontier:
+                if should_break:
+                    break
+
+                # Forward (outgoing)
+                if direction in ("forward", "both"):
+                    for src, tgt, edge_data in graph.out_edges(rx_idx):
+                        if edge_kinds and edge_data["kind"] not in edge_kinds:
+                            continue
+                        if tgt not in visited:
+                            if len(visited) + len(next_frontier) >= max_nodes:
+                                truncated = True
+                                should_break = True
+                                break
+                            next_frontier.add(tgt)
+                            collected_edges.append((
+                                index.rx_to_id[src],
+                                index.rx_to_id[tgt],
+                                dict(edge_data),
+                            ))
+
+                if should_break:
+                    break
+
+                # Reverse (incoming)
+                if direction in ("reverse", "both"):
+                    for src, tgt, edge_data in graph.in_edges(rx_idx):
+                        if edge_kinds and edge_data["kind"] not in edge_kinds:
+                            continue
+                        if src not in visited:
+                            if len(visited) + len(next_frontier) >= max_nodes:
+                                truncated = True
+                                should_break = True
+                                break
+                            next_frontier.add(src)
+                            collected_edges.append((
+                                index.rx_to_id[src],
+                                index.rx_to_id[tgt],
+                                dict(edge_data),
+                            ))
+
+            impacted_rx.update(next_frontier)
+            visited.update(next_frontier)
+            frontier = next_frontier
+            depth += 1
+
+            if truncated:
+                break
+
+        # Convert to node IDs
+        changed_ids = frozenset(index.rx_to_id[rx] for rx in seed_rx)
+        impacted_ids = frozenset(index.rx_to_id[rx] for rx in impacted_rx)
+
+        # Compute impacted file paths
+        impacted_files = frozenset(
+            graph[rx]["file_path"] for rx in impacted_rx
+        )
+
+        return BlastRadiusResult(
+            changed_nodes=changed_ids,
+            impacted_nodes=impacted_ids,
+            impacted_files=impacted_files,
+            edges=tuple(collected_edges),
+            depth_reached=depth,
+            truncated=truncated,
+        )

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

@@ -0,0 +1,36 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory v3.4 — CodeGraph Bridge Module
+
+"""Bridge between code_graph.db and SLM memory.db.
+
+Five mechanisms cross-pollinate code structure with semantic memory:
+
+1. **Entity Resolver** — Matches code mentions in fact text against
+   code graph nodes.  Creates `code_memory_links` entries.
+2. **Fact Enricher** — Appends file/function metadata to fact
+   descriptions for better auto-invoke precision.
+3. **Hebbian Linker** — Creates/strengthens association edges when
+   two facts reference code nodes in the same call subgraph.
+4. **Event Listeners** — Bidirectional event bus listeners bridging
+   `memory.stored` → code linking and `code_graph.node_*` → staleness.
+5. **Temporal Checker** — Marks memories about deleted/renamed code
+   as temporally stale.
+
+**Hard Rule (HR-1):** The bridge NEVER modifies memory.db schema.
+All bridge data lives in code_graph.db via the `code_memory_links` table.
+"""
+
+from superlocalmemory.code_graph.bridge.entity_resolver import EntityResolver
+from superlocalmemory.code_graph.bridge.fact_enricher import FactEnricher
+from superlocalmemory.code_graph.bridge.hebbian_linker import HebbianLinker
+from superlocalmemory.code_graph.bridge.event_listeners import BridgeEventListeners
+from superlocalmemory.code_graph.bridge.temporal_checker import TemporalChecker
+
+__all__ = [
+    "EntityResolver",
+    "FactEnricher",
+    "HebbianLinker",
+    "BridgeEventListeners",
+    "TemporalChecker",
+]