superlocalmemory 2.8.5 → 3.0.0

package/src/superlocalmemory/mcp/tools_v28.py

@@ -0,0 +1,223 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3 — V2.8 Ported MCP Tools (6 tools).
+
+report_outcome, get_lifecycle_status, set_retention_policy,
+compact_memories, get_behavioral_patterns, audit_trail.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+
+def register_v28_tools(server, get_engine: Callable) -> None:
+    """Register 6 V2.8-ported tools on *server*."""
+
+    # ------------------------------------------------------------------
+    # 1. report_outcome
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def report_outcome(
+        memory_ids: str,
+        outcome: str,
+        context: str = "",
+    ) -> dict:
+        """Report outcome of using recalled memories.
+
+        Feeds into the adaptive learning loop to improve future retrieval.
+        Valid outcomes: success, failure, partial.
+
+        Args:
+            memory_ids: Comma-separated list of fact/memory IDs.
+            outcome: One of 'success', 'failure', 'partial'.
+            context: Optional freetext context about the outcome.
+        """
+        try:
+            engine = get_engine()
+            from superlocalmemory.learning.outcomes import OutcomeTracker
+            tracker = OutcomeTracker(engine._db)
+            ids = [mid.strip() for mid in memory_ids.split(",") if mid.strip()]
+            ctx = {"note": context} if context else None
+            ao = tracker.record_outcome(
+                query="[mcp_feedback]",
+                fact_ids=ids,
+                outcome=outcome,
+                profile_id=engine.profile_id,
+                context=ctx,
+            )
+            return {"success": True, "outcome_id": ao.outcome_id, "outcome": outcome}
+        except Exception as exc:
+            logger.exception("report_outcome failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 2. get_lifecycle_status
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def get_lifecycle_status(limit: int = 50) -> dict:
+        """Get lifecycle state distribution for stored memories.
+
+        Shows counts per lifecycle state (active, warm, cold, archived)
+        and the most recent facts in each state.
+
+        Args:
+            limit: Maximum facts to inspect (default 50).
+        """
+        try:
+            engine = get_engine()
+            pid = engine.profile_id
+            facts = engine._db.get_all_facts(pid)[:limit]
+            states: dict[str, list[dict]] = {
+                "active": [], "warm": [], "cold": [], "archived": [],
+            }
+            for f in facts:
+                state = f.lifecycle.value
+                if state in states and len(states[state]) < 10:
+                    states[state].append({
+                        "fact_id": f.fact_id,
+                        "content": f.content[:80],
+                        "access_count": f.access_count,
+                        "created_at": f.created_at,
+                    })
+            counts = {k: len(v) for k, v in states.items()}
+            return {"success": True, "counts": counts, "samples": states}
+        except Exception as exc:
+            logger.exception("get_lifecycle_status failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 3. set_retention_policy
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def set_retention_policy(
+        cold_after_days: int = 30,
+        archive_after_days: int = 90,
+    ) -> dict:
+        """Set memory retention policy thresholds.
+
+        Controls when memories transition from active to warm, cold,
+        and archived states. Coupled with Langevin dynamics when available.
+
+        Args:
+            cold_after_days: Days of inactivity before cold state (default 30).
+            archive_after_days: Days before archival (default 90).
+        """
+        try:
+            engine = get_engine()
+            engine._db.set_config("retention_cold_days", str(cold_after_days))
+            engine._db.set_config("retention_archive_days", str(archive_after_days))
+            return {
+                "success": True,
+                "cold_after_days": cold_after_days,
+                "archive_after_days": archive_after_days,
+            }
+        except Exception as exc:
+            logger.exception("set_retention_policy failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 4. compact_memories
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def compact_memories(dry_run: bool = True) -> dict:
+        """Compact memory store by archiving cold/stale facts.
+
+        Transitions eligible memories from cold to archived state.
+        Run with dry_run=True first to preview changes.
+
+        Args:
+            dry_run: If True, only preview without making changes (default True).
+        """
+        try:
+            engine = get_engine()
+            pid = engine.profile_id
+            from superlocalmemory.compliance.lifecycle import LifecycleManager
+            mgr = LifecycleManager(engine._db)
+            facts = engine._db.get_all_facts(pid)
+            candidates = []
+            for f in facts:
+                new_state = mgr.get_lifecycle_state(f)
+                if new_state != f.lifecycle:
+                    candidates.append({
+                        "fact_id": f.fact_id,
+                        "current": f.lifecycle.value,
+                        "proposed": new_state.value,
+                    })
+            if not dry_run:
+                for c in candidates:
+                    engine._db.update_fact(
+                        c["fact_id"], {"lifecycle": c["proposed"]},
+                    )
+            return {
+                "success": True,
+                "dry_run": dry_run,
+                "candidates": len(candidates),
+                "transitions": candidates[:20],
+            }
+        except Exception as exc:
+            logger.exception("compact_memories failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 5. get_behavioral_patterns
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def get_behavioral_patterns(limit: int = 20) -> dict:
+        """Get detected behavioral patterns for the active profile.
+
+        Returns patterns such as topic interests, refinement habits,
+        and time-of-day usage with confidence scores.
+
+        Args:
+            limit: Maximum patterns to return (default 20).
+        """
+        try:
+            engine = get_engine()
+            from superlocalmemory.learning.behavioral import BehavioralStore
+            store = BehavioralStore(engine._db.db_path)
+            patterns = store.get_patterns(engine.profile_id, limit=limit)
+            summary = store.get_summary(engine.profile_id)
+            return {
+                "success": True,
+                "patterns": patterns,
+                "summary": summary,
+                "count": len(patterns),
+            }
+        except Exception as exc:
+            logger.exception("get_behavioral_patterns failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 6. audit_trail
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def audit_trail(limit: int = 50) -> dict:
+        """Get compliance audit trail for the active profile.
+
+        Returns logged operations (store, retrieve, delete, export)
+        for GDPR and EU AI Act compliance reporting.
+
+        Args:
+            limit: Maximum audit entries to return (default 50).
+        """
+        try:
+            engine = get_engine()
+            from superlocalmemory.compliance.gdpr import GDPRCompliance
+            gdpr = GDPRCompliance(engine._db)
+            entries = gdpr.get_audit_trail(engine.profile_id, limit=limit)
+            return {
+                "success": True,
+                "entries": entries,
+                "count": len(entries),
+            }
+        except Exception as exc:
+            logger.exception("audit_trail failed")
+            return {"success": False, "error": str(exc)}

package/src/superlocalmemory/mcp/tools_v3.py

@@ -0,0 +1,286 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SuperLocalMemory V3 — V3-Only MCP Tools (5 tools).
+
+set_mode, get_mode, health, consistency_check, recall_trace.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+
+def register_v3_tools(server, get_engine: Callable) -> None:
+    """Register 5 V3-exclusive tools on *server*."""
+
+    # ------------------------------------------------------------------
+    # 1. set_mode
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def set_mode(mode: str) -> dict:
+        """Switch operating mode (a, b, or c).
+
+        Mode A: Local Guardian (zero LLM, EU AI Act full compliance).
+        Mode B: Smart Local (local Ollama LLM, EU AI Act full).
+        Mode C: Full Power (cloud LLM, best accuracy).
+
+        Resets the engine to apply the new mode configuration.
+
+        Args:
+            mode: Target mode - 'a', 'b', or 'c'.
+        """
+        try:
+            mode_lower = mode.strip().lower()
+            if mode_lower not in ("a", "b", "c"):
+                return {
+                    "success": False,
+                    "error": f"Invalid mode '{mode}'. Use 'a', 'b', or 'c'.",
+                }
+            from superlocalmemory.core.config import SLMConfig
+            from superlocalmemory.storage.models import Mode
+            from superlocalmemory.mcp.server import reset_engine
+
+            mode_enum = Mode(mode_lower)
+            config = SLMConfig.for_mode(mode_enum)
+            config.save()
+            reset_engine()
+
+            return {
+                "success": True,
+                "mode": mode_lower,
+                "description": _mode_description(mode_lower),
+            }
+        except Exception as exc:
+            logger.exception("set_mode failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 2. get_mode
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def get_mode() -> dict:
+        """Get current operating mode and its capabilities.
+
+        Returns mode identifier, description, and feature flags
+        (LLM availability, cross-encoder, agentic retrieval).
+        """
+        try:
+            engine = get_engine()
+            m = engine._config.mode.value
+            caps = {
+                "llm_available": engine._llm is not None,
+                "cross_encoder": engine._config.retrieval.use_cross_encoder,
+                "agentic_rounds": engine._config.retrieval.agentic_max_rounds,
+                "sheaf_at_encoding": engine._config.math.sheaf_at_encoding,
+            }
+            return {
+                "success": True,
+                "mode": m,
+                "description": _mode_description(m),
+                "capabilities": caps,
+            }
+        except Exception as exc:
+            logger.exception("get_mode failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 3. health
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def health() -> dict:
+        """Get system health including math layer status.
+
+        Reports on Fisher-Rao, Sheaf consistency, and Langevin dynamics
+        health. Also includes database integrity and component status.
+        """
+        try:
+            engine = get_engine()
+            pid = engine.profile_id
+
+            status: dict = {
+                "success": True,
+                "mode": engine._config.mode.value,
+                "profile": pid,
+                "components": {},
+            }
+
+            # Database health
+            fact_count = engine._db.get_fact_count(pid)
+            status["components"]["database"] = {
+                "status": "ok",
+                "fact_count": fact_count,
+            }
+
+            # Embedding service
+            status["components"]["embedder"] = {
+                "status": "ok" if engine._embedder else "unavailable",
+                "model": engine._config.embedding.model_name,
+            }
+
+            # LLM
+            status["components"]["llm"] = {
+                "status": "ok" if engine._llm else "disabled",
+                "provider": engine._config.llm.provider or "none",
+            }
+
+            # Fisher-Rao (math layer 1)
+            fisher_facts = 0
+            if fact_count > 0:
+                rows = engine._db.execute(
+                    "SELECT COUNT(*) AS c FROM atomic_facts "
+                    "WHERE profile_id = ? AND fisher_mean IS NOT NULL",
+                    (pid,),
+                )
+                fisher_facts = int(dict(rows[0])["c"]) if rows else 0
+            status["components"]["fisher_rao"] = {
+                "status": "ok" if fisher_facts > 0 else "no_data",
+                "indexed_facts": fisher_facts,
+                "temperature": engine._config.math.fisher_temperature,
+            }
+
+            # Sheaf consistency (math layer 2)
+            status["components"]["sheaf"] = {
+                "status": "active" if engine._sheaf_checker else "disabled",
+                "threshold": engine._config.math.sheaf_contradiction_threshold,
+            }
+
+            # Langevin dynamics (math layer 3)
+            langevin_facts = 0
+            if fact_count > 0:
+                rows = engine._db.execute(
+                    "SELECT COUNT(*) AS c FROM atomic_facts "
+                    "WHERE profile_id = ? AND langevin_position IS NOT NULL",
+                    (pid,),
+                )
+                langevin_facts = int(dict(rows[0])["c"]) if rows else 0
+            status["components"]["langevin"] = {
+                "status": "ok" if langevin_facts > 0 else "no_data",
+                "positioned_facts": langevin_facts,
+            }
+
+            return status
+        except Exception as exc:
+            logger.exception("health failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 4. consistency_check
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def consistency_check(limit: int = 100) -> dict:
+        """Run sheaf consistency check on stored memories.
+
+        Detects contradictions between facts using algebraic topology
+        (sheaf cohomology). Returns pairs of contradicting facts with
+        severity scores.
+
+        Args:
+            limit: Maximum facts to check (default 100).
+        """
+        try:
+            engine = get_engine()
+            pid = engine.profile_id
+
+            if not engine._sheaf_checker:
+                return {
+                    "success": True,
+                    "contradictions": [],
+                    "note": "Sheaf checker is disabled in current configuration.",
+                }
+
+            facts = engine._db.get_all_facts(pid)[:limit]
+            all_contradictions: list[dict] = []
+            for fact in facts:
+                if not fact.embedding or not fact.canonical_entities:
+                    continue
+                try:
+                    contradictions = engine._sheaf_checker.check_consistency(
+                        fact, pid,
+                    )
+                    for c in contradictions:
+                        all_contradictions.append({
+                            "fact_a": fact.fact_id,
+                            "fact_b": c.fact_id_b,
+                            "severity": round(c.severity, 3),
+                            "content_a": fact.content[:80],
+                        })
+                except Exception:
+                    continue
+
+            return {
+                "success": True,
+                "facts_checked": len(facts),
+                "contradictions": all_contradictions[:50],
+                "total_contradictions": len(all_contradictions),
+            }
+        except Exception as exc:
+            logger.exception("consistency_check failed")
+            return {"success": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # 5. recall_trace
+    # ------------------------------------------------------------------
+    @server.tool()
+    async def recall_trace(query: str, limit: int = 10) -> dict:
+        """Recall with per-channel score breakdown.
+
+        Like recall, but returns detailed channel-by-channel scores
+        for debugging retrieval quality.
+
+        Args:
+            query: Natural-language search query.
+            limit: Maximum results (default 10).
+        """
+        try:
+            engine = get_engine()
+            response = engine.recall(query, limit=limit)
+            results = []
+            for r in response.results[:limit]:
+                results.append({
+                    "fact_id": r.fact.fact_id,
+                    "content": r.fact.content,
+                    "final_score": round(r.score, 4),
+                    "confidence": round(r.confidence, 3),
+                    "trust_score": round(r.trust_score, 3),
+                    "channel_scores": {
+                        k: round(v, 4) for k, v in r.channel_scores.items()
+                    },
+                    "evidence_chain": r.evidence_chain,
+                    "fact_type": r.fact.fact_type.value,
+                    "lifecycle": r.fact.lifecycle.value,
+                    "access_count": r.fact.access_count,
+                })
+            return {
+                "success": True,
+                "results": results,
+                "count": len(results),
+                "query_type": response.query_type,
+                "channel_weights": {
+                    k: round(v, 3)
+                    for k, v in response.channel_weights.items()
+                },
+                "total_candidates": response.total_candidates,
+                "retrieval_time_ms": round(response.retrieval_time_ms, 1),
+            }
+        except Exception as exc:
+            logger.exception("recall_trace failed")
+            return {"success": False, "error": str(exc)}
+
+
+# -- Helpers ------------------------------------------------------------------
+
+def _mode_description(mode: str) -> str:
+    """Human-readable description for a mode."""
+    descriptions = {
+        "a": "Local Guardian: zero LLM, full EU AI Act compliance",
+        "b": "Smart Local: local Ollama LLM, full EU AI Act compliance",
+        "c": "Full Power: cloud LLM, best accuracy, partial EU AI Act",
+    }
+    return descriptions.get(mode, "Unknown mode")