superlocalmemory 2.8.6 → 3.0.0

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()

package/src/superlocalmemory/cli/setup_wizard.py

@@ -0,0 +1,129 @@
+# 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
+
+"""Interactive setup wizard for first-time configuration.
+
+Guides new users through mode selection and provider setup.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+
+def run_wizard() -> None:
+    """Run the interactive setup wizard."""
+    print()
+    print("SuperLocalMemory V3 — First Time Setup")
+    print("=" * 40)
+    print()
+    print("Choose your operating mode:")
+    print()
+    print("  [A] Local Guardian (default)")
+    print("      Zero cloud. Zero LLM. Your data never leaves your machine.")
+    print("      EU AI Act compliant. Works immediately.")
+    print()
+    print("  [B] Smart Local")
+    print("      Local LLM via Ollama for answer synthesis.")
+    print("      Still private — nothing leaves your machine.")
+    print()
+    print("  [C] Full Power")
+    print("      Cloud LLM for best accuracy (~78% on LoCoMo).")
+    print("      Requires: API key from a supported provider.")
+    print()
+
+    choice = input("Select mode [A/B/C] (default: A): ").strip().lower() or "a"
+
+    if choice not in ("a", "b", "c"):
+        print(f"Invalid choice: {choice}. Using Mode A.")
+        choice = "a"
+
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.models import Mode
+
+    if choice == "a":
+        config = SLMConfig.for_mode(Mode.A)
+        config.save()
+        print()
+        print("Mode A configured. Zero cloud, zero LLM.")
+        print(f"Config saved to: {config.base_dir / 'config.json'}")
+
+    elif choice == "b":
+        config = SLMConfig.for_mode(Mode.B)
+        print()
+        print("Checking for Ollama...")
+        if shutil.which("ollama"):
+            print("  Ollama found!")
+        else:
+            print("  Ollama not found. Install it from https://ollama.ai")
+            print("  After installing, run: ollama pull llama3.2")
+        config.save()
+        print(f"Config saved to: {config.base_dir / 'config.json'}")
+
+    elif choice == "c":
+        config = SLMConfig.for_mode(Mode.C)
+        configure_provider(config)
+
+    print()
+    print("Ready! Your AI now remembers you.")
+    print()
+
+
+def configure_provider(config: object) -> None:
+    """Configure LLM provider for Mode C.
+
+    Args:
+        config: An SLMConfig instance (typed as object to avoid circular import
+                at module level; actual type checked at runtime).
+    """
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.storage.models import Mode
+
+    presets = SLMConfig.provider_presets()
+
+    print()
+    print("Choose your LLM provider:")
+    print()
+    providers = list(presets.keys())
+    for i, name in enumerate(providers, 1):
+        preset = presets[name]
+        print(f"  [{i}] {name.capitalize()} — {preset['model']}")
+    print()
+
+    idx = input(f"Select provider [1-{len(providers)}]: ").strip()
+    try:
+        provider_name = providers[int(idx) - 1]
+    except (ValueError, IndexError):
+        print("Invalid choice. Using OpenAI.")
+        provider_name = "openai"
+
+    preset = presets[provider_name]
+
+    # Resolve API key from environment or prompt
+    env_key = preset.get("env_key", "")
+    api_key = ""
+    if env_key:
+        existing = os.environ.get(env_key, "")
+        if existing:
+            print(f"  Found {env_key} in environment.")
+            api_key = existing
+        else:
+            api_key = input(
+                f"  Enter your {provider_name.capitalize()} API key: ",
+            ).strip()
+
+    updated = SLMConfig.for_mode(
+        Mode.C,
+        llm_provider=provider_name,
+        llm_model=preset["model"],
+        llm_api_key=api_key,
+        llm_api_base=preset["base_url"],
+    )
+    updated.save()
+    print(f"  Provider: {provider_name}")
+    print(f"  Model: {preset['model']}")
+    print(f"Config saved to: {updated.base_dir / 'config.json'}")