superlocalmemory 4.1.9 → 4.1.12

package/src/superlocalmemory/mcp/tools_learning.py

@@ -15,11 +15,14 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import os
+import sqlite3
 import uuid
 from datetime import datetime, timezone
+from pathlib import Path
 from typing import Callable
 
 from mcp.types import ToolAnnotations
@@ -33,6 +36,72 @@ logger = logging.getLogger(__name__)
 _MAX_SUMMARY_LEN = 500  # Truncate input/output summaries
 
 
+def settle_pending_session_outcomes(
+    memory_db_path: str | Path,
+    *,
+    profile_id: str,
+    session_id: str,
+    evidence_only: bool = False,
+) -> dict[str, int]:
+    """Finalize real pending recalls for one host-owned session.
+
+    This is deliberately a narrow adapter around ``EngagementRewardModel``:
+    it selects only pending rows belonging to the supplied active profile and
+    exact host session, then delegates every state transition and reward
+    calculation to the established finalizer.  No feedback is inferred here.
+    Repeating the call is a no-op because settled rows are not selected.
+    """
+    session_id = session_id.strip()
+    if not session_id:
+        return {"selected": 0, "settled": 0}
+
+    path = Path(memory_db_path)
+    try:
+        with sqlite3.connect(str(path), timeout=2.0) as conn:
+            rows = conn.execute(
+                "SELECT outcome_id, signals_json FROM pending_outcomes "
+                "WHERE profile_id=? AND session_id=? AND status='pending'",
+                (profile_id, session_id),
+            ).fetchall()
+    except sqlite3.Error as exc:
+        raise RuntimeError("pending outcome lookup failed") from exc
+
+    if evidence_only:
+        from superlocalmemory.learning.reward import _carries_evidence
+
+        rows = [
+            row for row in rows
+            if _carries_evidence(json.loads(row[1] or "{}"))
+        ]
+
+    if not rows:
+        return {"selected": 0, "settled": 0}
+
+    from superlocalmemory.learning.reward import EngagementRewardModel
+
+    model = EngagementRewardModel(memory_db_path=str(path))
+    try:
+        for outcome_id, _signals_json in rows:
+            # Preserve the established keyword-only finalization contract.
+            model.finalize_outcome(outcome_id=outcome_id)
+    finally:
+        model.close()
+
+    outcome_ids = [row[0] for row in rows]
+    placeholders = ",".join("?" for _ in outcome_ids)
+    try:
+        with sqlite3.connect(str(path), timeout=2.0) as conn:
+            settled = conn.execute(
+                "SELECT COUNT(*) FROM pending_outcomes "
+                "WHERE profile_id=? AND session_id=? AND status='settled' "
+                f"AND outcome_id IN ({placeholders})",
+                (profile_id, session_id, *outcome_ids),
+            ).fetchone()[0]
+    except sqlite3.Error as exc:
+        raise RuntimeError("pending outcome settlement verification failed") from exc
+    return {"selected": len(outcome_ids), "settled": int(settled)}
+
+
 def register_learning_tools(server, get_engine: Callable) -> None:
     """Register learning MCP tools for two-way intelligence."""
 
@@ -45,6 +114,9 @@ def register_learning_tools(server, get_engine: Callable) -> None:
         output_summary: str = "",
         duration_ms: int = 0,
         metadata: str = "{}",
+        session_id: str = "",
+        agent_id: str = "",
+        project_path: str = "",
     ) -> dict:
         """Log a tool usage event for behavioral learning.
 
@@ -62,8 +134,11 @@ def register_learning_tools(server, get_engine: Callable) -> None:
         """
         engine = get_engine()
         now = datetime.now(timezone.utc).isoformat()
-        session_id = os.environ.get("CLAUDE_SESSION_ID", "unknown")
-        project_path = (
+        from superlocalmemory.mcp.session_binding import resolve_session_id
+        effective_session_id = resolve_session_id(
+            session_id, agent_id=agent_id or "mcp_client", allow_agent_fallback=True,
+        )
+        effective_project_path = project_path or (
             os.environ.get("CLAUDE_PROJECT_DIR")
             or os.environ.get("PROJECT_PATH")
             or os.getcwd()
@@ -86,15 +161,59 @@ def register_learning_tools(server, get_engine: Callable) -> None:
                 "(session_id, profile_id, project_path, tool_name, event_type, "
                 " input_summary, output_summary, duration_ms, metadata, created_at) "
                 "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-                (session_id, engine.profile_id, project_path, tool_name,
+                (effective_session_id, engine.profile_id, effective_project_path, tool_name,
                  event_type, input_clean, output_clean, duration_ms, metadata, now),
             )
             authorization.complete()
-            return {"success": True, "tool": tool_name, "event": event_type}
+            return {"success": True, "tool": tool_name, "event": event_type,
+                    "session_id": effective_session_id}
         except Exception as exc:
             logger.debug("log_tool_event failed: %s", exc)
             return {"success": False, "error": str(exc)}
 
+    @server.tool()
+    @admits(OperationKind.REMEMBER)
+    async def settle_session_outcomes(
+        session_id: str, agent_id: str = "", finalize: bool = False,
+    ) -> dict:
+        """Settle pending recall outcomes for one exact host session.
+
+        Native hosts call this after each turn and at finalization. Per-turn
+        calls settle only recalls that have actual evidence; finalization also
+        clears evidence-free pending rows. The operation never treats a hook
+        boundary itself as feedback. ``session_id`` must be explicit.
+        """
+        if not session_id or not session_id.strip():
+            return {"success": False, "error": "session_id is required"}
+        engine = get_engine()
+        try:
+            authorization = authorize_mcp_mutation(
+                engine,
+                "update",
+                mutation_source="mcp-settle-session-outcomes",
+                profile_id=engine.profile_id,
+                content_preview=agent_id[:100],
+            )
+            from superlocalmemory.hooks._outcome_common import memory_db_path
+
+            result = await asyncio.to_thread(
+                settle_pending_session_outcomes,
+                memory_db_path(),
+                profile_id=engine.profile_id,
+                session_id=session_id,
+                evidence_only=not finalize,
+            )
+            authorization.complete()
+            return {
+                "success": True,
+                "session_id": session_id.strip(),
+                "agent_id": agent_id.strip(),
+                **result,
+            }
+        except Exception as exc:
+            logger.debug("settle_session_outcomes failed: %s", exc)
+            return {"success": False, "error": str(exc)}
+
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
     async def get_assertions(
         min_confidence: float = 0.0,

package/src/superlocalmemory/mcp/tools_loops.py

@@ -47,6 +47,7 @@ from superlocalmemory.loops import (
     LedgerEntry,
     Verdict,
     engine_backed_ledger,
+    pool_backed_ledger,
     run_bounded_loop,
 )
 
@@ -69,7 +70,11 @@ _MAX_NAME_CHARS = 128
 _MAX_QUERY_CHARS = 2000
 
 
-def register_loop_tools(server, get_engine: Callable) -> None:
+def register_loop_tools(
+    server,
+    get_engine: Callable,
+    get_pool: Callable | None = None,
+) -> None:
     """Register the 3 bounded-loop tools on *server*.
 
     *server* is duck-typed: must support the ``@server.tool()`` decorator.
@@ -144,10 +149,46 @@ def register_loop_tools(server, get_engine: Callable) -> None:
             min_score = float(gate_min_score)
 
             engine = get_engine()
+            pool = get_pool() if get_pool is not None else None
 
             def gate(lap: int) -> Verdict:
-                resp = engine.recall(gate_query, limit=3, fast=True)
-                all_results = getattr(resp, "results", None) or []
+                if pool is not None:
+                    resp = pool.recall(gate_query, limit=3, fast=True)
+                    if not isinstance(resp, dict) or resp.get("ok") is False:
+                        raise RuntimeError(
+                            (resp or {}).get("error", "owned SLM reader rejected recall")
+                            if isinstance(resp, dict)
+                            else "owned SLM reader returned an invalid response"
+                        )
+                    all_results = resp.get("results", []) or []
+                    floored = bool(resp.get("no_confident_match", False))
+                else:
+                    resp = engine.recall(gate_query, limit=3, fast=True)
+                    all_results = getattr(resp, "results", None) or []
+                    floored = bool(getattr(resp, "no_confident_match", False))
+
+                def _content(result: Any) -> str:
+                    if isinstance(result, dict):
+                        fact = result.get("fact")
+                        if isinstance(fact, dict):
+                            return str(fact.get("content", "") or "")
+                        return str(result.get("content", "") or "")
+                    return str(
+                        getattr(getattr(result, "fact", None), "content", "") or ""
+                    )
+
+                def _score(result: Any) -> float:
+                    if isinstance(result, dict):
+                        value = result.get("score", result.get("relevance_score", 0.0))
+                    else:
+                        value = getattr(result, "score", None)
+                        if value is None:
+                            value = getattr(result, "relevance_score", 0.0) or 0.0
+                    try:
+                        return float(value)
+                    except (TypeError, ValueError):
+                        return 0.0
+
                 # Exclude the loop's own audit records from the gate evaluation.
                 # Each lap writes a LedgerEntry (JSON with "run_id" + "lap") into
                 # SLM via store_fast; the FTS5 trigger indexes every such insert.
@@ -157,20 +198,9 @@ def register_loop_tools(server, get_engine: Callable) -> None:
                 # can satisfy an independent gate.
                 results = [
                     r for r in all_results
-                    if LedgerEntry.from_json(
-                        getattr(getattr(r, "fact", None), "content", "") or ""
-                    ) is None
+                    if LedgerEntry.from_json(_content(r)) is None
                 ]
-                floored = bool(getattr(resp, "no_confident_match", False))
-                best: float = 0.0
-                for r in results:
-                    s = getattr(r, "score", None)
-                    if s is None:
-                        s = getattr(r, "relevance_score", 0.0) or 0.0
-                    try:
-                        best = max(best, float(s))
-                    except (TypeError, ValueError):
-                        pass
+                best = max((_score(result) for result in results), default=0.0)
                 passed = bool(results) and not floored and best >= min_score
                 return Verdict(
                     passed,
@@ -187,7 +217,11 @@ def register_loop_tools(server, get_engine: Callable) -> None:
                     time.sleep(poll)
                 return LapResult(changed=False, tokens=0)
 
-            ledger = engine_backed_ledger(engine)
+            ledger = (
+                pool_backed_ledger(pool, engine)
+                if pool is not None
+                else engine_backed_ledger(engine)
+            )
 
             # The loop blocks (sleeps between laps); run it off the event loop.
             # The engine's per-call WAL connection model makes this thread-safe.

package/src/superlocalmemory/server/unified_daemon.py

@@ -630,6 +630,10 @@ class RememberRequest(BaseModel):
     metadata: dict | None = None  # v3.4.26: pass-through from MCP pool_store
     idempotency_key: str | None = None
     session_id: str = ""
+    # Optional compare-and-write guard for profile-sensitive clients. The
+    # daemon remains single-profile, so a stale MCP client must fail instead
+    # of silently writing into whichever profile another client selected.
+    profile_id: str = ""
     #: WHEN this memory is about, as distinct from when it was written.
     #:
     #: The internal admission record has carried this field all along and this
@@ -693,6 +697,18 @@ class RememberRequest(BaseModel):
     shared_with: list[str] | None = None
 
 
+def _require_remember_profile(requested: str, active: str) -> None:
+    """Reject a stale profile-bound write before any durable mutation."""
+    if requested and requested != active:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                f"profile mismatch: request is bound to '{requested}' but "
+                f"the daemon currently serves '{active}'"
+            ),
+        )
+
+
 class SessionOpenRequest(BaseModel):
     # #49: local session-open warm (no model roundtrip needed)
     project_path: str = ""
@@ -4671,6 +4687,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
         trusted_actor_id = _require_write_actor(request)
         _update_activity()
         engine = _get_engine_or_503()
+        _require_remember_profile(req.profile_id, engine._profile_id)
 
         # v3.6.15 multi-scope: resolve the write scope. ``None`` (not specified
         # by the caller) → the configured default_scope (personal). Shared

package/src/superlocalmemory/storage/_migration_internals.py

@@ -165,6 +165,7 @@ from superlocalmemory.storage.migrations import (
     M047_fisher_vectors_are_stored_like_every_other_vector as _M047,
     M048_upcoming_holds_only_what_is_upcoming as _M048,
     M049_a_schema_version_marker_is_one_row as _M049,
+    M050_execution_learning_v2 as _M050,
 )
 
 # Emit under the runner's logger name so operational log filters that key on
@@ -223,6 +224,7 @@ _MODULES = {
     _M047.NAME: _M047,
     _M048.NAME: _M048,
     _M049.NAME: _M049,
+    _M050.NAME: _M050,
 }
 
 # Exact historical DDL fingerprints whose resulting schema is intentionally

package/src/superlocalmemory/storage/_schema_version.py

@@ -21,7 +21,7 @@ import sqlite3
 from pathlib import Path
 
 #: Highest schema_version this runner can write.  Matches the trailing serial of
-#: the latest migration (M049).  Increment when adding new migrations or
+#: the latest migration (M050).  Increment when adding new migrations or
 #: table-level breaking changes.
 #:
 #: This sat at 42 while M043, M044 and M045 shipped, so for three migrations the
@@ -44,7 +44,7 @@ from pathlib import Path
 #: be additive is a silent bad write.  Those are not comparable, and judging
 #: additivity per migration is exactly the judgement that let it fall three
 #: behind.
-SUPPORTED_SCHEMA_VERSION: int = 49
+SUPPORTED_SCHEMA_VERSION: int = 50
 
 
 class SchemaVersionError(RuntimeError):

package/src/superlocalmemory/storage/agent_experience.py

@@ -254,9 +254,33 @@ class AgentExperienceStore:
                 external_count = conn.execute(
                     "DELETE FROM external_evidence_receipts WHERE profile_id=?", (profile_id,)
                 ).rowcount
+            execution_count = 0
+            execution_tables = {
+                row[0]
+                for row in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table' "
+                    "AND name IN ('execution_learning_receipts', 'execution_learning_events')"
+                )
+            }
+            if execution_tables and execution_tables != {
+                "execution_learning_receipts", "execution_learning_events"
+            }:
+                raise sqlite3.OperationalError("incomplete execution-learning receipt schema")
+            has_execution = bool(execution_tables)
+            if has_execution:
+                execution_count += conn.execute(
+                    "DELETE FROM execution_learning_events WHERE profile_id=?", (profile_id,)
+                ).rowcount
+                execution_count += conn.execute(
+                    "DELETE FROM execution_learning_receipts WHERE profile_id=?", (profile_id,)
+                ).rowcount
             receipt_tables = ["agent_experiences", "cognitive_turn_receipts"]
             if has_external:
                 receipt_tables.append("external_evidence_receipts")
+            if has_execution:
+                receipt_tables.extend([
+                    "execution_learning_receipts", "execution_learning_events",
+                ])
             residue = sum(
                 int(
                     conn.execute(
@@ -267,7 +291,7 @@ class AgentExperienceStore:
             )
             if residue:
                 raise RuntimeError("learning receipt erasure left profile residue")
-            return experience_count + turn_count + external_count
+            return experience_count + turn_count + external_count + execution_count
 
         return self._write(erase)
 
@@ -434,7 +458,8 @@ 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', 'external_evidence_receipts')"
+                "'agent_receipt_profile_closures', 'external_evidence_receipts', "
+                "'execution_learning_receipts', 'execution_learning_events')"
             )
         }
     if not tables:
@@ -443,13 +468,22 @@ def purge_profile_receipts(
         "agent_experiences", "cognitive_turn_receipts", "agent_receipt_profile_closures"
     }
     if tables != expected:
-        if tables == expected | {"external_evidence_receipts"}:
+        optional = {"external_evidence_receipts"}
+        execution = {"execution_learning_receipts", "execution_learning_events"}
+        if tables in (expected | optional, expected | execution, expected | optional | execution):
             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):
+                external_ok = (
+                    "external_evidence_receipts" not in tables or m041._table_is_valid(conn)
+                )
+                execution_ok = (
+                    not execution.intersection(tables)
+                    or execution <= tables
+                )
+                if external_ok and execution_ok:
                     return AgentExperienceStore(
                         path, is_profile_active=lambda _: True
                     ).erase_profile(profile_id, close_profile=close_profile)