superlocalmemory 2.8.5 → 3.0.0

package/scripts/verify-install.sh

@@ -0,0 +1,266 @@
+#!/bin/bash
+# ============================================================================
+# SuperLocalMemory - Installation Verification Script
+# Copyright (c) 2026 Varun Pratap Bhardwaj
+# Licensed under MIT License
+# Repository: https://github.com/varun369/SuperLocalMemoryV2
+# ============================================================================
+
+set -e
+
+INSTALL_DIR="${HOME}/.claude-memory"
+
+# Print banner
+echo ""
+echo "╔══════════════════════════════════════════════════════════════╗"
+echo "║  SuperLocalMemory - Installation Verification         ║"
+echo "║  by Varun Pratap Bhardwaj                                    ║"
+echo "╚══════════════════════════════════════════════════════════════╝"
+echo ""
+
+# Track status
+CORE_OK=true
+SEARCH_OK=false
+UI_OK=false
+ERRORS=()
+
+# ============================================================================
+# CORE INSTALLATION CHECK
+# ============================================================================
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "1. Core Installation"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Check Python version
+echo -n "Python 3.8+               "
+PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+PYTHON_MAJOR=$(python3 -c 'import sys; print(sys.version_info.major)')
+PYTHON_MINOR=$(python3 -c 'import sys; print(sys.version_info.minor)')
+
+if [ "$PYTHON_MAJOR" -lt 3 ] || ([ "$PYTHON_MAJOR" -eq 3 ] && [ "$PYTHON_MINOR" -lt 8 ]); then
+    echo "✗ FAIL (found $PYTHON_VERSION)"
+    CORE_OK=false
+    ERRORS+=("Python 3.8+ required")
+else
+    echo "✓ OK (v$PYTHON_VERSION)"
+fi
+
+# Check installation directory
+echo -n "Installation directory    "
+if [ -d "${INSTALL_DIR}" ]; then
+    echo "✓ OK (${INSTALL_DIR})"
+else
+    echo "✗ FAIL (not found)"
+    CORE_OK=false
+    ERRORS+=("Installation directory missing")
+fi
+
+# Check core files
+echo -n "Core scripts              "
+MISSING_FILES=()
+for file in memory_store_v2.py graph_engine.py pattern_learner.py; do
+    if [ ! -f "${INSTALL_DIR}/${file}" ]; then
+        MISSING_FILES+=("${file}")
+    fi
+done
+
+if [ ${#MISSING_FILES[@]} -eq 0 ]; then
+    echo "✓ OK"
+else
+    echo "✗ FAIL (missing: ${MISSING_FILES[*]})"
+    CORE_OK=false
+    ERRORS+=("Core scripts missing")
+fi
+
+# Check CLI wrappers
+echo -n "CLI wrappers              "
+if [ -d "${INSTALL_DIR}/bin" ] && [ -x "${INSTALL_DIR}/bin/slm" ]; then
+    echo "✓ OK"
+else
+    echo "✗ FAIL"
+    CORE_OK=false
+    ERRORS+=("CLI wrappers missing or not executable")
+fi
+
+# Check PATH configuration
+echo -n "PATH configuration        "
+if command -v slm &>/dev/null; then
+    echo "✓ OK (commands globally available)"
+elif grep -q ".claude-memory/bin" "${HOME}/.zshrc" 2>/dev/null || grep -q ".claude-memory/bin" "${HOME}/.bashrc" 2>/dev/null || grep -q ".claude-memory/bin" "${HOME}/.bash_profile" 2>/dev/null; then
+    echo "○ PARTIAL (configured but needs shell restart)"
+else
+    echo "⚠️  WARNING (not in PATH)"
+    ERRORS+=("PATH not configured - run: source ~/.zshrc (or ~/.bashrc)")
+fi
+
+# Check database
+echo -n "Database                  "
+if [ -f "${INSTALL_DIR}/memory.db" ]; then
+    DB_SIZE=$(du -h "${INSTALL_DIR}/memory.db" | cut -f1)
+    echo "✓ OK (${DB_SIZE})"
+else
+    echo "○ NOT CREATED (will be created on first use)"
+fi
+
+# Check config
+echo -n "Configuration             "
+if [ -f "${INSTALL_DIR}/config.json" ]; then
+    echo "✓ OK"
+else
+    echo "⚠️  WARNING (using defaults)"
+fi
+
+echo ""
+
+# ============================================================================
+# OPTIONAL FEATURES CHECK
+# ============================================================================
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "2. Optional Features"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Advanced Search
+echo -n "Advanced Search           "
+if python3 -c "import sentence_transformers; import hnswlib" 2>/dev/null; then
+    echo "✓ ENABLED"
+    SEARCH_OK=true
+else
+    echo "○ DISABLED"
+    echo "  Install: pip3 install -r requirements-search.txt"
+fi
+
+# Web Dashboard
+echo -n "Web Dashboard             "
+if python3 -c "import fastapi; import uvicorn" 2>/dev/null; then
+    echo "✓ ENABLED"
+    UI_OK=true
+    if [ -f "${INSTALL_DIR}/api_server.py" ]; then
+        echo "  Start: python3 ~/.claude-memory/api_server.py"
+        echo "  URL:   http://127.0.0.1:8000"
+    fi
+else
+    echo "○ DISABLED"
+    echo "  Install: pip3 install -r requirements-ui.txt"
+fi
+
+echo ""
+
+# ============================================================================
+# PERFORMANCE QUICK TEST
+# ============================================================================
+
+if $CORE_OK; then
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "3. Performance Quick Test"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+
+    # Test memory store initialization
+    echo -n "Memory store init         "
+    if python3 -c "import sys; sys.path.insert(0, '${INSTALL_DIR}'); from memory_store_v2 import MemoryStoreV2; store = MemoryStoreV2()" 2>/dev/null; then
+        echo "✓ OK"
+    else
+        echo "✗ FAIL"
+        ERRORS+=("Memory store initialization failed")
+    fi
+
+    # Test database query
+    echo -n "Database query            "
+    START_TIME=$(python3 -c "import time; print(time.time())")
+    if python3 -c "import sys; sys.path.insert(0, '${INSTALL_DIR}'); from memory_store_v2 import MemoryStoreV2; store = MemoryStoreV2(); list(store.list_all(limit=1))" 2>/dev/null; then
+        END_TIME=$(python3 -c "import time; print(time.time())")
+        DURATION=$(python3 -c "print(f'{($END_TIME - $START_TIME) * 1000:.0f}ms')" 2>/dev/null || echo "OK")
+        echo "✓ OK ($DURATION)"
+    else
+        echo "✗ FAIL"
+        ERRORS+=("Database query failed")
+    fi
+
+    echo ""
+fi
+
+# ============================================================================
+# SUMMARY
+# ============================================================================
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "4. Summary"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+if $CORE_OK; then
+    echo "✓ Core Installation:      WORKING"
+else
+    echo "✗ Core Installation:      FAILED"
+fi
+
+if $SEARCH_OK; then
+    echo "✓ Advanced Search:        ENABLED"
+else
+    echo "○ Advanced Search:        DISABLED (optional)"
+fi
+
+if $UI_OK; then
+    echo "✓ Web Dashboard:          ENABLED"
+else
+    echo "○ Web Dashboard:          DISABLED (optional)"
+fi
+
+echo ""
+
+# Feature Status
+echo "Feature Status:"
+echo "  • Basic CLI commands:    $(if $CORE_OK; then echo '✓ Available'; else echo '✗ Not available'; fi)"
+echo "  • MCP Server:            $(if $CORE_OK; then echo '✓ Available'; else echo '✗ Not available'; fi)"
+echo "  • Skills:                $(if $CORE_OK; then echo '✓ Available'; else echo '✗ Not available'; fi)"
+echo "  • Semantic Search:       $(if $SEARCH_OK; then echo '✓ Enabled'; else echo '○ Disabled'; fi)"
+echo "  • Web Interface:         $(if $UI_OK; then echo '✓ Enabled'; else echo '○ Disabled'; fi)"
+echo ""
+
+# Errors
+if [ ${#ERRORS[@]} -gt 0 ]; then
+    echo "⚠️  Errors detected:"
+    for error in "${ERRORS[@]}"; do
+        echo "  • $error"
+    done
+    echo ""
+fi
+
+# Next Steps
+echo "Next Steps:"
+echo ""
+
+if $CORE_OK; then
+    echo "  Try it now:"
+    echo "    slm status"
+    echo "    slm remember 'My first memory'"
+    echo "    slm recall 'first'"
+    echo ""
+
+    if ! $SEARCH_OK && ! $UI_OK; then
+        echo "  Install optional features:"
+        echo "    pip3 install -r requirements-search.txt  # Advanced search"
+        echo "    pip3 install -r requirements-ui.txt      # Web dashboard"
+        echo "    pip3 install -r requirements-full.txt    # Everything"
+        echo ""
+    fi
+else
+    echo "  Fix installation issues:"
+    echo "    ./install.sh"
+    echo ""
+fi
+
+# Exit code
+if $CORE_OK; then
+    echo "✓ Installation verification PASSED"
+    echo ""
+    exit 0
+else
+    echo "✗ Installation verification FAILED"
+    echo ""
+    exit 1
+fi

package/src/superlocalmemory/attribution/__init__.py

@@ -0,0 +1,9 @@
+"""Attribution — Multi-layer provenance and ownership protection.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from superlocalmemory.attribution.signer import QualixarSigner
+from superlocalmemory.attribution.watermark import QualixarWatermark
+
+__all__ = ["QualixarSigner", "QualixarWatermark"]

package/src/superlocalmemory/attribution/mathematical_dna.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
+
+"""Self-enforcing inter-layer parameter constraints.
+
+The mathematical layers have parameters that are coupled through
+a constraint derived from a private seed.  If anyone modifies the
+parameters without knowing the constraint, performance degrades.
+
+Constraint: alpha * kappa = C * beta
+Where:
+    alpha = metric scaling parameter
+    kappa  = curvature parameter
+    beta   = inverse temperature
+    C      = derived from private HMAC key
+
+If the constraint is violated:
+    - Similarity calibration drifts
+    - Hierarchical distance fidelity drops
+    - Energy landscape flattens
+    - Overall retrieval quality drops 15-20%
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+
+import numpy as np
+
+# Hopfield inverse temperature (legacy constant, kept for DNA compatibility)
+HOPFIELD_INVERSE_TEMP = 4.0
+
+# Default seed — production should use env var SLM_DNA_SEED
+_DNA_SEED = "qualixar-slm-alpha-dna-v1"
+
+
+class MathematicalDNA:
+    """Self-enforcing parameter constraint system.
+
+    Derives a coupling constant from a private seed and provides
+    utilities to:
+        - Get a parameter set satisfying the constraint.
+        - Verify whether arbitrary parameters satisfy it.
+        - Compute an integrity score (1.0 = perfect).
+        - Embed / detect computation fingerprints at the precision level.
+
+    Args:
+        seed: Override the DNA seed.  If ``None``, falls back to
+              ``SLM_DNA_SEED`` env var, then the built-in default.
+    """
+
+    def __init__(self, seed: str | None = None) -> None:
+        self._seed = seed or os.environ.get("SLM_DNA_SEED", _DNA_SEED)
+        self._constraint_C = self._derive_constraint()
+
+    # ── Constraint derivation ─────────────────────────────────────
+
+    def _derive_constraint(self) -> float:
+        """Derive the inter-layer coupling constant from seed.
+
+        Uses HMAC-SHA256 to produce a deterministic float in [0.5, 2.0].
+
+        Returns:
+            Coupling constant C.
+        """
+        h = hmac.new(
+            self._seed.encode("utf-8"),
+            b"layer-coupling",
+            hashlib.sha256,
+        )
+        hash_int = int(h.hexdigest()[:8], 16)
+        return 0.5 + (hash_int / 0xFFFFFFFF) * 1.5
+
+    # ── Parameter generation ──────────────────────────────────────
+
+    def get_coupled_parameters(self) -> dict[str, float | bool]:
+        """Get a parameter set satisfying the constraint.
+
+        Returns:
+            Dict with ``fisher_alpha``, ``poincare_kappa``,
+            ``hopfield_beta``, ``constraint_C``, and
+            ``constraint_satisfied`` (always ``True``).
+        """
+        beta = HOPFIELD_INVERSE_TEMP
+        target_product = self._constraint_C * beta
+
+        kappa = abs(self._constraint_C)
+        alpha = target_product / kappa if kappa > 1e-10 else 1.0
+
+        return {
+            "fisher_alpha": float(alpha),
+            "poincare_kappa": float(kappa),
+            "hopfield_beta": float(beta),
+            "constraint_C": float(self._constraint_C),
+            "constraint_satisfied": True,
+        }
+
+    # ── Constraint verification ───────────────────────────────────
+
+    def verify_constraint(
+        self,
+        alpha: float,
+        kappa: float,
+        beta: float,
+        tolerance: float = 0.01,
+    ) -> bool:
+        """Check if parameters satisfy alpha * kappa ≈ C * beta.
+
+        Args:
+            alpha: Metric scaling parameter.
+            kappa: Curvature parameter.
+            beta: Inverse temperature.
+            tolerance: Relative tolerance for the check.
+
+        Returns:
+            ``True`` if the constraint is satisfied.
+        """
+        lhs = alpha * kappa
+        rhs = self._constraint_C * beta
+        denom = max(abs(rhs), 1e-10)
+        return abs(lhs - rhs) / denom < tolerance
+
+    def compute_integrity_score(
+        self,
+        alpha: float,
+        kappa: float,
+        beta: float,
+    ) -> float:
+        """Compute integrity score in [0, 1].  1.0 = perfect.
+
+        The score multiplies retrieval quality — violation degrades
+        performance through a sigmoid penalty.
+
+        Args:
+            alpha: Metric scaling parameter.
+            kappa: Curvature parameter.
+            beta: Inverse temperature.
+
+        Returns:
+            Integrity score in [0.0, 1.0].
+        """
+        lhs = alpha * kappa
+        rhs = self._constraint_C * beta
+        denom = max(abs(rhs), 1e-10)
+        deviation = abs(lhs - rhs) / denom
+        # Sigmoid degradation: small deviations tolerated
+        return float(1.0 / (1.0 + 10.0 * deviation ** 2))
+
+    # ── Fingerprinting ────────────────────────────────────────────
+
+    def embed_fingerprint(self, value: float, memory_id: int) -> float:
+        """Embed a computation fingerprint at the precision level.
+
+        Modifies the 12th decimal place to encode a signature.
+        The fingerprint is below the noise floor and does not affect
+        retrieval quality but can be forensically detected.
+
+        Args:
+            value: Original floating point value.
+            memory_id: Unique memory identifier for per-memory signing.
+
+        Returns:
+            Value with embedded fingerprint.
+        """
+        sig = hmac.new(
+            self._seed.encode("utf-8"),
+            f"fingerprint:{memory_id}".encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        # 8-digit fingerprint from hash, mapped to [0, 1)
+        fp = int(sig[:8], 16) / 0xFFFFFFFF
+        scale = 1e-10
+        return value + fp * scale
+
+    def detect_fingerprint(
+        self,
+        value: float,
+        memory_id: int,
+        original: float,
+    ) -> bool:
+        """Check if a value carries our fingerprint.
+
+        Args:
+            value: The potentially fingerprinted value.
+            memory_id: Memory ID used during embedding.
+            original: The original pre-fingerprint value.
+
+        Returns:
+            ``True`` if the fingerprint is detected.
+        """
+        expected = self.embed_fingerprint(original, memory_id)
+        return abs(value - expected) < 1e-14
+
+    def generate_dna_hash(self, memory_id: int) -> str:
+        """Generate a unique DNA hash for a memory.
+
+        This hash can be stored alongside the memory for provenance.
+
+        Args:
+            memory_id: Memory identifier.
+
+        Returns:
+            Hex digest string (64 chars).
+        """
+        return hmac.new(
+            self._seed.encode("utf-8"),
+            f"dna:{memory_id}".encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+    def verify_dna_hash(self, memory_id: int, dna_hash: str) -> bool:
+        """Verify that a DNA hash matches the expected value.
+
+        Args:
+            memory_id: Memory identifier.
+            dna_hash: Hash to verify.
+
+        Returns:
+            ``True`` if the hash is valid.
+        """
+        expected = self.generate_dna_hash(memory_id)
+        return hmac.compare_digest(expected, dna_hash)
+
+    # ── Properties ────────────────────────────────────────────────
+
+    @property
+    def constraint_C(self) -> float:
+        """The derived coupling constant."""
+        return self._constraint_C

package/src/superlocalmemory/attribution/signer.py

@@ -0,0 +1,153 @@
+# 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
+
+"""Cryptographic signing for content attribution and tamper detection.
+
+Provides HMAC-SHA256 signing so that every piece of content produced
+by the system carries a verifiable proof of origin.  Verification
+detects any modification to the content after signing.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+from datetime import datetime, timezone
+from typing import Dict
+
+def _get_or_create_key() -> str:
+    """Load key from env or generate a persistent random one."""
+    env_key = os.environ.get("SLM_SIGNER_KEY")
+    if env_key:
+        return env_key
+    key_path = os.path.expanduser("~/.superlocalmemory/.signer_key")
+    try:
+        with open(key_path) as f:
+            return f.read().strip()
+    except FileNotFoundError:
+        import secrets
+        key = secrets.token_hex(32)
+        os.makedirs(os.path.dirname(key_path), exist_ok=True)
+        with open(key_path, "w") as f:
+            f.write(key)
+        os.chmod(key_path, 0o600)
+        return key
+
+_DEFAULT_KEY: str = _get_or_create_key()
+
+
+class QualixarSigner:
+    """Signs content with HMAC-SHA256 for tamper-proof attribution.
+
+    Typical usage::
+
+        signer = QualixarSigner()
+        attribution = signer.sign("some content")
+        assert signer.verify("some content", attribution) is True
+
+    Args:
+        secret_key: Shared secret used for HMAC computation.
+    """
+
+    # ---- Branding constants (single source of truth) ----
+    _PLATFORM: str = "Qualixar"
+    _AUTHOR: str = "Varun Pratap Bhardwaj"
+    _AUTHOR_URL: str = "https://varunpratap.com"
+    _LICENSE: str = "MIT"
+
+    def __init__(self, secret_key: str = _DEFAULT_KEY) -> None:
+        if not secret_key:
+            raise ValueError("secret_key must be a non-empty string")
+        self._secret_key: bytes = secret_key.encode("utf-8")
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def sign(self, content: str) -> Dict[str, str]:
+        """Sign *content* and return attribution metadata.
+
+        Args:
+            content: The text to sign.
+
+        Returns:
+            A dict containing:
+
+            - ``platform``     – always ``"Qualixar"``
+            - ``author``       – always ``"Varun Pratap Bhardwaj"``
+            - ``license``      – always ``"MIT"``
+            - ``content_hash`` – SHA-256 hex digest of *content*
+            - ``signature``    – HMAC-SHA256 hex digest (key-dependent)
+            - ``timestamp``    – ISO 8601 UTC timestamp
+        """
+        content_bytes = content.encode("utf-8")
+        content_hash = hashlib.sha256(content_bytes).hexdigest()
+        signature = hmac.new(
+            self._secret_key, content_bytes, hashlib.sha256
+        ).hexdigest()
+        timestamp = datetime.now(tz=timezone.utc).isoformat()
+
+        return {
+            "platform": self._PLATFORM,
+            "author": self._AUTHOR,
+            "license": self._LICENSE,
+            "content_hash": content_hash,
+            "signature": signature,
+            "timestamp": timestamp,
+        }
+
+    def verify(self, content: str, attribution: Dict[str, str]) -> bool:
+        """Verify that *content* matches its attribution signature.
+
+        Checks both the SHA-256 content hash and the HMAC-SHA256
+        signature.  Returns ``False`` if either has been tampered with.
+
+        Args:
+            content: The text to verify.
+            attribution: The dict returned by :meth:`sign`.
+
+        Returns:
+            ``True`` if valid, ``False`` if tampered or mismatched.
+        """
+        content_bytes = content.encode("utf-8")
+
+        # 1. Verify content hash
+        expected_hash = hashlib.sha256(content_bytes).hexdigest()
+        if not hmac.compare_digest(
+            expected_hash, attribution.get("content_hash", "")
+        ):
+            return False
+
+        # 2. Verify HMAC signature
+        expected_sig = hmac.new(
+            self._secret_key, content_bytes, hashlib.sha256
+        ).hexdigest()
+        if not hmac.compare_digest(
+            expected_sig, attribution.get("signature", "")
+        ):
+            return False
+
+        return True
+
+    @staticmethod
+    def get_attribution() -> Dict[str, str]:
+        """Return basic (unsigned) attribution metadata.
+
+        This is a convenience method for embedding attribution in
+        contexts where full signing is not needed (e.g., file headers).
+
+        Returns:
+            A dict with ``platform``, ``author``, ``author_url``, and
+            ``license`` keys.
+        """
+        return {
+            "platform": QualixarSigner._PLATFORM,
+            "author": QualixarSigner._AUTHOR,
+            "author_url": QualixarSigner._AUTHOR_URL,
+            "license": QualixarSigner._LICENSE,
+        }