superlocalmemory 3.6.23 → 3.7.0

package/src/superlocalmemory/ingestion/base_adapter.py

@@ -12,12 +12,11 @@ All adapters inherit this. Enforces stateless, safe, cross-platform operation:
   - Structured logging
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
 
-import json
 import logging
 import os
 import signal
@@ -132,35 +131,30 @@ class BaseAdapter:
 
     def _ingest(self, item: IngestItem) -> bool:
         """POST to daemon /ingest endpoint. Returns True on success."""
-        try:
-            import urllib.request
-            payload = json.dumps({
-                "content": item.content,
-                "source_type": self.source_type,
-                "dedup_key": item.dedup_key,
-                "metadata": item.metadata if item.metadata else {},
-            }).encode()
-            req = urllib.request.Request(
-                f"{self.daemon_url}/ingest",
-                data=payload,
-                headers={"Content-Type": "application/json"},
-                method="POST",
-            )
-            resp = urllib.request.urlopen(req, timeout=30)
-            data = json.loads(resp.read().decode())
-            if data.get("ingested"):
-                self._items_this_hour += 1
-                self._total_ingested += 1
-                return True
-            return False  # Already ingested (dedup)
-        except Exception as exc:
-            error_str = str(exc)
-            if "429" in error_str:
-                logger.info("Daemon returned 429, backing off 5s")
-                self._stop_event.wait(5)
-                return self._ingest(item)  # Retry once
-            logger.debug("Ingest failed: %s", exc)
-            return False
+        payload = {
+            "content": item.content,
+            "source_type": self.source_type,
+            "dedup_key": item.dedup_key,
+            "metadata": item.metadata if item.metadata else {},
+        }
+        for attempt in range(2):
+            try:
+                from superlocalmemory.cli.daemon import daemon_request
+
+                data = daemon_request("POST", "/ingest", payload)
+                if data and data.get("ingested"):
+                    self._items_this_hour += 1
+                    self._total_ingested += 1
+                    return True
+                return False  # Already ingested (dedup)
+            except Exception as exc:
+                if "429" in str(exc) and attempt == 0:
+                    logger.info("Daemon returned 429, backing off 5s")
+                    self._stop_event.wait(5)
+                    continue
+                logger.debug("Ingest failed: %s", exc)
+                return False
+        return False
 
     def _rate_limited(self) -> bool:
         if time.time() - self._hour_start > 3600:

package/src/superlocalmemory/ingestion/calendar_adapter.py

@@ -10,7 +10,7 @@ Tier 2: Google Calendar API with OAuth polling — shares Gmail OAuth credential
 OPT-IN only. Enabled via: slm adapters enable calendar
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -22,10 +22,19 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from superlocalmemory.ingestion.base_adapter import BaseAdapter, AdapterConfig, IngestItem
+from superlocalmemory.infra.data_root import state_path
 
 logger = logging.getLogger("superlocalmemory.ingestion.calendar")
 
 
+def _adapters_config_path() -> Path:
+    return state_path("adapters.json")
+
+
+def _import_dir() -> Path:
+    return state_path("import")
+
+
 class CalendarAdapter(BaseAdapter):
     """Google Calendar ingestion with automatic tier detection."""
 
@@ -62,7 +71,7 @@ class CalendarAdapter(BaseAdapter):
         if self._tier != "auto":
             return
 
-        adapters_path = Path.home() / ".superlocalmemory" / "adapters.json"
+        adapters_path = _adapters_config_path()
         cfg = {}
         if adapters_path.exists():
             cfg = json.loads(adapters_path.read_text()).get("calendar", {})
@@ -79,7 +88,7 @@ class CalendarAdapter(BaseAdapter):
             return
 
         # Look for ICS files
-        import_dir = Path.home() / ".superlocalmemory" / "import"
+        import_dir = _import_dir()
         ics_files = list(import_dir.glob("*.ics")) if import_dir.exists() else []
         if ics_files:
             self._tier = "ics"
@@ -330,7 +339,7 @@ if __name__ == "__main__":
     import logging as _logging
     _logging.basicConfig(level=_logging.INFO, format="%(asctime)s %(message)s")
 
-    adapters_path = Path.home() / ".superlocalmemory" / "adapters.json"
+    adapters_path = _adapters_config_path()
     tier = "auto"
     if adapters_path.exists():
         cfg = json.loads(adapters_path.read_text()).get("calendar", {})

package/src/superlocalmemory/ingestion/credentials.py

@@ -8,7 +8,7 @@ Uses OS keychain via keyring library (macOS Keychain, Windows Credential Locker,
 Linux SecretService). Falls back to file-based storage with restricted permissions.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -19,12 +19,18 @@ import os
 import sys
 from pathlib import Path
 
+from superlocalmemory.infra.data_root import state_path
+
 logger = logging.getLogger("superlocalmemory.ingestion.credentials")
 
-_CRED_DIR = Path.home() / ".superlocalmemory" / "credentials"
+_CRED_DIR = None  # test-only compatibility override
 _SERVICE_PREFIX = "slm"
 
 
+def _credential_dir() -> Path:
+    return Path(_CRED_DIR) if _CRED_DIR is not None else state_path("credentials")
+
+
 def store_credential(service: str, key: str, value: str) -> bool:
     """Store a credential securely. Returns True on success."""
     # Try OS keychain first
@@ -38,8 +44,9 @@ def store_credential(service: str, key: str, value: str) -> bool:
 
     # Fallback: encrypted file with restricted permissions
     try:
-        _CRED_DIR.mkdir(parents=True, exist_ok=True)
-        cred_file = _CRED_DIR / f"{service}.json"
+        cred_dir = _credential_dir()
+        cred_dir.mkdir(parents=True, exist_ok=True)
+        cred_file = cred_dir / f"{service}.json"
 
         existing = {}
         if cred_file.exists():
@@ -54,7 +61,7 @@ def store_credential(service: str, key: str, value: str) -> bool:
         # Restrict permissions (Unix only — Windows skipped)
         if sys.platform != "win32":
             os.chmod(cred_file, 0o600)
-            os.chmod(_CRED_DIR, 0o700)
+            os.chmod(cred_dir, 0o700)
 
         logger.debug("Stored %s/%s in file (keychain unavailable)", service, key)
         return True
@@ -76,7 +83,7 @@ def load_credential(service: str, key: str) -> str | None:
 
     # Fallback: file
     try:
-        cred_file = _CRED_DIR / f"{service}.json"
+        cred_file = _credential_dir() / f"{service}.json"
         if cred_file.exists():
             data = json.loads(cred_file.read_text())
             return data.get(key)
@@ -100,7 +107,7 @@ def delete_credential(service: str, key: str) -> bool:
 
     # Also remove from file
     try:
-        cred_file = _CRED_DIR / f"{service}.json"
+        cred_file = _credential_dir() / f"{service}.json"
         if cred_file.exists():
             data = json.loads(cred_file.read_text())
             if key in data:

package/src/superlocalmemory/ingestion/gmail_adapter.py

@@ -12,7 +12,7 @@ Tier 3: Gmail API with Pub/Sub push — full GCP (future)
 OPT-IN only. Enabled via: slm adapters enable gmail
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -23,10 +23,19 @@ import sys
 from pathlib import Path
 
 from superlocalmemory.ingestion.base_adapter import BaseAdapter, AdapterConfig, IngestItem
+from superlocalmemory.infra.data_root import state_path
 
 logger = logging.getLogger("superlocalmemory.ingestion.gmail")
 
 
+def _adapters_config_path() -> Path:
+    return state_path("adapters.json")
+
+
+def _import_dir() -> Path:
+    return state_path("import")
+
+
 class GmailAdapter(BaseAdapter):
     """Gmail ingestion with automatic tier detection."""
 
@@ -71,7 +80,7 @@ class GmailAdapter(BaseAdapter):
         if self._tier != "auto":
             return
 
-        adapters_path = Path.home() / ".superlocalmemory" / "adapters.json"
+        adapters_path = _adapters_config_path()
         cfg = {}
         if adapters_path.exists():
             cfg = json.loads(adapters_path.read_text()).get("gmail", {})
@@ -93,7 +102,7 @@ class GmailAdapter(BaseAdapter):
             return
 
         # Default: look for mbox file
-        mbox_dir = Path.home() / ".superlocalmemory" / "import"
+        mbox_dir = _import_dir()
         mbox_files = list(mbox_dir.glob("*.mbox")) if mbox_dir.exists() else []
         if mbox_files:
             self._tier = "mbox"
@@ -359,7 +368,7 @@ if __name__ == "__main__":
     import logging as _logging
     _logging.basicConfig(level=_logging.INFO, format="%(asctime)s %(message)s")
 
-    adapters_path = Path.home() / ".superlocalmemory" / "adapters.json"
+    adapters_path = _adapters_config_path()
     tier = "auto"
     if adapters_path.exists():
         cfg = json.loads(adapters_path.read_text()).get("gmail", {})

package/src/superlocalmemory/ingestion/transcript_adapter.py

@@ -11,7 +11,7 @@ to the daemon's /ingest endpoint.
 OPT-IN only. Enabled via: slm adapters enable transcript
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -23,12 +23,17 @@ import time
 from pathlib import Path
 
 from superlocalmemory.ingestion.base_adapter import BaseAdapter, AdapterConfig, IngestItem
+from superlocalmemory.infra.data_root import state_path
 
 logger = logging.getLogger("superlocalmemory.ingestion.transcript")
 
 _WATCH_EXTENSIONS = {".srt", ".vtt", ".txt"}
 
 
+def _adapters_config_path() -> Path:
+    return state_path("adapters.json")
+
+
 class TranscriptAdapter(BaseAdapter):
     """Watches a directory for transcript files and ingests them."""
 
@@ -142,7 +147,7 @@ if __name__ == "__main__":
 
     # Load config
     watch_dir = ""
-    adapters_path = Path.home() / ".superlocalmemory" / "adapters.json"
+    adapters_path = _adapters_config_path()
     if adapters_path.exists():
         cfg = json.loads(adapters_path.read_text())
         watch_dir = cfg.get("transcript", {}).get("watch_dir", "")

package/src/superlocalmemory/learning/consolidation_quantization_worker.py

@@ -12,7 +12,7 @@ Wraps CognitiveConsolidator with scheduling logic:
 Integration point: ConsolidationEngine._step7_ccq() calls this worker.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/learning/ensemble.py

@@ -269,6 +269,17 @@ def ensemble_rerank(
         for b, l in zip(n_bandit, n_lgbm)
     ]
 
+    # Retain the model/policy utility for auditability without overwriting the
+    # public query-relative relevance score.
+    for candidate, utility in zip(candidates, blended):
+        if isinstance(candidate, dict):
+            candidate["ranking_score"] = float(utility)
+        else:
+            try:
+                candidate.ranking_score = float(utility)
+            except (AttributeError, TypeError):
+                pass
+
     # Stable-sort descending so equal scores preserve original order.
     indexed = list(enumerate(candidates))
     indexed.sort(key=lambda pair: -blended[pair[0]])

package/src/superlocalmemory/learning/entity_compiler.py

@@ -11,7 +11,7 @@ Builds knowledge summaries using PageRank centrality + Louvain community detecti
 Runs after consolidation (every 6 hours or on-demand).
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/learning/feedback.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# SPDX-License-Identifier: Elastic-2.0
+# SPDX-License-Identifier: AGPL-3.0-or-later
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
 # Part of Qualixar | Author: Varun Pratap Bhardwaj (qualixar.com | varunpratap.com)
 """

package/src/superlocalmemory/learning/forgetting_scheduler.py

@@ -18,7 +18,7 @@ HR-08: Runs synchronously in main thread.
 HR-09: Access events are idempotent.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -60,7 +60,7 @@ class ForgettingScheduler:
         self._last_run_times: dict[str, float] = {}
 
     def run_decay_cycle(
-        self, profile_id: str, *, force: bool = False,
+        self, profile_id: str, *, force: bool = False, dry_run: bool = False,
     ) -> dict:
         """Run a full decay cycle for all facts in a profile.
 
@@ -70,6 +70,7 @@ class ForgettingScheduler:
         Args:
             profile_id: Profile to process.
             force: If True, bypass interval check.
+            dry_run: Compute transitions without persisting retention or lifecycle.
 
         Returns:
             Stats dict: {total, active, warm, cold, archive, forgotten,
@@ -87,7 +88,8 @@ class ForgettingScheduler:
         facts_data = self._fetch_facts_with_metadata(profile_id)
 
         if not facts_data:
-            self._last_run_times[profile_id] = now
+            if not dry_run:
+                self._last_run_times[profile_id] = now
             return {
                 "total": 0, "active": 0, "warm": 0, "cold": 0,
                 "archive": 0, "forgotten": 0, "transitions": 0,
@@ -100,7 +102,8 @@ class ForgettingScheduler:
         retention_results = self._ebbinghaus.batch_compute_retention(facts_data)
 
         # Step 4: Batch UPSERT into fact_retention
-        self._db.batch_upsert_retention(retention_results, profile_id)
+        if not dry_run:
+            self._db.batch_upsert_retention(retention_results, profile_id)
 
         # Step 5: Count zones and transitions
         zone_counts = {"active": 0, "warm": 0, "cold": 0, "archive": 0, "forgotten": 0}
@@ -121,11 +124,13 @@ class ForgettingScheduler:
                 forgotten_fact_ids.append(result["fact_id"])
 
         # Step 6: Soft-delete forgotten facts (HR-04)
-        for fact_id in forgotten_fact_ids:
-            self._soft_delete_with_audit(fact_id, profile_id)
+        if not dry_run:
+            for fact_id in forgotten_fact_ids:
+                self._soft_delete_with_audit(fact_id, profile_id)
 
         # Update last run time
-        self._last_run_times[profile_id] = now
+        if not dry_run:
+            self._last_run_times[profile_id] = now
 
         return {
             "total": len(retention_results),

package/src/superlocalmemory/learning/quantization_scheduler.py

@@ -17,7 +17,7 @@ HR-08: Synchronous execution (no threading).
 HR-09: Audit trail for every change.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/learning/ranker.py

@@ -208,7 +208,10 @@ class AdaptiveRanker:
             return self._rerank_heuristic(results, query_context)
 
         order = np.argsort(-scores, kind="stable")
-        return [results[int(i)] for i in order]
+        return [
+            {**results[int(i)], "_adaptive_score": float(scores[int(i)])}
+            for i in order
+        ]
 
     # --- legacy load path (back-compat) --------------------------------
 

package/src/superlocalmemory/learning/source_quality.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# SPDX-License-Identifier: Elastic-2.0
+# SPDX-License-Identifier: AGPL-3.0-or-later
 # Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
 # Part of Qualixar | Author: Varun Pratap Bhardwaj (qualixar.com | varunpratap.com)
 """

package/src/superlocalmemory/learning/trigram_index.py

@@ -44,6 +44,7 @@ from typing import Optional
 # Import the RAM semaphore at module scope so tests can monkeypatch
 # ``trigram_index.ram_reservation`` to a no-op on CI boxes with tight RAM.
 from superlocalmemory.core.ram_lock import ram_reservation
+from superlocalmemory.infra.data_root import DynamicStatePath, state_path
 
 
 # --------------------------------------------------------------------------
@@ -205,7 +206,7 @@ class TrigramIndex:
     ``(entity_id, hits)`` candidates.
     """
 
-    CACHE_DB_PATH: Path = Path.home() / ".superlocalmemory" / "active_brain_cache.db"
+    CACHE_DB_PATH: Path = DynamicStatePath("active_brain_cache.db")
     MAX_TRIGRAMS: int = 1_000_000
     LOOKUP_LIMIT: int = 10
     LOOKUP_MIN_HITS: int = 2
@@ -537,7 +538,7 @@ def get_or_none() -> Optional[TrigramIndex]:
         return _SINGLETON
     if not TrigramIndex.CACHE_DB_PATH.exists():
         return None
-    default_source = Path.home() / ".superlocalmemory" / "memory.db"
+    default_source = state_path("memory.db")
     if not default_source.exists():
         return None
     _SINGLETON = TrigramIndex(source_db_path=default_source)

package/src/superlocalmemory/llm/backbone.py

@@ -14,7 +14,7 @@ Providers:
 - ``"azure"``: Azure OpenAI (via AI Foundry deployment).
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/math/ebbinghaus.py

@@ -34,7 +34,7 @@ References:
         Long-Term Memory. AAAI 2024.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/math/fisher.py

@@ -42,7 +42,7 @@ References:
         cases, bounds and applications. Entropy 22(4):404.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/math/fisher_quantized.py

@@ -19,7 +19,7 @@ Mathematical basis:
     on the statistical manifold of diagonal Gaussians
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/math/hopfield.py

@@ -19,7 +19,7 @@ Key properties:
   - Convergence: 1 step for well-separated patterns
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/math/langevin.py

@@ -42,7 +42,7 @@ References:
         Probability Letters, 91, 59--67.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/math/polar_quant.py

@@ -26,7 +26,7 @@ References:
     the classical compact groups.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -41,6 +41,7 @@ import numpy as np
 from numpy.typing import NDArray
 
 from superlocalmemory.core.config import PolarQuantConfig
+from superlocalmemory.infra.data_root import state_path
 
 logger = logging.getLogger(__name__)
 
@@ -113,9 +114,7 @@ class PolarQuantEncoder:
         """
         path_str = self._config.rotation_matrix_path
         if not path_str:
-            path_str = str(
-                Path.home() / ".superlocalmemory" / f"polar_rotation_{self._d}.npy",
-            )
+            path_str = str(state_path(f"polar_rotation_{self._d}.npy"))
 
         path = Path(path_str)
 

package/src/superlocalmemory/math/qjl.py

@@ -27,7 +27,7 @@ References:
   - TurboQuant (ICLR 2026, arXiv 2504.19874).
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/math/sheaf.py

@@ -14,7 +14,7 @@ Severity = ||delta_0 f(e)|| / (||R_a emb_a|| + ||R_b emb_b||).
 Refs: Curry 2014 (arXiv:1303.3255), Hansen & Ghrist 2019, Robinson 2020.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 from __future__ import annotations
 

package/src/superlocalmemory/math/turbo_quant.py

@@ -9,7 +9,7 @@ D_mse <= sqrt(3*pi/2) / 4^b. No scipy (HR-SCIPY-01). 2-byte "TQ" prefix on
 all BLOBs (HR-MIG-02). Bit-widths: 2, 4, 8 only (HR-3BIT-01).
 
 References: TurboQuant (arXiv 2504.19874), PolarQuant (arXiv 2502.02617).
-Part of Qualixar | Author: Varun Pratap Bhardwaj | License: Elastic-2.0
+Part of Qualixar | Author: Varun Pratap Bhardwaj | License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -24,6 +24,7 @@ import numpy as np
 from numpy.typing import NDArray
 
 from superlocalmemory.core.config import PolarQuantConfig
+from superlocalmemory.infra.data_root import canonical_data_root
 
 logger = logging.getLogger(__name__)
 
@@ -173,7 +174,7 @@ class TurboQuantEncoder:
     def _load_or_create_rotation_matrix(self) -> NDArray:
         """Load/create rotation matrix with copy-on-detect (AUDIT C4-MED-01)."""
         d = self._d
-        slm_dir = Path.home() / ".superlocalmemory"
+        slm_dir = canonical_data_root()
 
         turbo_path_str = self._config.rotation_matrix_path
         if not turbo_path_str:

package/src/superlocalmemory/mcp/_daemon_proxy.py

@@ -79,25 +79,26 @@ class DaemonPoolProxy:
     def store(
         self, content: str, metadata: dict | None = None,
     ) -> dict[str, Any]:
-        body = json.dumps({
+        body = {
             "content": content,
             "tags": (metadata or {}).get("tags", ""),
             "metadata": metadata or {},
-        }).encode()
-        req = urllib.request.Request(
-            self._url("/remember"),
-            data=body,
-            headers={"Content-Type": "application/json"},
-            method="POST",
-        )
+            "session_id": (metadata or {}).get("session_id", ""),
+            "idempotency_key": (metadata or {}).get("idempotency_key") or None,
+        }
         try:
-            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
-                data = json.loads(resp.read().decode() or "{}")
+            # One identity-aware daemon client owns descriptor validation,
+            # capability delivery, and exact-instance targeting.  A raw urllib
+            # POST here previously became unauthenticated when /remember was
+            # hardened and could also attach to a stale/foreign port.
+            from superlocalmemory.cli.daemon import daemon_request
+
+            data = daemon_request("POST", "/remember", body)
         except Exception as exc:
             logger.warning("daemon /remember failed: %s", exc)
             return {"ok": False, "error": str(exc)}
         if not isinstance(data, dict):
-            return {"ok": False, "error": "non-dict response"}
+            return {"ok": False, "error": "owned daemon unavailable"}
         data.setdefault("ok", True)
         return data