superlocalmemory 3.6.23 → 3.7.0

package/src/superlocalmemory/core/recall_pipeline.py

@@ -177,6 +177,34 @@ def _get_forgetting_scheduler(db: Any, config: Any) -> Any:
     return _forgetting_scheduler_cache[key]
 
 
+def release_recall_resources(db: Any) -> None:
+    """Release process-level recall singletons owned by a closing database."""
+    key = id(db)
+    _behavioral_tracker_cache.pop(key, None)
+    _forgetting_scheduler_cache.pop(key, None)
+
+
+def _behavioral_entities(results: list[Any], limit: int = 20) -> list[str]:
+    """Read canonical entity IDs from the typed retrieval-result contract.
+
+    ``RetrievalResult`` is a dataclass whose entity evidence lives on
+    ``result.fact.canonical_entities``. Treating it as a SQLite mapping silently
+    discarded every entity and disabled behavioral entity learning.
+    """
+    entities: list[str] = []
+    seen: set[str] = set()
+    for result in results:
+        fact = getattr(result, "fact", None)
+        for entity_id in getattr(fact, "canonical_entities", ()) or ():
+            if not isinstance(entity_id, str) or not entity_id or entity_id in seen:
+                continue
+            seen.add(entity_id)
+            entities.append(entity_id)
+            if len(entities) >= limit:
+                return entities
+    return entities
+
+
 # ---------------------------------------------------------------------------
 # S8-ARC-04 (v3.4.22): unified ranking entry point.
 # ---------------------------------------------------------------------------
@@ -268,10 +296,10 @@ def apply_adaptive_ranking(
     Phase 2 (50+): heuristic boosts from recency, access count, trust.
     Phase 3 (200+): LightGBM ML-based reranking.
     """
+    from superlocalmemory.infra.data_root import state_path
     from superlocalmemory.learning.feedback import FeedbackCollector
-    from pathlib import Path
 
-    learning_db = Path.home() / ".superlocalmemory" / "learning.db"
+    learning_db = state_path("learning.db")
     if not learning_db.exists():
         return response
 
@@ -284,7 +312,8 @@ def apply_adaptive_ranking(
     from superlocalmemory.learning.ranker import AdaptiveRanker
     ranker = AdaptiveRanker(signal_count=signal_count)
 
-    from datetime import UTC, datetime as _dt
+    from datetime import UTC
+    from datetime import datetime as _dt
     _now = _dt.now(UTC)
 
     result_dicts = []
@@ -314,6 +343,10 @@ def apply_adaptive_ranking(
     reranked = ranker.rerank(result_dicts, query_context)
 
     # Rebuild response with new ordering
+    for item in reranked:
+        original = item.get("_original")
+        if original is not None and item.get("_adaptive_score") is not None:
+            original.ranking_score = float(item["_adaptive_score"])
     new_results = [d["_original"] for d in reranked]
 
     return RecallResponse(
@@ -354,17 +387,13 @@ def apply_v2_adaptive_ranking(
     try:
         from pathlib import Path as _P
 
+        from superlocalmemory.infra.data_root import state_path
         from superlocalmemory.learning.database import LearningDatabase
         from superlocalmemory.learning.model_cache import load_active
         from superlocalmemory.learning.ranker import AdaptiveRanker
-        from superlocalmemory.learning.signals import (
-            SignalBatch,
-            SignalCandidate,
-            enqueue,
-        )
 
         db_path = (_P(learning_db_path) if learning_db_path
-                   else _P.home() / ".superlocalmemory" / "learning.db")
+                   else state_path("learning.db"))
         if not db_path.exists():
             return response
 
@@ -378,7 +407,8 @@ def apply_v2_adaptive_ranking(
         )
 
         # Build result-dict shape expected by the ranker's rerank() path.
-        from datetime import UTC, datetime as _dt
+        from datetime import UTC
+        from datetime import datetime as _dt
         _now_v2 = _dt.now(UTC)
 
         result_dicts: list[dict] = []
@@ -410,6 +440,10 @@ def apply_v2_adaptive_ranking(
             "profile_id": profile_id,
         }
         reranked_dicts = ranker.rerank(result_dicts, query_context)
+        for item in reranked_dicts:
+            original = item.get("_original")
+            if original is not None and item.get("_adaptive_score") is not None:
+                original.ranking_score = float(item["_adaptive_score"])
         new_results = [d["_original"] for d in reranked_dicts
                        if "_original" in d]
 
@@ -463,9 +497,9 @@ def apply_v2_bandit_ensemble(
         return response
 
     try:
-        from datetime import datetime as _dt
         from pathlib import Path as _P
 
+        from superlocalmemory.infra.data_root import state_path
         from superlocalmemory.learning.bandit import ContextualBandit
         from superlocalmemory.learning.ensemble import (
             choose_ensemble,
@@ -479,7 +513,7 @@ def apply_v2_bandit_ensemble(
         from superlocalmemory.retrieval.engine import apply_channel_weights
 
         db_path = (_P(learning_db_path) if learning_db_path
-                   else _P.home() / ".superlocalmemory" / "learning.db")
+                   else state_path("learning.db"))
         if not db_path.exists():
             return response
 
@@ -597,9 +631,8 @@ def run_recall(
 
     Pipeline: retrieval -> agentic sufficiency (if configured) -> post-recall updates.
 
-    V3.4.40: ``fast=True`` adds spreading_activation to the per-recall
-    extra_disabled_channels set, skipping the 5th channel for sub-second
-    response.
+    ``fast=True`` skips spreading activation and remote agentic verification,
+    retaining the bounded single-pass retrieval channels.
     """
     # Pre-operation hooks
     hook_ctx = {
@@ -639,7 +672,7 @@ def run_recall(
     # Single-hop/factual/temporal queries get WORSE with decomposition —
     # sub-query noise dilutes precision. Mode C (LLM) can trigger broadly.
     agentic_rounds = config.retrieval.agentic_max_rounds
-    if agentic_rounds > 0 and response.results:
+    if not fast and agentic_rounds > 0 and response.results:
         max_score = max((r.score for r in response.results), default=0.0)
         has_llm = llm is not None and getattr(llm, "is_available", False)
         should_trigger = (
@@ -679,6 +712,9 @@ def run_recall(
                             fact=f, score=1.0 / (i + 1),
                             channel_scores={"agentic": 1.0},
                             confidence=f.confidence,
+                            relevance_score=1.0 / (i + 1),
+                            ranking_score=None,
+                            memory_confidence=f.confidence,
                             evidence_chain=["agentic_round_2"],
                             trust_score=fact_trust,
                         ))
@@ -708,58 +744,18 @@ def run_recall(
         except Exception as exc:
             logger.debug("Access log batch store failed: %s", exc)
 
-    # V3.4.11: Promote recalled facts back to active tier (single batch UPDATE)
-    if response.results:
-        try:
-            from superlocalmemory.core.tier_manager import promote_on_access_batch
-            fact_ids = [r.fact.fact_id for r in response.results[:10]]
-            promote_on_access_batch(db, fact_ids)
-        except Exception:
-            pass  # tier_manager not available yet — graceful
-
-    # V3.3.16: Behavioral tracking + spaced repetition use module-level
-    # singletons to avoid creating new objects per recall (was causing
-    # object accumulation across 304 benchmark recalls).
+    # Query telemetry is permitted, but result-derived entities are not fed
+    # back as preferences.  Retrieval exposure is not positive feedback.
     try:
-        # v3.4.7: Extract entities from results for behavioral tracking.
-        # Was passing wrong param (result_count instead of entities) → TypeError.
-        entities: list[str] = []
-        for r in response.results[:10]:
-            rd = r if isinstance(r, dict) else (dict(r) if hasattr(r, "keys") else {})
-            ents_json = rd.get("canonical_entities_json", "")
-            if ents_json:
-                try:
-                    import json as _json
-                    entities.extend(_json.loads(ents_json))
-                except (ValueError, TypeError):
-                    pass
         _get_behavioral_tracker(db).record_query(
             query=query,
             query_type=response.query_type,
-            entities=entities[:20],
+            entities=[],
             profile_id=profile_id,
         )
     except Exception as exc:
         logger.debug("Behavioral tracking: %s", exc)
 
-    if response.results:
-        try:
-            fsched = _get_forgetting_scheduler(db, config)
-            for r in response.results[:10]:
-                fsched.on_access_event(r.fact.fact_id, profile_id)
-        except Exception as exc:
-            logger.debug("Spaced repetition update: %s", exc)
-
-    # Phase 3: Hebbian strengthening for co-accessed facts
-    if auto_linker and response.results:
-        try:
-            recalled_ids = [
-                r.fact.fact_id for r in response.results[:10]
-            ]
-            auto_linker.strengthen_co_access(recalled_ids, profile_id)
-        except Exception as exc:
-            logger.debug("Hebbian strengthening: %s", exc)
-
     # S8-ARC-04 (v3.4.22): unified ranking entry point. Single env-var
     # (SLM_RANKING=off|v1|v2|v2-ensemble) controls the pipeline. Legacy
     # SLM_V2_PIPELINE_DISABLED + SLM_BANDIT_DISABLED still honoured for
@@ -777,54 +773,17 @@ def run_recall(
         logger.debug("Ranking pipeline skipped: %s", exc)
 
     _mark("learning+ranking")
-    # Reconsolidation: access updates trust + count (neuroscience principle)
-    if trust_scorer:
-        for r in response.results:
-            trust_scorer.update_on_access("fact", r.fact.fact_id, profile_id)
-
-    # Fisher Bayesian update on recall — narrows variance on accessed facts
-    # so they score higher on subsequent recalls (critical for benchmark: +24pp).
-    # V3.3.16: Reuse query embedding from retrieval engine cache instead of
-    # calling embedder.embed() again (which was the memory leak source).
-    q_var_arr = None
-    if embedder and hasattr(retrieval_engine, '_query_embedding_cache'):
-        cached_emb = retrieval_engine._query_embedding_cache.get(query)
-        if cached_emb is not None:
-            import numpy as _np
-            _, q_var_list = embedder.compute_fisher_params(cached_emb)
-            q_var_arr = _np.array(q_var_list, dtype=_np.float64)
-
-    for r in response.results:
-        updates: dict[str, object] = {
-            "access_count": r.fact.access_count + 1,
-        }
-        if (q_var_arr is not None
-                and r.fact.fisher_variance
-                and len(r.fact.fisher_variance) == len(q_var_arr)
-                and r.fact.access_count >= 3):
-            import numpy as _np
-            f_var = _np.array(r.fact.fisher_variance, dtype=_np.float64)
-            new_var = 1.0 / (1.0 / _np.maximum(f_var, 0.05) + 1.0 / _np.maximum(q_var_arr, 0.05))
-            new_var = _np.clip(new_var, 0.05, 2.0)
-            updates["fisher_variance"] = new_var.tolist()
-        db.update_fact(r.fact.fact_id, updates)
+    # Deliberately no trust, Fisher, retention, lifecycle, popularity, or graph
+    # mutation here.  Those state transitions require a separately authenticated
+    # positive/negative outcome; merely returning a result is an exposure.
 
     # Post-operation hooks (audit, trust signal, learning)
     hook_ctx["result_count"] = len(response.results)
     hook_ctx["query_type"] = response.query_type
     hooks.run_post("recall", hook_ctx)
 
-    # v3.5.0 (M2): soft-normalize ALL scores to [0,1] after the full pipeline.
-    # The retrieval engine _build_results normalizes, but the ranking pipeline
-    # (v1/v2/bandit-ensemble) re-weights and may produce scores outside [0,1].
-    # This final sigmoid catches every path (MCP/CLI/Dashboard) and is monotonic.
-    if response.results:
-        import math as _mn
-        max_s = max((r.score for r in response.results), default=1.0)
-        scale = 2.0 / max(1.0, max_s)
-        for r in response.results:
-            r.score = round(1.0 / (1.0 + _mn.exp(-r.score * scale)), 4)
-            r.confidence = min(1.0, r.score * 2.0)
+    from superlocalmemory.core.score_contract import finalize_score_contract
+    finalize_score_contract(response)
 
     # LLD-00 §3 — stamp HMAC markers on every result so post_tool_outcome_hook
     # can validate fact_ids observed in downstream tool output.

package/src/superlocalmemory/core/recall_worker.py

@@ -78,7 +78,10 @@ def _handle_recall(
 
     # v3.6.6: same shared chokepoint as the daemon HTTP route + CLI fallback,
     # so the MCP WorkerPool subprocess path returns identical budgeted output.
-    from superlocalmemory.server.recall_serializer import serialize_recall_response
+    from superlocalmemory.server.recall_serializer import (
+        recall_response_metadata,
+        serialize_recall_response,
+    )
     _rc = getattr(engine._config, "retrieval", None)
     results, no_confident_match = serialize_recall_response(
         response,
@@ -99,13 +102,43 @@ def _handle_recall(
         "total_candidates": getattr(response, "total_candidates", 0),
         "results": results,
         "no_confident_match": no_confident_match,
+        **recall_response_metadata(response),
     }
 
 
 def _handle_store(content: str, metadata: dict) -> dict:
     engine = _get_engine()
-    session_id = metadata.pop("session_id", "")
-    fact_ids = engine.store(content, session_id=session_id, metadata=metadata)
+    values = dict(metadata or {})
+    session_id = str(values.pop("session_id", "") or "")
+    scope = str(values.pop("scope", "personal") or "personal")
+    shared_with = list(values.pop("shared_with", []) or [])
+    idempotency_key = str(values.pop("idempotency_key", "") or "")
+    from superlocalmemory.core.engine_ingestion import (
+        canonical_store,
+        local_trusted_actor_id,
+    )
+    operation = canonical_store(
+        engine,
+        content,
+        source_type="mcp-offline-worker",
+        trusted_actor_id=local_trusted_actor_id("recall-worker"),
+        metadata=values,
+        scope=scope,
+        shared_with=shared_with,
+        session_id=session_id,
+        idempotency_key=idempotency_key,
+        return_receipt=True,
+    )
+    if hasattr(operation, "fact_ids"):
+        fact_ids = list(operation.fact_ids)
+        operation_id = getattr(operation, "operation_id", None)
+        materialization_state = getattr(
+            getattr(operation, "state", None), "value", "complete"
+        )
+    else:
+        fact_ids = list(operation)
+        operation_id = None
+        materialization_state = "complete"
 
     # Generate and persist summary immediately after store (Mode A heuristic, B/C LLM)
     if fact_ids:
@@ -125,7 +158,15 @@ def _handle_store(content: str, metadata: dict) -> dict:
         except Exception:
             pass  # Summary is non-critical
 
-    return {"ok": True, "fact_ids": fact_ids, "count": len(fact_ids)}
+    pending = materialization_state != "complete"
+    return {
+        "ok": True,
+        "fact_ids": fact_ids,
+        "count": len(fact_ids),
+        "operation_id": operation_id,
+        "pending_id": operation_id if pending else None,
+        "materialization_state": materialization_state,
+    }
 
 
 def _handle_get_memory_facts(memory_id: str) -> dict:
@@ -154,65 +195,40 @@ def _handle_get_memory_facts(memory_id: str) -> dict:
     }
 
 
-def _handle_delete_memory(fact_id: str, agent_id: str = "system") -> dict:
-    """Delete a specific atomic fact by ID with audit logging."""
+def _handle_delete_memory(
+    fact_id: str,
+    source_agent_id: str = "system",
+) -> dict:
+    """Delete a fact after capability-derived authorization."""
     engine = _get_engine()
-    pid = engine.profile_id
-    rows = engine._db.execute(
-        "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ? LIMIT 1",
-        (fact_id, pid),
+    from superlocalmemory.core.engine_ingestion import local_trusted_actor_id
+    from superlocalmemory.core.mutations import delete_fact_authorized
+
+    return delete_fact_authorized(
+        engine,
+        fact_id,
+        trusted_actor_id=local_trusted_actor_id("recall-worker"),
+        source_agent_id=source_agent_id,
     )
-    if not rows:
-        return {"ok": False, "error": f"Memory {fact_id} not found"}
-    content_preview = dict(rows[0]).get("content", "")[:80]
-    engine._db.delete_fact(fact_id)
-    # Audit log
-    import logging as _logging
-    _logging.getLogger("superlocalmemory.audit").info(
-        "DELETE fact_id=%s by agent=%s content=%s", fact_id[:16], agent_id, content_preview,
-    )
-    return {"ok": True, "deleted": fact_id, "content_preview": content_preview}
 
 
-def _handle_update_memory(fact_id: str, content: str, agent_id: str = "system") -> dict:
-    """Update content of a specific atomic fact with audit logging."""
+def _handle_update_memory(
+    fact_id: str,
+    content: str,
+    source_agent_id: str = "system",
+) -> dict:
+    """Update a fact after capability-derived authorization."""
     engine = _get_engine()
-    pid = engine.profile_id
-    rows = engine._db.execute(
-        "SELECT content FROM atomic_facts WHERE fact_id = ? AND profile_id = ? LIMIT 1",
-        (fact_id, pid),
-    )
-    if not rows:
-        return {"ok": False, "error": f"Memory {fact_id} not found"}
-    old_content = dict(rows[0]).get("content", "")[:80]
-    # V3.3.12: Re-embed updated content so semantic search + BM25 stay consistent.
-    # Previously only the text column was updated, leaving stale embeddings.
-    updates: dict = {"content": content}
-    if engine._embedder:
-        try:
-            new_emb = engine._embedder.embed(content)
-            if new_emb:
-                updates["embedding"] = new_emb
-                fm, fv = engine._embedder.compute_fisher_params(new_emb)
-                updates["fisher_mean"] = fm
-                updates["fisher_variance"] = fv
-        except Exception:
-            pass
-    engine._db.update_fact(fact_id, updates)
-    # Update BM25 index for the new content
-    if hasattr(engine, '_retrieval_engine') and engine._retrieval_engine:
-        bm25 = getattr(engine._retrieval_engine, '_bm25', None)
-        if bm25:
-            try:
-                bm25.add(fact_id, content, pid)
-            except Exception:
-                pass
-    import logging as _logging
-    _logging.getLogger("superlocalmemory.audit").info(
-        "UPDATE fact_id=%s by agent=%s old=%s new=%s",
-        fact_id[:16], agent_id, old_content, content[:80],
+    from superlocalmemory.core.engine_ingestion import local_trusted_actor_id
+    from superlocalmemory.core.mutations import update_fact_authorized
+
+    return update_fact_authorized(
+        engine,
+        fact_id,
+        content,
+        trusted_actor_id=local_trusted_actor_id("recall-worker"),
+        source_agent_id=source_agent_id,
     )
-    return {"ok": True, "fact_id": fact_id, "content": content}
 
 
 def _handle_summarize(texts: list[str], mode: str) -> dict:
@@ -299,14 +315,15 @@ def _worker_main() -> None:
                 _respond(result)
             elif cmd == "delete_memory":
                 result = _handle_delete_memory(
-                    req.get("fact_id", ""), req.get("agent_id", "system"),
+                    req.get("fact_id", ""),
+                    req.get("source_agent_id", req.get("agent_id", "system")),
                 )
                 _respond(result)
             elif cmd == "update_memory":
                 result = _handle_update_memory(
                     req.get("fact_id", ""),
                     req.get("content", ""),
-                    req.get("agent_id", "system"),
+                    req.get("source_agent_id", req.get("agent_id", "system")),
                 )
                 _respond(result)
             elif cmd == "get_memory_facts":

package/src/superlocalmemory/core/registry.py

@@ -10,7 +10,7 @@ via an advisory lock mechanism. Persisted as JSON for
 survival across process restarts.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations