superlocalmemory 2.8.5 → 3.0.0

package/src/superlocalmemory/encoding/type_router.py

@@ -0,0 +1,235 @@
+# 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 — Typed Memory Router.
+
+Routes extracted facts to appropriate typed stores (ENGRAM pattern).
+Typed separation gave +31 points on LoCoMo benchmark.
+
+Mode A: all-MiniLM similarity against type templates.
+Mode B/C: LLM classifies fact type.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING
+
+from superlocalmemory.storage.models import AtomicFact, FactType, Mode
+
+if TYPE_CHECKING:
+    from superlocalmemory.core.embeddings import EmbeddingService
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Type templates for Mode A (all-MiniLM classification)
+# ---------------------------------------------------------------------------
+
+_EPISODIC_TEMPLATES = [
+    "someone did something at a place",
+    "a person went somewhere or performed an action",
+    "an event happened on a specific date",
+    "someone traveled to a location",
+    "a meeting or gathering occurred",
+]
+
+_SEMANTIC_TEMPLATES = [
+    "a person is a specific profession or role",
+    "something is a fact about the world",
+    "a place is located somewhere",
+    "an organization does something",
+    "a general knowledge statement",
+]
+
+_OPINION_TEMPLATES = [
+    "someone thinks or believes something",
+    "a person likes or dislikes something",
+    "someone prefers one thing over another",
+    "a subjective judgment or evaluation",
+    "an emotional reaction to something",
+]
+
+_TEMPORAL_TEMPLATES = [
+    "something will happen on a future date",
+    "an event is scheduled or planned",
+    "a deadline or due date for something",
+    "something started or will end at a time",
+    "a recurring event or appointment",
+]
+
+# ---------------------------------------------------------------------------
+# Keyword patterns for Mode A fallback
+# ---------------------------------------------------------------------------
+
+_OPINION_MARKERS = re.compile(
+    r"\b(think|believe|feel|prefer|like|love|hate|dislike|enjoy|"
+    r"opinion|seems?|probably|maybe|might|could be|i guess|"
+    r"personally|in my view|i'd say)\b",
+    re.IGNORECASE,
+)
+
+_TEMPORAL_MARKERS = re.compile(
+    r"\b(scheduled|deadline|appointment|planned|tomorrow|"
+    r"next week|next month|upcoming|due date|starts?|ends?|"
+    r"will happen|going to|plan to)\b",
+    re.IGNORECASE,
+)
+
+_EPISODIC_MARKERS = re.compile(
+    r"\b(went|visited|traveled|attended|met|saw|did|"
+    r"happened|occurred|took place|experienced)\b",
+    re.IGNORECASE,
+)
+
+
+class TypeRouter:
+    """Route facts to typed stores based on content classification.
+
+    Uses embedding similarity (Mode A) or LLM (Mode B/C) to classify
+    each fact as episodic, semantic, opinion, or temporal.
+    """
+
+    def __init__(
+        self,
+        mode: Mode = Mode.A,
+        embedder: EmbeddingService | None = None,
+        llm: object | None = None,
+    ) -> None:
+        self._mode = mode
+        self._embedder = embedder
+        self._llm = llm
+        self._template_embeddings: dict[FactType, list[list[float]]] | None = None
+
+    def classify(self, fact: AtomicFact) -> FactType:
+        """Classify a fact into a typed store category."""
+        if self._mode in (Mode.B, Mode.C) and self._llm is not None:
+            return self._classify_llm(fact)
+        if self._embedder is not None:
+            return self._classify_embedding(fact)
+        return self._classify_keywords(fact)
+
+    def route_facts(self, facts: list[AtomicFact]) -> list[AtomicFact]:
+        """Classify and update fact_type for a batch of facts."""
+        result = []
+        for fact in facts:
+            classified_type = self.classify(fact)
+            # Create new fact with updated type (immutability pattern)
+            updated = AtomicFact(
+                fact_id=fact.fact_id,
+                memory_id=fact.memory_id,
+                profile_id=fact.profile_id,
+                content=fact.content,
+                fact_type=classified_type,
+                entities=fact.entities,
+                canonical_entities=fact.canonical_entities,
+                observation_date=fact.observation_date,
+                referenced_date=fact.referenced_date,
+                interval_start=fact.interval_start,
+                interval_end=fact.interval_end,
+                confidence=fact.confidence,
+                importance=fact.importance,
+                evidence_count=fact.evidence_count,
+                source_turn_ids=fact.source_turn_ids,
+                session_id=fact.session_id,
+                embedding=fact.embedding,
+                fisher_mean=fact.fisher_mean,
+                fisher_variance=fact.fisher_variance,
+                emotional_valence=fact.emotional_valence,
+                emotional_arousal=fact.emotional_arousal,
+                signal_type=fact.signal_type,
+                created_at=fact.created_at,
+            )
+            result.append(updated)
+        return result
+
+    # -- Classification strategies -----------------------------------------
+
+    def _classify_keywords(self, fact: AtomicFact) -> FactType:
+        """Keyword-based classification (fastest, lowest quality)."""
+        text = fact.content
+
+        if _OPINION_MARKERS.search(text):
+            return FactType.OPINION
+        if _TEMPORAL_MARKERS.search(text):
+            return FactType.TEMPORAL
+        if _EPISODIC_MARKERS.search(text):
+            return FactType.EPISODIC
+        return FactType.SEMANTIC
+
+    def _classify_embedding(self, fact: AtomicFact) -> FactType:
+        """Embedding similarity against type templates (Mode A)."""
+        if self._embedder is None:
+            return self._classify_keywords(fact)
+
+        if self._template_embeddings is None:
+            self._build_template_embeddings()
+
+        assert self._template_embeddings is not None
+        fact_emb = self._embedder.embed(fact.content)
+
+        best_type = FactType.SEMANTIC
+        best_score = -1.0
+
+        for ftype, template_embs in self._template_embeddings.items():
+            avg_sim = sum(
+                _cosine(fact_emb, t) for t in template_embs
+            ) / max(len(template_embs), 1)
+            if avg_sim > best_score:
+                best_score = avg_sim
+                best_type = ftype
+
+        return best_type
+
+    def _classify_llm(self, fact: AtomicFact) -> FactType:
+        """LLM-based classification (Mode B/C, highest quality)."""
+        if self._llm is None:
+            return self._classify_embedding(fact)
+
+        prompt = (
+            f"Classify this fact into exactly one category.\n"
+            f"Fact: \"{fact.content}\"\n"
+            f"Categories:\n"
+            f"- episodic: An event that happened (who did what when)\n"
+            f"- semantic: A general fact about the world (X is Y)\n"
+            f"- opinion: A subjective belief or preference\n"
+            f"- temporal: A scheduled/planned future event\n"
+            f"Reply with ONLY the category name (one word)."
+        )
+        try:
+            response = self._llm.generate(prompt).strip().lower()
+            type_map = {
+                "episodic": FactType.EPISODIC,
+                "semantic": FactType.SEMANTIC,
+                "opinion": FactType.OPINION,
+                "temporal": FactType.TEMPORAL,
+            }
+            return type_map.get(response, FactType.SEMANTIC)
+        except Exception:
+            logger.warning("LLM classification failed, falling back to keywords")
+            return self._classify_keywords(fact)
+
+    def _build_template_embeddings(self) -> None:
+        """Pre-compute embeddings for type templates."""
+        if self._embedder is None:
+            return
+        self._template_embeddings = {
+            FactType.EPISODIC: self._embedder.embed_batch(_EPISODIC_TEMPLATES),
+            FactType.SEMANTIC: self._embedder.embed_batch(_SEMANTIC_TEMPLATES),
+            FactType.OPINION: self._embedder.embed_batch(_OPINION_TEMPLATES),
+            FactType.TEMPORAL: self._embedder.embed_batch(_TEMPORAL_TEMPLATES),
+        }
+
+
+def _cosine(a: list[float], b: list[float]) -> float:
+    """Cosine similarity between two vectors."""
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = sum(x * x for x in a) ** 0.5
+    norm_b = sum(x * x for x in b) ** 0.5
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    return dot / (norm_a * norm_b)

package/src/superlocalmemory/hooks/__init__.py

@@ -0,0 +1,3 @@
+# 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

package/src/superlocalmemory/hooks/auto_capture.py

@@ -0,0 +1,111 @@
+# 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
+
+"""Auto-capture — detect and store important information automatically."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Patterns that indicate capture-worthy content
+_DECISION_PATTERNS = [
+    r"(?i)\b(decided|chose|picked|selected|went with|using|switched to)\b",
+    r"(?i)\b(because|reason|rationale|due to|since)\b.*\b(chose|use|prefer)\b",
+]
+
+_BUG_PATTERNS = [
+    r"(?i)\b(fixed|resolved|solved|root cause|bug|issue|error)\b",
+    r"(?i)\b(the (?:fix|solution|problem) (?:was|is))\b",
+]
+
+_PREFERENCE_PATTERNS = [
+    r"(?i)\b(prefer|always use|never use|I like|I hate|don't like)\b",
+    r"(?i)\b(convention|standard|style|pattern)\b.*\b(is|should be|must be)\b",
+]
+
+
+@dataclass(frozen=True)
+class CaptureDecision:
+    """Result of evaluating content for auto-capture."""
+
+    capture: bool
+    confidence: float
+    category: str  # "decision", "bug", "preference", "session_summary", "none"
+    reason: str
+
+
+class AutoCapture:
+    """Detect and classify content for automatic storage."""
+
+    def __init__(self, engine=None, config: dict | None = None):
+        self._engine = engine
+        self._config = config or {}
+        self._enabled = self._config.get("enabled", True)
+        self._min_confidence = self._config.get("min_confidence", 0.5)
+        self._capture_decisions = self._config.get("capture_decisions", True)
+        self._capture_bugs = self._config.get("capture_bugs", True)
+        self._capture_preferences = self._config.get("capture_preferences", True)
+
+    def evaluate(self, content: str) -> CaptureDecision:
+        """Evaluate whether content should be auto-captured.
+
+        Returns a CaptureDecision with capture=True/False,
+        confidence score, and category.
+        """
+        if not self._enabled:
+            return CaptureDecision(False, 0.0, "none", "auto-capture disabled")
+
+        if len(content.strip()) < 20:
+            return CaptureDecision(False, 0.0, "none", "content too short")
+
+        # Check for decisions
+        if self._capture_decisions:
+            score = self._match_patterns(content, _DECISION_PATTERNS)
+            if score >= self._min_confidence:
+                return CaptureDecision(True, score, "decision", "decision pattern detected")
+
+        # Check for bug fixes
+        if self._capture_bugs:
+            score = self._match_patterns(content, _BUG_PATTERNS)
+            if score >= self._min_confidence:
+                return CaptureDecision(True, score, "bug", "bug fix pattern detected")
+
+        # Check for preferences
+        if self._capture_preferences:
+            score = self._match_patterns(content, _PREFERENCE_PATTERNS)
+            if score >= self._min_confidence:
+                return CaptureDecision(True, score, "preference", "preference pattern detected")
+
+        return CaptureDecision(False, 0.0, "none", "no patterns matched")
+
+    def capture(self, content: str, category: str = "", metadata: dict | None = None) -> bool:
+        """Store content via engine if auto-capture decides to."""
+        if not self._engine:
+            return False
+
+        try:
+            meta = metadata or {}
+            meta["source"] = "auto-capture"
+            meta["category"] = category
+            fact_ids = self._engine.store(content, metadata=meta)
+            return len(fact_ids) > 0
+        except Exception as exc:
+            logger.debug("Auto-capture store failed: %s", exc)
+            return False
+
+    def _match_patterns(self, content: str, patterns: list[str]) -> float:
+        """Match content against regex patterns. Returns confidence 0.0-1.0."""
+        matches = sum(1 for p in patterns if re.search(p, content))
+        if matches == 0:
+            return 0.0
+        return min(1.0, 0.5 + (matches * 0.25))
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled

package/src/superlocalmemory/hooks/auto_recall.py

@@ -0,0 +1,93 @@
+# 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
+
+"""Auto-recall — inject relevant memories into AI context automatically."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class AutoRecall:
+    """Automatically recalls relevant context for AI sessions.
+
+    Called at session start or before each prompt to inject
+    relevant memories without user intervention.
+    """
+
+    def __init__(self, engine=None, config: dict | None = None):
+        self._engine = engine
+        self._config = config or {}
+        self._enabled = self._config.get("enabled", True)
+        self._max_memories = self._config.get("max_memories_injected", 10)
+        self._threshold = self._config.get("relevance_threshold", 0.3)
+
+    def get_session_context(self, project_path: str = "", query: str = "") -> str:
+        """Get relevant context for a session or query.
+
+        Returns a formatted string of relevant memories suitable
+        for injection into an AI's system prompt.
+        """
+        if not self._enabled or not self._engine:
+            return ""
+
+        try:
+            # Build query from project path or explicit query
+            search_query = query or f"project context {project_path}"
+            response = self._engine.recall(search_query, limit=self._max_memories)
+
+            if not response.results:
+                return ""
+
+            # Filter by relevance threshold
+            relevant = [r for r in response.results if r.score >= self._threshold]
+
+            if not relevant:
+                return ""
+
+            # Format for injection
+            lines = ["# Relevant Memory Context", ""]
+            for r in relevant[:self._max_memories]:
+                lines.append(f"- {r.fact.content[:200]}")
+
+            return "\n".join(lines)
+        except Exception as exc:
+            logger.debug("Auto-recall failed: %s", exc)
+            return ""
+
+    def get_query_context(self, query: str) -> list[dict]:
+        """Get relevant memories for a specific query.
+
+        Returns structured data (not formatted string) for MCP tools.
+        """
+        if not self._enabled or not self._engine:
+            return []
+
+        try:
+            response = self._engine.recall(query, limit=self._max_memories)
+            results = []
+            for r in response.results:
+                if r.score >= self._threshold:
+                    results.append({
+                        "fact_id": r.fact.fact_id,
+                        "content": r.fact.content[:300],
+                        "score": round(r.score, 3),
+                    })
+            return results
+        except Exception as exc:
+            logger.debug("Auto-recall query failed: %s", exc)
+            return []
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    def enable(self) -> None:
+        self._enabled = True
+
+    def disable(self) -> None:
+        self._enabled = False

package/src/superlocalmemory/hooks/ide_connector.py

@@ -0,0 +1,204 @@
+# 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
+
+"""IDE connector — detect installed IDEs and generate SLM integration configs.
+
+Supports: Claude Code, Cursor, VS Code/Copilot, Windsurf, Gemini CLI,
+JetBrains IDEs, Continue.dev, Zed, Aider.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# SLM marker to detect our config sections (for idempotency)
+SLM_MARKER = "## SuperLocalMemory"
+SLM_MARKER_START = "<!-- SLM-START -->"
+SLM_MARKER_END = "<!-- SLM-END -->"
+
+# Known IDE config paths (relative to home directory)
+IDE_CONFIGS: dict[str, dict[str, Any]] = {
+    "claude_code": {
+        "name": "Claude Code",
+        "detect_paths": [".claude"],
+        "config_files": [".claude/CLAUDE.md"],
+        "type": "markdown_append",
+    },
+    "cursor": {
+        "name": "Cursor",
+        "detect_paths": [".cursor"],
+        "config_files": [".cursorrules"],
+        "type": "markdown_append",
+    },
+    "vscode": {
+        "name": "VS Code / Copilot",
+        "detect_paths": [".vscode", "Library/Application Support/Code"],
+        "config_files": [".github/copilot-instructions.md"],
+        "type": "markdown_append",
+    },
+    "windsurf": {
+        "name": "Windsurf",
+        "detect_paths": [".codeium/windsurf"],
+        "config_files": [".windsurfrules"],
+        "type": "markdown_append",
+    },
+    "gemini": {
+        "name": "Gemini CLI",
+        "detect_paths": [".gemini"],
+        "config_files": ["GEMINI.md"],
+        "type": "markdown_append",
+    },
+    "continue_dev": {
+        "name": "Continue.dev",
+        "detect_paths": [".continue"],
+        "config_files": [".continue/config.json"],
+        "type": "json_merge",
+    },
+    "zed": {
+        "name": "Zed Editor",
+        "detect_paths": [".config/zed"],
+        "config_files": [".config/zed/settings.json"],
+        "type": "json_merge",
+    },
+}
+
+# Template for markdown-based IDE rules
+MARKDOWN_TEMPLATE = """
+{marker_start}
+{marker}
+- Before responding to questions, check SuperLocalMemory for relevant context using the `recall` tool
+- After making decisions, fixing bugs, or learning preferences, store them using the `remember` tool
+- On session start, load project context from SuperLocalMemory
+- Available tools: remember, recall, search, fetch, get_status, set_mode, health
+- Documentation: https://superlocalmemory.com
+{marker_end}
+"""
+
+
+class IDEConnector:
+    """Detect installed IDEs and generate SLM integration configs."""
+
+    def __init__(self, home: Path | None = None) -> None:
+        self._home = home or Path.home()
+
+    def detect_ides(self) -> dict[str, bool]:
+        """Detect which IDEs are installed.
+
+        Returns a dict mapping IDE id to whether it was detected.
+        """
+        result: dict[str, bool] = {}
+        for ide_id, config in IDE_CONFIGS.items():
+            detected = any(
+                (self._home / p).exists() for p in config["detect_paths"]
+            )
+            result[ide_id] = detected
+        return result
+
+    def connect(self, ide_id: str) -> bool:
+        """Configure a specific IDE for SLM integration.
+
+        Returns True if configuration was written successfully.
+        Idempotent — safe to run multiple times.
+        Does NOT overwrite existing user rules.
+        """
+        if ide_id not in IDE_CONFIGS:
+            logger.warning("Unknown IDE: %s", ide_id)
+            return False
+
+        config = IDE_CONFIGS[ide_id]
+        config_type = config["type"]
+
+        for config_file in config["config_files"]:
+            path = self._home / config_file
+
+            if config_type == "markdown_append":
+                return self._append_markdown(path)
+            elif config_type == "json_merge":
+                return self._merge_json(path)
+
+        return False
+
+    def connect_all(self) -> dict[str, str]:
+        """Detect and configure all installed IDEs.
+
+        Returns dict of {ide_id: status} where status is
+        "connected", "not_installed", or "error".
+        """
+        detected = self.detect_ides()
+        results: dict[str, str] = {}
+
+        for ide_id, is_installed in detected.items():
+            if not is_installed:
+                results[ide_id] = "not_installed"
+                continue
+            try:
+                success = self.connect(ide_id)
+                results[ide_id] = "connected" if success else "error"
+            except Exception as exc:
+                logger.debug("Failed to connect %s: %s", ide_id, exc)
+                results[ide_id] = "error"
+
+        return results
+
+    def get_status(self) -> list[dict[str, Any]]:
+        """Get connection status for all known IDEs."""
+        detected = self.detect_ides()
+        status: list[dict[str, Any]] = []
+        for ide_id, config in IDE_CONFIGS.items():
+            status.append({
+                "id": ide_id,
+                "name": config["name"],
+                "installed": detected.get(ide_id, False),
+                "config_path": str(self._home / config["config_files"][0]),
+            })
+        return status
+
+    def _append_markdown(self, path: Path) -> bool:
+        """Append SLM section to a markdown file. Idempotent."""
+        content = ""
+        if path.exists():
+            content = path.read_text()
+
+        # Check if already configured (idempotent)
+        if SLM_MARKER in content:
+            return True
+
+        # Append SLM section
+        section = MARKDOWN_TEMPLATE.format(
+            marker=SLM_MARKER,
+            marker_start=SLM_MARKER_START,
+            marker_end=SLM_MARKER_END,
+        )
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content + "\n" + section)
+        return True
+
+    def _merge_json(self, path: Path) -> bool:
+        """Merge SLM config into a JSON config file."""
+        data: dict[str, Any] = {}
+        if path.exists():
+            try:
+                data = json.loads(path.read_text())
+            except json.JSONDecodeError:
+                data = {}
+
+        # Add MCP server config
+        if "mcpServers" not in data:
+            data["mcpServers"] = {}
+
+        data["mcpServers"]["superlocalmemory"] = {
+            "command": "python3",
+            "args": ["-m", "superlocalmemory.mcp.server"],
+            "enabled": True,
+        }
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, indent=2))
+        return True