superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/cli/summary_cmd.py

@@ -1,215 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory | https://qualixar.com
-
-"""``slm summary`` — the readable layer over your memories (issue #113).
-
-WHY THIS FILE EXISTS
---------------------
-4.0.6 shipped the three generators in ``superlocalmemory/summaries/`` with no way
-to call them: no command, no MCP tool, no route. The changelog listed the feature
-as added, the issue reply said it had landed, and a user could do nothing with it.
-This is that missing surface.
-
-Three summaries, each bounded and traceable:
-
-  ``slm summary session <id>``   what one session covered
-  ``slm summary day [DATE]``     what a day's main topics were
-  ``slm summary project <path>`` what was worked on in a project
-
-Every result states its coverage. Session data in particular is sparse — roughly
-4% of facts carry a session id on a real store — so a session summary reports what
-fraction it could actually see rather than presenting a slice as the whole.
-
-No language model is required: the generators are extractive by default, so this
-works in Local Guardian mode with nothing installed.
-"""
-
-from __future__ import annotations
-
-import json
-from argparse import Namespace
-from datetime import date, timedelta
-from pathlib import Path
-from typing import Any
-
-from superlocalmemory.infra.data_root import state_path
-
-def _coverage_is_complete(coverage: str) -> bool:
-    """Whether *coverage* means "this really is the whole picture".
-
-    Deliberately inverted. My first version listed the values that needed a
-    caveat — ``("partial", "sparse", "none", "empty")`` — and three of those four
-    are not values this system emits. The real vocabulary is COVERAGE_FULL /
-    PARTIAL / INSUFFICIENT / NO_SESSION / UNAVAILABLE, so a session summary
-    reporting "no_session" printed no caveat at all: the one honesty feature
-    issue #113 asked for, silently inactive.
-
-    Testing for completeness instead means any value that is not FULL — including
-    one added later — gets the caveat. The failure mode becomes an unnecessary
-    warning rather than a missing one.
-    """
-    try:
-        from superlocalmemory.summaries.base import COVERAGE_FULL
-
-        return coverage == COVERAGE_FULL
-    except Exception:
-        return coverage == "full"
-
-
-def _db_path() -> Path:
-    return state_path("memory.db")
-
-
-def _active_profile() -> str:
-    """Resolve the active profile without a daemon and without side effects.
-
-    Reads the ``active`` pointer out of ``profiles.json`` directly.
-    ``ProfileManager`` would give the same answer, but its constructor calls
-    ``mkdir(parents=True)`` — creating directories is not something a read-only
-    summary command should do. ``core.profiles`` also has no module-level
-    accessor; ``get_active_profile`` there is a method on the manager, and the
-    module-level one lives in ``server/routes/helpers.py``, which the CLI must
-    not import.
-    """
-    try:
-        from superlocalmemory.core.profiles import DEFAULT_PROFILES_FILE
-
-        path = state_path(DEFAULT_PROFILES_FILE)
-        if path.exists():
-            raw = json.loads(path.read_text(encoding="utf-8"))
-            active = raw.get("active")
-            if isinstance(active, str) and active:
-                return active
-    except Exception:
-        pass
-    return "default"
-
-
-def _load_config() -> Any:
-    """The active SLMConfig, so Mode B/C get LLM-written summaries.
-
-    Without this the generators receive ``config=None``, ``get_mode_str`` returns
-    ``"a"``, and the LLM branch is unreachable — every summary comes out
-    extractive no matter which mode the user runs. That is not a graceful
-    fallback, it is the enrichment path never being offered.
-
-    Returns None on any failure, which lands on the extractive path. That is the
-    right fallback: a deterministic summary beats an error.
-    """
-    try:
-        from superlocalmemory.core.config import SLMConfig
-
-        return SLMConfig.load()
-    except Exception:
-        return None
-
-
-def _emit(result: Any, as_json: bool) -> None:
-    """Print a SummaryResult as JSON or as prose."""
-    if as_json:
-        print(json.dumps({
-            "kind": result.kind,
-            "profile_id": result.profile_id,
-            "content": result.content,
-            "source_fact_ids": result.source_fact_ids,
-            "coverage": result.coverage,
-            "generated_by": result.generated_by,
-            "metadata": result.metadata,
-        }, indent=2, default=str))
-        return
-
-    print()
-    print(result.content.rstrip() or "(nothing recorded)")
-    print()
-
-    # Coverage is not decoration. A summary built from a fraction of the data
-    # that presents itself as the whole is the failure mode issue #113 called
-    # out by name, so it is stated on every single result, not only bad ones.
-    n = len(result.source_fact_ids)
-    line = f"Built from {n} memor{'y' if n == 1 else 'ies'} · coverage: {result.coverage}"
-    if not _coverage_is_complete(result.coverage):
-        line += " — treat as a partial view, not a complete record"
-    print(line)
-    if result.generated_by:
-        print(f"Method: {result.generated_by}")
-    print("Use --json to see the exact memories this came from.")
-
-
-def cmd_summary(args: Namespace) -> None:
-    """Dispatch ``slm summary <subcommand>``."""
-    sub = getattr(args, "summary_command", None)
-    as_json = bool(getattr(args, "json", False))
-    profile = getattr(args, "profile", None) or _active_profile()
-    db = _db_path()
-    cfg = _load_config()   # Mode B/C enrichment; None -> extractive
-
-    if not db.exists():
-        print(f"No memory database at {db}. Run `slm status` first.")
-        return
-
-    if sub == "session":
-        from superlocalmemory.summaries import generate_session_summary
-
-        _emit(generate_session_summary(db, args.session_id, profile, cfg), as_json)
-        return
-
-    if sub == "day":
-        from superlocalmemory.summaries import generate_daily_reflection
-
-        target = getattr(args, "date", None) or date.today().isoformat()
-        if target == "yesterday":
-            target = (date.today() - timedelta(days=1)).isoformat()
-        elif target == "today":
-            target = date.today().isoformat()
-        _emit(generate_daily_reflection(db, target, profile, cfg), as_json)
-        return
-
-    if sub == "project":
-        from superlocalmemory.summaries import generate_project_work_log
-
-        path = getattr(args, "path", None) or str(Path.cwd())
-        _emit(generate_project_work_log(db, path, profile, cfg), as_json)
-        return
-
-    print("Usage: slm summary {session <id> | day [DATE] | project [PATH]}")
-    print()
-    print("  slm summary day                 what you recorded today")
-    print("  slm summary day yesterday       ...or yesterday")
-    print("  slm summary day 2026-08-17      ...or a specific date")
-    print("  slm summary project             work log for the current directory")
-    print("  slm summary session <id>        what one session covered")
-    print()
-    print("Add --json to include the ids of the memories a summary came from.")
-
-
-def register_summary_parser(sub: Any) -> None:
-    """Attach the ``summary`` parser. Called from cli/main.py."""
-    p = sub.add_parser(
-        "summary",
-        help="Readable summaries of your memories (session, day, project)",
-    )
-    p.add_argument("--json", action="store_true", help="machine-readable output")
-    p.add_argument("--profile", help="profile to summarise (default: active)")
-    ssub = p.add_subparsers(dest="summary_command", title="summary subcommands")
-
-    s = ssub.add_parser("session", help="what one session covered")
-    s.add_argument("session_id", help="session id (see `slm status`)")
-    s.add_argument("--json", action="store_true")
-    s.add_argument("--profile")
-
-    d = ssub.add_parser("day", help="what a day's main topics were")
-    d.add_argument(
-        "date", nargs="?",
-        help="YYYY-MM-DD, 'today' or 'yesterday' (default: today)",
-    )
-    d.add_argument("--json", action="store_true")
-    d.add_argument("--profile")
-
-    pr = ssub.add_parser("project", help="what was worked on in a project")
-    pr.add_argument(
-        "path", nargs="?",
-        help="project directory (default: current directory)",
-    )
-    pr.add_argument("--json", action="store_true")
-    pr.add_argument("--profile")

package/src/superlocalmemory/cli/version_banner.py

@@ -1,202 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Post-upgrade version banner.
-
-Writes ``$SLM_DATA_DIR/.version`` (default ``~/.superlocalmemory/.version``)
-and prints a short factual banner the first time the CLI or daemon is
-invoked after a ``pip install -U`` / ``npm install -g`` that changes the
-installed version. Every subsequent invocation is a no-op.
-
-The banner is best-effort and must never raise — a disk error or a
-corrupt marker makes the banner silent, not the CLI broken.
-"""
-from __future__ import annotations
-
-import os
-import re
-import sys
-from pathlib import Path
-
-# Strict allowlist: semver-ish only. Anything else in the marker is
-# treated as "unknown" so a tampered or binary marker can't leak into
-# banner strings or downstream consumers.
-_VERSION_PATTERN = re.compile(r"^[0-9A-Za-z.\-+_]{1,32}$")
-
-_MAX_MARKER_BYTES = 64  # a semver string is ≤ 32 chars; 64 is plenty
-
-_RELEASE_NOTES: dict[str, tuple[str, ...]] = {
-    "3.8.1": (
-        "Large existing databases no longer delay daemon readiness",
-        "Failed enrichment retries stop after ten automatic attempts",
-        "Dashboard panes stay mounted between navigation changes",
-        "Local model workers stay warm for a 30-minute working session",
-    ),
-}
-
-
-def _data_dir() -> Path:
-    from superlocalmemory.infra.data_root import canonical_data_root
-    return canonical_data_root()
-
-
-def _marker_path() -> Path:
-    return _data_dir() / ".version"
-
-
-def read_marker_version() -> str | None:
-    """Return the marker string or None if missing / unreadable / invalid."""
-    target = _marker_path()
-    # Refuse to follow symlinks on the marker file — a co-tenant
-    # attacker who can drop a symlink into our data dir must not be
-    # able to redirect us to an arbitrary file.
-    try:
-        st = target.lstat()
-    except (FileNotFoundError, NotADirectoryError, PermissionError, OSError):
-        return None
-    import stat as _stat
-    if _stat.S_ISLNK(st.st_mode) or not _stat.S_ISREG(st.st_mode):
-        return None
-    try:
-        with open(target, "rb") as f:
-            raw = f.read(_MAX_MARKER_BYTES + 1)
-    except (FileNotFoundError, NotADirectoryError, PermissionError, OSError):
-        return None
-    if len(raw) > _MAX_MARKER_BYTES:
-        return None
-    try:
-        text = raw.decode("ascii").strip()
-    except UnicodeDecodeError:
-        return None
-    if not _VERSION_PATTERN.fullmatch(text):
-        return None
-    return text
-
-
-def write_marker_version(version: str) -> bool:
-    """Persist the current version to the marker with 0600 perms.
-
-    Uses a PID-scoped tmp file + ``os.replace`` for atomicity so
-    concurrent CLI / daemon / npm-postinstall invocations can't corrupt
-    each other's write. The final file is mode 0600 so the upgrade
-    timestamp is not a side-channel for co-tenant attackers.
-    """
-    # Validate input — never write garbage, even on a programmer bug.
-    if not _VERSION_PATTERN.fullmatch(version):
-        return False
-    target = _marker_path()
-    try:
-        target.parent.mkdir(parents=True, exist_ok=True)
-        # Parent dir 0700 on POSIX (mirrors safe_fs._ensure_parent_0700)
-        if sys.platform != "win32":
-            try:
-                os.chmod(target.parent, 0o700)
-            except OSError:
-                pass
-        tmp = target.parent / f".version.tmp.{os.getpid()}"
-        # Open with 0600 so the tmp is never world-readable either.
-        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
-        if hasattr(os, "O_NOFOLLOW"):
-            flags |= os.O_NOFOLLOW
-        fd = os.open(tmp, flags, 0o600)
-        try:
-            os.write(fd, (version + "\n").encode("ascii"))
-        finally:
-            os.close(fd)
-        os.replace(tmp, target)
-        if sys.platform != "win32":
-            try:
-                os.chmod(target, 0o600)
-            except OSError:
-                pass
-        return True
-    except OSError:
-        return False
-
-
-def _has_existing_db() -> bool:
-    """True if a memory.db already exists — signals a pre-v3.4.26 user
-    upgrading in-place (the marker only began shipping in v3.4.26)."""
-    return (_data_dir() / "memory.db").exists()
-
-
-def _banner(prior: str | None, current: str) -> str:
-    header = (f"SuperLocalMemory upgraded from {prior} to {current}"
-              if prior else
-              f"SuperLocalMemory upgraded to {current} (from an earlier version)")
-    notes = _RELEASE_NOTES.get(
-        current,
-        (
-            "The installed version has changed; existing memory remains in place",
-            "See the release notes for version-specific changes",
-        ),
-    )
-    return "\n".join([
-        header,
-        *(f"  - {note}" for note in notes),
-        "Run `slm doctor` to verify your setup.",
-        "",
-    ])
-
-
-def check_and_emit_upgrade_banner(current: str) -> bool:
-    """Print the banner once per upgrade boundary. Idempotent.
-
-    Returns True if the banner was emitted on this call, else False.
-    Never raises — swallows I/O errors so a broken data directory cannot
-    take down the CLI.
-
-    Concurrent CLI + daemon + npm-postinstall callers serialize through
-    an O_CREAT|O_EXCL lock file so at most one emits the banner.
-    """
-    try:
-        prior = read_marker_version()
-
-        if prior == current:
-            return False
-
-        # Fresh install: no marker, no DB. Stay quiet — the setup wizard
-        # handles the welcome. Still write the marker so subsequent
-        # invocations are no-ops.
-        if prior is None and not _has_existing_db():
-            write_marker_version(current)
-            return False
-
-        # Serialize concurrent emitters via O_CREAT|O_EXCL lock file.
-        lock = _data_dir() / ".version-banner.lock"
-        lock_fd = None
-        try:
-            lock.parent.mkdir(parents=True, exist_ok=True)
-            lock_fd = os.open(
-                str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600,
-            )
-        except FileExistsError:
-            return False
-        except OSError:
-            pass
-
-        try:
-            # Re-check after winning the lock — the loser may have
-            # already written the marker while we raced.
-            if read_marker_version() == current:
-                return False
-
-            # v3.6.13 (CRITICAL): write to STDERR, never stdout. On the `slm mcp`
-            # stdio transport, ANY stdout byte that isn't JSON-RPC corrupts the
-            # stream and the MCP client (e.g. Claude Desktop) rejects every
-            # message as "not valid JSON". The banner is a human notice → stderr.
-            sys.stderr.write(_banner(prior, current))
-            sys.stderr.flush()
-            write_marker_version(current)
-            return True
-        finally:
-            if lock_fd is not None:
-                os.close(lock_fd)
-            try:
-                lock.unlink(missing_ok=True)
-            except OSError:
-                pass
-    except Exception:
-        # Banner is advisory. A failure here must never propagate.
-        return False

package/src/superlocalmemory/cli/wizard_v3426_options.py

@@ -1,129 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Setup-wizard extensions for v3.4.26.
-
-Keeps the user-facing surface tiny: one yes/no prompt for the queue.
-Everything else defaults; advanced users edit ``v3426_options.json``.
-
-Also validates the chosen data directory at install time so cloud-sync
-folders (iCloud, Dropbox, OneDrive, …) fail loud BEFORE the user stores
-their first memory.
-"""
-from __future__ import annotations
-
-import json
-import logging
-import os
-import sys
-from dataclasses import asdict, dataclass
-from pathlib import Path
-
-from superlocalmemory.core.safe_fs import SafeFsError, validate_data_dir
-
-logger = logging.getLogger(__name__)
-
-
-# Defaults tuned for a commodity laptop with 4 concurrent IDEs
-# (Claude Code, Cursor, Antigravity, VS Code). See the release notes
-# for the reasoning behind the numbers.
-_DEFAULT_QUEUE_ENABLED = True
-_DEFAULT_RATE_PER_PID = 30
-_DEFAULT_RATE_PER_AGENT = 10
-_DEFAULT_RATE_GLOBAL = 100
-
-
-@dataclass(frozen=True)
-class V3426Options:
-    queue_enabled: bool
-    rate_limit_per_pid: int
-    rate_limit_per_agent: int
-    rate_limit_global: int
-
-
-def _default_options() -> V3426Options:
-    return V3426Options(
-        queue_enabled=_DEFAULT_QUEUE_ENABLED,
-        rate_limit_per_pid=_DEFAULT_RATE_PER_PID,
-        rate_limit_per_agent=_DEFAULT_RATE_PER_AGENT,
-        rate_limit_global=_DEFAULT_RATE_GLOBAL,
-    )
-
-
-def prompt_v3426_options(interactive: bool) -> V3426Options:
-    """Return user-chosen (or default) v3.4.26 options.
-
-    Non-interactive / EOFError (pipe) returns the defaults silently.
-    Ctrl-C propagates so the user can actually abort install.
-    """
-    if not interactive:
-        return _default_options()
-
-    try:
-        answer = input(
-            "Enable SLM's concurrent-recall queue (recommended)? [Y/n]: "
-        ).strip().lower()
-    except EOFError:
-        return _default_options()
-
-    queue_enabled = answer not in ("n", "no")
-    return V3426Options(
-        queue_enabled=queue_enabled,
-        rate_limit_per_pid=_DEFAULT_RATE_PER_PID,
-        rate_limit_per_agent=_DEFAULT_RATE_PER_AGENT,
-        rate_limit_global=_DEFAULT_RATE_GLOBAL,
-    )
-
-
-def validate_install_data_dir(path: Path) -> tuple[bool, str]:
-    """Return (ok, reason). Empty reason on success."""
-    try:
-        validate_data_dir(path)
-    except SafeFsError as exc:
-        return False, str(exc)
-    return True, ""
-
-
-def persist_v3426_options(opts: V3426Options, home_dir: Path) -> Path:
-    """Write the options JSON with 0600 perms and atomic replace.
-
-    Atomic: a crash mid-write leaves either the old file or nothing,
-    never a truncated JSON that the daemon can't parse on boot.
-    0600: rate-limit config is not sensitive per se, but the file
-    also carries future secrets — enforce the tight mode now.
-    """
-    home_dir.mkdir(parents=True, exist_ok=True)
-    if sys.platform != "win32":
-        try:
-            os.chmod(home_dir, 0o700)
-        except OSError as exc:
-            logger.warning("could not tighten %s to 0700: %s", home_dir, exc)
-    target = home_dir / "v3426_options.json"
-    payload = (json.dumps(asdict(opts), indent=2) + "\n").encode("utf-8")
-    tmp = home_dir / f"v3426_options.json.tmp.{os.getpid()}"
-    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
-    if hasattr(os, "O_NOFOLLOW"):
-        flags |= os.O_NOFOLLOW
-    try:
-        fd = os.open(tmp, flags, 0o600)
-        try:
-            os.write(fd, payload)
-        finally:
-            os.close(fd)
-        os.replace(tmp, target)
-        if sys.platform != "win32":
-            try:
-                os.chmod(target, 0o600)
-            except OSError:
-                pass
-    except OSError:
-        # Fallback for odd filesystems that don't support O_NOFOLLOW
-        # or the perm bits — log + emit something rather than crash.
-        logger.warning(
-            "atomic write of %s failed; falling back to write_text", target,
-        )
-        target.write_text(
-            json.dumps(asdict(opts), indent=2) + "\n", encoding="utf-8",
-        )
-    return target

package/src/superlocalmemory/code_graph/__init__.py

@@ -1,46 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory v3.4 — CodeGraph Module
-
-"""Code Knowledge Graph for SuperLocalMemory.
-
-Unifies AST-derived code structure with SLM's semantic memory.
-Separate code_graph.db — does not touch memory.db.
-
-Usage:
-    from superlocalmemory.code_graph import CodeGraphService, CodeGraphConfig
-
-    config = CodeGraphConfig(enabled=True, repo_root=Path("/my/repo"))
-    service = CodeGraphService(config)
-    stats = service.get_stats()
-"""
-
-from superlocalmemory.code_graph.config import CodeGraphConfig
-from superlocalmemory.code_graph.models import (
-    CodeMemoryLink,
-    EdgeKind,
-    FileRecord,
-    GraphEdge,
-    GraphNode,
-    LinkType,
-    NodeKind,
-    ParseResult,
-)
-from superlocalmemory.code_graph.service import (
-    CodeGraphNotEnabledError,
-    CodeGraphService,
-)
-
-__all__ = [
-    "CodeGraphConfig",
-    "CodeGraphService",
-    "CodeGraphNotEnabledError",
-    "GraphNode",
-    "GraphEdge",
-    "FileRecord",
-    "CodeMemoryLink",
-    "ParseResult",
-    "NodeKind",
-    "EdgeKind",
-    "LinkType",
-]