superlocalmemory 4.0.1 → 4.0.3

package/src/superlocalmemory/cli/commands.py

@@ -321,25 +321,22 @@ def cmd_session(args: Namespace) -> None:
         print("Session close failed (daemon unreachable?)")
 
 
+def _cmd_upgrade_hosts(args: Namespace) -> None:
+    """Run the consented host-integration refresh command."""
+    from superlocalmemory.cli.host_upgrades import cmd_upgrade_hosts
+
+    cmd_upgrade_hosts(args)
+
+
 def dispatch(args: Namespace) -> None:
     """Route CLI command to the appropriate handler."""
-    # Auto-install/upgrade hooks on version change (single file read, ~0.1ms)
-    if (
-        args.command not in ("hooks", "codex", "init", "mcp")
-        and not getattr(args, "dry_run", False)
-    ):
-        try:
-            from superlocalmemory.hooks.claude_code_hooks import auto_install_if_needed
-            auto_install_if_needed()
-        except Exception:
-            pass
-
     handlers = {
         "init": cmd_init,
         "setup": cmd_setup,
         "mode": cmd_mode,
         "provider": cmd_provider,
         "connect": cmd_connect,
+        "upgrade-hosts": _cmd_upgrade_hosts,
         "migrate": cmd_migrate,
         "list": cmd_list,
         "remember": cmd_remember,
@@ -349,6 +346,7 @@ def dispatch(args: Namespace) -> None:
         "delete": cmd_delete,
         "update": cmd_update,
         "status": cmd_status,
+        "brain": cmd_brain,
         "health": cmd_health,
         "doctor": cmd_doctor,
         "trace": cmd_trace,
@@ -1486,10 +1484,27 @@ def cmd_recall(args: Namespace) -> None:
                     _sys.exit(1)
                 _as_of = _as_of_norm
             as_of_qs = f"&as_of={quote(_as_of)}" if _as_of else ""
+            def _strict_time_qs(attr: str, parameter: str) -> str:
+                raw = getattr(args, attr, "") or ""
+                if not raw:
+                    return ""
+                from superlocalmemory.retrieval.temporal_utils import normalize_as_of
+                normalized = normalize_as_of(raw)
+                if normalized is None:
+                    import sys as _sys
+                    _sys.stderr.write(
+                        f"Error: invalid --{attr.replace('_', '-')} value: {raw!r}\n"
+                    )
+                    _sys.exit(1)
+                return f"&{parameter}={quote(normalized)}"
+            known_as_of_qs = _strict_time_qs("known_as_of", "known_as_of")
+            valid_at_qs = _strict_time_qs("valid_at", "valid_at")
+            unknown_qs = "&include_unknown=true" if getattr(args, "include_unknown", False) else ""
             result = daemon_request(
                 "GET",
                 f"/recall?q={quote(args.query)}&limit={args.limit}"
-                f"&session_id={quote(session_id)}{fast_qs}{scope_qs}{window_qs}{as_of_qs}",
+                f"&session_id={quote(session_id)}{fast_qs}{scope_qs}{window_qs}{as_of_qs}"
+                f"{known_as_of_qs}{valid_at_qs}{unknown_qs}",
             )
             if result and "results" in result:
                 # Format daemon response same as engine response
@@ -2133,6 +2148,7 @@ _COMMAND_GROUPS: list[tuple[str, list[tuple[str, str]]]] = [
         ("mode", "Switch memory mode: a (local) / b (Ollama) / c (cloud)"),
         ("provider", "Configure the cloud LLM provider + API key (Mode C)"),
         ("connect", "Auto-configure detected IDEs (Cursor, VS Code, …)"),
+        ("upgrade-hosts", "Preview or explicitly refresh existing SLM host integrations"),
         ("hooks", "Install/inspect Claude Code hooks"),
         ("codex", "Configure the Codex / OpenAI integration"),
     ]),
@@ -2188,6 +2204,7 @@ _COMMAND_GROUPS: list[tuple[str, list[tuple[str, str]]]] = [
     ("Learning & maintenance", [
         ("evolve", "Skill-evolution controls"),
         ("observe", "External observation / telemetry ingestion"),
+        ("brain", "Show profile-scoped Living Brain evidence"),
         ("decay", "Run a forgetting/decay pass"),
         ("consolidate", "Merge/consolidate related memories"),
         ("quantize", "Quantize embeddings to save space"),
@@ -2949,14 +2966,6 @@ def cmd_mcp(_args: Namespace) -> None:
     except Exception:
         pass  # A diagnostic must never prevent the server from starting.
 
-    # Auto-install hooks on MCP startup (fast path: ~0.1ms if already current)
-    # CRITICAL: No stdout — MCP uses stdio transport, any print corrupts protocol
-    try:
-        from superlocalmemory.hooks.claude_code_hooks import auto_install_if_needed
-        auto_install_if_needed()
-    except Exception:
-        pass
-
     from superlocalmemory.mcp.server import server
 
     server.run(transport="stdio")
@@ -3680,6 +3689,47 @@ def cmd_session_context(args: Namespace) -> None:
         logger.debug("session-context (fast) failed: %s", exc)
 
 
+def cmd_brain(args: Namespace) -> None:
+    """Read the portable, profile-scoped Agent Experience evidence summary.
+
+    This command deliberately opens no memory engine and starts no daemon. It
+    is an indexed ``learning.db`` read, so support scripts and non-technical
+    users can inspect the Living Brain without affecting recall latency.
+    """
+    from superlocalmemory.core.config import SLMConfig
+    from superlocalmemory.infra.data_root import state_path
+    from superlocalmemory.storage.agent_experience import get_profile_receipt_summary
+
+    config = SLMConfig.load()
+    profile_id = config.active_profile
+    data = {
+        "profile_id": profile_id,
+        "agent_experience": get_profile_receipt_summary(
+            state_path("learning.db"), profile_id
+        ),
+        "control_plane": "observation_only",
+    }
+    if getattr(args, "json", False):
+        from superlocalmemory.cli.json_output import json_print
+
+        json_print("brain", data=data, next_actions=[
+            {"command": "slm dashboard", "description": "Open the Living Brain dashboard"},
+        ])
+        return
+    evidence = data["agent_experience"]
+    print("SuperLocalMemory Living Brain")
+    print(f"  Profile: {profile_id}")
+    print(f"  Agent experiences: {evidence['experiences_total']}")
+    print(f"  Claimed evidence authority: {evidence['claimed_evidence_experiences']}")
+    print(f"  Cognitive turns: {evidence['turns_total']}")
+    if evidence["turns_by_state"]:
+        states = ", ".join(
+            f"{state}: {count}" for state, count in sorted(evidence["turns_by_state"].items())
+        )
+        print(f"  Turn states: {states}")
+    print("  Retrieval control: observation only")
+
+
 def cmd_observe(args: Namespace) -> None:
     """Evaluate and auto-capture content from stdin or argument.
 

package/src/superlocalmemory/cli/host_upgrades.py

@@ -0,0 +1,175 @@
+"""Consented, non-destructive upgrades for existing host integrations.
+
+Package installation owns the SLM executable.  This module owns the separate
+operator-approved step that refreshes SLM-owned integration assets.  It never
+discovers a host and edits it implicitly: preview is the default and apply
+requires either explicit hosts or an explicit all-detected acknowledgement.
+"""
+
+from __future__ import annotations
+
+from argparse import Namespace
+from pathlib import Path
+from typing import Any
+
+
+def validate_upgrade_request(*, apply: bool, hosts: list[str], all_detected: bool) -> None:
+    """Reject unbounded mutations before any host filesystem access."""
+    if apply and not hosts and not all_detected:
+        raise ValueError("--apply requires at least one --host or --all-detected")
+    if hosts and all_detected:
+        raise ValueError("choose explicit --host values or --all-detected, not both")
+
+
+def cmd_upgrade_hosts(args: Namespace) -> None:
+    """Preview or explicitly apply host integration refreshes."""
+    hosts = list(getattr(args, "hosts", []) or [])
+    apply = bool(getattr(args, "apply", False))
+    all_detected = bool(getattr(args, "all_detected", False))
+    try:
+        validate_upgrade_request(apply=apply, hosts=hosts, all_detected=all_detected)
+    except ValueError as exc:
+        print(f"Error: {exc}")
+        return
+
+    from superlocalmemory.hooks.portable_kit import supported_ides
+
+    detected = set(_detected_hosts())
+    targets = sorted(detected) if all_detected else (hosts or sorted(detected))
+    managed_hosts = set(supported_ides()) | {"claude-code", "hermes"}
+    unknown = sorted(set(targets) - managed_hosts)
+    if unknown:
+        print(f"Error: unsupported host(s): {', '.join(unknown)}")
+        return
+    if not targets:
+        print("No existing SLM host integrations were detected.")
+        print("Run `slm setup` for first-time setup, or use `--host <name>` to target one host.")
+        return
+
+    operation = "Applying" if apply else "Previewing"
+    print(f"{operation} SLM host upgrades: {', '.join(targets)}")
+    if not apply:
+        print("No host files will be changed. Re-run with --apply and explicit targets to proceed.")
+
+    for host in targets:
+        result = _upgrade_host(host, apply=apply, already_integrated=host in detected)
+        status = result.get("status", "error")
+        detail = result.get("detail", "")
+        print(f"  [{status}] {host}: {detail}")
+
+    if apply:
+        print("Restart affected host applications, then run `slm doctor` to verify SLM itself.")
+
+
+def _detected_hosts(home: Path | None = None) -> list[str]:
+    """Return only hosts already containing an SLM-owned integration block."""
+    from superlocalmemory.hooks.portable_kit import (
+        IDE_MATRIX,
+        _load_config,
+        _ParseError,
+    )
+
+    effective_home = home or Path.home()
+    detected: list[str] = []
+    for host, desc in IDE_MATRIX.items():
+        if not desc.fmt:
+            continue
+        path = effective_home / desc.mcp_path_global
+        try:
+            data = _load_config(path, desc.fmt)
+        except _ParseError:
+            continue
+        if _contains_slm_block(data, desc):
+            detected.append(host)
+
+    # Claude Code's plugin is host-managed. A local SLM hook installation is
+    # the durable evidence that its SLM integration exists; upgrading the
+    # plugin remains an explicit Claude Code marketplace action.
+    try:
+        from superlocalmemory.hooks.claude_code_hooks import check_status
+
+        if check_status().get("installed"):
+            detected.append("claude-code")
+    except Exception:
+        pass
+
+    # Hermes has a native YAML mapping rather than the portable-kit schema.
+    # Detect it for reporting, but never overwrite it with an invented format.
+    hermes_path = effective_home / ".hermes" / "config.yaml"
+    try:
+        hermes = _load_config(hermes_path, "yaml")
+        servers = hermes.get("mcp_servers", {})
+        if isinstance(servers, dict) and "superlocalmemory" in servers:
+            detected.append("hermes")
+    except _ParseError:
+        pass
+    return sorted(set(detected))
+
+
+def _contains_slm_block(data: dict[str, Any], desc: Any) -> bool:
+    if desc.fmt == "yaml":
+        providers = data.get(desc.server_key, [])
+        return isinstance(providers, list) and any(
+            isinstance(item, dict)
+            and item.get("params", {}).get("serverName") == "superlocalmemory"
+            for item in providers
+        )
+    servers = data.get(desc.server_key, {})
+    return isinstance(servers, dict) and "superlocalmemory" in servers
+
+
+def _upgrade_host(host: str, *, apply: bool, already_integrated: bool) -> dict[str, str]:
+    """Refresh assets without degrading a working, host-specific MCP block."""
+    if host == "claude-code":
+        return {
+            "status": "plugin-managed",
+            "detail": "run `claude plugin update superlocalmemory@qualixar` in Claude Code",
+        }
+
+    if host == "hermes":
+        if already_integrated:
+            return {
+                "status": "verified",
+                "detail": "existing native Hermes SLM mapping preserved",
+            }
+        return {
+            "status": "blocked",
+            "detail": "Hermes is not connected; follow docs/ide-setup.md before retrying",
+        }
+
+    if host == "codex" and already_integrated:
+        from superlocalmemory.hooks.codex_assets import install_assets
+        from superlocalmemory.hooks.codex_hooks import install_hooks
+
+        assets, hooks = install_assets(dry_run=not apply), install_hooks(dry_run=not apply)
+        if not assets.get("success") or not hooks.get("success"):
+            return {"status": "blocked", "detail": "could not refresh SLM-owned Codex assets"}
+        action = "would refresh" if not apply else "refreshed"
+        return {
+            "status": "updated" if apply else "preview",
+            "detail": (
+                f"{action} SLM-owned Codex skills, agents, and hooks; "
+                "MCP block preserved"
+            ),
+        }
+
+    if already_integrated:
+        return {
+            "status": "verified",
+            "detail": "existing SLM MCP block preserved; no portable host assets require refresh",
+        }
+
+    # An explicitly named, not-yet-connected host is a first-time connection.
+    # This branch is never reached by --all-detected.
+    from superlocalmemory.hooks.portable_kit import connect_ide
+
+    result = connect_ide(host, dry_run=not apply)
+    if result.get("error"):
+        return {"status": "blocked", "detail": str(result["error"])}
+    action = result.get("mcp_config", "unknown")
+    if not apply:
+        return {"status": "preview", "detail": f"would refresh SLM MCP block ({action})"}
+    return {"status": "updated", "detail": f"SLM MCP block {action}"}
+
+
+__all__ = ("cmd_upgrade_hosts", "validate_upgrade_request")

package/src/superlocalmemory/cli/main.py

@@ -64,17 +64,19 @@ examples:
 documentation:
   Website:    https://superlocalmemory.com
   GitHub:     https://github.com/qualixar/superlocalmemory
-  Paper:      https://arxiv.org/abs/2603.14588
+  Paper:      https://arxiv.org/abs/2608.08253
 """
 
 
 _NO_DAEMON_COMMANDS = {
-    "setup", "mode", "provider", "connect", "migrate", "mcp", "warmup", "hooks", "codex",
+    "setup", "mode", "provider", "connect", "upgrade-hosts", "migrate", "mcp", "warmup", "hooks", "codex",
     "config", "evolve", "db",
     # v3.4.22 escape hatches — never auto-start the daemon on these.
     "disable", "enable", "clear-cache", "reconfigure", "benchmark",
     "rotate-token",
     "evidence",
+    # v4.0.2 receipt summary is a direct read-only learning.db query.
+    "brain",
     "diagnostics",
     # LLD-06 — agents launched through wrap start the daemon on demand.
     "wrap",
@@ -121,12 +123,17 @@ def main() -> None:
         and sys.argv[1] == "connect"
         and "--dry-run" in sys.argv[2:]
     )
+    _is_host_upgrade_preview = (
+        len(sys.argv) >= 2
+        and sys.argv[1] == "upgrade-hosts"
+        and "--apply" not in sys.argv[2:]
+    )
 
     # WP-07: lazy first-run init — runs after hook/mcp fast-paths so stdout
     # is never polluted on those paths (CRIT-3, MCP JSON-RPC purity).
     # Guarded: any failure must not crash the CLI (AC4).
     _is_mcp_cmd = len(sys.argv) >= 2 and sys.argv[1] == "mcp"
-    if not _is_mcp_cmd and not _is_metadata_cmd and not _is_connect_dry_run:
+    if not _is_mcp_cmd and not _is_metadata_cmd and not _is_connect_dry_run and not _is_host_upgrade_preview:
         try:
             from superlocalmemory.cli._lazy_init import _ensure_initialized
             _ensure_initialized()
@@ -146,7 +153,7 @@ def main() -> None:
 
     # One-time post-upgrade banner — silent for fresh installs and
     # same-version runs. Guarded against I/O errors internally.
-    if not _is_mcp_stdio and not _is_metadata_cmd and not _is_connect_dry_run:
+    if not _is_mcp_stdio and not _is_metadata_cmd and not _is_connect_dry_run and not _is_host_upgrade_preview:
         from superlocalmemory.cli.version_banner import check_and_emit_upgrade_banner
         if check_and_emit_upgrade_banner(_ver):
             # First post-upgrade invocation: apply the data-dir migration if
@@ -283,6 +290,23 @@ def main() -> None:
         ),
     )
 
+    upgrade_p = sub.add_parser(
+        "upgrade-hosts",
+        help="Preview or explicitly refresh installed SLM host integrations",
+    )
+    upgrade_p.add_argument(
+        "--host", action="append", dest="hosts", default=[],
+        help="Explicit host to refresh (repeatable; for example: codex, cursor)",
+    )
+    upgrade_p.add_argument(
+        "--all-detected", action="store_true", default=False,
+        help="Target only hosts that already contain an SLM integration",
+    )
+    upgrade_p.add_argument(
+        "--apply", action="store_true", default=False,
+        help="Apply the previewed changes; default is read-only preview",
+    )
+
     migrate_p = sub.add_parser("migrate", help="Migrate data from V2 to V3 schema")
     migrate_p.add_argument(
         "--rollback", action="store_true", help="Rollback migration",
@@ -394,6 +418,18 @@ def main() -> None:
              "(2026-01-01T00:00:00+00:00) that pins retrieval to a temporal "
              "snapshot. Default: current-state recall.",
     )
+    recall_p.add_argument(
+        "--known-as-of", dest="known_as_of", default="",
+        help="Strict transaction-time boundary: return only facts SLM knew by this ISO-8601 time.",
+    )
+    recall_p.add_argument(
+        "--valid-at", dest="valid_at", default="",
+        help="Strict event-time boundary: return only facts valid at this ISO-8601 time.",
+    )
+    recall_p.add_argument(
+        "--include-unknown", action="store_true",
+        help="Include pre-4.0.2 facts with unknown temporal provenance in strict time-travel.",
+    )
     recall_p.add_argument(
         "--fast", action="store_true",
         help="Force-skip the internal agentic verification round (all six retrieval "
@@ -606,6 +642,15 @@ def main() -> None:
     obs_p = sub.add_parser("observe", help="Auto-capture content (pipe or argument)")
     obs_p.add_argument("content", nargs="?", default="", help="Content to evaluate")
 
+    brain_p = sub.add_parser(
+        "brain", help="Show the local, profile-scoped Living Brain evidence summary"
+    )
+    brain_p.add_argument(
+        "action", nargs="?", default="status", choices=["status"],
+        help="Read-only Brain action (default: status)",
+    )
+    brain_p.add_argument("--json", action="store_true", help="Output structured JSON")
+
     # -- V3.3 Commands -------------------------------------------------
     decay_p = sub.add_parser("decay", help="Run Ebbinghaus forgetting decay cycle")
     decay_p.add_argument(
@@ -943,7 +988,10 @@ def main() -> None:
         sys.exit(0)
 
     # V3.3.19: Auto-trigger setup wizard on first use
-    if not (args.command == "connect" and getattr(args, "dry_run", False)):
+    if not (
+        (args.command == "connect" and getattr(args, "dry_run", False))
+        or (args.command == "upgrade-hosts" and not getattr(args, "apply", False))
+    ):
         from superlocalmemory.cli.setup_wizard import check_first_use
         check_first_use(args.command)