superlocalmemory 4.0.6 → 4.0.7

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

@@ -57,12 +57,23 @@ class BridgeEventListeners:
         return self._started
 
     def start(self, event_bus: Any) -> None:
-        """Register all listeners on the event bus.
+        """Register code-graph listeners on the event bus.
 
         Registers:
-        - on_memory_stored: listens to "memory.stored"
         - on_code_node_deleted: listens to "code_graph.node_deleted"
         - on_code_node_changed: listens to "code_graph.node_changed"
+
+        DELIBERATELY NOT REGISTERED: ``on_memory_stored``.
+        ``EventBus._notify_listeners`` invokes every listener synchronously on
+        the emitting thread, so subscribing to ``memory.stored`` would run entity
+        resolution, enrichment and Hebbian linking inside each ``remember`` —
+        putting all three on the write path. That work now runs in background
+        maintenance instead; see ``code_graph.bridge.maintenance``.
+
+        ``on_memory_stored`` is kept as a callable so a caller that genuinely
+        wants synchronous linking for one fact can invoke it directly, but
+        nothing subscribes it to the bus. ``tests/test_code_graph/
+        test_bridge_off_write_path.py`` fails if that changes.
         """
         if self._started:
             logger.warning("BridgeEventListeners already started")
@@ -70,8 +81,8 @@ class BridgeEventListeners:
 
         self._event_bus = event_bus
 
+        # Both events are emitted by code-graph builds, never by memory writes.
         listeners: list[tuple[str, Callable[..., Any]]] = [
-            ("memory.stored", self.on_memory_stored),
             ("code_graph.node_deleted", self.on_code_node_deleted),
             ("code_graph.node_changed", self.on_code_node_changed),
         ]

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

@@ -0,0 +1,206 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory | https://qualixar.com
+
+"""Bridge pass — runs the code↔memory bridge as background maintenance.
+
+WHY THIS MODULE EXISTS
+----------------------
+The bridge was authored to run from ``BridgeEventListeners.on_memory_stored``,
+i.e. once per ``memory.stored`` event. ``EventBus._notify_listeners`` calls
+listeners **synchronously on the emitting thread**, so that design puts entity
+resolution, enrichment and Hebbian linking inside every single ``remember``.
+The owner's constraint for this release is explicit: remember and recall timing
+must not move. So the memory-stored listener is gone and the work happens here,
+in the same background pass that already runs ``consolidate_facts``.
+
+WHAT THIS PASS TOUCHES
+----------------------
+Writes to ``code_graph.db`` only:
+  * ``code_memory_links``            — EntityResolver output
+  * ``code_memory_links.enriched_description`` — FactEnricher output
+
+Recall never opens ``code_graph.db`` — verified: nothing under ``retrieval/`` or
+``core/`` references ``code_memory_links`` or ``CodeGraphDatabase``. That makes
+this half of the bridge recall-neutral by construction rather than by
+measurement.
+
+DELIBERATELY NOT HERE: Hebbian association edges. ``HebbianLinker`` produces
+edges for ``association_edges`` in **memory.db**, which
+``retrieval/spreading_activation.py`` reads via a UNION with ``graph_edges``.
+Every such edge is an extra neighbour recall must traverse and changes which
+memories come back — not just how fast. That cannot be made safe by moving it
+into this pass, so it is deferred to its own release, where the edge volume at
+production scale can be measured against the recall baseline first. No writer for
+it ships here; ``bridge/hebbian_linker.py`` remains unwired on purpose.
+
+IDEMPOTENCE
+-----------
+A watermark in ``graph_metadata`` records the ``created_at`` of the newest fact
+processed. Re-running the pass processes only facts newer than that, so a
+maintenance cycle every few minutes does not rescan the whole store. Links use
+``INSERT OR REPLACE`` on a deterministic key, so reprocessing a fact cannot
+duplicate its links.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from superlocalmemory.code_graph.database import CodeGraphDatabase
+
+logger = logging.getLogger(__name__)
+
+#: Watermark key in graph_metadata.
+_WATERMARK_KEY = "bridge.last_fact_created_at"
+
+#: Facts examined in a single pass. Bounds the pass so a first run on a large
+#: store cannot occupy the maintenance thread indefinitely; the watermark means
+#: the next cycle resumes where this one stopped.
+MAX_FACTS_PER_PASS = 500
+
+#: Links kept for one fact, highest confidence first. A single file-path mention
+#: matches every node in that file — "the parser in code_graph/parser.py was
+#: dropping edges" produced 17 links at confidence 0.6-0.8, against one link at
+#: 0.95 for a backticked function name. Without a bound the broad matches bury
+#: the precise ones in the UI and hand a large node set to the Hebbian pass.
+MAX_LINKS_PER_FACT = 10
+
+
+def _fact_rows(
+    memory_db: Any,
+    profile_id: str,
+    since: str | None,
+    limit: int,
+) -> list[tuple[str, str, str]]:
+    """Return (fact_id, content, created_at) for facts newer than *since*.
+
+    Ordered by ``created_at`` so the watermark advances monotonically even when
+    the pass stops at ``limit``.
+    """
+    sql = (
+        "SELECT fact_id, content, created_at FROM atomic_facts "
+        "WHERE profile_id = ? AND content IS NOT NULL AND content != '' "
+    )
+    # M011 (archive_status) is a DEFERRED migration, so the column is absent on
+    # a database where it has not run yet. DatabaseManager._has_archive_status
+    # exists for exactly this and its docstring is explicit: "callers must not
+    # filter on a column that may not exist." Filtering unconditionally made
+    # this query raise "no such column" on any fresh install, which the caller's
+    # except swallowed into a warning and zero links — the bridge would simply
+    # never have run for a new user.
+    try:
+        has_archive = memory_db._has_archive_status()
+    except Exception:  # pragma: no cover - helper absent on an unusual manager
+        has_archive = False
+    if has_archive:
+        sql += "AND (archive_status IS NULL OR archive_status = '') "
+
+    params: list[Any] = [profile_id]
+    if since:
+        sql += "AND created_at > ? "
+        params.append(since)
+    sql += "ORDER BY created_at ASC LIMIT ?"
+    params.append(limit)
+
+    # DatabaseManager.execute serves both reads and writes (see
+    # core/maintenance.py, which uses it for each). It returns sqlite3.Row;
+    # index by position so a plain-tuple factory also works.
+    rows = memory_db.execute(sql, tuple(params))
+    return [(r[0], r[1], r[2]) for r in rows]
+
+
+def run_bridge_pass(
+    memory_db: Any,
+    code_graph_db: CodeGraphDatabase,
+    profile_id: str,
+    *,
+    max_facts: int = MAX_FACTS_PER_PASS,
+) -> dict[str, int]:
+    """Resolve code mentions in new facts and enrich the resulting links.
+
+    Returns counts. Never raises — the caller is background maintenance and a
+    bridge failure must not abort the rest of the cycle.
+    """
+    counts = {"facts_scanned": 0, "links_created": 0, "enriched": 0}
+
+    try:
+        from superlocalmemory.code_graph.bridge.entity_resolver import EntityResolver
+        from superlocalmemory.code_graph.bridge.fact_enricher import FactEnricher
+    except Exception as exc:  # pragma: no cover - import guard
+        logger.debug("bridge pass unavailable: %s", exc)
+        return counts
+
+    # Nothing to match against — skip before touching memory.db at all.
+    stats = code_graph_db.get_stats()
+    if not stats.get("nodes"):
+        logger.debug("bridge pass: code graph is empty, nothing to resolve against")
+        return counts
+
+    watermark = code_graph_db.get_metadata(_WATERMARK_KEY)
+    try:
+        rows = _fact_rows(memory_db, profile_id, watermark, max_facts)
+    except Exception as exc:
+        logger.warning("bridge pass could not read facts: %s", exc)
+        return counts
+
+    if not rows:
+        return counts
+
+    resolver = EntityResolver(code_graph_db)
+    enricher = FactEnricher(code_graph_db)
+    newest = watermark
+
+    for fact_id, content, created_at in rows:
+        counts["facts_scanned"] += 1
+        newest = created_at if newest is None or created_at > newest else newest
+        try:
+            links = resolver.resolve(content, fact_id, max_links=MAX_LINKS_PER_FACT)
+        except Exception as exc:
+            logger.debug("bridge resolve failed for %s: %s", fact_id, exc)
+            continue
+        if not links:
+            continue
+        counts["links_created"] += len(links)
+
+        # Enrichment is derived from (fact text, matched nodes) and is stored
+        # beside the link in code_graph.db. The user's own fact wording in
+        # memory.db is never rewritten: doing that would invalidate the fact's
+        # embedding, and would compound a suffix on every maintenance cycle.
+        try:
+            matched = resolver.get_matched_nodes(content)
+            if not matched:
+                continue
+            enriched = enricher.enrich(fact_id, matched, content)
+            if enriched and enriched != content:
+                _store_enrichment(code_graph_db, fact_id, enriched)
+                counts["enriched"] += 1
+        except Exception as exc:
+            logger.debug("bridge enrichment failed for %s: %s", fact_id, exc)
+
+    if newest and newest != watermark:
+        try:
+            code_graph_db.set_metadata(_WATERMARK_KEY, newest)
+        except Exception as exc:
+            logger.warning("bridge watermark not advanced: %s", exc)
+
+    # One summary line per pass, never one per fact. A 3,527-fact store must not
+    # produce 3,527 log lines; per-fact detail stays at debug.
+    if counts["links_created"]:
+        logger.info(
+            "Code bridge: %d facts scanned, %d links, %d enriched",
+            counts["facts_scanned"], counts["links_created"], counts["enriched"],
+        )
+    return counts
+
+
+def _store_enrichment(
+    code_graph_db: CodeGraphDatabase, fact_id: str, enriched: str
+) -> None:
+    """Persist enrichment text onto every link for *fact_id*."""
+    code_graph_db.execute_write(
+        "UPDATE code_memory_links SET enriched_description = ? WHERE slm_fact_id = ?",
+        (enriched, fact_id),
+    )

package/src/superlocalmemory/code_graph/config.py

@@ -9,7 +9,7 @@ Frozen dataclass with all tunables. Sensible defaults for typical repos.
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, fields
 from pathlib import Path
 
 from superlocalmemory.infra.data_root import state_path
@@ -88,3 +88,67 @@ class CodeGraphConfig:
         if slm_base_dir is not None:
             return slm_base_dir / "code_graph.db"
         return state_path("code_graph.db")
+
+    @classmethod
+    def load(cls, **overrides: object) -> CodeGraphConfig:
+        """Build a config from ``code_graph_config.json``, then apply overrides.
+
+        WHY THIS EXISTS (4.0.7). ``cli/setup_wizard.py`` has always written
+        ``code_graph_config.json`` with ``enabled`` and ``bridge_enabled``, and
+        until now **nothing read it**. There was no loader on this class at all,
+        and every call site constructed ``CodeGraphConfig(enabled=True)`` with
+        hardcoded defaults. So a user could answer "yes, enable the code graph"
+        in setup, get ``bridge_enabled: true`` written to disk, and have it
+        affect nothing — silently, with no way to tell from the outside.
+
+        Unknown keys in the file are ignored rather than raising: the file is
+        user-editable, and a stray key should not stop the code graph from
+        loading. Malformed JSON falls back to defaults with a warning, because
+        failing closed here would disable a working code graph over a typo.
+        """
+        import json
+        import logging
+
+        data: dict[str, object] = {}
+        path = state_path("code_graph_config.json")
+        try:
+            if path.exists():
+                loaded = json.loads(path.read_text(encoding="utf-8"))
+                if isinstance(loaded, dict):
+                    data = loaded
+                else:
+                    logging.getLogger(__name__).warning(
+                        "%s does not contain a JSON object; using defaults", path,
+                    )
+        except (OSError, json.JSONDecodeError) as exc:
+            logging.getLogger(__name__).warning(
+                "could not read %s (%s); using defaults", path, exc,
+            )
+
+        data.update(overrides)
+
+        valid = {f.name for f in fields(cls)}
+        unknown = sorted(set(data) - valid)
+        if unknown:
+            logging.getLogger(__name__).debug(
+                "ignoring unknown code_graph config keys: %s", ", ".join(unknown),
+            )
+
+        kwargs = {k: v for k, v in data.items() if k in valid}
+
+        # JSON has no frozenset/Path; coerce the fields that need it.
+        if isinstance(kwargs.get("languages"), list):
+            kwargs["languages"] = frozenset(kwargs["languages"])
+        if isinstance(kwargs.get("exclude_dirs"), list):
+            kwargs["exclude_dirs"] = frozenset(kwargs["exclude_dirs"])
+        for key in ("repo_root", "db_path"):
+            if isinstance(kwargs.get(key), str):
+                kwargs[key] = Path(kwargs[key])
+
+        try:
+            return cls(**kwargs)  # type: ignore[arg-type]
+        except TypeError as exc:
+            logging.getLogger(__name__).warning(
+                "code_graph config rejected (%s); using defaults", exc,
+            )
+            return cls()

package/src/superlocalmemory/core/fact_consolidator.py

@@ -159,7 +159,30 @@ def consolidate_facts(
             stats["error_detail"] = str(exc)
         return stats
 
-    # Backward-compat: str | Path — open own connection.
+    # Backward-compat: str | Path — open our own connection.
+    #
+    # Type-checked, not assumed. This branch used to run for ANYTHING that was
+    # not a DatabaseManager, stringify it, and hand the result to
+    # sqlite3.connect — which creates whatever filename it is given. A test
+    # passing a MagicMock therefore had a real 4 KB SQLite file named
+    # "<MagicMock id='4422448000'>" written into the repository root, one per
+    # test. 42 of them had accumulated, and tests/test_ci_guards/
+    # test_no_magicmock_artifacts.py failed after any full-suite run.
+    #
+    # 4.0.6 is where this started firing: it wired consolidate_facts into
+    # run_maintenance, so every caller with a mock config reached this line.
+    #
+    # Refusing an unusable argument is also right beyond the test symptom —
+    # silently creating a database at a nonsense path cannot be what any caller
+    # wanted, and it hides the real bug (the caller passed the wrong thing).
+    if not isinstance(db_or_path, (str, Path)):
+        raise TypeError(
+            "consolidate_facts() expects a DatabaseManager, or a str/Path to "
+            f"memory.db for backward compatibility; got {type(db_or_path).__name__}. "
+            "Passing anything else previously created a database file named after "
+            "the object's repr."
+        )
+
     logger.warning(
         "consolidate_facts: passing a db_path is deprecated — pass a "
         "DatabaseManager instead (Fix A backward-compat shim active)"

package/src/superlocalmemory/core/maintenance.py

@@ -678,12 +678,62 @@ def run_maintenance(
             "which is distinct from 0 = nothing to merge): %s", exc,
         )
 
+    # 5. Code↔memory bridge (4.0.7).
+    # Resolves code entity mentions in new facts against the code graph and
+    # stores the links, plus derived enrichment text, in code_graph.db.
+    #
+    # RUNS HERE, NOT ON THE WRITE PATH. The bridge was authored to fire from
+    # BridgeEventListeners.on_memory_stored, and EventBus._notify_listeners
+    # dispatches synchronously on the emitting thread — which would have put
+    # entity resolution and enrichment inside every remember. The owner's
+    # constraint for 4.0.7 is that remember/recall timing must not move, so the
+    # memory-stored subscription is gone and the work happens in this pass.
+    # tests/test_code_graph/test_bridge_off_write_path.py fails if it comes back.
+    #
+    # Writes only code_graph.db, which no recall path opens, so this step cannot
+    # affect recall latency or results. Hebbian edges are the one exception and
+    # are NOT run here — they land in association_edges, which spreading
+    # activation reads; they are generated on explicit request instead.
+    counts["bridge_links"] = 0
+    counts["bridge_enriched"] = 0
+    try:
+        from superlocalmemory.code_graph.config import CodeGraphConfig
+
+        cg_cfg = CodeGraphConfig.load()
+        if cg_cfg.enabled and cg_cfg.bridge_enabled:
+            from superlocalmemory.code_graph.bridge.maintenance import run_bridge_pass
+            from superlocalmemory.code_graph.database import CodeGraphDatabase
+
+            cg_path = cg_cfg.get_db_path()
+            if cg_path.exists():
+                bridge_stats = run_bridge_pass(
+                    db, CodeGraphDatabase(cg_path), profile_id,
+                )
+                counts["bridge_links"] = bridge_stats.get("links_created", 0)
+                counts["bridge_enriched"] = bridge_stats.get("enriched", 0)
+    except Exception as exc:
+            # -1 rather than 0, for the same reason fact consolidation uses it:
+            # a step that never worked must not report the same numbers as a
+            # healthy step with no work to do.
+            counts["bridge_links"] = -1
+            logger.warning(
+                "Code bridge pass FAILED during maintenance (reported as -1, "
+                "which is distinct from 0 = nothing to link): %s", exc,
+            )
+
     logger.info(
         "Maintenance complete: %d backfilled, %d Langevin, %d Fisher-coupled, "
-        "%d Sheaf, %d entity-summaries, %d facts-consolidated",
+        "%d Sheaf, %d entity-summaries, %d facts-consolidated, %d code-links",
         counts["langevin_backfilled"], counts["langevin_updated"],
         counts["fisher_coupled"], counts["sheaf_checked"],
         counts["entity_summaries_consolidated"],
         counts["facts_consolidated"],
+        counts["bridge_links"],
     )
     return counts
+
+
+# The bridge gate reads code_graph_config.json via CodeGraphConfig.load(), not
+# SLMConfig: SLMConfig has no code_graph block, so there is nothing to read
+# there. cli/setup_wizard.py writes that file; before 4.0.7 no loader existed
+# and every call site hardcoded CodeGraphConfig(enabled=True) instead.

package/src/superlocalmemory/mcp/tools_code_graph.py

@@ -75,11 +75,36 @@ def _graph_not_built_error() -> dict[str, Any]:
     }
 
 
+def _bridge_is_enabled() -> bool:
+    """Whether the code↔memory bridge is switched on in the saved settings."""
+    try:
+        cfg = _get_service()
+        if cfg is not None and getattr(cfg.config, "bridge_enabled", False):
+            return True
+        # No live service yet (e.g. a tool called before any build): read the
+        # saved settings directly rather than reporting "off" by default.
+        from superlocalmemory.code_graph.config import CodeGraphConfig
+        return bool(CodeGraphConfig.load().bridge_enabled)
+    except Exception:
+        return False
+
+
 def _bridge_not_enabled_error() -> dict[str, Any]:
-    """Standard error when bridge is not enabled."""
+    """Standard error when the code↔memory bridge is not enabled.
+
+    The remediation text used to name ``code_graph.bridge.enabled``, which is not
+    a key that exists anywhere. The real field is ``bridge_enabled`` in
+    ``code_graph_config.json``, so anyone who followed this message edited
+    nothing that mattered. This helper was also never called from any tool, so
+    the message could not appear even when it was correct.
+    """
     return {
         "success": False,
-        "error": "Bridge not enabled. Set code_graph.bridge.enabled = true in config.",
+        "error": (
+            'Code↔memory bridge not enabled. Set "bridge_enabled": true in '
+            "~/.superlocalmemory/code_graph_config.json, then run "
+            "build_code_graph. Links are created during background maintenance."
+        ),
     }
 
 
@@ -167,7 +192,13 @@ def register_code_graph_tools(server, get_engine: Callable) -> None:
                     p.strip() for p in exclude_patterns.split(",") if p.strip()
                 )
 
-            config = CodeGraphConfig(**config_kwargs)
+            # Start from the user's saved settings, then apply this call's
+            # arguments. Previously this constructed CodeGraphConfig(**kwargs)
+            # from scratch, so every field the caller did not name reverted to a
+            # class default — including bridge_enabled, which the setup wizard
+            # writes to code_graph_config.json. A user who enabled the code graph
+            # during setup therefore had the flag on disk and off in every build.
+            config = CodeGraphConfig.load(**config_kwargs)
             global _service
             _service = CodeGraphService(config)
 
@@ -727,6 +758,11 @@ def register_code_graph_tools(server, get_engine: Callable) -> None:
                 "total_edges": stats.get("edges", 0),
                 "total_code_memory_links": total_links,
                 "stale_links": stale_links,
+                # Without this, total_code_memory_links == 0 is ambiguous: it
+                # means either "no memory mentions your code" or "the feature
+                # that creates links is switched off". Those call for opposite
+                # actions, so the reader has to be told which one it is.
+                "bridge_enabled": _bridge_is_enabled(),
                 "built": stats.get("built", False),
                 "db_path": stats.get("db_path", ""),
             }
@@ -1514,6 +1550,14 @@ def register_code_graph_tools(server, get_engine: Callable) -> None:
             if err is not None:
                 return err
 
+            # Every answer this tool can give comes from code_memory_links, and
+            # only the bridge populates that table. With the bridge off the query
+            # returns an empty list, which reads as "nothing is stale" — the
+            # strongest possible reassurance, produced by a feature that never
+            # ran. Say so instead.
+            if not _bridge_is_enabled():
+                return _bridge_not_enabled_error()
+
             db = _get_db()
 
             if scope == "all":

package/src/superlocalmemory/server/routes/memories.py

@@ -1061,6 +1061,7 @@ async def get_fact_detail(request: Request, fact_id: str):
             )
         except Exception:
             row["canonical_entities"] = []
+        row["code_links"] = _code_links_for_fact(fact_id)
         return row
     except HTTPException:
         raise
@@ -1068,6 +1069,66 @@ async def get_fact_detail(request: Request, fact_id: str):
         raise _internal_error("Fact detail error")
 
 
+def _code_links_for_fact(fact_id: str) -> list[dict]:
+    """Code entities this fact mentions, from the code graph.
+
+    Fail-open by design: this is a display extra on a detail popup. No code graph
+    built, bridge switched off, or database missing all mean "no section shown",
+    never an error on the fact itself. A user who has never touched the code
+    graph must not see a failure because of a feature they do not use.
+
+    Reads code_graph.db, which is a separate database from memory.db and is never
+    opened by the recall path — so nothing here can affect recall.
+    """
+    try:
+        from superlocalmemory.code_graph.config import CodeGraphConfig
+
+        cfg = CodeGraphConfig.load()
+        if not (cfg.enabled and cfg.bridge_enabled):
+            return []
+        db_path = cfg.get_db_path()
+        if not db_path.exists():
+            return []
+
+        import sqlite3
+
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+        try:
+            conn.row_factory = dict_factory
+            rows = conn.execute(
+                "SELECT cml.link_type, cml.confidence, cml.is_stale, "
+                "       cml.enriched_description, "
+                "       gn.name, gn.qualified_name, gn.kind, gn.file_path "
+                "FROM code_memory_links cml "
+                "LEFT JOIN graph_nodes gn ON gn.node_id = cml.code_node_id "
+                "WHERE cml.slm_fact_id = ? "
+                "ORDER BY cml.confidence DESC, gn.qualified_name",
+                (fact_id,),
+            ).fetchall()
+        finally:
+            conn.close()
+
+        return [
+            {
+                "name": r.get("name") or "",
+                "qualified_name": r.get("qualified_name") or "",
+                "kind": r.get("kind") or "",
+                "file_path": r.get("file_path") or "",
+                "link_type": r.get("link_type") or "mentions",
+                "confidence": r.get("confidence"),
+                "is_stale": bool(r.get("is_stale")),
+                "description": r.get("enriched_description") or "",
+            }
+            for r in rows
+            # A link whose node is gone (LEFT JOIN produced no row) is a stale
+            # pointer, not something to render as a blank entry.
+            if r.get("qualified_name")
+        ]
+    except Exception:
+        logger.debug("code links unavailable for %s", fact_id, exc_info=True)
+        return []
+
+
 @router.delete("/api/memories/{fact_id}")
 async def delete_memory(request: Request, fact_id: str):
     """Delete a specific memory (atomic fact) by ID."""

package/src/superlocalmemory/storage/schema_code_graph.py

@@ -104,11 +104,49 @@ _DDL_STATEMENTS: tuple[str, ...] = (
         confidence      REAL NOT NULL DEFAULT 0.8 CHECK (confidence >= 0.0 AND confidence <= 1.0),
         created_at      TEXT NOT NULL DEFAULT (datetime('now')),
         last_verified   TEXT,
-        is_stale        INTEGER NOT NULL DEFAULT 0
+        is_stale        INTEGER NOT NULL DEFAULT 0,
+        enriched_description TEXT
     )
     """,
 )
 
+#: Columns added to existing tables after their first release.
+#:
+#: This file's DDL is all ``CREATE TABLE IF NOT EXISTS`` and code_graph.db has
+#: no migration framework, so appending a column to a _DDL_STATEMENTS block
+#: reaches NEW databases only — every database created by an earlier version
+#: skips the statement entirely and never gains the column. That silent
+#: divergence is what this list exists to close.
+#:
+#: ADDITIVE ONLY: ``ALTER TABLE ... ADD COLUMN`` with no NOT NULL and no
+#: default, so it cannot fail on a populated table and cannot rewrite a row.
+#: Never put a DROP, a RENAME, or a type change here.
+_ADDITIVE_COLUMNS: tuple[tuple[str, str, str], ...] = (
+    # (table, column, type) — enrichment text for a code↔memory link. Lives
+    # here rather than in memory.db so the user's own fact wording is never
+    # overwritten, and so recall (which never opens code_graph.db) is unaffected.
+    ("code_memory_links", "enriched_description", "TEXT"),
+)
+
+
+def _apply_additive_columns(cursor: sqlite3.Cursor) -> None:
+    """Add any missing column from _ADDITIVE_COLUMNS. Idempotent."""
+    for table, column, coltype in _ADDITIVE_COLUMNS:
+        try:
+            existing = {row[1] for row in cursor.execute(f"PRAGMA table_info({table})")}
+        except sqlite3.Error as exc:  # table absent on a partial database
+            logger.debug("additive column probe skipped for %s: %s", table, exc)
+            continue
+        if not existing or column in existing:
+            continue
+        try:
+            cursor.execute(f"ALTER TABLE {table} ADD COLUMN {column} {coltype}")
+            logger.info("code_graph schema: added %s.%s", table, column)
+        except sqlite3.OperationalError as exc:
+            # Concurrent initialiser won the race, or the column appeared
+            # between the probe and the ALTER. Both are benign.
+            logger.debug("additive column %s.%s not applied: %s", table, column, exc)
+
 # Indexes (separate from tables for clarity)
 _INDEX_STATEMENTS: tuple[str, ...] = (
     # graph_nodes indexes
@@ -194,6 +232,11 @@ def create_all_tables(conn: sqlite3.Connection) -> None:
     for ddl in _DDL_STATEMENTS:
         cursor.execute(ddl)
 
+    # Columns added after a table's first release. Must run AFTER the CREATEs
+    # (so a fresh database already has them and this is a no-op) and BEFORE the
+    # indexes (in case one is ever declared on an added column).
+    _apply_additive_columns(cursor)
+
     # Indexes
     for idx in _INDEX_STATEMENTS:
         cursor.execute(idx)

package/src/superlocalmemory/ui/index.html

@@ -1575,7 +1575,7 @@
     <script src="static/js/math-health.js"></script>
     <script src="static/js/auto-settings.js"></script>
     <script src="static/js/ide-status.js"></script>
-    <script src="static/js/fact-detail.js"></script>
+    <script src="static/js/fact-detail.js?v=e9076ee3"></script>
 
     <!-- Neural Glass shell (v3.4.21 restructured) -->
     <script src="static/js/ng-health.js?v=345"></script>