superlocalmemory 4.0.4 → 4.0.6

package/src/superlocalmemory/mcp/profiles.py

@@ -17,10 +17,13 @@ from __future__ import annotations
 # v3.6.14 WP-01: Named profile definitions
 # ---------------------------------------------------------------------------
 
-_PROFILE_CORE: frozenset[str] = frozenset({  # 14
+_PROFILE_CORE: frozenset[str] = frozenset({  # 16
     "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",
 })
 
 # Portable Brain evidence must reach the coding-host profile shipped by the
@@ -31,7 +34,7 @@ _PROFILE_BRAIN: frozenset[str] = frozenset({
     "observe_bounded_loop_evidence",
 })
 
-_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  # 29
+_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  # 31
     "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
@@ -48,22 +51,23 @@ _PROFILE_FULL_MESH: frozenset[str] = frozenset({  # 8
     "mesh_state", "mesh_lock", "mesh_events", "mesh_status",
 })
 
-_PROFILE_FULL: frozenset[str] = frozenset({  # 39 base — EXPLICIT literal, NOT runtime _ESSENTIAL_TOOLS (OQ-2)
+# 41 base — explicit literal, not runtime _ESSENTIAL_TOOLS (OQ-2).
+_PROFILE_FULL: frozenset[str] = frozenset({
     "remember", "recall", "search", "fetch", "list_recent", "delete_memory", "update_memory",
     "get_status", "session_init", "observe", "close_session", "report_feedback", "forget",
     "run_maintenance", "consolidate_cognitive", "get_soft_prompts", "set_mode", "report_outcome",
     "log_tool_event", "get_assertions", "reinforce_assertion", "contradict_assertion",
     "get_brain_evidence_status", "record_agent_experience",
     "record_cognitive_turn", "finalize_cognitive_turn",
-    "observe_bounded_loop_evidence",
+    "observe_bounded_loop_evidence", "review_correction", "list_corrections",
     "evolve_skill", "skill_health", "skill_lineage", "switch_profile",
     "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",
     # prestage_context remains registered but deliberately raw-server-only.
-}) | _PROFILE_FULL_MESH  # 47
+}) | _PROFILE_FULL_MESH  # 49
 
-_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 59
+_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 61
     "get_version", "get_mode", "health", "consistency_check", "recall_trace",
     "get_lifecycle_status", "set_retention_policy", "compact_memories",
     "get_behavioral_patterns", "audit_trail", "quantize", "get_retention_stats",
@@ -86,6 +90,7 @@ _PROFILE_DEFINITIONS: dict[str, frozenset[str]] = {
 # at server startup.  Any other value is a configuration error (fail closed).
 _PROFILE_ALIASES: dict[str, str] = {
     "core14": "core",
+    "core16": "core",
     # 3.8.0 and later additions grew code/full/power; every historical count
     # power. Every historical count-suffixed name is kept so a v3.6/3.7/early-
     # 3.8 config still resolves (back-compat); new 3.8.0 counts added alongside.
@@ -94,21 +99,25 @@ _PROFILE_ALIASES: dict[str, str] = {
     "code24": "code",
     "code28": "code",
     "code29": "code",
+    "code31": "code",
     "full38": "full",
     "full39": "full",
     "full42": "full",
     "full46": "full",
     "full47": "full",
+    "full49": "full",
     "power50": "power",
     "power51": "power",
     "power54": "power",
     "power58": "power",
     "power59": "power",
+    "power61": "power",
     "mesh8": "mesh",
     "whole81": "whole",
     "whole84": "whole",
     "whole91": "whole",
     "whole92": "whole",
+    "whole94": "whole",
 }
 
 # Plain-English descriptions for UI display.
@@ -116,7 +125,10 @@ _PROFILE_ALIASES: dict[str, str] = {
 # one sentence, user-facing language only.
 PROFILE_DESCRIPTIONS: dict[str, str] = {
     "core": "Essential memory: store, recall, search, sessions",
-    "code": "Core + code graph, portable Brain evidence, and profile switching (default for IDE coding agents)",
+    "code": (
+        "Core + code graph, portable Brain evidence, and profile switching "
+        "(default for IDE coding agents)"
+    ),
     "full": "All everyday memory, portable Brain evidence, optimization, and mesh tools",
     "power": "Everything in full plus advanced governance and behavioral tools",
     "mesh": "Cross-device mesh coordination only",

package/src/superlocalmemory/mcp/server.py

@@ -77,13 +77,13 @@ def reset_engine():
 
 # Register tools and resources -------------------------------------------------
 #
-# Essential-only default: 39 base tools + 8 mesh tools = 47 registered.
+# Essential-only default: 41 base tools + 8 mesh tools = 49 registered.
 # when mesh is enabled. Set ``SLM_MCP_ALL_TOOLS=1`` to expose the full
 # toolset. Rationale: IDEs cap at 50-100 tools total (Cursor,
 # Antigravity, Windsurf) and a maximal SLM registration crowds out
 # other MCP servers the user may have installed.
 # Admin/diagnostics tools remain available via CLI (`slm <command>`).
-# Set SLM_MCP_ALL_TOOLS=1 to enable all 92 tools (power users).
+# Set SLM_MCP_ALL_TOOLS=1 to enable all 94 tools (power users).
 
 import os as _os_reg
 
@@ -103,6 +103,8 @@ _ESSENTIAL_TOOLS: set[str] = {
     # v4.0.4: explicit, optional observation from the separately installed
     # Bounded Loops MCP producer. It never participates in recall/ranking.
     "observe_bounded_loop_evidence",
+    # Update, review, and list form one core correction lifecycle.
+    "review_correction", "list_corrections",
     # Memory management (2)
     "forget", "run_maintenance",
     # NOTE: prestage_context IS registered (see register_prestage_tool below)

package/src/superlocalmemory/mcp/tools_brain.py

@@ -16,6 +16,7 @@ from typing import Any, Callable
 
 from mcp.types import ToolAnnotations
 
+from superlocalmemory.brain.truth import BrainTruthService
 from superlocalmemory.core.admission import admits
 from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.infra.data_root import state_path
@@ -26,13 +27,11 @@ from superlocalmemory.storage.agent_experience import (
     CognitiveTurnTransitionError,
     LearningWriteBusyError,
     ProfileAdmissionError,
-    get_profile_receipt_summary,
 )
 from superlocalmemory.storage.external_evidence import (
     ExternalEvidenceConflictError,
     ExternalEvidenceStore,
     ExternalEvidenceValidationError,
-    get_profile_external_evidence_summary,
 )
 
 
@@ -52,6 +51,48 @@ def _external_store_for(engine: Any) -> ExternalEvidenceStore:
     )
 
 
+def _brain_truth_for(engine: Any) -> dict[str, Any]:
+    """Read the portable truth snapshot without opening an engine or a writer."""
+    return BrainTruthService(
+        memory_db_path=state_path("memory.db"),
+        learning_db_path=state_path("learning.db"),
+    ).snapshot(engine.profile_id)
+
+
+def _legacy_agent_experience(truth: dict[str, Any]) -> dict[str, Any]:
+    """Keep the v4.0.4 MCP alias during the one-release transition window."""
+    evidence = truth["agent_experience"]
+    available = evidence["availability"] == "available"
+    claimed = evidence["claimed_experiences_total"]
+    turns = evidence["cognitive_turns_total"]
+    states = evidence["cognitive_turns_by_state"]
+    return {
+        "is_real": available,
+        "availability": evidence["availability"],
+        "experiences_total": claimed if available else 0,
+        "turns_total": turns if available else 0,
+        "turns_by_state": states if available else {},
+        # The old name remains an alias only.  BrainTruth deliberately calls
+        # these declared claims, never independently verified learning.
+        "claimed_evidence_experiences": claimed if available else 0,
+        "source": evidence["source"],
+    }
+
+
+def _legacy_external_evidence(truth: dict[str, Any]) -> dict[str, Any]:
+    """Keep the v4.0.4 external-graph alias without a second database read."""
+    evidence = truth["external_evidence"]
+    available = evidence["availability"] == "available"
+    return {
+        "is_real": available,
+        "availability": evidence["availability"],
+        "total": evidence["receipts_total"] if available else 0,
+        "by_run_state": evidence["receipts_by_run_state"] if available else {},
+        "demonstrations": evidence["demonstrations_total"] if available else 0,
+        "control_plane": "observation_only",
+    }
+
+
 def _require_active_profile(engine: Any, payload: dict[str, Any]) -> str | None:
     supplied = payload.get("profile_id")
     if supplied != engine.profile_id:
@@ -90,18 +131,21 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_brain_evidence_status() -> dict[str, Any]:
-        """Get profile-scoped, observation-only Brain evidence totals."""
+        """Get profile-scoped, observation-only Living Brain evidence totals.
+
+        ``brain_truth`` is the canonical v1 payload.  The legacy aliases are
+        retained for one release so existing hosts can move independently.
+        """
         engine = get_engine()
+        truth = _brain_truth_for(engine)
         return {
             "success": True,
             "profile_id": engine.profile_id,
-            "agent_experience": get_profile_receipt_summary(
-                state_path("learning.db"), engine.profile_id
-            ),
-            "external_graph_evidence": get_profile_external_evidence_summary(
-                state_path("learning.db"), engine.profile_id
-            ),
-            "control_plane": "observation_only",
+            "brain_truth": truth,
+            "agent_experience": _legacy_agent_experience(truth),
+            "external_evidence": truth["external_evidence"],
+            "external_graph_evidence": _legacy_external_evidence(truth),
+            "control_plane": truth["control_plane"],
         }
 
     @server.tool()

package/src/superlocalmemory/mcp/tools_code_graph.py

@@ -204,8 +204,12 @@ def register_code_graph_tools(server, get_engine: Callable) -> None:
                 if fp in file_groups:
                     file_groups[fp][1].append(e)
 
-            for fp, (ns, es, fr) in file_groups.items():
-                store.store_file_nodes_edges(fp, ns, es, fr)
+            # Two-phase commit: all nodes first, then edges.
+            # This makes storage order-independent so cross-file CALLS edges
+            # (e.g., a.py calls bar() defined in b.py) are never silently
+            # dropped because of the file iteration order.
+            batch = [(fp, ns, es, fr) for fp, (ns, es, fr) in file_groups.items()]
+            store.commit_build_batch(batch)
 
             # Build in-memory graph
             engine = GraphEngine(store)
@@ -357,11 +361,14 @@ def register_code_graph_tools(server, get_engine: Callable) -> None:
                     continue
                 try:
                     source = full.read_bytes()
-                    file_nodes, file_edges = parser.parse_file(
+                    file_nodes, file_edges, file_import_map = parser.parse_file(
                         Path(fp), source, lang
                     )
                     import hashlib
                     from superlocalmemory.code_graph.models import FileRecord
+                    from superlocalmemory.code_graph.parser import (
+                        _clean_and_resolve_edges,
+                    )
                     fr = FileRecord(
                         file_path=fp,
                         content_hash=hashlib.sha256(source).hexdigest(),
@@ -371,7 +378,27 @@ def register_code_graph_tools(server, get_engine: Callable) -> None:
                         edge_count=len(file_edges),
                         last_indexed=time.time(),
                     )
-                    store.store_file_nodes_edges(fp, file_nodes, file_edges, fr)
+                    # Wire the resolver for the incremental path.
+                    # parse_all has _clean_and_resolve_edges built in, but
+                    # update_code_graph goes through parse_file which emits raw
+                    # placeholder targets (__call__<name>).  Without resolution,
+                    # Fix B (defensive filter) drops ALL CALLS edges — silent
+                    # data loss on every incremental update.
+                    #
+                    # Load the full DB node set as the resolution universe so
+                    # Strategy 3 (global heuristic) can match cross-file calls.
+                    db_nodes, _ = store.get_all_nodes_and_edges()
+                    resolution_universe = list(file_nodes) + [
+                        n for n in db_nodes if n.file_path != fp
+                    ]
+                    resolved_edges = _clean_and_resolve_edges(
+                        resolution_universe,
+                        list(file_edges),
+                        {fp: file_import_map},
+                        repo,
+                        config,
+                    )
+                    store.store_file_nodes_edges(fp, file_nodes, resolved_edges, fr)
                 except Exception as exc:
                     logger.warning("Failed to update %s: %s", fp, exc)
 

package/src/superlocalmemory/mcp/tools_core.py

@@ -928,8 +928,11 @@ def register_core_tools(server, get_engine: Callable) -> None:
                 )
                 if isinstance(result, dict) and result.get("success"):
                     return {
-                        "success": True, "fact_id": fact_id,
-                        "content": content.strip(),
+                        "success": True,
+                        "predecessor_fact_id": result.get("predecessor_fact_id", fact_id),
+                        "successor_fact_id": result.get("successor_fact_id"),
+                        "correction_case": result.get("correction_case"),
+                        "review_required": bool(result.get("review_required", False)),
                     }
                 return {
                     "success": False,
@@ -947,12 +950,94 @@ def register_core_tools(server, get_engine: Callable) -> None:
             })
             if result.get("ok"):
                 logger.info("Memory updated: %s by agent: %s", fact_id[:16], agent_id)
-                return {"success": True, "fact_id": fact_id, "content": content.strip()}
+                return {
+                    "success": True,
+                    "predecessor_fact_id": result.get("predecessor_fact_id", fact_id),
+                    "successor_fact_id": result.get("successor_fact_id"),
+                    "correction_case": result.get("correction_case"),
+                    "review_required": bool(result.get("review_required", False)),
+                }
             return {"success": False, "error": result.get("error", "Update failed")}
         except Exception as exc:
             logger.exception("update_memory failed")
             return {"success": False, "error": str(exc)}
 
+    @server.tool(annotations=ToolAnnotations(idempotentHint=True))
+    @admits(OperationKind.CORRECT)
+    async def review_correction(
+        case_id: str,
+        action: str,
+        expected_version: int,
+        event_valid_until: str | None = None,
+    ) -> dict:
+        """Apply, reject, or roll back a review-gated correction case.
+
+        The active daemon derives reviewer identity and profile from its local
+        authenticated MCP boundary.  Clients provide only a case address, a
+        CAS version, and an optional reviewer-approved event-time boundary.
+        """
+        if action not in {"apply", "reject", "rollback"}:
+            return {"success": False, "error": "action must be apply, reject, or rollback"}
+        if not isinstance(expected_version, int) or isinstance(expected_version, bool):
+            return {"success": False, "error": "expected_version must be an integer"}
+        if expected_version < 0:
+            return {"success": False, "error": "expected_version must be non-negative"}
+        try:
+            import asyncio
+            import urllib.parse
+
+            from superlocalmemory.cli.daemon import daemon_request, is_daemon_running
+
+            if not await asyncio.to_thread(is_daemon_running):
+                return {
+                    "success": False,
+                    "retryable": True,
+                    "error": "correction review requires the resident canonical daemon",
+                }
+            payload: dict[str, object] = {"expected_version": expected_version}
+            if event_valid_until is not None:
+                payload["event_valid_until"] = event_valid_until
+            path = "/api/corrections/" + urllib.parse.quote(case_id, safe="") + "/" + action
+            result = await asyncio.to_thread(daemon_request, "POST", path, payload)
+            if isinstance(result, dict) and result.get("success"):
+                return result
+            return {
+                "success": False,
+                "retryable": True,
+                "error": "resident daemon rejected the correction review",
+            }
+        except Exception:
+            logger.exception("review_correction failed")
+            return {"success": False, "retryable": True, "error": "correction review unavailable"}
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def list_corrections(limit: int = 100) -> dict:
+        """List active-profile correction cases for a human or host reviewer."""
+        if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= 500:
+            return {"success": False, "error": "limit must be an integer from 1 to 500"}
+        try:
+            import asyncio
+
+            from superlocalmemory.cli.daemon import daemon_request, is_daemon_running
+
+            if not await asyncio.to_thread(is_daemon_running):
+                return {
+                    "success": False,
+                    "retryable": True,
+                    "error": "correction review requires the resident canonical daemon",
+                }
+            result = await asyncio.to_thread(daemon_request, "GET", f"/api/corrections?limit={limit}")
+            if isinstance(result, dict) and result.get("success"):
+                return result
+            return {
+                "success": False,
+                "retryable": True,
+                "error": "resident daemon rejected correction listing",
+            }
+        except Exception:
+            logger.exception("list_corrections failed")
+            return {"success": False, "retryable": True, "error": "correction listing unavailable"}
+
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_attribution() -> dict:
         """Get system attribution: author, version, license, and provenance metadata."""

package/src/superlocalmemory/mcp/tools_v3.py

@@ -55,9 +55,12 @@ def register_v3_tools(server, get_engine: Callable) -> None:
     async def set_mode(mode: str) -> dict:
         """Switch operating mode (a, b, or c).
 
-        Mode A: Local Guardian (zero LLM, local embeddings only).
-        Mode B: Smart Local (local Ollama LLM, on-device inference).
-        Mode C: Full Power (configured cloud LLM provider, best accuracy).
+        Mode A (Local Guardian): Nothing leaves this device. No AI language
+                model runs. Fastest and most private.
+        Mode B: All data stays on this device. Uses a local Ollama AI model
+                to improve recall quality. Requires Ollama installed.
+        Mode C: Uses a cloud AI provider (OpenAI, Anthropic, …) for best
+                recall quality. Queries leave this device; API key required.
 
         Resets the engine to apply the new mode configuration.
 
@@ -377,8 +380,19 @@ def register_v3_tools(server, get_engine: Callable) -> None:
 def _mode_description(mode: str) -> str:
     """Human-readable capability description for a mode (never a legal claim)."""
     descriptions = {
-        "a": "Local Guardian: zero LLM, local embeddings only",
-        "b": "Smart Local: local Ollama LLM, on-device inference",
-        "c": "Full Power: configured cloud LLM provider, best accuracy",
+        "a": (
+            "Local Guardian — on-device only: no AI language model runs and "
+            "nothing leaves this device. Fastest and most private."
+        ),
+        "b": (
+            "Smart Local — on-device plus a local Ollama model: better recall "
+            "quality, and nothing leaves this device. Requires Ollama to be "
+            "installed and running."
+        ),
+        "c": (
+            "Full Power — uses a cloud AI provider (OpenAI, Anthropic, …) for "
+            "the best recall quality. Your queries leave this device and an "
+            "API key is required."
+        ),
     }
     return descriptions.get(mode, "Unknown mode")

package/src/superlocalmemory/retrieval/engine.py

@@ -29,6 +29,7 @@ from superlocalmemory.core.config import ChannelWeights, RetrievalConfig
 from superlocalmemory.retrieval.fusion import FusionResult, weighted_rrf
 from superlocalmemory.retrieval.strategy import QueryStrategy, QueryStrategyClassifier
 from superlocalmemory.retrieval.temporal_validity_filter import (
+    CorrectionAdmissionCache,
     admit_correction_candidates,
     admit_correction_fusion_results,
 )
@@ -232,6 +233,10 @@ class RetrievalEngine:
             include_unknown=include_unknown,
         )
         _em("run_channels")
+        # One request may need admission before fusion and again after optional
+        # bridge/scene expansion.  Cache only the IDs checked during this one
+        # request; every newly expanded candidate remains a hard DB lookup.
+        correction_admission = CorrectionAdmissionCache()
         if profile_hits:
             ch_results["profile"] = profile_hits
         # The profile shortcut bypasses _run_channels(), so it needs the same
@@ -241,6 +246,7 @@ class RetrievalEngine:
             known_as_of=known_as_of, valid_at=valid_at,
             include_unknown=include_unknown,
             include_global=include_global, include_shared=include_shared,
+            lifecycle_cache=correction_admission,
         )
         total = sum(len(v) for v in ch_results.values())
 
@@ -357,6 +363,7 @@ class RetrievalEngine:
             known_as_of=known_as_of, valid_at=valid_at,
             include_unknown=include_unknown,
             include_global=include_global, include_shared=include_shared,
+            lifecycle_cache=correction_admission,
         )
 
         _em("expand+entity_enh")
@@ -949,16 +956,6 @@ class RetrievalEngine:
                 except Exception as exc:
                     logger.warning("Post-retrieval filter failed: %s", exc)
 
-        # The legacy temporal filter preserves its score-demotion semantics for
-        # compatibility. Admission is separate and hard: no current
-        # system-superseded fact may seed fusion, bridge discovery, or rerank.
-        out = admit_correction_candidates(
-            out, profile_id, self._db, as_of=as_of,
-            known_as_of=known_as_of, valid_at=valid_at,
-            include_unknown=include_unknown,
-            include_global=include_global, include_shared=include_shared,
-        )
-
         return out
 
     def close(self, *, wait: bool = False) -> None:
@@ -1069,6 +1066,27 @@ class RetrievalEngine:
         if not applied:
             return fused, False, status
 
+        # The worker can report applied=True while returning scores=null — the
+        # subprocess answers, so the call "succeeded", but there is nothing to
+        # score with.  Iterating None here raised TypeError from OUTSIDE the
+        # try/except above (which only wraps the rerank call itself), so the
+        # error escaped into the recall path rather than degrading to the fused
+        # ordering.  Fail soft: reranking is a quality improvement on top of a
+        # correct result set, never a correctness requirement.
+        # `not scored` covers None AND an empty sequence. An empty list is the
+        # same defect wearing different clothes: the worker says applied=True but
+        # supplied nothing to rank with. Guarding only None would let [] through
+        # to build an empty score_map, and every candidate would then be scored
+        # against a degenerate min/max — silently shrinking the fused component
+        # by (1 - alpha) while still reporting the rerank as applied.
+        if not scored:
+            logger.warning(
+                "Cross-encoder worker reported applied=True with %s scores; "
+                "falling back to fused ranking for this query.",
+                "null" if scored is None else "empty",
+            )
+            return fused, False, "worker_null_scores"
+
         score_map = {fact.fact_id: score for fact, score in scored}
 
         # Min-max normalize CE scores to [0, 1] within the batch instead of