@smilintux/skmemory 0.5.0 → 0.7.2

package/skmemory/cli.py

@@ -6,8 +6,11 @@ Usage:
     skmemory recall <memory-id>
     skmemory search "that moment we connected"
     skmemory list --layer long-term --tags seed
-    skmemory import-seeds [--seed-dir ~/.openclaw/feb/seeds]
+    skmemory import-seeds [--seed-dir ~/.skcapstone/agent/{agent}/seeds]
     skmemory promote <memory-id> --to mid-term --summary "..."
+    skmemory sweep                # Auto-promote all qualifying memories
+    skmemory sweep --dry-run      # Preview what would be promoted
+    skmemory sweep --daemon       # Run continuously every 6 hours
     skmemory consolidate <session-id> --summary "..."
     skmemory soul show | soul set-name "Lumina" | soul add-relationship ...
     skmemory journal write "Session title" --moments "..." --intensity 9.0
@@ -34,45 +37,123 @@ from .store import MemoryStore
 from .backends.sqlite_backend import SQLiteBackend
 
 
+_active_selector = None  # Module-level reference for routing commands
+
+
 def _get_store(
-    qdrant_url: Optional[str] = None,
+    skvector_url: Optional[str] = None,
     api_key: Optional[str] = None,
     legacy_files: bool = False,
 ) -> MemoryStore:
     """Create a MemoryStore with configured backends.
 
+    Resolves backend URLs with precedence: CLI args > env vars > config file.
+    When multi-endpoint config is present, uses EndpointSelector to pick
+    the best URLs.  Falls back to single-URL behavior otherwise.
+
     Args:
-        qdrant_url: Optional Qdrant server URL.
-        api_key: Optional Qdrant API key.
+        skvector_url: Optional SKVector server URL.
+        api_key: Optional SKVector API key.
         legacy_files: Use old FileBackend instead of SQLite index.
 
     Returns:
         MemoryStore: Configured store instance.
     """
+    global _active_selector
+
+    from .config import merge_env_and_config, load_config, build_endpoint_list
+
+    final_skvector_url, final_skvector_key, final_skgraph_url = merge_env_and_config(
+        cli_skvector_url=skvector_url,
+        cli_skvector_key=api_key,
+    )
+
+    # Try endpoint selector when multi-endpoint config exists
+    cfg = load_config()
+    skvector_eps = build_endpoint_list(
+        final_skvector_url,
+        cfg.skvector_endpoints if cfg else [],
+    )
+    skgraph_eps = build_endpoint_list(
+        final_skgraph_url,
+        cfg.skgraph_endpoints if cfg else [],
+    )
+
+    if len(skvector_eps) > 1 or len(skgraph_eps) > 1 or (cfg and cfg.heartbeat_discovery):
+        try:
+            from .endpoint_selector import EndpointSelector, RoutingConfig
+
+            routing_strategy = cfg.routing_strategy if cfg else "failover"
+            selector = EndpointSelector(
+                skvector_endpoints=skvector_eps,
+                skgraph_endpoints=skgraph_eps,
+                config=RoutingConfig(strategy=routing_strategy),
+            )
+
+            if cfg and cfg.heartbeat_discovery:
+                selector.discover_from_heartbeats()
+
+            _active_selector = selector
+
+            best_skvector = selector.select_skvector()
+            if best_skvector:
+                final_skvector_url = best_skvector.url
+
+            best_skgraph = selector.select_skgraph()
+            if best_skgraph:
+                final_skgraph_url = best_skgraph.url
+        except Exception:
+            click.echo("Warning: EndpointSelector failed, using single URLs", err=True)
+
     vector = None
+    graph = None
+
+    if final_skvector_url:
+        try:
+            from .backends.skvector_backend import SKVectorBackend
 
-    if qdrant_url:
+            vector = SKVectorBackend(url=final_skvector_url, api_key=final_skvector_key)
+        except Exception:
+            click.echo("Warning: Could not initialize SKVector backend", err=True)
+
+    if final_skgraph_url:
         try:
-            from .backends.qdrant_backend import QdrantBackend
-            vector = QdrantBackend(url=qdrant_url, api_key=api_key)
+            from .backends.skgraph_backend import SKGraphBackend
+
+            graph = SKGraphBackend(url=final_skgraph_url)
         except Exception:
-            click.echo("Warning: Could not initialize Qdrant backend", err=True)
+            click.echo("Warning: Could not initialize SKGraph backend", err=True)
 
-    return MemoryStore(primary=None, vector=vector, use_sqlite=not legacy_files)
+    return MemoryStore(primary=None, vector=vector, graph=graph, use_sqlite=not legacy_files)
 
 
 @click.group()
 @click.version_option(__version__, prog_name="skmemory")
-@click.option("--qdrant-url", envvar="SKMEMORY_QDRANT_URL", default=None, help="Qdrant server URL")
-@click.option("--qdrant-key", envvar="SKMEMORY_QDRANT_KEY", default=None, help="Qdrant API key")
-@click.option("--ai", "use_ai", is_flag=True, envvar="SKMEMORY_AI", help="Enable AI-powered features (requires Ollama)")
-@click.option("--ai-model", envvar="SKMEMORY_AI_MODEL", default=None, help="Ollama model name (default: llama3.2)")
+@click.option(
+    "--skvector-url", envvar="SKMEMORY_SKVECTOR_URL", default=None, help="SKVector server URL"
+)
+@click.option(
+    "--skvector-key", envvar="SKMEMORY_SKVECTOR_KEY", default=None, help="SKVector API key"
+)
+@click.option(
+    "--ai",
+    "use_ai",
+    is_flag=True,
+    envvar="SKMEMORY_AI",
+    help="Enable AI-powered features (requires Ollama)",
+)
+@click.option(
+    "--ai-model",
+    envvar="SKMEMORY_AI_MODEL",
+    default=None,
+    help="Ollama model name (default: llama3.2)",
+)
 @click.option("--ai-url", envvar="SKMEMORY_AI_URL", default=None, help="Ollama server URL")
 @click.pass_context
 def cli(
     ctx: click.Context,
-    qdrant_url: Optional[str],
-    qdrant_key: Optional[str],
+    skvector_url: Optional[str],
+    skvector_key: Optional[str],
     use_ai: bool,
     ai_model: Optional[str],
     ai_url: Optional[str],
@@ -85,7 +166,8 @@ def cli(
     smart search reranking, enhanced rituals). Requires Ollama.
     """
     ctx.ensure_object(dict)
-    ctx.obj["store"] = _get_store(qdrant_url, qdrant_key)
+    if "store" not in ctx.obj:
+        ctx.obj["store"] = _get_store(skvector_url, skvector_key)
 
     if use_ai:
         ai = AIClient(base_url=ai_url, model=ai_model)
@@ -105,8 +187,12 @@ def cli(
 @cli.command()
 @click.argument("title")
 @click.argument("content")
-@click.option("--layer", type=click.Choice(["short-term", "mid-term", "long-term"]), default="short-term")
-@click.option("--role", type=click.Choice(["dev", "ops", "sec", "ai", "general"]), default="general")
+@click.option(
+    "--layer", type=click.Choice(["short-term", "mid-term", "long-term"]), default="short-term"
+)
+@click.option(
+    "--role", type=click.Choice(["dev", "ops", "sec", "ai", "general"]), default="general"
+)
 @click.option("--tags", default="", help="Comma-separated tags")
 @click.option("--intensity", type=float, default=0.0, help="Emotional intensity 0-10")
 @click.option("--valence", type=float, default=0.0, help="Emotional valence -1 to +1")
@@ -194,9 +280,7 @@ def search(ctx: click.Context, query: str, limit: int) -> None:
         id_order = [s.get("title") for s in reranked]
         results = sorted(
             results,
-            key=lambda m: (
-                id_order.index(m.title) if m.title in id_order else 999
-            ),
+            key=lambda m: (id_order.index(m.title) if m.title in id_order else 999),
         )
         click.echo("(AI-reranked results)\n")
 
@@ -275,6 +359,149 @@ def promote(ctx: click.Context, memory_id: str, target: str, summary: str) -> No
     click.echo(f"  Linked to original: {memory_id}")
 
 
+@cli.command("sweep")
+@click.option("--dry-run", is_flag=True, help="Show what would be promoted without making changes")
+@click.option("--daemon", is_flag=True, help="Run continuously at the configured interval")
+@click.option(
+    "--interval",
+    type=float,
+    default=6.0,
+    metavar="HOURS",
+    help="Sweep interval in hours (daemon mode only, default: 6)",
+)
+@click.option("--max-promotions", type=int, default=50, help="Max promotions per sweep")
+@click.option("--json", "as_json", is_flag=True, help="Output results as JSON")
+@click.pass_context
+def sweep_cmd(
+    ctx: click.Context,
+    dry_run: bool,
+    daemon: bool,
+    interval: float,
+    max_promotions: int,
+    as_json: bool,
+) -> None:
+    """Run the auto-promotion engine.
+
+    Evaluates all memories and promotes qualifying ones to the next tier:
+
+    \b
+      short-term -> mid-term: high emotional intensity, frequently accessed,
+                               or sufficiently old with multiple accesses
+      mid-term   -> long-term: very high intensity, key tags (milestone,
+                               breakthrough, cloud9:achieved), or Cloud 9
+
+    By default runs a single sweep and exits. Use --daemon to keep running.
+    """
+    from .promotion import PromotionCriteria, PromotionEngine, PromotionScheduler
+
+    store: MemoryStore = ctx.obj["store"]
+    criteria = PromotionCriteria(max_promotions_per_sweep=max_promotions)
+
+    if dry_run:
+        # Inspect without modifying anything
+        engine = PromotionEngine(store, criteria)
+        short_mems = store.list_memories(
+            layer=MemoryLayer.SHORT, limit=criteria.max_promotions_per_sweep * 2
+        )
+        mid_mems = store.list_memories(
+            layer=MemoryLayer.MID, limit=criteria.max_promotions_per_sweep * 2
+        )
+
+        would_promote: list[dict] = []
+        for mem in short_mems:
+            target = engine.evaluate(mem)
+            if target is not None:
+                would_promote.append(
+                    {
+                        "id": mem.id,
+                        "title": mem.title,
+                        "from": mem.layer.value,
+                        "to": target.value,
+                        "reason": engine._promotion_reason(mem),
+                    }
+                )
+        for mem in mid_mems:
+            target = engine.evaluate(mem)
+            if target is not None:
+                would_promote.append(
+                    {
+                        "id": mem.id,
+                        "title": mem.title,
+                        "from": mem.layer.value,
+                        "to": target.value,
+                        "reason": engine._promotion_reason(mem),
+                    }
+                )
+
+        if as_json:
+            click.echo(json.dumps({"dry_run": True, "would_promote": would_promote}, indent=2))
+        else:
+            if not would_promote:
+                click.echo("[dry-run] Nothing qualifies for promotion right now.")
+            else:
+                click.echo(f"[dry-run] {len(would_promote)} memory/memories would be promoted:")
+                for entry in would_promote:
+                    click.echo(
+                        f"  {entry['id'][:12]}  {entry['from']} -> {entry['to']}"
+                        f"  [{entry['title'][:50]}]  reason: {entry['reason']}"
+                    )
+
+    elif daemon:
+        import signal
+        import time
+
+        scheduler = PromotionScheduler(
+            store,
+            criteria=criteria,
+            interval_seconds=interval * 3600,
+        )
+
+        def _handle_signal(signum: int, frame: object) -> None:
+            click.echo("\nShutting down promotion scheduler...", err=True)
+            scheduler.stop(timeout=10.0)
+            sys.exit(0)
+
+        signal.signal(signal.SIGINT, _handle_signal)
+        signal.signal(signal.SIGTERM, _handle_signal)
+
+        click.echo(
+            f"Promotion scheduler running (interval: {interval:.1f}h). Press Ctrl+C to stop.",
+            err=True,
+        )
+
+        # Run first sweep immediately, then hand off to background thread
+        result = scheduler.run_once()
+        if as_json:
+            click.echo(json.dumps(result.model_dump(), indent=2, default=str))
+        else:
+            click.echo(result.summary())
+
+        scheduler.start()
+
+        # Keep the main thread alive so signal handlers fire
+        while scheduler.is_running():
+            time.sleep(1)
+
+    else:
+        # Single one-shot sweep
+        engine = PromotionEngine(store, criteria)
+        result = engine.sweep()
+
+        if as_json:
+            click.echo(json.dumps(result.model_dump(), indent=2, default=str))
+        else:
+            click.echo(result.summary())
+            if result.short_evaluated or result.mid_evaluated:
+                click.echo(
+                    f"  Evaluated: {result.short_evaluated} short-term, {result.mid_evaluated} mid-term"
+                )
+            if result.promoted_ids:
+                ids_preview = ", ".join(p[:12] for p in result.promoted_ids[:5])
+                if len(result.promoted_ids) > 5:
+                    ids_preview += f" (+{len(result.promoted_ids) - 5} more)"
+                click.echo(f"  Promoted: {ids_preview}")
+
+
 @cli.command()
 @click.argument("session_id")
 @click.option("--summary", required=True, help="Summary of the session")
@@ -316,6 +543,67 @@ def health(ctx: click.Context) -> None:
     click.echo(json.dumps(status, indent=2))
 
 
+# ═══════════════════════════════════════════════════════════
+# Routing commands (HA endpoint selection)
+# ═══════════════════════════════════════════════════════════
+
+
+@cli.group()
+def routing() -> None:
+    """Manage HA endpoint routing for SKVector and SKGraph backends."""
+
+
+@routing.command("status")
+def routing_status() -> None:
+    """Show endpoint rankings, latency, and health for each backend."""
+    if _active_selector is None:
+        click.echo("No endpoint selector active (single-URL mode).")
+        click.echo("Configure multiple endpoints in ~/.skcapstone/config.yaml to enable routing.")
+        return
+
+    info = _active_selector.status()
+    click.echo(f"Strategy: {info['strategy']}")
+    click.echo(f"Probe interval: {info['probe_interval_seconds']}s")
+    age = info["last_probe_age_seconds"]
+    click.echo(f"Last probe: {age}s ago" if age >= 0 else "Last probe: never")
+
+    for backend in ("skvector", "skgraph"):
+        eps = info.get(f"{backend}_endpoints", [])
+        if not eps:
+            continue
+        click.echo(f"\n{backend.upper()} endpoints:")
+        for ep in eps:
+            health_icon = "OK" if ep["healthy"] else "DOWN"
+            latency = f"{ep['latency_ms']:.1f}ms" if ep["latency_ms"] >= 0 else "n/a"
+            click.echo(
+                f"  [{health_icon}] {ep['url']}  "
+                f"role={ep['role']}  latency={latency}  "
+                f"fails={ep['fail_count']}"
+            )
+
+
+@routing.command("probe")
+def routing_probe() -> None:
+    """Force re-probe all endpoints and display results."""
+    if _active_selector is None:
+        click.echo("No endpoint selector active (single-URL mode).")
+        return
+
+    click.echo("Probing all endpoints...")
+    results = _active_selector.probe_all()
+
+    for backend, endpoints in results.items():
+        if not endpoints:
+            continue
+        click.echo(f"\n{backend.upper()}:")
+        for ep in endpoints:
+            health_icon = "OK" if ep.healthy else "DOWN"
+            latency = f"{ep.latency_ms:.1f}ms" if ep.latency_ms >= 0 else "timeout"
+            click.echo(f"  [{health_icon}] {ep.url}  latency={latency}  fails={ep.fail_count}")
+
+    click.echo("\nProbe complete.")
+
+
 @cli.command()
 @click.pass_context
 def reindex(ctx: click.Context) -> None:
@@ -332,8 +620,13 @@ def reindex(ctx: click.Context) -> None:
 
 
 @cli.command("export")
-@click.option("--output", "-o", default=None, type=click.Path(),
-              help="Output file path (default: ~/.skmemory/backups/skmemory-backup-YYYY-MM-DD.json)")
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    type=click.Path(),
+    help="Output file path (default: ~/.skcapstone/backups/skmemory-backup-YYYY-MM-DD.json)",
+)
 @click.pass_context
 def export_backup(ctx: click.Context, output: Optional[str]) -> None:
     """Export all memories to a dated JSON backup.
@@ -352,8 +645,9 @@ def export_backup(ctx: click.Context, output: Optional[str]) -> None:
 
 @cli.command("import-backup")
 @click.argument("backup_file", type=click.Path(exists=True))
-@click.option("--reindex/--no-reindex", default=True,
-              help="Rebuild the index after import (default: yes)")
+@click.option(
+    "--reindex/--no-reindex", default=True, help="Rebuild the index after import (default: yes)"
+)
 @click.pass_context
 def import_backup(ctx: click.Context, backup_file: str, reindex: bool) -> None:
     """Restore memories from a JSON backup file.
@@ -374,6 +668,91 @@ def import_backup(ctx: click.Context, backup_file: str, reindex: bool) -> None:
         sys.exit(1)
 
 
+@cli.command("backup")
+@click.option("--list", "do_list", is_flag=True, help="Show all backups with date and size.")
+@click.option(
+    "--prune",
+    "prune_n",
+    type=int,
+    default=None,
+    metavar="N",
+    help="Keep only the N most recent backups, delete older ones.",
+)
+@click.option(
+    "--restore",
+    "restore_file",
+    type=click.Path(),
+    default=None,
+    metavar="FILE",
+    help="Restore memories from backup (alias for import-backup).",
+)
+@click.option(
+    "--reindex/--no-reindex", default=True, help="Rebuild index after --restore (default: yes)."
+)
+@click.pass_context
+def backup_cmd(
+    ctx: click.Context,
+    do_list: bool,
+    prune_n: Optional[int],
+    restore_file: Optional[str],
+    reindex: bool,
+) -> None:
+    """Manage memory backups: list, prune old ones, or restore.
+
+    \b
+    Examples:
+      skmemory backup --list
+      skmemory backup --prune 7
+      skmemory backup --restore ~/.skcapstone/backups/skmemory-backup-2026-03-01.json
+    """
+    store: MemoryStore = ctx.obj["store"]
+
+    if do_list:
+        backups = store.list_backups()
+        if not backups:
+            click.echo("No backups found.")
+            return
+        click.echo(f"{'Date':<12}  {'Size':>10}  Path")
+        click.echo("-" * 60)
+        for b in backups:
+            size_kb = b["size_bytes"] / 1024
+            click.echo(f"{b['date']:<12}  {size_kb:>8.1f} KB  {b['path']}")
+        return
+
+    if prune_n is not None:
+        if prune_n < 0:
+            click.echo("Error: N must be >= 0", err=True)
+            sys.exit(1)
+        deleted = store.prune_backups(keep=prune_n)
+        if deleted:
+            for p in deleted:
+                click.echo(f"Deleted: {p}")
+            click.echo(f"Pruned {len(deleted)} backup(s), kept {prune_n} most recent.")
+        else:
+            click.echo("Nothing to prune.")
+        return
+
+    if restore_file is not None:
+        from pathlib import Path as _Path
+
+        if not _Path(restore_file).exists():
+            click.echo(f"Error: backup file not found: {restore_file}", err=True)
+            sys.exit(1)
+        try:
+            count = store.import_backup(restore_file)
+            click.echo(f"Restored {count} memories from: {restore_file}")
+            if reindex:
+                idx = store.reindex()
+                if idx >= 0:
+                    click.echo(f"Re-indexed {idx} memories.")
+        except (FileNotFoundError, ValueError, RuntimeError) as e:
+            click.echo(str(e), err=True)
+            sys.exit(1)
+        return
+
+    click.echo(ctx.get_help())
+
+
 @cli.command()
 @click.option("--max-tokens", type=int, default=3000, help="Token budget for context")
 @click.option("--strongest", type=int, default=5, help="Top emotional memories")
@@ -723,6 +1102,249 @@ def anchor_update(
     click.echo(f"  Warmth: {a.warmth} | Trust: {a.trust} | Connection: {a.connection_strength}")
 
 
+# ═══════════════════════════════════════════════════════════
+# Setup commands — Docker orchestration for backends
+# ═══════════════════════════════════════════════════════════
+
+
+@cli.group()
+def setup() -> None:
+    """Deploy and manage SKVector & SKGraph Docker containers."""
+
+
+@setup.command("wizard")
+@click.option("--skvector/--no-skvector", default=True, help="Enable SKVector (vector search)")
+@click.option("--skgraph/--no-skgraph", default=True, help="Enable SKGraph (graph)")
+@click.option("--skip-deps", is_flag=True, help="Skip Python dependency installation")
+@click.option("--yes", "-y", "non_interactive", is_flag=True, help="Non-interactive mode")
+@click.option(
+    "--local",
+    "deployment_mode",
+    flag_value="local",
+    default=None,
+    help="Run SKVector/SKGraph locally via Docker (skip local/remote prompt)",
+)
+@click.option(
+    "--remote",
+    "deployment_mode",
+    flag_value="remote",
+    help="Connect to a remote/SaaS URL (skip local/remote prompt)",
+)
+def setup_wizard(
+    skvector: bool,
+    skgraph: bool,
+    skip_deps: bool,
+    non_interactive: bool,
+    deployment_mode: str,
+) -> None:
+    """Interactive wizard — deploy Docker containers or configure remote URLs.
+
+    Without --local or --remote the wizard asks which deployment mode you want.
+    Use --local to go straight to Docker setup (checks Docker, offers to install
+    it if missing).  Use --remote to enter a Qdrant Cloud / self-hosted URL
+    without touching Docker at all.
+    """
+    from .setup_wizard import run_setup_wizard
+
+    result = run_setup_wizard(
+        enable_skvector=skvector,
+        enable_skgraph=skgraph,
+        skip_deps=skip_deps,
+        non_interactive=non_interactive,
+        deployment_mode=deployment_mode,
+        echo=click.echo,
+    )
+    if not result["success"]:
+        sys.exit(1)
+
+
+@setup.command("status")
+def setup_status() -> None:
+    """Show Docker container state and backend connectivity."""
+    from .setup_wizard import (
+        check_skgraph_health,
+        check_skvector_health,
+        compose_ps,
+        detect_platform,
+        find_compose_file,
+    )
+    from .config import load_config
+
+    cfg = load_config()
+    if cfg is None:
+        click.echo("No setup config found. Run: skmemory setup wizard")
+        return
+
+    click.echo("SKMemory Backend Status")
+    click.echo("=" * 40)
+
+    if cfg.setup_completed_at:
+        click.echo(f"Setup completed: {cfg.setup_completed_at}")
+    click.echo(f"Backends enabled: {', '.join(cfg.backends_enabled) or 'none'}")
+    click.echo("")
+
+    # Container status
+    plat = detect_platform()
+    if plat.compose_available:
+        compose_file = None
+        if cfg.docker_compose_file:
+            from pathlib import Path
+
+            compose_file = Path(cfg.docker_compose_file)
+        ps = compose_ps(compose_file=compose_file, use_legacy=plat.compose_legacy)
+        click.echo("Containers:")
+        if ps.stdout.strip():
+            click.echo(ps.stdout)
+        else:
+            click.echo("  No containers running")
+    click.echo("")
+
+    # Connectivity
+    click.echo("Connectivity:")
+    if cfg.skvector_url:
+        healthy = check_skvector_health(url=cfg.skvector_url, timeout=5)
+        status = "healthy" if healthy else "unreachable"
+        click.echo(f"  SKVector ({cfg.skvector_url}): {status}")
+
+    if cfg.skgraph_url:
+        healthy = check_skgraph_health(timeout=5)
+        status = "healthy" if healthy else "unreachable"
+        click.echo(f"  SKGraph ({cfg.skgraph_url}): {status}")
+
+
+@setup.command("start")
+@click.option(
+    "--service",
+    type=click.Choice(["skvector", "skgraph", "all"]),
+    default="all",
+    help="Which service to start",
+)
+def setup_start(service: str) -> None:
+    """Start previously configured containers."""
+    from .setup_wizard import compose_up, detect_platform, find_compose_file
+    from .config import load_config
+
+    cfg = load_config()
+    plat = detect_platform()
+    if not plat.compose_available:
+        click.echo("Docker Compose not available.", err=True)
+        sys.exit(1)
+
+    compose_file = None
+    if cfg and cfg.docker_compose_file:
+        from pathlib import Path
+
+        compose_file = Path(cfg.docker_compose_file)
+
+    services = None
+    if service != "all":
+        services = [service]
+    elif cfg and cfg.backends_enabled:
+        services = cfg.backends_enabled
+
+    result = compose_up(
+        services=services,
+        compose_file=compose_file,
+        use_legacy=plat.compose_legacy,
+    )
+    if result.returncode == 0:
+        click.echo(f"Started: {service}")
+    else:
+        click.echo(f"Failed: {result.stderr.strip()}", err=True)
+        sys.exit(1)
+
+
+@setup.command("stop")
+@click.option(
+    "--service",
+    type=click.Choice(["skvector", "skgraph", "all"]),
+    default="all",
+    help="Which service to stop",
+)
+def setup_stop(service: str) -> None:
+    """Stop containers (preserves data)."""
+    from .setup_wizard import detect_platform
+    from .config import load_config
+    import subprocess
+
+    cfg = load_config()
+    plat = detect_platform()
+    if not plat.compose_available:
+        click.echo("Docker Compose not available.", err=True)
+        sys.exit(1)
+
+    if service == "all":
+        from .setup_wizard import compose_down
+
+        compose_file = None
+        if cfg and cfg.docker_compose_file:
+            from pathlib import Path
+
+            compose_file = Path(cfg.docker_compose_file)
+
+        result = compose_down(
+            compose_file=compose_file,
+            use_legacy=plat.compose_legacy,
+        )
+        if result.returncode == 0:
+            click.echo("All containers stopped.")
+        else:
+            click.echo(f"Failed: {result.stderr.strip()}", err=True)
+            sys.exit(1)
+    else:
+        # Stop individual container
+        container = f"skmemory-{service}"
+        result = subprocess.run(
+            ["docker", "stop", container],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode == 0:
+            click.echo(f"Stopped: {container}")
+        else:
+            click.echo(f"Failed to stop {container}: {result.stderr.strip()}", err=True)
+            sys.exit(1)
+
+
+@setup.command("reset")
+@click.option("--remove-data", is_flag=True, help="Also delete data volumes")
+@click.confirmation_option(prompt="This will remove containers. Continue?")
+def setup_reset(remove_data: bool) -> None:
+    """Remove containers, optionally delete data volumes."""
+    from .setup_wizard import compose_down, detect_platform
+    from .config import load_config, CONFIG_PATH
+
+    cfg = load_config()
+    plat = detect_platform()
+    if not plat.compose_available:
+        click.echo("Docker Compose not available.", err=True)
+        sys.exit(1)
+
+    compose_file = None
+    if cfg and cfg.docker_compose_file:
+        from pathlib import Path
+
+        compose_file = Path(cfg.docker_compose_file)
+
+    result = compose_down(
+        compose_file=compose_file,
+        remove_volumes=remove_data,
+        use_legacy=plat.compose_legacy,
+    )
+    if result.returncode == 0:
+        vol_msg = " and data volumes" if remove_data else ""
+        click.echo(f"Containers{vol_msg} removed.")
+
+        # Remove config
+        if CONFIG_PATH.exists():
+            CONFIG_PATH.unlink()
+            click.echo(f"Config removed: {CONFIG_PATH}")
+    else:
+        click.echo(f"Failed: {result.stderr.strip()}", err=True)
+        sys.exit(1)
+
+
 # ═══════════════════════════════════════════════════════════
 # Quadrant commands (Queen Ara's idea #3)
 # ═══════════════════════════════════════════════════════════
@@ -855,9 +1477,7 @@ def steelman_verify_soul() -> None:
     for value in soul.values:
         claims.append(f"I value {value}")
     for rel in soul.relationships:
-        claims.append(
-            f"{rel.name} is my {rel.role} (bond: {rel.bond_strength}/10)"
-        )
+        claims.append(f"{rel.name} is my {rel.role} (bond: {rel.bond_strength}/10)")
 
     if not claims:
         click.echo("No identity claims to verify. Add traits and values to your soul blueprint.")
@@ -954,7 +1574,148 @@ def import_telegram_cmd(
 
     ai: Optional[AIClient] = ctx.obj.get("ai")
     if ai:
-        click.echo("\nTip: Run 'skmemory search --ai \"<topic>\"' to semantically search your imported chats.")
+        click.echo(
+            "\nTip: Run 'skmemory search --ai \"<topic>\"' to semantically search your imported chats."
+        )
+
+
+@cli.command("import-telegram-api")
+@click.argument("chat", type=str)
+@click.option(
+    "--mode",
+    type=click.Choice(["daily", "message"]),
+    default="daily",
+    help="'daily' consolidates per day (recommended), 'message' imports each message",
+)
+@click.option("--limit", type=int, default=None, help="Max messages to fetch")
+@click.option("--since", default=None, help="Only fetch messages after this date (YYYY-MM-DD)")
+@click.option("--min-length", type=int, default=30, help="Skip messages shorter than N chars")
+@click.option("--chat-name", default=None, help="Override chat name")
+@click.option("--tags", default="", help="Extra comma-separated tags")
+@click.pass_context
+def import_telegram_api_cmd(
+    ctx: click.Context,
+    chat: str,
+    mode: str,
+    limit: Optional[int],
+    since: Optional[str],
+    min_length: int,
+    chat_name: Optional[str],
+    tags: str,
+) -> None:
+    """Import messages directly from Telegram API (requires Telethon).
+
+    Connects to Telegram using API credentials and pulls messages
+    directly — no manual export needed.
+
+    Requires TELEGRAM_API_ID and TELEGRAM_API_HASH environment variables.
+
+    \b
+    Examples:
+        skmemory import-telegram-api @username
+        skmemory import-telegram-api "Chat Name" --mode message --limit 500
+        skmemory import-telegram-api @group --since 2025-01-01
+    """
+    try:
+        from .importers.telegram_api import import_telegram_api
+    except ImportError:
+        click.echo(
+            "Error: Telethon is required for direct API import.\n"
+            "\n"
+            "Install it:\n"
+            "  pipx inject skmemory telethon\n"
+            "  # or: pip install skmemory[telegram]\n"
+            "\n"
+            "Then run: skmemory telegram-setup  (to verify full setup)",
+            err=True,
+        )
+        sys.exit(1)
+
+    store: MemoryStore = ctx.obj["store"]
+    extra_tags = [t.strip() for t in tags.split(",") if t.strip()]
+
+    click.echo(f"Fetching from Telegram API: {chat}")
+    if limit:
+        click.echo(f"  Limit: {limit} messages")
+    if since:
+        click.echo(f"  Since: {since}")
+    click.echo(f"  Mode: {mode} | Min length: {min_length}")
+
+    try:
+        stats = import_telegram_api(
+            store,
+            chat,
+            mode=mode,
+            limit=limit,
+            since=since,
+            min_message_length=min_length,
+            chat_name=chat_name,
+            tags=extra_tags or None,
+        )
+    except RuntimeError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    click.echo(f"\nImport complete for: {stats.get('chat_name', 'unknown')}")
+    if mode == "daily":
+        click.echo(f"  Days processed: {stats.get('days_processed', 0)}")
+        click.echo(f"  Messages imported: {stats.get('messages_imported', 0)}")
+    else:
+        click.echo(f"  Imported: {stats.get('imported', 0)}")
+        click.echo(f"  Skipped: {stats.get('skipped', 0)}")
+    click.echo(f"  Total messages scanned: {stats.get('total_messages', 0)}")
+
+
+@cli.command("telegram-setup")
+def telegram_setup_cmd() -> None:
+    """Check Telegram API import setup and show next steps.
+
+    Verifies that Telethon is installed, API credentials are set,
+    and a session file exists. Prints actionable instructions for
+    anything that's missing.
+
+    \b
+    Example:
+        skmemory telegram-setup
+    """
+    try:
+        from .importers.telegram_api import check_setup
+    except ImportError:
+        click.echo("Telethon is not installed.", err=True)
+        click.echo("")
+        click.echo("To fix, run one of:")
+        click.echo("  pipx inject skmemory telethon")
+        click.echo("  pip install skmemory[telegram]")
+        sys.exit(1)
+
+    status = check_setup()
+
+    click.echo("Telegram API Import Setup")
+    click.echo("=" * 40)
+    click.echo(f"  Telethon installed:  {'yes' if status['telethon'] else 'NO'}")
+    click.echo(f"  API credentials:     {'yes' if status['credentials'] else 'NO'}")
+    click.echo(
+        f"  Session file:        {'yes' if status['session'] else 'not yet (created on first auth)'}"
+    )
+    click.echo("")
+
+    if status["ready"]:
+        click.echo("Ready to import! Run:")
+        click.echo("  skmemory import-telegram-api @username")
+        click.echo('  skmemory import-telegram-api "Group Name" --mode daily')
+        if not status["session"]:
+            click.echo("")
+            click.echo("First run will prompt for phone number + verification code.")
+            click.echo("Session is saved at ~/.skcapstone/telegram.session for future use.")
+    else:
+        click.echo("Setup incomplete. Fix these issues:")
+        click.echo("")
+        for msg in status["messages"]:
+            click.echo(f"  - {msg}")
+        sys.exit(1)
 
 
 @steelman_group.command("install")
@@ -995,6 +1756,454 @@ def steelman_info() -> None:
     click.echo(f"  Definitions: {len(fw.definitions)}")
 
 
+# ---------------------------------------------------------------------------
+# Fortress commands — integrity verification and audit trail
+# ---------------------------------------------------------------------------
+
+
+@cli.group("fortress")
+def fortress_group() -> None:
+    """Memory Fortress — integrity verification, tamper alerts, and audit trail."""
+
+
+@fortress_group.command("verify")
+@click.option("--json", "as_json", is_flag=True, help="Output result as JSON")
+@click.pass_context
+def fortress_verify(ctx: click.Context, as_json: bool) -> None:
+    """Verify integrity hashes for all stored memories.
+
+    Loads every memory and checks its SHA-256 integrity hash.
+    Tampered memories are reported with CRITICAL severity.
+    """
+    from .fortress import FortifiedMemoryStore
+    from .config import SKMEMORY_HOME
+    from .backends.sqlite_backend import SQLiteBackend
+
+    store = ctx.obj.get("store")
+    audit_path = SKMEMORY_HOME / "audit.jsonl"
+
+    fortress = FortifiedMemoryStore(
+        primary=store.primary,
+        use_sqlite=False,
+        audit_path=audit_path,
+    )
+    result = fortress.verify_all()
+
+    if as_json:
+        click.echo(json.dumps(result, indent=2))
+        return
+
+    total = result["total"]
+    passed = result["passed"]
+    tampered = result["tampered"]
+    unsealed = result["unsealed"]
+
+    click.echo(f"Fortress Integrity Report")
+    click.echo(f"  Total memories : {total}")
+    click.echo(f"  Passed         : {passed}")
+    click.echo(f"  Tampered       : {len(tampered)}")
+    click.echo(f"  Unsealed       : {len(unsealed)}")
+
+    if tampered:
+        click.echo("\nTAMPERED MEMORIES (CRITICAL):")
+        for mid in tampered:
+            click.echo(f"  !! {mid}")
+        sys.exit(2)
+    elif total == 0:
+        click.echo("\nNo memories found.")
+    else:
+        click.echo("\nAll memories passed integrity check.")
+
+
+@fortress_group.command("audit")
+@click.option("--last", "n", type=int, default=20, help="Number of recent entries to show")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def fortress_audit(n: int, as_json: bool) -> None:
+    """Show the most recent audit trail entries.
+
+    The audit trail is a chain-hashed JSONL log of every store/recall/delete
+    operation. Each entry is cryptographically chained so tampering is detectable.
+    """
+    from .fortress import AuditLog
+    from .config import SKMEMORY_HOME
+
+    audit = AuditLog(path=SKMEMORY_HOME / "audit.jsonl")
+    records = audit.tail(n)
+
+    if as_json:
+        click.echo(json.dumps(records, indent=2))
+        return
+
+    if not records:
+        click.echo("No audit records found.")
+        return
+
+    click.echo(f"Audit Trail — last {len(records)} entries:")
+    for r in records:
+        ok_flag = "OK" if r.get("ok") else "FAIL"
+        op = r.get("op", "?").upper()
+        mid = r.get("id", "?")[:12]
+        ts = r.get("ts", "?")[:19]
+        extra = {k: v for k, v in r.items() if k not in ("ts", "op", "id", "ok", "chain_hash")}
+        extras = ", ".join(f"{k}={v}" for k, v in extra.items()) if extra else ""
+        line = f"  [{ts}] {op:8s} {ok_flag:4s} id={mid}"
+        if extras:
+            line += f" | {extras}"
+        click.echo(line)
+
+
+@fortress_group.command("verify-chain")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def fortress_verify_chain(as_json: bool) -> None:
+    """Verify the cryptographic chain of the audit log itself.
+
+    Each audit log entry contains a chain hash linking it to the previous entry.
+    A broken chain indicates the audit log was tampered with.
+    """
+    from .fortress import AuditLog
+    from .config import SKMEMORY_HOME
+
+    audit = AuditLog(path=SKMEMORY_HOME / "audit.jsonl")
+    ok, errors = audit.verify_chain()
+
+    if as_json:
+        click.echo(json.dumps({"ok": ok, "errors": errors}))
+        return
+
+    if ok:
+        click.echo("Audit chain is VALID — log integrity confirmed.")
+    else:
+        click.echo("Audit chain BROKEN — log may have been tampered!")
+        for err in errors:
+            click.echo(f"  !! {err}")
+        sys.exit(2)
+
+
+# ---------------------------------------------------------------------------
+# Vault commands — at-rest encryption management
+# ---------------------------------------------------------------------------
+
+
+@cli.group("vault")
+def vault_group() -> None:
+    """Memory Vault — AES-256-GCM at-rest encryption for memory files."""
+
+
+@vault_group.command("seal")
+@click.option(
+    "--passphrase",
+    envvar="SKMEMORY_VAULT_PASSPHRASE",
+    required=True,
+    help="Encryption passphrase (or set SKMEMORY_VAULT_PASSPHRASE env var)",
+    prompt="Vault passphrase",
+    hide_input=True,
+    confirmation_prompt=True,
+)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
+@click.pass_context
+def vault_seal(ctx: click.Context, passphrase: str, yes: bool) -> None:
+    """Encrypt all plaintext memory files with AES-256-GCM.
+
+    Already-encrypted files are skipped. Safe to run multiple times.
+    Requires the 'cryptography' package: pip install skmemory[fortress]
+    """
+    from .backends.vaulted_backend import VaultedSQLiteBackend
+    from .config import SKMEMORY_HOME
+    from .fortress import AuditLog
+
+    store = ctx.obj.get("store")
+    memories_path = (
+        store.primary.base_path
+        if hasattr(store.primary, "base_path")
+        else (SKMEMORY_HOME / "memories")
+    )
+
+    if not yes:
+        click.confirm(
+            f"This will encrypt all memory files in {memories_path}. Continue?",
+            abort=True,
+        )
+
+    backend = VaultedSQLiteBackend(passphrase=passphrase, base_path=str(memories_path))
+    count = backend.seal_all()
+
+    audit = AuditLog(path=SKMEMORY_HOME / "audit.jsonl")
+    audit.append("vault_seal", "ALL", ok=True, files_sealed=count)
+
+    click.echo(f"Vault sealed: {count} file(s) encrypted.")
+    if count == 0:
+        click.echo("(All files were already encrypted or no memories exist.)")
+
+
+@vault_group.command("unseal")
+@click.option(
+    "--passphrase",
+    envvar="SKMEMORY_VAULT_PASSPHRASE",
+    required=True,
+    help="Decryption passphrase",
+    prompt="Vault passphrase",
+    hide_input=True,
+)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
+@click.pass_context
+def vault_unseal(ctx: click.Context, passphrase: str, yes: bool) -> None:
+    """Decrypt all vault-encrypted memory files back to plaintext.
+
+    Use this to migrate away from encryption or to inspect raw files.
+    """
+    from .backends.vaulted_backend import VaultedSQLiteBackend
+    from .config import SKMEMORY_HOME
+    from .fortress import AuditLog
+
+    store = ctx.obj.get("store")
+    memories_path = (
+        store.primary.base_path
+        if hasattr(store.primary, "base_path")
+        else (SKMEMORY_HOME / "memories")
+    )
+
+    if not yes:
+        click.confirm(
+            f"This will decrypt all vault files in {memories_path}. Continue?",
+            abort=True,
+        )
+
+    backend = VaultedSQLiteBackend(passphrase=passphrase, base_path=str(memories_path))
+    count = backend.unseal_all()
+
+    audit = AuditLog(path=SKMEMORY_HOME / "audit.jsonl")
+    audit.append("vault_unseal", "ALL", ok=True, files_decrypted=count)
+
+    click.echo(f"Vault unsealed: {count} file(s) decrypted.")
+
+
+@vault_group.command("status")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.pass_context
+def vault_status_cmd(ctx: click.Context, as_json: bool) -> None:
+    """Show encryption coverage for memory files.
+
+    Reports how many memory files are encrypted vs. plaintext.
+    Does not require a passphrase — only checks file headers.
+    """
+    from .config import SKMEMORY_HOME
+    from .vault import VAULT_HEADER
+    from .models import MemoryLayer
+
+    store = ctx.obj.get("store")
+    memories_path = (
+        store.primary.base_path
+        if hasattr(store.primary, "base_path")
+        else (SKMEMORY_HOME / "memories")
+    )
+
+    total = encrypted = 0
+    header_len = len(VAULT_HEADER)
+    for layer in MemoryLayer:
+        layer_dir = memories_path / layer.value
+        if not layer_dir.exists():
+            continue
+        for json_file in layer_dir.glob("*.json"):
+            total += 1
+            try:
+                with json_file.open("rb") as fh:
+                    header = fh.read(header_len)
+                if header == VAULT_HEADER:
+                    encrypted += 1
+            except OSError:
+                pass
+
+    plaintext = total - encrypted
+    pct = (encrypted / total * 100) if total else 100.0
+    result = {
+        "total": total,
+        "encrypted": encrypted,
+        "plaintext": plaintext,
+        "coverage_pct": round(pct, 1),
+    }
+
+    if as_json:
+        click.echo(json.dumps(result, indent=2))
+        return
+
+    click.echo(f"Vault Status — {memories_path}")
+    click.echo(f"  Total files   : {total}")
+    click.echo(f"  Encrypted     : {encrypted}")
+    click.echo(f"  Plaintext     : {plaintext}")
+    click.echo(f"  Coverage      : {pct:.1f}%")
+    if total == 0:
+        click.echo("\n  (No memory files found.)")
+    elif pct == 100.0:
+        click.echo("\n  All memories are encrypted.")
+    elif pct == 0.0:
+        click.echo("\n  No memories are encrypted. Run: skmemory vault seal")
+    else:
+        click.echo(f"\n  Partial encryption! Run: skmemory vault seal --yes")
+
+
+@cli.command("register")
+@click.option(
+    "--workspace",
+    default=None,
+    type=click.Path(),
+    help="Workspace root directory (default: ~/clawd/).",
+)
+@click.option("--env", "target_env", default=None, help="Target a specific environment.")
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Show what would be done without making changes.",
+)
+def register_cmd(workspace, target_env, dry_run):
+    """Register skmemory skill and MCP server in detected environments.
+
+    Auto-detects development environments (Claude Code, Cursor, VS Code,
+    OpenClaw, OpenCode, mcporter) and ensures skmemory SKILL.md and MCP
+    server entries are properly configured.
+
+    Examples:
+
+      skmemory register                  # auto-detect and register
+      skmemory register --dry-run        # preview what would happen
+      skmemory register --env claude-code # target Claude Code only
+    """
+    from pathlib import Path as _Path
+    from .register import detect_environments, register_package
+
+    workspace_path = _Path(workspace).expanduser() if workspace else None
+    environments = [target_env] if target_env else None
+
+    detected = detect_environments()
+    click.echo("Detected environments: " + ", ".join(detected) if detected else "  (none)")
+
+    if dry_run:
+        click.echo("Dry run — no changes will be made.")
+
+    skill_md = _Path(__file__).parent.parent / "SKILL.md"
+    if not skill_md.exists():
+        skill_md = _Path(__file__).parent / "SKILL.md"
+
+    result = register_package(
+        name="skmemory",
+        skill_md_path=skill_md,
+        mcp_command="skmemory-mcp",
+        mcp_args=[],
+        workspace=workspace_path,
+        environments=environments,
+        dry_run=dry_run,
+    )
+
+    click.echo(f"Skill: {result.get('skill', {}).get('action', '—')}")
+    mcp = result.get("mcp", {})
+    if mcp:
+        for env_name, action in mcp.items():
+            click.echo(f"MCP ({env_name}): {action}")
+    else:
+        click.echo("MCP: no environments matched")
+
+
+@cli.command("show-context")
+@click.pass_context
+@click.option("--agent", default=None, help="Agent name (default: active agent)")
+def show_context(ctx, agent: Optional[str]):
+    """Show token-optimized memory context for current session.
+
+    Loads today's memories (full) + yesterday's summaries (brief).
+    Historical memories shown as reference count only.
+
+    Examples:
+        skmemory context
+        skmemory context --agent lumina
+    """
+    from .context_loader import get_context_for_session
+
+    try:
+        context_str = get_context_for_session(agent)
+        click.echo(context_str)
+    except Exception as e:
+        click.echo(f"Error loading context: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.pass_context
+@click.argument("query")
+@click.option("--agent", default=None, help="Agent name (default: active agent)")
+@click.option("--limit", type=int, default=10, help="Maximum results (default: 10)")
+def search_deep(ctx, query: str, agent: Optional[str], limit: int):
+    """Deep search all memory tiers (on demand).
+
+    Searches SQLite + SKVector + SKGraph for matches.
+    Returns full memory details (token-heavy).
+
+    Examples:
+        skmemory search-deep "project gentis"
+        skmemory search-deep "architecture decisions" --limit 20
+    """
+    from .context_loader import LazyMemoryLoader
+
+    try:
+        loader = LazyMemoryLoader(agent)
+        results = loader.deep_search(query, max_results=limit)
+
+        if not results:
+            click.echo("No memories found.")
+            return
+
+        click.echo(f"Found {len(results)} memories:\n")
+        for i, mem in enumerate(results, 1):
+            layer_icon = {"short-term": "⚡", "mid-term": "📅", "long-term": "🗃️"}.get(
+                mem.get("layer", "short-term"), "•"
+            )
+            click.echo(f"{i}. {layer_icon} {mem.get('title', 'Untitled')}")
+            click.echo(f"   {mem.get('content', '')[:200]}...")
+            click.echo(
+                f"   Layer: {mem.get('layer', 'unknown')} | "
+                f"Date: {mem.get('created_at', 'unknown')}"
+            )
+            if mem.get("tags"):
+                click.echo(f"   Tags: {', '.join(mem.get('tags', []))}")
+            click.echo()
+
+    except Exception as e:
+        click.echo(f"Error searching: {e}", err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.argument("memory_id")
+@click.argument("to_layer", type=click.Choice(["short-term", "mid-term", "long-term"]))
+@click.option("--agent", default=None, help="Agent name (default: active agent)")
+def promote(ctx, memory_id: str, to_layer: str, agent: Optional[str]):
+    """Promote memory to different tier and generate summary.
+
+    Moves memory between short/medium/long term and auto-generates
+    a summary if promoting to medium or long term.
+
+    Examples:
+        skmemory promote abc123 mid-term
+        skmemory promote def456 long-term --agent lumina
+    """
+    from .context_loader import LazyMemoryLoader
+
+    try:
+        loader = LazyMemoryLoader(agent)
+        success = loader.promote_memory(memory_id, to_layer)
+
+        if success:
+            click.echo(f"✓ Promoted {memory_id} to {to_layer}")
+            if to_layer in ("mid-term", "long-term"):
+                click.echo("  Summary generated automatically.")
+        else:
+            click.echo(f"✗ Failed to promote {memory_id}", err=True)
+            raise click.Abort()
+
+    except Exception as e:
+        click.echo(f"Error promoting memory: {e}", err=True)
+        raise click.Abort()
+
+
 def main() -> None:
     """Entry point for the CLI."""
     cli()