superlocalmemory 3.7.7 → 3.8.0

package/src/superlocalmemory/hooks/hook_daemon.py

@@ -25,6 +25,7 @@ import json
 import logging
 import os
 import socket
+import sys
 import threading
 import time
 from pathlib import Path
@@ -35,6 +36,12 @@ logger = logging.getLogger(__name__)
 
 _DEFAULT_SOCK_NAME = "hook_daemon.sock"
 
+# AF_UNIX is absent on Windows builds < 10.0.17063 and on Python < 3.9. When it
+# is unavailable the hook daemon does not start and callers fall back to the
+# subprocess recall path. Detect it explicitly (once, with a log) instead of
+# relying on an AttributeError being swallowed by a broad except.
+_AF_UNIX = getattr(socket, "AF_UNIX", None)
+
 
 def _default_sock_path() -> Path:
     return state_path(_DEFAULT_SOCK_NAME)
@@ -77,7 +84,13 @@ class HookDaemon:
         from superlocalmemory.core.recall_queue import RecallQueue
         self._queue = RecallQueue(self._queue_db_path)
 
-        self._server_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        if _AF_UNIX is None:
+            logger.info(
+                "HookDaemon: AF_UNIX unavailable on %s; hook recall uses the "
+                "subprocess fallback", sys.platform,
+            )
+            raise RuntimeError("AF_UNIX unavailable on this platform")
+        self._server_sock = socket.socket(_AF_UNIX, socket.SOCK_STREAM)
         self._server_sock.bind(str(self._sock_path))
         self._server_sock.listen(8)
         self._server_sock.settimeout(1.0)
@@ -226,9 +239,11 @@ def try_socket_recall(
     path = sock_path or _default_sock_path()
     if not path.exists():
         return None
+    if _AF_UNIX is None:
+        return None
 
     try:
-        client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        client = socket.socket(_AF_UNIX, socket.SOCK_STREAM)
         client.settimeout(timeout)
         client.connect(str(path))
 
@@ -259,10 +274,12 @@ def ensure_hook_daemon(
 ) -> HookDaemon | None:
     """Start hook daemon if not already running. Returns daemon or None."""
     path = sock_path or _default_sock_path()
+    if _AF_UNIX is None:
+        return None
 
     if path.exists():
         try:
-            test = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            test = socket.socket(_AF_UNIX, socket.SOCK_STREAM)
             test.settimeout(1.0)
             test.connect(str(path))
             test.close()

package/src/superlocalmemory/hooks/memory_protocol.py

@@ -93,6 +93,58 @@ def memory_protocol_markdown() -> str:
         "learned>\", \"tags\": \"<comma-separated kebab-case keywords>\"}`.\n"
         "- A \"substantial task\" is anything you would write a commit "
         "message or handoff note about — not every tool call.\n"
+        "\n"
+        + optimize_protocol_markdown()
+        + "\n"
+        + loop_protocol_markdown()
+    )
+
+
+def optimize_protocol_markdown() -> str:
+    """Return the agent-facing token-optimization protocol block (cache/compress).
+
+    Proxy-free: these MCP tools let the agent losslessly shrink large tool output
+    and reuse repeated reads through the same surface, so an agent on any
+    front-end (not just Claude Code) can save tokens without a proxy. Fail-open —
+    a non-ok result means "use the original and continue".
+    """
+    return (
+        "## Runtime token-optimization protocol (fail-open)\n"
+        "SLM can losslessly compress large tool output and cache repeated reads "
+        "through the same MCP surface — no proxy required. These calls only save "
+        "tokens; if one returns `ok: false`, use the original and continue.\n\n"
+        "- **Large tool output (>2000 chars)** → `hub__call_tool` with "
+        "`tool=\"slm__slm_compress\"` and `arguments={\"content\": \"<text>\", "
+        "\"mode\": \"auto\", \"reversible\": true}`; keep the returned `ccr_id` "
+        "and call `tool=\"slm__slm_retrieve\"` if you later need the full "
+        "original.\n"
+        "- **Repeated reads/searches** → `hub__call_tool` with "
+        "`tool=\"slm__slm_cache_get\"` and `arguments={\"key\": \"file:<path>\"}` "
+        "first; on a miss, store the result with `tool=\"slm__slm_cache_set\"` "
+        "(ttl ~1800).\n"
+        "- **Never compress or cache**: code you will edit, JSON you will parse, "
+        "secrets, ccr_ids, or anything under ~500 chars.\n"
+    )
+
+
+def loop_protocol_markdown() -> str:
+    """Return the agent-facing bounded-loop protocol block.
+
+    Bounded loops make an agent stop when an INDEPENDENT gate passes — not when
+    the agent claims it is done. Persisting each lap to SLM memory makes a run
+    auditable and resumable. This block is appended to the shared memory
+    protocol so any connected front-end (Claude Code, Codex, Antigravity,
+    Cursor, and other IDEs) learns the feature exists and how to reach it.
+    """
+    return (
+        "## Runtime bounded-loop protocol\n"
+        "For a task with a checkable gate (tests, schema, lint, reconciliation), "
+        "run a *bounded loop*: iterate until an INDEPENDENT gate passes — never "
+        "on the agent's own claim, which is advisory only. Try `slm loop demo`; "
+        "inspect with `slm loop history` / `slm loop show <run_id>` (each lap "
+        "persists as SLM memory, tag `loop:<name>`). Statuses: DONE / HALT / "
+        "PAUSE / KILLED / ERROR — report exactly, never as success unless DONE. "
+        "Full guide: the slm-loop skill.\n"
     )
 
 
@@ -101,4 +153,6 @@ __all__ = (
     "SLM_MARKER_END",
     "strip_slm_block",
     "memory_protocol_markdown",
+    "optimize_protocol_markdown",
+    "loop_protocol_markdown",
 )

package/src/superlocalmemory/hooks/portable_kit.py

@@ -139,7 +139,7 @@ IDE_MATRIX: dict[str, IDEDescriptor] = {
         mcp_path_project=".mcp.json",
         server_key="mcpServers",
         fmt="json",
-        agents_md_path=None,
+        agents_md_path=".junie/AGENTS.md",  # Junie guidelines file (GA) — carries memory + optimize protocol
         server_block={"command": "slm", "args": ["mcp"], "type": "stdio"},
         caveats="path per product [CN-ONLINE]",
     ),
@@ -347,6 +347,54 @@ def connect_ide(
     return result
 
 
+def connect_many(
+    ide_ids: list[str],
+    *,
+    home: Path | None = None,
+    project: Path | None = None,
+    here: bool = False,
+    profile: str | None = None,
+    agents_md_source: Callable[[], str] | None = None,
+) -> list[dict[str, Any]]:
+    """Wire SLM into multiple IDE configs via non-destructive merge.
+
+    Iterates over ``ide_ids`` and calls :func:`connect_ide` for each entry.
+    Each IDE is processed independently — a failure on one IDE does NOT abort
+    the remaining targets.
+
+    The underlying :func:`connect_ide` is MERGE-NOT-CLOBBER:
+    - Only the ``superlocalmemory`` server key is touched.
+    - All other MCP servers + top-level keys are preserved byte-for-byte.
+    - Writes are atomic (.tmp + os.replace).
+
+    Args:
+        ide_ids: IDE ids to wire (from :data:`IDE_MATRIX`).  Pass an empty
+            list to no-op.  Unknown ids produce error entries in the output.
+        home: Override ``$HOME`` (test hook).
+        project: Project root for ``here=True`` installs.
+        here: When True, write to project-relative path instead of global.
+        profile: Inject ``SLM_MCP_PROFILE`` env-var into every server block.
+        agents_md_source: Callable returning AGENTS.md content to append.
+
+    Returns:
+        List of per-IDE result dicts, one per input id.  Each dict has the
+        same shape as :func:`connect_ide`'s return value::
+
+            {ide, mcp_config, mcp_path, agents_md, servers_preserved, error}
+    """
+    return [
+        connect_ide(
+            ide_id,
+            home=home,
+            project=project,
+            here=here,
+            profile=profile,
+            agents_md_source=agents_md_source,
+        )
+        for ide_id in ide_ids
+    ]
+
+
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------
@@ -504,3 +552,68 @@ def _handle_agents_md(
     _tmp.write_text(existing + section, encoding="utf-8")
     os.replace(_tmp, agents_path)
     return "wrote"
+
+
+# ---------------------------------------------------------------------------
+# __main__ — `python -m superlocalmemory.hooks.portable_kit [ids...]`
+#
+# Used by the npm installer to execute non-destructive IDE connects when
+# Python is available at postinstall time. If Python / the package is not
+# importable the installer records a pending_ide_connections.json instead.
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":  # pragma: no cover
+    import argparse as _argparse
+
+    _parser = _argparse.ArgumentParser(
+        description="SLM IDE connector — non-destructive merge-not-clobber."
+    )
+    _parser.add_argument(
+        "ide_ids",
+        nargs="*",
+        metavar="IDE",
+        help=(
+            "IDE ids to connect.  Pass 'all' to connect every supported IDE "
+            "(excluding claude-code which uses the WP-06 plugin)."
+        ),
+    )
+    _parser.add_argument("--home", help="Override home directory (test hook).")
+    _parser.add_argument("--profile", help="SLM_MCP_PROFILE to inject.")
+    _parser.add_argument(
+        "--list", action="store_true",
+        help="Print supported IDE ids with display names and exit.",
+    )
+    _args = _parser.parse_args()
+
+    if _args.list:
+        for _id, _desc in IDE_MATRIX.items():
+            _flag = "[OUT]" if not _desc.fmt else ""
+            print(f"  {_id:22s} {_desc.display} {_flag}".rstrip())
+        sys.exit(0)
+
+    _home = Path(_args.home) if _args.home else None
+
+    # Resolve targets: "all" → every MCP-capable IDE (fmt != ""), else explicit list.
+    if "all" in _args.ide_ids:
+        _targets = [k for k, d in IDE_MATRIX.items() if d.fmt]
+    else:
+        _targets = [t for t in _args.ide_ids if t]
+
+    if not _targets:
+        print("No IDE ids given. Pass ide ids or 'all'. Use --list to see options.")
+        sys.exit(0)
+
+    _results = connect_many(_targets, home=_home, profile=_args.profile)
+    _ok = 0
+    _fail = 0
+    for _r in _results:
+        _err = _r.get("error")
+        _status = _r.get("mcp_config", "error")
+        if _err:
+            print(f"  ERROR     {_r['ide']}: {_err}", file=sys.stderr)
+            _fail += 1
+        else:
+            print(f"  {_status.upper():9s} {_r['ide']} → {_r.get('mcp_path', '')}")
+            _ok += 1
+    print(f"\n{_ok} connected, {_fail} errors.")
+    sys.exit(0 if _fail == 0 else 1)

package/src/superlocalmemory/infra/auth_middleware.py

@@ -15,6 +15,7 @@ V3 change: base directory moved from ``~/.claude-memory/`` to
 import hashlib
 import hmac
 import logging
+import os
 from pathlib import Path
 from typing import Optional
 
@@ -26,6 +27,13 @@ logger = logging.getLogger("superlocalmemory.auth")
 MEMORY_DIR = DynamicStatePath()
 API_KEY_FILE = DynamicStatePath("api_key")
 
+# v3.7.8 (F1): opt-in env flag that restores the pre-v3.7.6 shared-host
+# posture -- when set AND an api_key file is configured, uncredentialed
+# loopback writes must also present a matching X-SLM-API-Key. Default OFF
+# preserves the v3.7.6 local-first fix (#71/#73/#74): loopback callers are
+# trusted as the local OS-user boundary without needing any credential.
+SLM_REQUIRE_API_KEY_LOOPBACK_ENV = "SLM_REQUIRE_API_KEY_LOOPBACK"
+
 
 def _load_api_key_hash(key_file: Optional[Path] = None) -> Optional[str]:
     """Load and hash the API key from disk.
@@ -96,6 +104,26 @@ def verify_api_key(
     return hmac.compare_digest(actual, expected)
 
 
+def loopback_strict_mode_enabled(key_file: Optional[Path] = None) -> bool:
+    """Whether uncredentialed loopback writes must present the API key.
+
+    v3.7.8 (F1/F2): opt-in via ``SLM_REQUIRE_API_KEY_LOOPBACK`` (any of
+    "1"/"true"/"yes"/"on", case-insensitive). This is the sole enforcement
+    point for the strict shared-host posture -- it is checked ONLY for the
+    uncredentialed-loopback case (a caller presenting none of
+    X-SLM-Daemon-Capability / X-Install-Token / X-SLM-API-Key). Callers who
+    already present a valid capability or install token are unaffected: those
+    are stronger, explicit credentials and this flag never re-litigates them.
+
+    Returns ``False`` (no-op) when the flag is unset/false, OR when no
+    api_key file is configured -- there is nothing to require in that case.
+    """
+    raw = os.environ.get(SLM_REQUIRE_API_KEY_LOOPBACK_ENV, "")
+    if raw.strip().lower() not in ("1", "true", "yes", "on"):
+        return False
+    return _load_api_key_hash(key_file) is not None
+
+
 def authorize_http_mcp_request(
     request_headers: dict,
     *,

package/src/superlocalmemory/infra/backup.py

@@ -266,7 +266,18 @@ class BackupManager:
 
         A safety snapshot of the current state is taken first.
         """
-        backup_path = self.backup_dir / filename
+        # Containment: filename must be a bare .db name inside backup_dir — no
+        # path separators or traversal. Prevents restoring (and thus copying
+        # over memory.db) an arbitrary file the daemon user can read.
+        if (not filename or "/" in filename or "\\" in filename
+                or ".." in filename or not filename.endswith(".db")):
+            logger.error("Restore rejected: invalid backup filename: %r", filename)
+            return False
+        backup_dir = self.backup_dir.resolve()
+        backup_path = (self.backup_dir / filename).resolve()
+        if backup_path.parent != backup_dir:
+            logger.error("Restore rejected: path escapes backup dir: %r", filename)
+            return False
         if not backup_path.exists():
             logger.error("Backup not found: %s", filename)
             return False

package/src/superlocalmemory/infra/daemon_identity.py

@@ -14,8 +14,11 @@ import getpass
 import hashlib
 import hmac
 import json
+import logging
 import os
 import secrets
+import subprocess
+import sys
 import time
 import uuid
 from dataclasses import asdict, dataclass
@@ -30,6 +33,8 @@ DAEMON_SERVICE = "superlocalmemory-daemon"
 _NAMESPACE_DOMAIN = b"superlocalmemory-daemon-namespace-v1\0"
 _CAPABILITY_DOMAIN = b"superlocalmemory-daemon-capability-v1\0"
 
+logger = logging.getLogger(__name__)
+
 
 def _canonical_path(value: str | Path) -> Path:
     expanded = Path(value).expanduser().resolve(strict=False)
@@ -144,6 +149,40 @@ def descriptor_path(data_root: str | Path | None = None) -> Path:
     return root / "daemon.json"
 
 
+def _restrict_to_owner(path: Path) -> None:
+    """Restrict a sensitive file to the current user on every platform.
+
+    ``daemon.json`` holds the capability token that authorizes write requests.
+    POSIX gets a 0600 chmod. On Windows chmod is a no-op, so use icacls to strip
+    inherited ACEs and grant the current user only — otherwise the token can be
+    read by other local accounts (privilege escalation on shared machines).
+    Files under %USERPROFILE% usually inherit user-only ACLs already; this is
+    defense-in-depth. Fail-soft — a hardening failure warns, never crashes.
+    """
+    if sys.platform == "win32":
+        try:
+            user = getpass.getuser()
+            subprocess.run(
+                ["icacls", str(path), "/inheritance:r"],
+                check=False, capture_output=True,
+            )
+            if user:
+                subprocess.run(
+                    ["icacls", str(path), "/grant:r", f"{user}:F"],
+                    check=False, capture_output=True,
+                )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "could not restrict ACL on %s (%s); the capability token may be "
+                "readable by other local users", path, exc,
+            )
+    else:
+        try:
+            os.chmod(path, 0o600)
+        except OSError as exc:
+            logger.warning("could not chmod %s to 0600: %s", path, exc)
+
+
 def write_descriptor(
     descriptor: DaemonDescriptor,
     *,
@@ -162,10 +201,7 @@ def write_descriptor(
             stream.flush()
             os.fsync(stream.fileno())
         os.replace(temporary, destination)
-        try:
-            os.chmod(destination, 0o600)
-        except OSError:
-            pass
+        _restrict_to_owner(destination)
     finally:
         temporary.unlink(missing_ok=True)
     return destination

package/src/superlocalmemory/infra/data_root.py

@@ -11,6 +11,7 @@ explicit process contract and always wins over persisted configuration.
 from __future__ import annotations
 
 import json
+import logging
 import os
 from pathlib import Path
 
@@ -24,6 +25,8 @@ _DURABLE_IDENTITY_NAMES = frozenset(
     },
 )
 
+logger = logging.getLogger(__name__)
+
 
 class DataRootConflictError(RuntimeError):
     """Raised when two state-bearing roots make startup ambiguous."""
@@ -122,17 +125,53 @@ def assert_no_durable_root_conflict(
     *,
     home: str | Path | None = None,
 ) -> None:
-    """Refuse ambiguous startup when selected and default roots hold state.
-
-    This check never writes, copies, or deletes data. A default root that only
-    contains the legacy relocation config is safe and does not trigger it.
+    """Refuse *ambiguous* startup when two state roots make the live namespace unclear.
+
+    The root actually selected for this process is always inspected: an
+    unreadable selected root fails closed. Beyond that, a conflict is only raised
+    when the selection was *implicit* — resolved from the legacy
+    ``config.json:base_dir`` relocation hint — and a separately-populated default
+    root leaves it genuinely ambiguous which namespace is live.
+
+    An explicit environment selection (``SLM_DATA_DIR`` / ``SL_MEMORY_PATH`` /
+    ``SLM_HOME``) is an unambiguous operator contract: a separately-populated
+    default root is then a deliberate multi-root / per-team / second-instance
+    layout, not an ambiguity, so startup proceeds. If the explicitly chosen root
+    is empty while the old default still holds data, that likely-mistyped path is
+    surfaced as a warning rather than a hard block.
+
+    This check never writes, copies, or deletes data.
     """
     home_path = _canonical_path(home if home is not None else Path.home())
     default_root = _canonical_path(home_path / ".superlocalmemory")
     selected_root = canonical_data_root(home=home_path)
     if selected_root == default_root:
         return
+
+    # The root about to be used must be inspectable regardless of how it was
+    # chosen; an unreadable selected root fails closed inside _durable_markers.
     selected_markers = _durable_markers(selected_root)
+
+    if environment_data_root() is not None:
+        # Explicit selection wins; a populated default root is a deliberate
+        # multi-root layout, not an ambiguity. Only warn on the "empty new root
+        # while the old default still holds data" case so a wrong SLM_DATA_DIR
+        # stays visible. Inspection of the unused default never blocks startup.
+        if not selected_markers:
+            try:
+                default_has_data = bool(_durable_markers(default_root))
+            except DataRootConflictError:
+                default_has_data = False
+            if default_has_data:
+                logger.warning(
+                    "SLM_DATA_DIR selects an empty state root (%s) while the "
+                    "default root (%s) still holds data; starting with the empty "
+                    "root as explicitly requested.",
+                    selected_root,
+                    default_root,
+                )
+        return
+
     default_markers = _durable_markers(default_root)
     if not selected_markers or not default_markers:
         return