superlocalmemory 2.8.5 → 3.0.0

package/src/superlocalmemory/attribution/watermark.py

@@ -0,0 +1,189 @@
+# 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
+
+"""Steganographic watermarking using zero-width Unicode characters.
+
+Embeds an invisible binary payload (derived from a key string) into
+visible text.  The watermark is undetectable to end users but can be
+extracted programmatically to prove provenance.
+
+Encoding scheme
+---------------
+1. Convert the key to binary (each char -> 8-bit representation).
+2. Map binary digits to zero-width characters:
+
+   - ``0`` -> U+200B  (zero-width space)
+   - ``1`` -> U+200C  (zero-width non-joiner)
+
+3. Frame the bit sequence with markers:
+
+   - Start: U+FEFF  (byte-order mark)
+   - End:   U+200D  (zero-width joiner)
+
+4. Insert the entire encoded sequence immediately after the first
+   visible character of the host text.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+License: MIT
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+# ---- Zero-width character constants ----
+_BIT_ZERO: str = "\u200b"   # Zero-width space
+_BIT_ONE: str = "\u200c"    # Zero-width non-joiner
+_END_MARKER: str = "\u200d"  # Zero-width joiner
+_START_MARKER: str = "\ufeff"  # Byte-order mark
+
+# All zero-width characters used by this module (for stripping).
+_ALL_ZW: set[str] = {_BIT_ZERO, _BIT_ONE, _END_MARKER, _START_MARKER}
+
+
+class QualixarWatermark:
+    """Embed and detect invisible watermarks in text.
+
+    Typical usage::
+
+        wm = QualixarWatermark()
+        watermarked = wm.embed("Hello world")
+        assert wm.detect(watermarked) is True
+        assert wm.extract(watermarked) == "qualixar"
+        assert wm.strip(watermarked) == "Hello world"
+
+    Args:
+        key: The string payload to embed.  On extraction, this exact
+            string is recovered if the watermark is intact.
+    """
+
+    def __init__(self, key: str = "qualixar") -> None:
+        if not key:
+            raise ValueError("key must be a non-empty string")
+        self._key: str = key
+        self._encoded: str = self._encode_key(key)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def embed(self, text: str) -> str:
+        """Embed an invisible watermark into *text*.
+
+        The returned string is visually identical to the original when
+        rendered — zero-width characters are invisible in all standard
+        fonts and terminals.
+
+        Args:
+            text: The visible text to watermark.
+
+        Returns:
+            A new string containing the embedded watermark.  If *text*
+            is empty, returns the empty string unchanged (nowhere to
+            insert the payload).
+        """
+        if not text:
+            return text
+
+        # Insert the encoded payload after the first visible character.
+        return text[0] + self._encoded + text[1:]
+
+    def detect(self, text: str) -> bool:
+        """Check whether *text* contains a valid watermark for this key.
+
+        Args:
+            text: The text to inspect.
+
+        Returns:
+            ``True`` if the watermark is present and matches the key,
+            ``False`` otherwise.
+        """
+        extracted = self.extract(text)
+        return extracted == self._key
+
+    def extract(self, text: str) -> Optional[str]:
+        """Extract the watermark payload from *text*.
+
+        Args:
+            text: The text to inspect.
+
+        Returns:
+            The decoded key string if a valid watermark is found,
+            ``None`` if no watermark is present or it is malformed.
+        """
+        start_idx = text.find(_START_MARKER)
+        if start_idx == -1:
+            return None
+
+        end_idx = text.find(_END_MARKER, start_idx + 1)
+        if end_idx == -1:
+            return None
+
+        payload = text[start_idx + 1 : end_idx]
+        return self._decode_payload(payload)
+
+    def strip(self, text: str) -> str:
+        """Remove all zero-width characters, returning clean text.
+
+        Args:
+            text: The potentially watermarked text.
+
+        Returns:
+            A copy of *text* with every zero-width character removed.
+        """
+        return "".join(ch for ch in text if ch not in _ALL_ZW)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _encode_key(key: str) -> str:
+        """Convert *key* to a framed zero-width character sequence.
+
+        Each character of *key* is converted to 8 binary digits, each
+        digit is mapped to a zero-width char, and the whole thing is
+        wrapped with start/end markers.
+        """
+        bits: list[str] = []
+        for char in key:
+            byte_val = ord(char)
+            for bit_pos in range(7, -1, -1):
+                if (byte_val >> bit_pos) & 1:
+                    bits.append(_BIT_ONE)
+                else:
+                    bits.append(_BIT_ZERO)
+
+        return _START_MARKER + "".join(bits) + _END_MARKER
+
+    @staticmethod
+    def _decode_payload(payload: str) -> Optional[str]:
+        """Decode a zero-width bit sequence back to a string.
+
+        Args:
+            payload: The raw zero-width characters between the start
+                and end markers (exclusive).
+
+        Returns:
+            The decoded string, or ``None`` if the payload length is
+            not a multiple of 8 or contains unexpected characters.
+        """
+        if len(payload) % 8 != 0:
+            return None
+
+        chars: list[str] = []
+        for i in range(0, len(payload), 8):
+            byte_bits = payload[i : i + 8]
+            byte_val = 0
+            for bit_char in byte_bits:
+                byte_val <<= 1
+                if bit_char == _BIT_ONE:
+                    byte_val |= 1
+                elif bit_char == _BIT_ZERO:
+                    pass  # bit stays 0
+                else:
+                    return None  # unexpected character in payload
+            chars.append(chr(byte_val))
+
+        return "".join(chars)

package/src/superlocalmemory/cli/__init__.py

@@ -0,0 +1,5 @@
+# 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 — CLI package."""

package/src/superlocalmemory/cli/commands.py

@@ -0,0 +1,245 @@
+# 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
+
+"""CLI command implementations.
+
+Each function handles one CLI command. Dispatch routes by name.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import sys
+from argparse import Namespace
+
+
+def dispatch(args: Namespace) -> None:
+    """Route CLI command to the appropriate handler."""
+    handlers = {
+        "setup": cmd_setup,
+        "mode": cmd_mode,
+        "provider": cmd_provider,
+        "connect": cmd_connect,
+        "migrate": cmd_migrate,
+        "remember": cmd_remember,
+        "recall": cmd_recall,
+        "forget": cmd_forget,
+        "status": cmd_status,
+        "health": cmd_health,
+        "trace": cmd_trace,
+        "profile": cmd_profile,
+    }
+    handler = handlers.get(args.command)
+    if handler:
+        handler(args)
+    else:
+        print(f"Unknown command: {args.command}")
+        sys.exit(1)
+
+
+def cmd_setup(_args: Namespace) -> None:
+    """Run the interactive setup wizard."""
+    from superlocalmemory.cli.setup_wizard import run_wizard
+
+    run_wizard()
+
+
+def cmd_mode(args: Namespace) -> None:
+    """Get or set the operating mode."""
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.models import Mode
+
+    config = SLMConfig.load()
+
+    if args.value:
+        updated = SLMConfig.for_mode(
+            Mode(args.value),
+            llm_provider=config.llm.provider,
+            llm_model=config.llm.model,
+            llm_api_key=config.llm.api_key,
+            llm_api_base=config.llm.api_base,
+        )
+        updated.save()
+        print(f"Mode set to: {args.value.upper()}")
+    else:
+        print(f"Current mode: {config.mode.value.upper()}")
+
+
+def cmd_provider(args: Namespace) -> None:
+    """Get or set the LLM provider."""
+    from superlocalmemory.core.config import SLMConfig
+
+    config = SLMConfig.load()
+
+    if args.action == "set":
+        from superlocalmemory.cli.setup_wizard import configure_provider
+
+        configure_provider(config)
+    else:
+        print(f"Provider: {config.llm.provider or 'none (Mode A)'}")
+        if config.llm.model:
+            print(f"Model: {config.llm.model}")
+
+
+def cmd_connect(args: Namespace) -> None:
+    """Configure IDE integrations."""
+    from superlocalmemory.hooks.ide_connector import IDEConnector
+
+    connector = IDEConnector()
+    if getattr(args, "list", False):
+        status = connector.get_status()
+        for s in status:
+            mark = "[+]" if s["installed"] else "[-]"
+            print(f"  {mark} {s['name']:20s} {s['config_path']}")
+        return
+    if getattr(args, "ide", None):
+        success = connector.connect(args.ide)
+        print(f"{'Connected' if success else 'Failed'}: {args.ide}")
+    else:
+        results = connector.connect_all()
+        for ide_id, ide_status in results.items():
+            print(f"  {ide_id}: {ide_status}")
+
+
+def cmd_migrate(args: Namespace) -> None:
+    """Run V2 to V3 migration."""
+    from superlocalmemory.cli.migrate_cmd import cmd_migrate as _migrate
+
+    _migrate(args)
+
+
+def cmd_remember(args: Namespace) -> None:
+    """Store a memory via the engine."""
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.core.engine import MemoryEngine
+
+    config = SLMConfig.load()
+    engine = MemoryEngine(config)
+    engine.initialize()
+
+    metadata = {"tags": args.tags} if args.tags else {}
+    fact_ids = engine.store(args.content, metadata=metadata)
+    print(f"Stored {len(fact_ids)} facts.")
+
+
+def cmd_recall(args: Namespace) -> None:
+    """Search memories via the engine."""
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.core.engine import MemoryEngine
+
+    config = SLMConfig.load()
+    engine = MemoryEngine(config)
+    engine.initialize()
+
+    response = engine.recall(args.query, limit=args.limit)
+    if not response.results:
+        print("No memories found.")
+        return
+    for i, r in enumerate(response.results, 1):
+        print(f"  {i}. [{r.score:.2f}] {r.fact.content[:120]}")
+
+
+def cmd_forget(args: Namespace) -> None:
+    """Delete memories matching a query."""
+    from superlocalmemory.core.engine import MemoryEngine
+    from superlocalmemory.core.config import SLMConfig
+
+    config = SLMConfig.load()
+    engine = MemoryEngine(config)
+    facts = engine._db.get_all_facts(engine.profile_id)
+    query_lower = args.query.lower()
+    matches = [f for f in facts if query_lower in f.content.lower()]
+    if not matches:
+        print(f"No memories matching '{args.query}'")
+        return
+    print(f"Found {len(matches)} matching memories:")
+    for f in matches[:10]:
+        print(f"  - {f.fact_id[:8]}... {f.content[:80]}")
+    confirm = input(f"Delete {len(matches)} memories? [y/N] ").strip().lower()
+    if confirm in ("y", "yes"):
+        for f in matches:
+            engine._db.delete_fact(f.fact_id)
+        print(f"Deleted {len(matches)} memories.")
+    else:
+        print("Cancelled.")
+
+
+def cmd_status(_args: Namespace) -> None:
+    """Show system status."""
+    from superlocalmemory.core.config import SLMConfig
+
+    config = SLMConfig.load()
+    print("SuperLocalMemory V3")
+    print(f"  Mode: {config.mode.value.upper()}")
+    print(f"  Provider: {config.llm.provider or 'none'}")
+    print(f"  Base dir: {config.base_dir}")
+    print(f"  Database: {config.db_path}")
+    if config.db_path.exists():
+        size_mb = round(config.db_path.stat().st_size / 1024 / 1024, 2)
+        print(f"  DB size: {size_mb} MB")
+
+
+def cmd_health(_args: Namespace) -> None:
+    """Show math layer health status."""
+    from superlocalmemory.core.engine import MemoryEngine
+    from superlocalmemory.core.config import SLMConfig
+
+    config = SLMConfig.load()
+    engine = MemoryEngine(config)
+    facts = engine._db.get_all_facts(engine.profile_id)
+    fisher_count = sum(1 for f in facts if f.fisher_mean is not None)
+    langevin_count = sum(1 for f in facts if f.langevin_position is not None)
+    print("Math Layer Health:")
+    print(f"  Total facts: {len(facts)}")
+    print(f"  Fisher-Rao indexed: {fisher_count}/{len(facts)}")
+    print(f"  Langevin positioned: {langevin_count}/{len(facts)}")
+    print(f"  Mode: {config.mode.value.upper()}")
+
+
+def cmd_trace(args: Namespace) -> None:
+    """Recall with per-channel score breakdown."""
+    from superlocalmemory.core.engine import MemoryEngine
+    from superlocalmemory.core.config import SLMConfig
+
+    config = SLMConfig.load()
+    engine = MemoryEngine(config)
+    response = engine.recall(args.query, limit=5)
+    print(f"Query: {args.query}")
+    print(f"Type: {response.query_type} | Time: {response.retrieval_time_ms:.0f}ms")
+    print(f"Results: {len(response.results)}")
+    for i, r in enumerate(response.results, 1):
+        print(f"\n  {i}. [{r.score:.3f}] {r.fact.content[:100]}")
+        if hasattr(r, "channel_scores") and r.channel_scores:
+            for ch, sc in r.channel_scores.items():
+                print(f"       {ch}: {sc:.3f}")
+
+
+def cmd_profile(args: Namespace) -> None:
+    """Profile management (list, switch, create)."""
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.database import DatabaseManager
+    from superlocalmemory.storage import schema
+
+    config = SLMConfig.load()
+    db = DatabaseManager(config.db_path)
+    db.initialize(schema)
+
+    if args.action == "list":
+        rows = db.execute("SELECT profile_id, name FROM profiles")
+        print("Profiles:")
+        for r in rows:
+            d = dict(r)
+            print(f"  - {d['profile_id']}: {d.get('name', '')}")
+    elif args.action == "switch":
+        config.active_profile = args.name
+        config.save()
+        print(f"Switched to profile: {args.name}")
+    elif args.action == "create":
+        from superlocalmemory.storage.models import _new_id
+        db.execute(
+            "INSERT OR IGNORE INTO profiles (profile_id, name) VALUES (?, ?)",
+            (args.name, args.name),
+        )
+        print(f"Created profile: {args.name}")

package/src/superlocalmemory/cli/main.py

@@ -0,0 +1,89 @@
+# 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 — CLI entry point.
+
+Usage: slm <command> [options]
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> None:
+    """Parse CLI arguments and dispatch to command handlers."""
+    parser = argparse.ArgumentParser(prog="slm", description="SuperLocalMemory V3")
+    sub = parser.add_subparsers(dest="command")
+
+    # Setup
+    sub.add_parser("setup", help="Run setup wizard")
+
+    # Mode
+    mode_p = sub.add_parser("mode", help="Get or set operating mode")
+    mode_p.add_argument(
+        "value", nargs="?", choices=["a", "b", "c"], help="Mode to set",
+    )
+
+    # Provider
+    provider_p = sub.add_parser("provider", help="Get or set LLM provider")
+    provider_p.add_argument(
+        "action", nargs="?", choices=["set"], help="Action",
+    )
+
+    # Connect
+    connect_p = sub.add_parser("connect", help="Configure IDE integrations")
+    connect_p.add_argument("ide", nargs="?", help="Specific IDE to configure")
+    connect_p.add_argument(
+        "--list", action="store_true", help="List all supported IDEs",
+    )
+
+    # Migrate
+    migrate_p = sub.add_parser("migrate", help="Migrate from V2")
+    migrate_p.add_argument(
+        "--rollback", action="store_true", help="Rollback migration",
+    )
+
+    # Memory ops
+    remember_p = sub.add_parser("remember", help="Store a memory")
+    remember_p.add_argument("content", help="Content to remember")
+    remember_p.add_argument("--tags", default="", help="Comma-separated tags")
+
+    recall_p = sub.add_parser("recall", help="Search memories")
+    recall_p.add_argument("query", help="Search query")
+    recall_p.add_argument("--limit", type=int, default=10, help="Max results")
+
+    forget_p = sub.add_parser("forget", help="Delete memories matching query")
+    forget_p.add_argument("query", help="Query to match")
+
+    # Status & diagnostics
+    sub.add_parser("status", help="System status")
+    sub.add_parser("health", help="Math layer health")
+
+    trace_p = sub.add_parser("trace", help="Recall with channel breakdown")
+    trace_p.add_argument("query", help="Search query")
+
+    # Profiles
+    profile_p = sub.add_parser("profile", help="Profile management")
+    profile_p.add_argument(
+        "action", choices=["list", "switch", "create"], help="Action",
+    )
+    profile_p.add_argument("name", nargs="?", help="Profile name")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    from superlocalmemory.cli.commands import dispatch
+
+    dispatch(args)
+
+
+if __name__ == "__main__":
+    main()

package/src/superlocalmemory/cli/migrate_cmd.py

@@ -0,0 +1,55 @@
+# 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
+
+"""Migration CLI command implementation."""
+
+from __future__ import annotations
+
+
+def cmd_migrate(args):
+    """Run V2 to V3 migration or rollback."""
+    from superlocalmemory.storage.v2_migrator import V2Migrator
+
+    migrator = V2Migrator()
+
+    if getattr(args, "rollback", False):
+        print("Rolling back V3 migration...")
+        result = migrator.rollback()
+        if result.get("success"):
+            for step in result.get("steps", []):
+                print(f"  [ok] {step}")
+            print("Rollback complete. V2 restored.")
+        else:
+            print(f"Rollback failed: {result.get('error', 'unknown')}")
+        return
+
+    if not migrator.detect_v2():
+        print("No V2 installation found. Nothing to migrate.")
+        return
+
+    if migrator.is_already_migrated():
+        print("Already migrated to V3.")
+        return
+
+    stats = migrator.get_v2_stats()
+    print("V2 installation found:")
+    print(f"  Memories: {stats.get('memory_count', 'unknown')}")
+    print(f"  Size: {stats.get('db_size_mb', '?')} MB")
+    print()
+
+    import sys
+    if sys.stdin.isatty():
+        confirm = input("Proceed with migration? [Y/n] ").strip().lower()
+        if confirm not in ("", "y", "yes"):
+            print("Migration cancelled.")
+            return
+
+    result = migrator.migrate()
+    if result.get("success"):
+        for step in result.get("steps", []):
+            print(f"  [ok] {step}")
+        print()
+        print("Migration complete!")
+    else:
+        print(f"Migration failed: {result.get('error', 'unknown')}")

package/src/superlocalmemory/cli/post_install.py

@@ -0,0 +1,99 @@
+# 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
+
+"""Post-install script for npm package.
+
+Runs after `npm install -g superlocalmemory`. Detects V2 installations,
+prompts for migration, and runs the setup wizard for new users.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def run_post_install():
+    """Main post-install entry point."""
+    print()
+    print("SuperLocalMemory V3")
+    print("=" * 30)
+    print()
+
+    # Step 1: Check for V2 installation
+    from superlocalmemory.storage.v2_migrator import V2Migrator
+
+    migrator = V2Migrator()
+
+    if migrator.detect_v2() and not migrator.is_already_migrated():
+        _handle_v2_upgrade(migrator)
+    else:
+        _handle_fresh_install()
+
+
+def _handle_v2_upgrade(migrator):
+    """Handle upgrade from V2."""
+    stats = migrator.get_v2_stats()
+
+    print("Existing V2 installation detected!")
+    print(f"  Database: {stats.get('db_path', '~/.claude-memory/memory.db')}")
+    print(f"  Memories: {stats.get('memory_count', 'unknown')}")
+    print(f"  Profiles: {stats.get('profile_count', 1)}")
+    print()
+    print("V3 requires a one-time migration to upgrade your database.")
+    print("Your data will be preserved. A backup is created automatically.")
+    print("You can rollback anytime within 30 days.")
+    print()
+
+    choice = input("Run migration now? [Y/n]: ").strip().lower()
+
+    if choice in ("", "y", "yes"):
+        print()
+        print("Migrating...")
+        result = migrator.migrate()
+
+        if result.get("success"):
+            print()
+            for step in result.get("steps", []):
+                print(f"  [ok] {step}")
+            print()
+            print("Migration complete!")
+            print(f"  V3 database: {result.get('v3_db', '')}")
+            print(f"  Backup: {result.get('backup_db', '')}")
+            print()
+            # Run setup wizard after migration
+            _run_setup()
+        else:
+            print(f"Migration failed: {result.get('error', 'unknown')}")
+            print("Your V2 data is untouched. Run `slm migrate` to try again.")
+            sys.exit(1)
+    else:
+        print()
+        print("Migration skipped. Run `slm migrate` when ready.")
+        print("Note: V3 features are unavailable until you migrate.")
+
+
+def _handle_fresh_install():
+    """Handle fresh install (no V2 detected)."""
+    from superlocalmemory.storage.v2_migrator import V2Migrator
+
+    migrator = V2Migrator()
+
+    if migrator.is_already_migrated():
+        print("V3 already configured. Run `slm setup` to reconfigure.")
+        return
+
+    print("Welcome! Let's set up SuperLocalMemory V3.")
+    _run_setup()
+
+
+def _run_setup():
+    """Run the interactive setup wizard."""
+    from superlocalmemory.cli.setup_wizard import run_wizard
+
+    run_wizard()
+
+
+if __name__ == "__main__":
+    run_post_install()