superlocalmemory 4.0.3 → 4.0.4

package/src/superlocalmemory/mcp/profiles.py

@@ -28,9 +28,10 @@ _PROFILE_CORE: frozenset[str] = frozenset({  # 14
 _PROFILE_BRAIN: frozenset[str] = frozenset({
     "get_brain_evidence_status", "record_agent_experience",
     "record_cognitive_turn", "finalize_cognitive_turn",
+    "observe_bounded_loop_evidence",
 })
 
-_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  # 28
+_PROFILE_CODE: frozenset[str] = _PROFILE_CORE | _PROFILE_BRAIN | frozenset({  # 29
     "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
@@ -47,21 +48,22 @@ _PROFILE_FULL_MESH: frozenset[str] = frozenset({  # 8
     "mesh_state", "mesh_lock", "mesh_events", "mesh_status",
 })
 
-_PROFILE_FULL: frozenset[str] = frozenset({  # 38 base — EXPLICIT literal, NOT runtime _ESSENTIAL_TOOLS (OQ-2)
+_PROFILE_FULL: frozenset[str] = frozenset({  # 39 base — EXPLICIT literal, NOT runtime _ESSENTIAL_TOOLS (OQ-2)
     "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",
     "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  # 46
+}) | _PROFILE_FULL_MESH  # 47
 
-_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 58
+_PROFILE_POWER: frozenset[str] = _PROFILE_FULL | frozenset({  # 59
     "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",
@@ -84,25 +86,29 @@ _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",
-    # 3.8.0: switch_profile (+1) then bounded-loop tools (+3) grew code/full/
+    # 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.
     "code20": "code",
     "code21": "code",
     "code24": "code",
     "code28": "code",
+    "code29": "code",
     "full38": "full",
     "full39": "full",
     "full42": "full",
     "full46": "full",
+    "full47": "full",
     "power50": "power",
     "power51": "power",
     "power54": "power",
     "power58": "power",
+    "power59": "power",
     "mesh8": "mesh",
     "whole81": "whole",
     "whole84": "whole",
     "whole91": "whole",
+    "whole92": "whole",
 }
 
 # Plain-English descriptions for UI display.

package/src/superlocalmemory/mcp/server.py

@@ -77,13 +77,13 @@ def reset_engine():
 
 # Register tools and resources -------------------------------------------------
 #
-# Essential-only default: 38 base tools + 8 mesh tools = 46 registered
+# Essential-only default: 39 base tools + 8 mesh tools = 47 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 91 tools (power users).
+# Set SLM_MCP_ALL_TOOLS=1 to enable all 92 tools (power users).
 
 import os as _os_reg
 
@@ -100,6 +100,9 @@ _ESSENTIAL_TOOLS: set[str] = {
     # v4.0.2 portable Brain evidence: profile-scoped receipt reads/writes.
     "get_brain_evidence_status", "record_agent_experience",
     "record_cognitive_turn", "finalize_cognitive_turn",
+    # v4.0.4: explicit, optional observation from the separately installed
+    # Bounded Loops MCP producer. It never participates in recall/ranking.
+    "observe_bounded_loop_evidence",
     # Memory management (2)
     "forget", "run_maintenance",
     # NOTE: prestage_context IS registered (see register_prestage_tool below)

package/src/superlocalmemory/mcp/tools_brain.py

@@ -9,6 +9,8 @@ or changes a memory answer.
 
 from __future__ import annotations
 
+import asyncio
+import sqlite3
 from pathlib import Path
 from typing import Any, Callable
 
@@ -17,6 +19,7 @@ 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
+from superlocalmemory.integrations.bounded_loops_mcp import BridgeUnavailable, observe_installed
 from superlocalmemory.storage.agent_experience import (
     AgentExperienceConflictError,
     AgentExperienceStore,
@@ -25,6 +28,12 @@ from superlocalmemory.storage.agent_experience import (
     ProfileAdmissionError,
     get_profile_receipt_summary,
 )
+from superlocalmemory.storage.external_evidence import (
+    ExternalEvidenceConflictError,
+    ExternalEvidenceStore,
+    ExternalEvidenceValidationError,
+    get_profile_external_evidence_summary,
+)
 
 
 def _store_for(engine: Any) -> AgentExperienceStore:
@@ -35,6 +44,14 @@ def _store_for(engine: Any) -> AgentExperienceStore:
     )
 
 
+def _external_store_for(engine: Any) -> ExternalEvidenceStore:
+    active_profile = engine.profile_id
+    return ExternalEvidenceStore(
+        Path(state_path("learning.db")),
+        is_profile_active=lambda profile_id: profile_id == active_profile,
+    )
+
+
 def _require_active_profile(engine: Any, payload: dict[str, Any]) -> str | None:
     supplied = payload.get("profile_id")
     if supplied != engine.profile_id:
@@ -42,6 +59,27 @@ def _require_active_profile(engine: Any, payload: dict[str, Any]) -> str | None:
     return None
 
 
+class _ExternalEvidenceWriteError(Exception):
+    """Preserve committed receipt count when a later snapshot item fails."""
+
+    def __init__(self, created: int, cause: Exception) -> None:
+        super().__init__(str(cause))
+        self.created = created
+        self.cause = cause
+
+
+def _record_external_evidence(store: ExternalEvidenceStore, observed: list[dict[str, Any]]) -> int:
+    """Write bounded evidence off the async MCP loop; return durable inserts."""
+    created = 0
+    for payload in observed:
+        try:
+            if store.record(payload):
+                created += 1
+        except Exception as exc:
+            raise _ExternalEvidenceWriteError(created, exc) from exc
+    return created
+
+
 def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
     """Register transport-neutral receipt reads and writes.
 
@@ -52,7 +90,7 @@ 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 Agent Experience and Cognitive Turn totals."""
+        """Get profile-scoped, observation-only Brain evidence totals."""
         engine = get_engine()
         return {
             "success": True,
@@ -60,6 +98,9 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
             "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",
         }
 
@@ -110,9 +151,7 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
 
     @server.tool()
     @admits(OperationKind.REMEMBER)
-    async def finalize_cognitive_turn(
-        receipt_id: str, outcome: dict[str, Any]
-    ) -> dict[str, Any]:
+    async def finalize_cognitive_turn(receipt_id: str, outcome: dict[str, Any]) -> dict[str, Any]:
         """Finalize an active-profile cognitive turn with outcome evidence."""
         engine = get_engine()
         try:
@@ -130,3 +169,49 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
         except (TypeError, ValueError) as exc:
             return {"success": False, "durable": False, "error": str(exc)}
         return {"success": True, "durable": True, "finalized": finalized}
+
+    @server.tool()
+    @admits(OperationKind.REMEMBER)
+    async def observe_bounded_loop_evidence(workspace: str) -> dict[str, Any]:
+        """Import one explicit, read-only snapshot from installed Bounded Loops.
+
+        Bounded Loops remains optional.  This tool negotiates its public MCP
+        contract at runtime, records only compatible terminal evidence, and
+        never changes recall, ranking, routing, or learned behaviour.
+        """
+        engine = get_engine()
+        created = 0
+        try:
+            observed = await observe_installed(workspace=workspace, profile_id=engine.profile_id)
+            store = _external_store_for(engine)
+            created = await asyncio.to_thread(_record_external_evidence, store, observed)
+        except _ExternalEvidenceWriteError as exc:
+            return {
+                "success": False,
+                "durable": exc.created > 0,
+                "created": exc.created,
+                "retryable": isinstance(exc.cause, LearningWriteBusyError),
+                "error": str(exc.cause),
+            }
+        except (
+            BridgeUnavailable,
+            ExternalEvidenceConflictError,
+            ExternalEvidenceValidationError,
+            ProfileAdmissionError,
+            sqlite3.Error,
+        ) as exc:
+            return {
+                "success": False,
+                "durable": created > 0,
+                "created": created,
+                "error": str(exc),
+            }
+        except LearningWriteBusyError as exc:
+            return {"success": False, "durable": False, "retryable": True, "error": str(exc)}
+        return {
+            "success": True,
+            "durable": True,
+            "observed": len(observed),
+            "created": created,
+            "control_plane": "observation_only",
+        }

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

@@ -327,7 +327,12 @@ def _compute_agent_experience(profile_id: str) -> dict:
     Receipt rows record observation and verification evidence only; this read
     model never alters retrieval, ranking, or model routing.
     """
-    return get_profile_receipt_summary(_learning_db_path(), profile_id)
+    from superlocalmemory.storage.external_evidence import get_profile_external_evidence_summary
+    path = _learning_db_path()
+    return {
+        **get_profile_receipt_summary(path, profile_id),
+        "external_graph_evidence": get_profile_external_evidence_summary(path, profile_id),
+    }
 
 
 def _resolve_phase(signals: int, model_active: bool,

package/src/superlocalmemory/storage/_migration_internals.py

@@ -147,6 +147,9 @@ from superlocalmemory.storage.migrations import (
 from superlocalmemory.storage.migrations import (
     M040_agent_experience_receipts as _M040,
 )
+from superlocalmemory.storage.migrations import (
+    M041_external_evidence_receipts as _M041,
+)
 
 # Emit under the runner's logger name so operational log filters that key on
 # "superlocalmemory.storage.migration_runner" keep matching after this split.
@@ -195,6 +198,7 @@ _MODULES = {
     _M038.NAME: _M038,
     _M039.NAME: _M039,
     _M040.NAME: _M040,
+    _M041.NAME: _M041,
 }
 
 # Exact historical DDL fingerprints whose resulting schema is intentionally

package/src/superlocalmemory/storage/_schema_version.py

@@ -21,9 +21,9 @@ import sqlite3
 from pathlib import Path
 
 #: Highest schema_version this runner can write.  Matches the trailing serial
-#: of the latest migration (M040).  Increment when adding new migrations or
+#: of the latest migration (M041).  Increment when adding new migrations or
 #: table-level breaking changes.
-SUPPORTED_SCHEMA_VERSION: int = 40
+SUPPORTED_SCHEMA_VERSION: int = 41
 
 
 class SchemaVersionError(RuntimeError):

package/src/superlocalmemory/storage/agent_experience.py

@@ -245,17 +245,29 @@ class AgentExperienceStore:
             turn_count = conn.execute(
                 "DELETE FROM cognitive_turn_receipts WHERE profile_id=?", (profile_id,)
             ).rowcount
+            external_count = 0
+            has_external = conn.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' "
+                "AND name='external_evidence_receipts'"
+            ).fetchone() is not None
+            if has_external:
+                external_count = conn.execute(
+                    "DELETE FROM external_evidence_receipts WHERE profile_id=?", (profile_id,)
+                ).rowcount
+            receipt_tables = ["agent_experiences", "cognitive_turn_receipts"]
+            if has_external:
+                receipt_tables.append("external_evidence_receipts")
             residue = sum(
                 int(
                     conn.execute(
                         f"SELECT COUNT(*) FROM {table} WHERE profile_id=?", (profile_id,)
                     ).fetchone()[0]
                 )
-                for table in ("agent_experiences", "cognitive_turn_receipts")
+                for table in receipt_tables
             )
             if residue:
                 raise RuntimeError("learning receipt erasure left profile residue")
-            return experience_count + turn_count
+            return experience_count + turn_count + external_count
 
         return self._write(erase)
 
@@ -422,7 +434,7 @@ def purge_profile_receipts(
             for row in conn.execute(
                 "SELECT name FROM sqlite_master WHERE type='table' "
                 "AND name IN ('agent_experiences', 'cognitive_turn_receipts', "
-                "'agent_receipt_profile_closures')"
+                "'agent_receipt_profile_closures', 'external_evidence_receipts')"
             )
         }
     if not tables:
@@ -431,6 +443,16 @@ def purge_profile_receipts(
         "agent_experiences", "cognitive_turn_receipts", "agent_receipt_profile_closures"
     }
     if tables != expected:
+        if tables == expected | {"external_evidence_receipts"}:
+            from superlocalmemory.storage.migrations import M041_external_evidence_receipts as m041
+
+            with sqlite3.connect(path) as conn:
+                # Erasure needs a valid table, not its optional performance indexes.
+                # A damaged index must never strand profile-scoped evidence.
+                if m041._table_is_valid(conn):
+                    return AgentExperienceStore(
+                        path, is_profile_active=lambda _: True
+                    ).erase_profile(profile_id, close_profile=close_profile)
         raise sqlite3.OperationalError("incomplete Agent Experience receipt schema")
     return AgentExperienceStore(
         path, is_profile_active=lambda _: True
@@ -459,7 +481,7 @@ def get_profile_receipt_summary(
     if not path.exists():
         return unavailable
     try:
-        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=0.5)
+        conn = sqlite3.connect(f"{path.resolve().as_uri()}?mode=ro", uri=True, timeout=0.5)
         try:
             experience = conn.execute(
                 "SELECT COUNT(*) FROM agent_experiences WHERE profile_id=?", (profile_id,)