superlocalmemory 4.0.6 → 4.0.8

package/src/superlocalmemory/cli/summary_cmd.py

@@ -0,0 +1,215 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory | https://qualixar.com
+
+"""``slm summary`` — the readable layer over your memories (issue #113).
+
+WHY THIS FILE EXISTS
+--------------------
+4.0.6 shipped the three generators in ``superlocalmemory/summaries/`` with no way
+to call them: no command, no MCP tool, no route. The changelog listed the feature
+as added, the issue reply said it had landed, and a user could do nothing with it.
+This is that missing surface.
+
+Three summaries, each bounded and traceable:
+
+  ``slm summary session <id>``   what one session covered
+  ``slm summary day [DATE]``     what a day's main topics were
+  ``slm summary project <path>`` what was worked on in a project
+
+Every result states its coverage. Session data in particular is sparse — roughly
+4% of facts carry a session id on a real store — so a session summary reports what
+fraction it could actually see rather than presenting a slice as the whole.
+
+No language model is required: the generators are extractive by default, so this
+works in Local Guardian mode with nothing installed.
+"""
+
+from __future__ import annotations
+
+import json
+from argparse import Namespace
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any
+
+from superlocalmemory.infra.data_root import state_path
+
+def _coverage_is_complete(coverage: str) -> bool:
+    """Whether *coverage* means "this really is the whole picture".
+
+    Deliberately inverted. My first version listed the values that needed a
+    caveat — ``("partial", "sparse", "none", "empty")`` — and three of those four
+    are not values this system emits. The real vocabulary is COVERAGE_FULL /
+    PARTIAL / INSUFFICIENT / NO_SESSION / UNAVAILABLE, so a session summary
+    reporting "no_session" printed no caveat at all: the one honesty feature
+    issue #113 asked for, silently inactive.
+
+    Testing for completeness instead means any value that is not FULL — including
+    one added later — gets the caveat. The failure mode becomes an unnecessary
+    warning rather than a missing one.
+    """
+    try:
+        from superlocalmemory.summaries.base import COVERAGE_FULL
+
+        return coverage == COVERAGE_FULL
+    except Exception:
+        return coverage == "full"
+
+
+def _db_path() -> Path:
+    return state_path("memory.db")
+
+
+def _active_profile() -> str:
+    """Resolve the active profile without a daemon and without side effects.
+
+    Reads the ``active`` pointer out of ``profiles.json`` directly.
+    ``ProfileManager`` would give the same answer, but its constructor calls
+    ``mkdir(parents=True)`` — creating directories is not something a read-only
+    summary command should do. ``core.profiles`` also has no module-level
+    accessor; ``get_active_profile`` there is a method on the manager, and the
+    module-level one lives in ``server/routes/helpers.py``, which the CLI must
+    not import.
+    """
+    try:
+        from superlocalmemory.core.profiles import DEFAULT_PROFILES_FILE
+
+        path = state_path(DEFAULT_PROFILES_FILE)
+        if path.exists():
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            active = raw.get("active")
+            if isinstance(active, str) and active:
+                return active
+    except Exception:
+        pass
+    return "default"
+
+
+def _load_config() -> Any:
+    """The active SLMConfig, so Mode B/C get LLM-written summaries.
+
+    Without this the generators receive ``config=None``, ``get_mode_str`` returns
+    ``"a"``, and the LLM branch is unreachable — every summary comes out
+    extractive no matter which mode the user runs. That is not a graceful
+    fallback, it is the enrichment path never being offered.
+
+    Returns None on any failure, which lands on the extractive path. That is the
+    right fallback: a deterministic summary beats an error.
+    """
+    try:
+        from superlocalmemory.core.config import SLMConfig
+
+        return SLMConfig.load()
+    except Exception:
+        return None
+
+
+def _emit(result: Any, as_json: bool) -> None:
+    """Print a SummaryResult as JSON or as prose."""
+    if as_json:
+        print(json.dumps({
+            "kind": result.kind,
+            "profile_id": result.profile_id,
+            "content": result.content,
+            "source_fact_ids": result.source_fact_ids,
+            "coverage": result.coverage,
+            "generated_by": result.generated_by,
+            "metadata": result.metadata,
+        }, indent=2, default=str))
+        return
+
+    print()
+    print(result.content.rstrip() or "(nothing recorded)")
+    print()
+
+    # Coverage is not decoration. A summary built from a fraction of the data
+    # that presents itself as the whole is the failure mode issue #113 called
+    # out by name, so it is stated on every single result, not only bad ones.
+    n = len(result.source_fact_ids)
+    line = f"Built from {n} memor{'y' if n == 1 else 'ies'} · coverage: {result.coverage}"
+    if not _coverage_is_complete(result.coverage):
+        line += " — treat as a partial view, not a complete record"
+    print(line)
+    if result.generated_by:
+        print(f"Method: {result.generated_by}")
+    print("Use --json to see the exact memories this came from.")
+
+
+def cmd_summary(args: Namespace) -> None:
+    """Dispatch ``slm summary <subcommand>``."""
+    sub = getattr(args, "summary_command", None)
+    as_json = bool(getattr(args, "json", False))
+    profile = getattr(args, "profile", None) or _active_profile()
+    db = _db_path()
+    cfg = _load_config()   # Mode B/C enrichment; None -> extractive
+
+    if not db.exists():
+        print(f"No memory database at {db}. Run `slm status` first.")
+        return
+
+    if sub == "session":
+        from superlocalmemory.summaries import generate_session_summary
+
+        _emit(generate_session_summary(db, args.session_id, profile, cfg), as_json)
+        return
+
+    if sub == "day":
+        from superlocalmemory.summaries import generate_daily_reflection
+
+        target = getattr(args, "date", None) or date.today().isoformat()
+        if target == "yesterday":
+            target = (date.today() - timedelta(days=1)).isoformat()
+        elif target == "today":
+            target = date.today().isoformat()
+        _emit(generate_daily_reflection(db, target, profile, cfg), as_json)
+        return
+
+    if sub == "project":
+        from superlocalmemory.summaries import generate_project_work_log
+
+        path = getattr(args, "path", None) or str(Path.cwd())
+        _emit(generate_project_work_log(db, path, profile, cfg), as_json)
+        return
+
+    print("Usage: slm summary {session <id> | day [DATE] | project [PATH]}")
+    print()
+    print("  slm summary day                 what you recorded today")
+    print("  slm summary day yesterday       ...or yesterday")
+    print("  slm summary day 2026-08-17      ...or a specific date")
+    print("  slm summary project             work log for the current directory")
+    print("  slm summary session <id>        what one session covered")
+    print()
+    print("Add --json to include the ids of the memories a summary came from.")
+
+
+def register_summary_parser(sub: Any) -> None:
+    """Attach the ``summary`` parser. Called from cli/main.py."""
+    p = sub.add_parser(
+        "summary",
+        help="Readable summaries of your memories (session, day, project)",
+    )
+    p.add_argument("--json", action="store_true", help="machine-readable output")
+    p.add_argument("--profile", help="profile to summarise (default: active)")
+    ssub = p.add_subparsers(dest="summary_command", title="summary subcommands")
+
+    s = ssub.add_parser("session", help="what one session covered")
+    s.add_argument("session_id", help="session id (see `slm status`)")
+    s.add_argument("--json", action="store_true")
+    s.add_argument("--profile")
+
+    d = ssub.add_parser("day", help="what a day's main topics were")
+    d.add_argument(
+        "date", nargs="?",
+        help="YYYY-MM-DD, 'today' or 'yesterday' (default: today)",
+    )
+    d.add_argument("--json", action="store_true")
+    d.add_argument("--profile")
+
+    pr = ssub.add_parser("project", help="what was worked on in a project")
+    pr.add_argument(
+        "path", nargs="?",
+        help="project directory (default: current directory)",
+    )
+    pr.add_argument("--json", action="store_true")
+    pr.add_argument("--profile")

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

@@ -152,9 +152,25 @@ class EntityResolver:
         self,
         fact_text: str,
         fact_id: str,
+        max_links: int | None = None,
     ) -> list[CodeMemoryLink]:
         """Resolve code entity mentions in fact text and create links.
 
+        Args:
+            fact_text: Text to scan for code mentions.
+            fact_id:   The fact these links belong to.
+            max_links: Keep at most this many links, highest confidence first.
+                ``None`` (the default) is unbounded, preserving the behaviour the
+                manual ``link_memory_to_code`` path relies on.
+
+                A bound matters for automatic resolution. One file-path mention
+                matches EVERY node in that file: the fact "the parser in
+                code_graph/parser.py was dropping edges" produced 17 links at
+                confidence 0.6-0.8, while a backticked function name produces one
+                at 0.95. Unbounded, a fact naming a few files buries its own
+                high-signal links and hands a large node set to HebbianLinker,
+                whose neighbourhood expansion then grows accordingly.
+
         Returns list of CodeMemoryLink objects created.
         """
         if not fact_text or not fact_id:
@@ -177,6 +193,16 @@ class EntityResolver:
         if not matches:
             return []
 
+        selected = list(matches.values())
+        if max_links is not None and len(selected) > max_links:
+            # Confidence ranks the match kinds correctly already — backticked and
+            # call-syntax mentions score 0.95, a bare identifier 0.9, file-path
+            # fan-out 0.6-0.8 — so ordering by it keeps the precise mentions and
+            # drops the broad ones.
+            selected.sort(key=lambda m: m.confidence, reverse=True)
+            selected = selected[:max_links]
+            matches = {m.node_id: m for m in selected}
+
         # Classify link type
         link_type = self._classify_link_type(fact_text)
         now_str = datetime.now(timezone.utc).isoformat()

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,212 @@
+# 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:
+        # COALESCE form, matching storage/database.py:759 and the learning
+        # modules. My first version tested `IS NULL OR = ''`, which excluded
+        # every fact on a real store: live facts are marked 'live', not blank.
+        # The synthetic fixtures I developed against left the column unset, so
+        # the pass linked happily in tests and would have linked NOTHING for any
+        # actual user — 3,608 of 3,608 facts filtered out on this machine.
+        sql += "AND COALESCE(archive_status, 'live') != 'archived' "
+
+    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/consolidation_engine.py

@@ -198,27 +198,26 @@ class ConsolidationEngine:
                     from superlocalmemory.parameterization.prompt_injector import PromptInjector
                     from superlocalmemory.parameterization.prompt_lifecycle import PromptLifecycleManager
                     from superlocalmemory.learning.behavioral import BehavioralPatternStore
-                    # cross_project and workflow_miner may not exist yet — stub them
-                    try:
-                        from superlocalmemory.parameterization.cross_project import CrossProjectAggregator
-                    except ImportError:
-                        class CrossProjectAggregator:
-                            def __init__(self, db): pass
-                            def get_preferences(self, *a, **kw): return {}
-                    try:
-                        from superlocalmemory.parameterization.workflow_miner import WorkflowMiner
-                    except ImportError:
-                        class WorkflowMiner:
-                            def __init__(self, db): pass
-                            def mine(self, *a, **kw): return []
+                    from superlocalmemory.parameterization.cross_project import CrossProjectAggregator
+                    from superlocalmemory.parameterization.workflow_miner import WorkflowMiner
                     from superlocalmemory.hooks.auto_parameterize import AutoParameterizeHook
                     from superlocalmemory.core.config import ParameterizationConfig
                     p_config = getattr(self._config, "parameterization", ParameterizationConfig())
                     from superlocalmemory.infra.data_root import state_path
                     learning_db = str(state_path("learning.db"))
                     beh_store = BehavioralPatternStore(learning_db)
-                    cross_proj = CrossProjectAggregator(self._db)
-                    wf_miner = WorkflowMiner(self._db)
+                    # Both take a DB PATH, not a DatabaseManager. Passing
+                    # self._db here made Path(db_path) raise "argument should be
+                    # a str or an os.PathLike object ... not 'DatabaseManager'",
+                    # which step 9 caught at debug level — so soft prompts were
+                    # never generated and nothing said why.
+                    #
+                    # The ImportError stubs these replaced were also dead: both
+                    # modules exist and re-export the canonical classes, so the
+                    # stub branch could never run and only served to hide the
+                    # real signatures.
+                    cross_proj = CrossProjectAggregator(learning_db)
+                    wf_miner = WorkflowMiner(learning_db)
                     extractor = PatternExtractor(self._db, beh_store, cross_proj, wf_miner, p_config)
                     generator = SoftPromptGenerator(p_config)
                     injector = PromptInjector(self._db, generator, p_config)

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)"