superlocalmemory 4.0.6 → 4.0.8

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/core/recall_worker.py

@@ -106,6 +106,10 @@ def _handle_recall(
         memory_map=memory_map,
         per_fact_max=getattr(_rc, "recall_per_fact_max_chars", 2400),
         total_max=getattr(_rc, "recall_total_max_chars", 12000),
+        # Option B: markers only on session-bearing recalls. A marker can
+        # only buy a learning signal when a pending_outcomes row exists
+        # to settle, and those exist only when session_id is present.
+        include_marker=bool(session_id),
     )
     return {
         "ok": True,

package/src/superlocalmemory/evolution/skill_evolver.py

@@ -140,9 +140,24 @@ class SkillEvolver:
         # automatically. Tests inject their own.
         if budget is None:
             slm_home = canonical_data_root()
+            # ``learning_db`` must be learning.db: migration M010 creates
+            # evolution_llm_cost_log there. Every production caller
+            # (consolidation_engine, routes/evolution, MCP, CLI) passes
+            # memory.db as db_path, so handing db_path straight to the budget
+            # pointed it at a database where that table does not exist. Every
+            # evolution cycle then died with "no such table:
+            # evolution_llm_cost_log" — swallowed at debug level in
+            # consolidation step 11, so skill evolution silently never ran.
+            #
+            # Redirect only for the exact production filename. Tests pass
+            # ":memory:" or their own tmp file and must keep the old behaviour,
+            # rather than having a learning.db invented beside them.
+            learning_db = Path(self._db_path)
+            if learning_db.name == "memory.db":
+                learning_db = learning_db.parent / "learning.db"
             budget = EvolutionBudget(
                 profile_id=profile_id,
-                learning_db=Path(self._db_path),
+                learning_db=learning_db,
                 lock_dir=slm_home,
             )
         self._budget = budget

package/src/superlocalmemory/hooks/hook_handlers.py

@@ -768,7 +768,29 @@ def _run_quiet(cmd: list[str], timeout: int = 5, postprocess=None) -> str:
 
 
 def _maybe_consolidate() -> None:
-    """Run cognitive consolidation if last run was >24h ago. Non-blocking."""
+    """Ask the daemon for a full consolidation if the last one was >24h ago.
+
+    Three things were wrong here before 4.0.8, and together they meant the
+    behavioural half of consolidation never ran on a real install:
+
+    1. **It ran the wrong pipeline.** ``slm consolidate --cognitive`` invokes
+       ``CognitiveConsolidator.run_pipeline()``. Behavioural assertion mining,
+       soft prompts, skill performance and skill evolution are steps 8-11 of
+       ``ConsolidationEngine.consolidate()`` — a different class entirely. On a
+       store with thousands of tool events, ``behavioral_assertions`` stayed at
+       zero rows while the miner, run once by hand, produced 9 immediately.
+    2. **It marked success before trying.** The 24h timestamp was written
+       *before* the subprocess launched, so a run that failed instantly still
+       bought a full day of silence. The marker is now written only after the
+       daemon confirms it scheduled the work.
+    3. **It could not fail visibly.** stdout and stderr went to DEVNULL and the
+       handler ended in a bare ``except: pass``, so nothing anywhere recorded a
+       failure. Errors now surface on stderr, where the hook runner logs them.
+
+    Non-blocking: the daemon schedules the pass and returns immediately, so
+    session end is never held up by a run that takes minutes. The daemon's own
+    periodic timer is the backstop for sessions where this hook never fires.
+    """
     try:
         last_ts = 0
         last_consolidation = _last_consolidation_path()
@@ -780,16 +802,21 @@ def _maybe_consolidate() -> None:
         if (now - last_ts) < 86400:  # 24 hours
             return
 
-        # Update timestamp FIRST to prevent concurrent runs
+        started = _daemon_post(
+            "/api/v3/consolidation/trigger",
+            {"lightweight": False, "background": True},
+        )
+        if not started:
+            # No marker written — the next session end retries. The daemon's
+            # consolidation lock makes a duplicate request a cheap no-op.
+            print(
+                "slm: consolidation could not be scheduled (daemon unreachable)",
+                file=sys.stderr,
+            )
+            return
+
         os.makedirs(os.path.dirname(last_consolidation), exist_ok=True)
         with open(last_consolidation, "w") as f:
             f.write(str(now))
-
-        # Run consolidation in background (don't block session end)
-        subprocess.Popen(
-            ["slm", "consolidate", "--cognitive"],
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )
-    except Exception:
-        pass
+    except Exception as exc:
+        print(f"slm: consolidation trigger failed: {exc}", file=sys.stderr)

package/src/superlocalmemory/learning/pattern_miner.py

@@ -367,18 +367,23 @@ def _mine_channel_and_coretrieval(
                 gen += 1
 
         try:
+            # Column names must match learning.db: the table is
+            # (fact_id_a, fact_id_b, co_count). This query asked for
+            # (fact_a, fact_b, co_access_count) and therefore raised
+            # sqlite3.OperationalError on every run since it was written —
+            # caught below, logged at WARNING, and otherwise invisible. Net
+            # effect: 912 co-retrieval edges on a real store never produced a
+            # single pattern, and the Brain pane had one fewer signal with no
+            # indication anything was missing.
             coret_rows = learn_conn.execute(
-                "SELECT fact_a, fact_b, co_access_count "
+                "SELECT fact_id_a, fact_id_b, co_count "
                 "FROM co_retrieval_edges "
-                "WHERE profile_id = ? AND co_access_count >= 3 "
-                "ORDER BY co_access_count DESC LIMIT 20",
+                "WHERE profile_id = ? AND co_count >= 3 "
+                "ORDER BY co_count DESC LIMIT 20",
                 (profile_id,),
             ).fetchall()
             if coret_rows and not dry_run:
-                top_pair = (
-                    dict(coret_rows[0]).get("co_access_count", 0)
-                    if coret_rows else 0
-                )
+                top_pair = dict(coret_rows[0]).get("co_count", 0)
                 store.record_pattern(
                     profile_id=profile_id,
                     pattern_type="co_retrieval_clusters",

package/src/superlocalmemory/mcp/profiles.py

@@ -17,13 +17,17 @@ from __future__ import annotations
 # v3.6.14 WP-01: Named profile definitions
 # ---------------------------------------------------------------------------
 
-_PROFILE_CORE: frozenset[str] = frozenset({  # 16
+_PROFILE_CORE: frozenset[str] = frozenset({  # 17
     "remember", "recall", "search", "fetch", "list_recent", "update_memory", "forget",
     "session_init", "close_session",
     "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
     # A client that can propose a correction must be able to inspect and
     # authenticate its review; otherwise the core lifecycle is incomplete.
     "review_correction", "list_corrections",
+    # v4.0.8: the readable summary layer (issue #113). In CORE because the
+    # natural caller is the agent holding the conversation — an assistant
+    # asked "what did I work on yesterday" should not need a power profile.
+    "get_memory_summary",
 })
 
 # Portable Brain evidence must reach the coding-host profile shipped by the
@@ -34,7 +38,7 @@ _PROFILE_BRAIN: frozenset[str] = frozenset({
     "observe_bounded_loop_evidence",
 })
 
-_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  # 31
+_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  # 32
     "build_code_graph", "get_blast_radius", "query_graph",
     "semantic_search_code", "get_review_context", "detect_changes",
     # switch_profile lets a plugin/IDE session change the active workspace over
@@ -64,8 +68,11 @@ _PROFILE_FULL: frozenset[str] = frozenset({
     "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
     # v3.8.0: bounded-loop tools (CLI + /slm-loop command + MCP).
     "slm_loop_run", "slm_loop_history", "slm_loop_show",
+    # v4.0.8: readable summaries (#113). In core, so it must be in full too —
+    # full is asserted to be a superset of core.
+    "get_memory_summary",
     # prestage_context remains registered but deliberately raw-server-only.
-}) | _PROFILE_FULL_MESH  # 49
+}) | _PROFILE_FULL_MESH  # 50
 
 _PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 61
     "get_version", "get_mode", "health", "consistency_check", "recall_trace",

package/src/superlocalmemory/mcp/server.py

@@ -105,6 +105,11 @@ _ESSENTIAL_TOOLS: set[str] = {
     "observe_bounded_loop_evidence",
     # Update, review, and list form one core correction lifecycle.
     "review_correction", "list_corrections",
+    # v4.0.8 (#113): readable summaries. Present here as well as in the named
+    # profiles because this set is the FALLBACK surface — it must mirror
+    # ``full``, and a tool that ships in the smallest profile ("core") cannot be
+    # missing from the fallback without a client silently losing it.
+    "get_memory_summary",
     # Memory management (2)
     "forget", "run_maintenance",
     # NOTE: prestage_context IS registered (see register_prestage_tool below)
@@ -280,6 +285,8 @@ from superlocalmemory.mcp.tools_ops import register_ops_tools
 register_ops_tools(_target, get_engine)  # Wave-3: operational recovery & admin remediation
 from superlocalmemory.mcp.tools_brain import register_brain_tools
 register_brain_tools(_target, get_engine)  # v4.0.2 portable Brain receipts
+from superlocalmemory.mcp.tools_summaries import register_summary_tools
+register_summary_tools(_target, get_engine)  # v4.0.8 issue #113 summary reads
 from superlocalmemory.mcp.tools_context import register_prestage_tool
 
 

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/mcp/tools_summaries.py

@@ -0,0 +1,147 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory | https://qualixar.com
+
+"""MCP surface for the readable summary layer (issue #113).
+
+WHY THIS EXISTS
+---------------
+4.0.6 shipped the summary generators with no caller at all. 4.0.7 added
+``slm summary``, which fixed it for a person at a terminal and left agents with
+nothing — the changelog said the defect was "no command, tool or endpoint" and
+only the command was built. This is the tool half.
+
+It matters more than the CLI: the natural consumer of "what did I work on
+yesterday" is the agent holding the conversation, not a human running a command.
+
+CONTRACT
+--------
+Read-only, profile-scoped, and honest about coverage. Every response carries
+``coverage`` and ``source_fact_ids``, so a caller can tell a summary of 4% of a
+session from a summary of all of it, and can drill back to the memories it came
+from. Callers must not present a partial summary as complete; the field exists
+precisely so they do not have to guess.
+
+NOT ON THE HOT PATH. Summaries read memory.db directly and are invoked on
+demand; nothing here runs during remember or recall.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, timedelta
+from typing import Any, Callable
+
+from mcp.types import ToolAnnotations
+
+from superlocalmemory.core.admission import admits
+from superlocalmemory.core.operation_request import OperationKind
+from superlocalmemory.infra.data_root import state_path
+
+logger = logging.getLogger("superlocalmemory.mcp.summaries")
+
+#: Accepted values for the ``kind`` argument.
+_KINDS = ("day", "project", "session")
+
+
+def _result_payload(result: Any) -> dict[str, Any]:
+    """Shape a SummaryResult for the wire.
+
+    ``coverage`` and ``source_fact_ids`` are non-negotiable parts of the
+    response: a summary that cannot be traced back, or that hides how much it
+    covered, is the opaque generic summary issue #113 asked us not to build.
+    """
+    return {
+        "success": True,
+        "kind": result.kind,
+        "profile_id": result.profile_id,
+        "summary": result.content,
+        "coverage": result.coverage,
+        "generated_by": result.generated_by,
+        "source_fact_ids": result.source_fact_ids,
+        "source_count": len(result.source_fact_ids),
+        "metadata": result.metadata,
+    }
+
+
+def _error(message: str, **extra: Any) -> dict[str, Any]:
+    out = {"success": False, "error": message}
+    out.update(extra)
+    return out
+
+
+def register_summary_tools(server: Any, get_engine: Callable[[], Any]) -> None:
+    """Register the read-only summary tool."""
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    @admits(OperationKind.RECALL)
+    async def get_memory_summary(
+        kind: str = "day",
+        target: str = "",
+    ) -> dict[str, Any]:
+        """Summarise your memories: a day, a project, or one session.
+
+        Args:
+            kind: "day", "project", or "session".
+            target: For "day", an ISO date, "today" or "yesterday" (default
+                today). For "project", a directory path (default: none — supply
+                one). For "session", the session id.
+
+        Returns a summary plus ``coverage`` and ``source_fact_ids``. Coverage is
+        not decoration: session data is sparse — roughly 4% of facts carry a
+        session id — so a session summary is usually partial. Do not present a
+        partial summary as a complete record of what happened.
+
+        No language model is required; summaries are extractive unless the
+        profile runs a local or cloud model, in which case that writes them.
+        """
+        kind = (kind or "day").strip().lower()
+        if kind not in _KINDS:
+            return _error(
+                f"unknown summary kind {kind!r}; expected one of {', '.join(_KINDS)}"
+            )
+
+        engine = get_engine()
+        profile_id = getattr(engine, "profile_id", "default")
+        db_path = state_path("memory.db")
+        if not db_path.exists():
+            return _error("no memory database found", db_path=str(db_path))
+
+        # The engine's config drives Mode B/C enrichment. Passing None would
+        # silently force the extractive path for every caller regardless of
+        # mode — the exact bug the CLI shipped with in 4.0.7.
+        config = getattr(engine, "config", None)
+
+        try:
+            if kind == "day":
+                from superlocalmemory.summaries import generate_daily_reflection
+
+                day = (target or "").strip() or date.today().isoformat()
+                if day == "today":
+                    day = date.today().isoformat()
+                elif day == "yesterday":
+                    day = (date.today() - timedelta(days=1)).isoformat()
+                result = generate_daily_reflection(db_path, day, profile_id, config)
+
+            elif kind == "project":
+                from superlocalmemory.summaries import generate_project_work_log
+
+                if not (target or "").strip():
+                    return _error("kind='project' requires target=<project path>")
+                result = generate_project_work_log(
+                    db_path, target.strip(), profile_id, config,
+                )
+
+            else:  # session
+                from superlocalmemory.summaries import generate_session_summary
+
+                if not (target or "").strip():
+                    return _error("kind='session' requires target=<session id>")
+                result = generate_session_summary(
+                    db_path, target.strip(), profile_id, config,
+                )
+        except Exception as exc:
+            logger.warning("summary generation failed (%s/%s): %s", kind, target, exc)
+            return _error(f"summary generation failed: {exc}", kind=kind)
+
+        return _result_payload(result)

package/src/superlocalmemory/server/consolidation_runner.py

@@ -0,0 +1,140 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory | https://qualixar.com
+
+"""One implementation of full consolidation, shared by every trigger.
+
+WHY THIS EXISTS
+---------------
+Steps 8-11 of ``ConsolidationEngine.consolidate()`` — behavioural assertion
+mining, soft prompts, skill performance, skill evolution — only run on the
+``lightweight=False`` path. Before 4.0.8 **nothing automatic ever took that
+path**:
+
+* ``consolidation_engine.py`` self-triggers with ``lightweight=True`` only.
+* The session-end hook shelled out to ``slm consolidate --cognitive``, which
+  runs ``CognitiveConsolidator.run_pipeline()`` — a different class that does
+  not contain steps 8-11 at all.
+* ``POST /consolidation/trigger`` did run the full path, but only when a human
+  called it.
+
+The measurable consequence on a real store: ``behavioral_assertions`` sat at 0
+rows while the miner, run once by hand against the same data, produced 9
+assertions immediately. The Behaviour tab was empty because the miner had never
+executed, not because there was nothing to mine.
+
+DESIGN
+------
+Two triggers, one implementation, one lock:
+
+* the daemon's periodic timer (the correctness guarantee), and
+* the session-end hook posting to ``/consolidation/trigger`` (the fast path).
+
+``_LOCK`` serialises them. A second trigger arriving while one is running is
+**skipped, not queued** — consolidation is idempotent catch-up work, so running
+it twice back to back buys nothing and doubles the write pressure.
+
+HOT PATH
+--------
+Never called from store or recall. The engine call is CPU/IO bound for seconds
+to minutes, so it runs inside ``asyncio.to_thread`` — blocking a worker thread
+is fine, blocking the event loop is not. The periodic trigger additionally
+refuses to start unless the daemon has been idle (see ``unified_daemon``), so
+scheduled consolidation cannot land in the middle of a burst of remember/recall
+traffic.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+logger = logging.getLogger("superlocalmemory.consolidation_runner")
+
+#: Serialises the timer and the hook. Module-level: there is one daemon.
+_LOCK = asyncio.Lock()
+
+
+def is_running() -> bool:
+    """True when a consolidation pass currently holds the lock."""
+    return _LOCK.locked()
+
+
+def _consolidate_blocking(app_state: Any, profile_id: str, lightweight: bool) -> dict:
+    """Run the engine synchronously. Caller must put this in a thread.
+
+    Lifted verbatim from ``POST /consolidation/trigger`` so the endpoint and the
+    timer cannot drift apart — two copies of this would be two different
+    definitions of "consolidated".
+    """
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.core.consolidation_engine import ConsolidationEngine
+    from superlocalmemory.server.profile_runtime import get_profile_runtime
+    from superlocalmemory.storage import schema as _schema
+    from superlocalmemory.storage.database import DatabaseManager
+
+    runtime = get_profile_runtime(app_state)
+    # Rule 18: hold the operation lease so a concurrent profile switch cannot
+    # commit halfway through a consolidation.
+    with runtime.operation():
+        config = SLMConfig.load()
+        db = DatabaseManager(config.db_path)
+        db.initialize(_schema)
+        engine = ConsolidationEngine(
+            db=db, config=config.consolidation, slm_config=config,
+        )
+        res = engine.consolidate(profile_id=profile_id, lightweight=lightweight)
+
+        # Behavioural pattern mining writes learning.db rather than memory.db, so
+        # it sits outside the engine. Kept non-fatal: a pattern-mining failure
+        # must not discard a completed consolidation.
+        try:
+            from superlocalmemory.learning.consolidation_worker import (
+                ConsolidationWorker,
+            )
+            learning_db = config.base_dir / "learning.db"
+            cw = ConsolidationWorker(str(config.db_path), str(learning_db))
+            res["patterns_mined"] = cw._generate_patterns(profile_id, False)
+        except Exception as exc:
+            logger.warning("pattern mining after consolidation failed: %s", exc)
+            # -1, not 0: "it broke" and "there was nothing to mine" are
+            # different answers and the dashboard must not conflate them.
+            res["patterns_mined"] = -1
+    return res
+
+
+async def run_full_consolidation(
+    app_state: Any,
+    profile_id: str,
+    *,
+    lightweight: bool = False,
+    trigger: str = "manual",
+) -> dict:
+    """Run one consolidation pass, or skip if one is already in flight.
+
+    Returns the engine result dict, plus ``trigger``. When a pass is already
+    running the result is ``{"skipped": True, "reason": "already running"}`` —
+    an explicit skip rather than a silent no-op, so a caller can tell "did not
+    need to run" from "ran and found nothing".
+    """
+    if _LOCK.locked():
+        logger.info("consolidation skipped (%s): a pass is already running", trigger)
+        return {"skipped": True, "reason": "already running", "trigger": trigger}
+
+    async with _LOCK:
+        logger.info(
+            "consolidation starting (trigger=%s, profile=%s, lightweight=%s)",
+            trigger, profile_id, lightweight,
+        )
+        result = await asyncio.to_thread(
+            _consolidate_blocking, app_state, profile_id, lightweight,
+        )
+        logger.info(
+            "consolidation finished (trigger=%s): assertions=%s patterns=%s",
+            trigger,
+            (result.get("assertions") or {}).get("created", "n/a"),
+            result.get("patterns_mined", "n/a"),
+        )
+        result["trigger"] = trigger
+        return result