superlocalmemory 4.0.7 → 4.0.8

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

package/src/superlocalmemory/server/recall_serializer.py

@@ -170,6 +170,7 @@ def serialize_recall_response(
     total_max: int = 12000,
     full: bool = False,
     include_source: bool = False,
+    include_marker: bool = False,
 ) -> tuple[list[dict], bool]:
     """Convert a RecallResponse into budgeted, source-disciplined dicts.
 
@@ -185,10 +186,33 @@ def serialize_recall_response(
         total_max:      Total content char budget before stubs (config-driven).
         full:           Bypass clamping/stubs (additive escape hatch).
         include_source: Return full source_content (else ≤280-char preview).
+        include_marker: Emit each result's HMAC usage marker. See below.
 
     Returns:
         (results, no_confident_match) — results is a list of dicts; the bool
         is the evidence-floor signal lifted from the response (additive).
+
+    THE MARKER, AND WHY IT WAS MISSING
+    ----------------------------------
+    ``run_recall`` sets ``result.marker`` on every result — an HMAC of the
+    fact id, computed on the hot path already. Until 4.0.8 **no serialiser
+    ever read it**, so the value was computed and discarded on every recall.
+
+    That one omission broke the entire closed learning loop. The
+    ``post_tool_outcome`` hook settles an outcome by finding a validated
+    ``slm:fact:<id>:<hmac8>`` marker in a later tool response; with markers
+    never reaching the agent it found nothing, every outcome settled at the
+    formula's 0.5 base, and the consequences were visible all the way out to
+    the dashboard: 162 outcomes at the default label, all 294 source-quality
+    observations at exactly 0.5, therefore ``alpha == beta`` for all 18
+    sources and "no quality signal has settled", and 165 bandit arms with 4
+    plays between them.
+
+    Off by default, and gated by the caller on ``session_id``. A marker costs
+    roughly 33 characters of the agent's context per result, and it can only
+    buy a signal when a ``pending_outcomes`` row exists to settle — which
+    happens only for session-bearing recalls. Spending context on an ad-hoc
+    recall that could never learn from it is pure waste.
     """
     memory_map = memory_map or {}
     # T-inject: one shared "now" so every result's age label is consistent.
@@ -200,7 +224,7 @@ def serialize_recall_response(
         _created = getattr(fact, "created_at", "") or ""
         fact_type = getattr(fact, "fact_type", None)
         lifecycle = getattr(fact, "lifecycle", None)
-        raw.append({
+        entry = {
             "fact_id": fact.fact_id,
             "memory_id": fact.memory_id,
             "content": fact.content or "",
@@ -235,7 +259,15 @@ def serialize_recall_response(
             # weigh recency without doing date math. "" when undated.
             "age_label": relative_age(_created, _now),
             "evidence_chain": list(getattr(r, "evidence_chain", []) or []),
-        })
+        }
+        # Only when asked, and only when the engine actually produced one —
+        # an empty key would be indistinguishable from a marker that failed
+        # to compute, and the hook validates before trusting anything anyway.
+        if include_marker:
+            marker = getattr(r, "marker", "") or ""
+            if marker:
+                entry["marker"] = marker
+        raw.append(entry)
 
     # F-3 source discipline, then F-2 budget — order matters (discipline first
     # so the template firewall runs before any preview slicing).

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

@@ -106,24 +106,68 @@ async def get_agent_memory_activity(
         conn = get_read_connection(DB_PATH)
         try:
             try:
-                rows = conn.execute(
-                    "SELECT CASE WHEN trusted_actor_id='' THEN 'unknown' "
-                    "ELSE trusted_actor_id END AS agent_id, "
+                # Group by the agent's OWN identity, not by the capability that
+                # authorised the write.
+                #
+                # This grouped by ``trusted_actor_id``, which on a real store is
+                # a capability digest — 43 distinct agents rendered as 43 rows of
+                # ``daemon-capability:923b7d6e616f46d3...`` and not one readable
+                # name. For a pane whose entire purpose is telling agents apart,
+                # that is the same as showing nothing.
+                #
+                # The real name was already being stored the whole time: writers
+                # pass ``agent_id`` and it lands in ``raw_metadata_json``. On this
+                # store that yields claude-desktop, claude, gemini, codex, grok
+                # and mcp_client. Capability digests remain available per row for
+                # audit — they answer "what was allowed to write this", which is a
+                # different and also useful question, just not this pane's.
+                # raw_metadata_json is absent on stores predating it. Try the
+                # identity query and fall back to capability grouping if the
+                # column is missing — without this, the OperationalError is
+                # caught below and an older install shows ZERO agents while
+                # having plenty. Deliberately not PRAGMA table_info: this
+                # handler is on the dashboard read path, which is gated against
+                # anything that parses as DDL.
+                _tail = (
                     "COUNT(*) AS cnt, MAX(created_at) AS last_active, "
-                    "GROUP_CONCAT(DISTINCT source_type) AS sources "
+                    "GROUP_CONCAT(DISTINCT source_type) AS sources, "
+                    "COUNT(DISTINCT NULLIF(trusted_actor_id, '')) AS capabilities "
                     "FROM ingestion_operations WHERE profile_id=? "
                     "GROUP BY agent_id ORDER BY cnt DESC, agent_id ASC "
-                    "LIMIT 500",
-                    (pid,),
-                ).fetchall()
+                    "LIMIT 500"
+                )
+                try:
+                    rows = conn.execute(
+                        "SELECT COALESCE("
+                        "  NULLIF(json_extract(raw_metadata_json, '$.agent_id'), ''),"
+                        "  NULLIF(trusted_actor_id, ''),"
+                        "  'unknown'"
+                        ") AS agent_id, " + _tail,
+                        (pid,),
+                    ).fetchall()
+                except sqlite3.OperationalError:
+                    rows = conn.execute(
+                        "SELECT COALESCE(NULLIF(trusted_actor_id, ''), 'unknown')"
+                        " AS agent_id, " + _tail,
+                        (pid,),
+                    ).fetchall()
                 for r in rows:
+                    name = r["agent_id"]
                     agents.append({
-                        "agent_id": r["agent_id"],
+                        "agent_id": name,
                         "count": r["cnt"],
                         "last_active": r["last_active"],
                         "source_types": (
                             [s for s in (r["sources"] or "").split(",") if s]
                         ),
+                        # How many distinct capabilities this agent wrote under.
+                        "capability_count": r["capabilities"],
+                        # True when we fell back to a digest — the UI can then say
+                        # "this writer did not identify itself" instead of
+                        # presenting a hash as though it were a name.
+                        "identified": not str(name).startswith(
+                            ("daemon-capability:", "local-capability:")
+                        ) and name != "unknown",
                     })
                     total += r["cnt"]
             except sqlite3.OperationalError:

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

@@ -1764,6 +1764,114 @@ async def patterns_deprecated(
     }
 
 
+@router.get("/bounded-loops/evidence",
+            dependencies=[Depends(require_install_token)])
+async def bounded_loops_evidence(
+    request: Request, profile_id: str | None = None, limit: int = 20,
+) -> dict:
+    """Terminal Bounded Loops runs this profile has observed.
+
+    Bounded Loops is a SEPARATE PRODUCT. SLM is one optional consumer of a
+    document any MCP client can request over the published contract
+    ``bounded-loops.dev/slm-bridge/v1``; neither product depends on the other,
+    and installing either alone is complete.
+
+    What travels is deliberately narrow, and the pane must not imply otherwise:
+
+    * **Observation, not authorization.** ``eligible_for_learning`` is a hard
+      field in the contract and is always ``False`` in v1. A SUCCEEDED run is
+      not permission to retrain, re-rank or route on it. Nothing in SLM treats
+      it as such, and this endpoint returns the flag so the UI can say so.
+    * **Digests, not paths.** ``workspace_id`` is a hash precisely so a client's
+      directory name never reaches a memory system. Gate reasons, artifact
+      contents, commands and environment values are excluded at the source.
+    * **``local_hash_chain_only``.** The receipt log is an append-only hash
+      chain on local disk: tampering is detectable by anyone holding an earlier
+      head. That is NOT authentication, notarization or independent audit, and
+      calling it "verified" would claim a guarantee no part of the system
+      provides.
+    * **``demonstration``** separates real execution from a scripted replay. A
+      demo run proves the wiring works and proves nothing about the work.
+
+    Read-only, off the hot path, and empty is a normal answer — most installs
+    have no Bounded Loops at all.
+    """
+    profile_id = _authorized_profile(request, profile_id)
+    limit = max(1, min(int(limit or 20), 100))
+
+    out: dict[str, Any] = {
+        "contract": "bounded-loops.dev/slm-bridge/v1",
+        "control_plane": "observation_only",
+        "runs": [],
+        "total": 0,
+        "demonstration_count": 0,
+        "installed": None,
+    }
+
+    try:
+        out["installed"] = bool(_compute_bounded_loops().get("installed"))
+    except Exception:  # pragma: no cover — presence probe must never 500
+        out["installed"] = None
+
+    db_path = _learning_db_path()
+    if not db_path.exists():
+        return out
+
+    import sqlite3
+
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True, timeout=3)
+        conn.row_factory = sqlite3.Row
+        try:
+            rows = conn.execute(
+                "SELECT run_id, run_ref, outcome, run_state, demonstration,"
+                " eligible_for_learning, terminal_at, observed_at,"
+                " receipt_sequence, receipt_trust, workspace_id, contract_id"
+                " FROM external_evidence_receipts WHERE profile_id=?"
+                " ORDER BY observed_at DESC LIMIT ?",
+                (profile_id, limit),
+            ).fetchall()
+            total = conn.execute(
+                "SELECT COUNT(*) AS n FROM external_evidence_receipts"
+                " WHERE profile_id=?", (profile_id,),
+            ).fetchone()["n"]
+            demos = conn.execute(
+                "SELECT COUNT(*) AS n FROM external_evidence_receipts"
+                " WHERE profile_id=? AND demonstration=1", (profile_id,),
+            ).fetchone()["n"]
+        finally:
+            conn.close()
+    except sqlite3.Error as exc:
+        # The table only exists once the bridge has been used. Absent is a
+        # normal state, not an error, and must not surface as a failed pane.
+        logger.debug("bounded-loops evidence unavailable: %s", exc)
+        return out
+
+    out["total"] = total
+    out["demonstration_count"] = demos
+    out["runs"] = [
+        {
+            "run_id": r["run_id"],
+            "run_ref": r["run_ref"],
+            "outcome": r["outcome"],
+            # Both, because the mapping to three buckets loses information: a
+            # HALTED run (budget/policy stop) and a FAILED run (work the gate
+            # rejected) are different events.
+            "run_state": r["run_state"],
+            "demonstration": bool(r["demonstration"]),
+            "eligible_for_learning": bool(r["eligible_for_learning"]),
+            "terminal_at": r["terminal_at"],
+            "observed_at": r["observed_at"],
+            "receipt_sequence": r["receipt_sequence"],
+            "trust": r["receipt_trust"],
+            "workspace_id": r["workspace_id"],
+            "contract": r["contract_id"],
+        }
+        for r in rows
+    ]
+    return out
+
+
 @router.get("/behavioral",
             dependencies=[Depends(require_install_token)])
 async def behavioral_deprecated(