superlocalmemory 4.1.21 → 4.1.23

package/hermes-plugin/remote.py

@@ -0,0 +1,390 @@
+"""Remote mode for the Hermes SLM plugin: /slm commands over Hermes's own MCP client.
+
+Selected only by ``plugins.entries.superlocalmemory.settings.connection: remote``.
+This module opens no sockets and runs no programs: every call goes through
+``ctx.call_mcp("superlocalmemory", ...)``, i.e. the MCP server the user configured
+in Hermes (URL, TLS verification and key all live in Hermes's config). It imports
+no SuperLocalMemory package.
+
+A save that the SLM server did not confirm is reported as ``NOT SAVED`` - never as
+success. Automatic captures pause while the server is unreachable and are counted,
+so ``/slm status`` shows what was skipped. Nothing is kept on this computer.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+logger = logging.getLogger("superlocalmemory.hermes.remote")
+
+SERVER = "superlocalmemory"
+CIRCUIT_SECONDS = 30.0
+VERSION_CACHE_SECONDS = 300.0
+MAX_CONTENT = 50_000
+READ_ONLY_TAG = "[remote_key_read_only]"
+#: Lifecycle tools that write. A read-only key is refused these; once that is
+#: seen the plugin stops sending them (and counts them as skipped).
+LIFECYCLE_WRITES = frozenset({"session_init", "log_tool_event", "observe",
+                              "settle_session_outcomes", "close_session"})
+#: Skills that work against a remote SLM (the rest manage the SLM computer).
+REMOTE_SKILLS = ("slm-cache", "slm-compress", "slm-recall", "slm-remember", "slm-scope",
+                 "slm-session", "slm-status")
+HOST_ONLY_ROLES = frozenset({"governance", "loop"})
+HOST_ONLY_MESSAGE = ("'/slm {cmd}' manages the SLM computer and is not available over a "
+                     "remote connection. Run 'slm {cmd}' on the SLM computer.")
+_TIMEOUTS = {"recall": 8, "remember": 15, "delete_memory": 15, "update_memory": 15}
+
+
+def _bounded(value: Any, limit: int = 300) -> str:
+    text = "" if value is None else str(value)
+    return text[:limit] + ("… [truncated]" if len(text) > limit else "")
+
+
+@dataclass(frozen=True)
+class Envelope:
+    ok: bool
+    payload: Any = None
+    reason: str = ""
+    truncated: bool = False
+
+    @classmethod
+    def fail(cls, code: str, reason: str) -> "Envelope":
+        return cls(False, None, f"{reason} ({code})" if code else reason)
+
+    @classmethod
+    def from_hermes(cls, raw: Any) -> "Envelope":
+        if not isinstance(raw, dict):
+            return cls.fail("bad_envelope", "Hermes returned an unexpected result")
+        if raw.get("ok") is not True:
+            return cls(False, None, _bounded(raw.get("error") or "the SLM server did not answer"))
+        payload = raw.get("structuredContent")
+        if payload is None:
+            result = raw.get("result")
+            if isinstance(result, str):
+                try:
+                    payload = json.loads(result)
+                except ValueError:
+                    payload = result
+            else:
+                payload = result
+        return cls(True, payload, "", raw.get("truncated") is True)
+
+
+class RemoteHealth:
+    """Outage circuit and counters for automatic captures. Thread-safe."""
+
+    def __init__(self, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self._lock = threading.Lock()
+        self.failures_total = 0
+        self.dropped_while_open = 0
+        self.dropped_read_only = 0
+        self.last_error = ""
+        self.last_ok_at: str | None = None
+        self.read_only_key = False
+        self._open_until = 0.0
+        self._down = False
+        self._version: tuple[float, str | None] | None = None
+
+    def record(self, ok: bool, reason: str = "") -> None:
+        with self._lock:
+            if ok:
+                if self._down:
+                    logger.info("SLM remote reachable again")
+                self._down = False
+                self._open_until = 0.0
+                self.last_ok_at = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+                return
+            self.failures_total += 1
+            self.last_error = _bounded(reason, 300)
+            self._open_until = self._clock() + CIRCUIT_SECONDS
+            if not self._down:
+                self._down = True
+                logger.warning("SLM remote unreachable: %s; automatic capture paused for %d s; "
+                               "explicit /slm remember still tries every time",
+                               self.last_error, int(CIRCUIT_SECONDS))
+
+    def mark_read_only(self) -> None:
+        with self._lock:
+            if not self.read_only_key:
+                logger.warning("SLM remote key is read-only: automatic capture is off; "
+                               "recall still works")
+            self.read_only_key = True
+
+    def lifecycle_allowed(self, tool: str) -> bool:
+        with self._lock:
+            if self.read_only_key and tool in LIFECYCLE_WRITES:
+                self.dropped_read_only += 1
+                return False
+            if self._clock() < self._open_until:
+                self.dropped_while_open += 1
+                return False
+            return True
+
+    def status_line(self) -> str:
+        with self._lock:
+            parts = [
+                "connection: remote",
+                f"failures since start: {self.failures_total}",
+                f"lifecycle captures skipped while unreachable: {self.dropped_while_open}",
+            ]
+            if self.read_only_key:
+                parts.append(f"read-only key, captures not sent: {self.dropped_read_only}")
+            parts.append(f"last error: {self.last_error or 'none'}")
+            parts.append(f"last success: {self.last_ok_at or 'never'}")
+            return " · ".join(parts)
+
+    def cached_version(self) -> str | None | bool:
+        """The cached server version, or ``False`` when the cache is stale."""
+        with self._lock:
+            if self._version is None or self._clock() - self._version[0] > VERSION_CACHE_SECONDS:
+                return False
+            return self._version[1]
+
+    def remember_version(self, version: str | None) -> None:
+        with self._lock:
+            self._version = (self._clock(), version)
+
+
+def is_read_only_refusal(text: Any) -> bool:
+    return READ_ONLY_TAG in str(text or "")
+
+
+def call(ctx: Any, tool: str, args: dict[str, Any], timeout: float) -> Envelope:
+    try:
+        raw = ctx.call_mcp(SERVER, tool, args, timeout=timeout)
+    except PermissionError:
+        return Envelope.fail("grant_missing", "Hermes has not granted the superlocalmemory MCP "
+                             "server to this plugin (plugins.entries.superlocalmemory."
+                             "mcp_allowlist)")
+    except Exception as exc:  # noqa: BLE001 — a transport failure is a reason, not a crash
+        return Envelope.fail("transport", _bounded(exc))
+    return Envelope.from_hermes(raw)
+
+
+# -- argument builders -------------------------------------------------------------------
+
+
+class _Usage(Exception):
+    pass
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:  # never exit the Hermes process
+        raise _Usage(message)
+
+    def exit(self, status: int = 0, message: str | None = None) -> None:
+        raise _Usage(message or "")
+
+
+def _parser(prog: str) -> _Parser:
+    return _Parser(prog=f"/slm {prog}", add_help=False, exit_on_error=False)
+
+
+def _int_range(low: int, high: int):
+    def convert(text: str) -> int:
+        value = int(text)
+        if not low <= value <= high:
+            raise ValueError
+        return value
+    convert.__name__ = f"integer {low}-{high}"
+    return convert
+
+
+def _no_args(argv: list[str], _sid: str) -> dict | str:
+    return {} if not argv else "This command takes no arguments over a remote connection."
+
+
+def _recall_args(argv: list[str], _sid: str) -> dict | str:
+    p = _parser("recall")
+    p.add_argument("query", nargs="+")
+    p.add_argument("--limit", type=_int_range(1, 50), default=10)
+    p.add_argument("--kind", default="")
+    ns = p.parse_args(argv)
+    args = {"query": " ".join(ns.query), "limit": ns.limit, "agent_id": "hermes"}
+    return {**args, "kind": ns.kind} if ns.kind else args
+
+
+def _remember_args(argv: list[str], session_id: str) -> dict | str:
+    p = _parser("remember")
+    p.add_argument("content", nargs="+")
+    p.add_argument("--tags", default="")
+    p.add_argument("--kind", default="")
+    p.add_argument("--replaces", default=None)
+    ns = p.parse_args(argv)
+    content = " ".join(ns.content)
+    if len(content) > MAX_CONTENT:
+        return f"NOT SAVED: the memory is longer than {MAX_CONTENT} characters."
+    args: dict[str, Any] = {"content": content, "tags": ns.tags, "agent_id": "hermes"}
+    if ns.kind:
+        args["kind"] = ns.kind
+    if ns.replaces:
+        args["replaces"] = ns.replaces
+    seed = json.dumps({"session": session_id, **args}, sort_keys=True)
+    args["idempotency_key"] = hashlib.sha256(
+        ("hermes-remote\0" + seed).encode("utf-8")).hexdigest()[:32]
+    return args
+
+
+def _list_args(argv: list[str], _sid: str) -> dict | str:
+    p = _parser("list")
+    p.add_argument("-n", "--limit", type=_int_range(1, 200), default=20)
+    p.add_argument("--kind", default="")
+    ns = p.parse_args(argv)
+    return {"limit": ns.limit, **({"kind": ns.kind} if ns.kind else {})}
+
+
+def _fact_id_args(argv: list[str], _sid: str) -> dict | str:
+    p = _parser("delete")
+    p.add_argument("fact_id")
+    return {"fact_id": p.parse_args(argv).fact_id, "agent_id": "hermes"}
+
+
+def _update_args(argv: list[str], _sid: str) -> dict | str:
+    p = _parser("update")
+    p.add_argument("fact_id")
+    p.add_argument("content", nargs="+")
+    ns = p.parse_args(argv)
+    return {"fact_id": ns.fact_id, "content": " ".join(ns.content), "agent_id": "hermes"}
+
+
+def _summary_args(argv: list[str], _sid: str) -> dict | str:
+    p = _parser("summary")
+    p.add_argument("kind", nargs="?", default="day")
+    p.add_argument("target", nargs="?", default="")
+    ns = p.parse_args(argv)
+    return {"kind": ns.kind, "target": ns.target}
+
+
+def _trace_args(argv: list[str], _sid: str) -> dict | str:
+    p = _parser("trace")
+    p.add_argument("query", nargs="+")
+    p.add_argument("--limit", type=_int_range(1, 50), default=10)
+    ns = p.parse_args(argv)
+    return {"query": " ".join(ns.query), "limit": ns.limit}
+
+
+# -- renderers ---------------------------------------------------------------------------
+
+
+def _render_json(env: Envelope) -> str:
+    if not env.ok:
+        return f"SLM server error: {env.reason}"
+    text = env.payload if isinstance(env.payload, str) else json.dumps(env.payload, indent=2,
+                                                                      sort_keys=True)
+    return _bounded(text, 8_000)
+
+
+def _render_remember(env: Envelope) -> str:
+    if not env.ok:
+        return f"NOT SAVED: {env.reason}"
+    payload = env.payload
+    if not isinstance(payload, dict) or payload.get("success") is not True:
+        detail = (payload or {}) if isinstance(payload, dict) else {}
+        reason = detail.get("error") or detail.get("code") or \
+            "the SLM server did not confirm the write"
+        return f"NOT SAVED: {_bounded(reason)}"
+    count = len(payload.get("fact_ids") or [])
+    if payload.get("pending"):
+        return f"Saved ({count} fact(s); queryable now, enrichment still running)."
+    return f"Saved ({count} fact(s))."
+
+
+def _render_mutation(env: Envelope) -> str:
+    if not env.ok:
+        return f"NOT CHANGED: {env.reason}"
+    payload = env.payload
+    if not isinstance(payload, dict) or payload.get("success") is not True:
+        detail = payload if isinstance(payload, dict) else {}
+        return f"NOT CHANGED: {_bounded(detail.get('error') or 'the SLM server did not confirm it')}"
+    return "Done."
+
+
+def remote_help() -> str:
+    names = ", ".join(sorted(REMOTE_COMMANDS))
+    return ("Remote connection: these /slm commands run on the SLM server: " + names +
+            ". Commands that manage the SLM computer run there with 'slm <command>'.")
+
+
+@dataclass(frozen=True)
+class RemoteSpec:
+    tool: str | None
+    build: Callable[[list[str], str], dict | str]
+    render: Callable[[Envelope], str]
+
+
+REMOTE_COMMANDS: dict[str, RemoteSpec] = {
+    "status": RemoteSpec("get_status", _no_args, _render_json),
+    "health": RemoteSpec("health", _no_args, _render_json),
+    "recall": RemoteSpec("recall", _recall_args, _render_json),
+    "remember": RemoteSpec("remember", _remember_args, _render_remember),
+    "list": RemoteSpec("list_recent", _list_args, _render_json),
+    "delete": RemoteSpec("delete_memory", _fact_id_args, _render_mutation),
+    "update": RemoteSpec("update_memory", _update_args, _render_mutation),
+    "summary": RemoteSpec("get_memory_summary", _summary_args, _render_json),
+    "trace": RemoteSpec("recall_trace", _trace_args, _render_json),
+    "kinds": RemoteSpec("memory_kinds_status", _no_args, _render_json),
+    "help": RemoteSpec(None, _no_args, lambda _env: remote_help()),
+}
+
+
+def version_problem(ctx: Any, health: RemoteHealth, release: tuple[int, int, int]) -> str | None:
+    """The plugin runs only with the SLM release it ships with, remote or local."""
+    wanted = ".".join(str(p) for p in release)
+    cached = health.cached_version()
+    if cached is False:
+        env = call(ctx, "get_status", {}, timeout=8)
+        if not env.ok:
+            health.record(False, env.reason)
+            return f"SLM server unavailable: {env.reason}"
+        health.record(True)
+        version = env.payload.get("version") if isinstance(env.payload, dict) else None
+        health.remember_version(str(version) if version else None)
+        cached = health.cached_version()
+    if cached != wanted:
+        return (f"Hermes SLM plugin requires exactly SLM {wanted} on the SLM server; the server "
+                f"reports {cached or 'no version'}. Upgrade one side so they match.")
+    return None
+
+
+def run_remote(ctx: Any, argv: list[str], session_id: str, health: RemoteHealth,
+               release: tuple[int, int, int]) -> str:
+    command = argv[0]
+    spec = REMOTE_COMMANDS.get(command)
+    if spec is None:
+        return HOST_ONLY_MESSAGE.format(cmd=command)
+    if spec.tool is None:
+        return remote_help()
+    try:
+        args = spec.build(argv[1:], session_id)
+    except (_Usage, argparse.ArgumentError) as exc:
+        return f"Usage error for /slm {command}: {exc}"
+    if isinstance(args, str):
+        return args
+    problem = version_problem(ctx, health, release)
+    if problem:
+        return f"NOT SAVED: {problem}" if command == "remember" else problem
+    env = call(ctx, spec.tool, args, timeout=_TIMEOUTS.get(spec.tool, 8))
+    if env.ok:
+        health.record(True)
+    elif is_read_only_refusal(env.reason):
+        health.mark_read_only()
+    else:
+        health.record(False, env.reason)
+    rendered = spec.render(env)
+    if command == "status":
+        rendered = f"{rendered}\n{health.status_line()}"
+    return rendered
+
+
+__all__ = ["Envelope", "HOST_ONLY_MESSAGE", "HOST_ONLY_ROLES", "LIFECYCLE_WRITES",
+           "REMOTE_COMMANDS", "REMOTE_SKILLS", "RemoteHealth", "call", "is_read_only_refusal",
+           "remote_help", "run_remote", "version_problem"]

package/hermes-plugin/skills/slm-bot-memory/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: slm-bot-memory
+description: Cross-bot memory on a shared computer (Grok Bot, Cursor plugin, any host where several agents share one machine). Explains agent_id attribution vs. profile/scope access, how to namespace by agent_id + profile + scope, and what must never be written to memory. Read this before the first remember/recall on a new Grok-Bot-style host.
+when_to_use: |
+  - First session on a Grok Bot computer or any shared-bot host
+  - "Will my other bots see this memory?"
+  - "How do I keep this bot's notes separate from that one?"
+  - Deciding whether to store something that looks like a secret or personal data
+  - Setting up a second bot on a computer that already has SLM configured
+allowed-tools: remember, recall, search, session_init, switch_profile
+---
+
+# slm-bot-memory — Cross-Bot Memory on a Shared Host
+
+SuperLocalMemory ships as an MCP server. On a single-user laptop, one bot is
+the only thing talking to it. On a **shared-bot host** — Grok Bot's "one
+computer, shared by all your Bots" model, several Cursor windows, or any
+setup where more than one agent process points at the same install — several
+agents can reach the same memory store at once. This skill is about that
+case: what is actually isolated, what is not, and what must never be written
+regardless.
+
+---
+
+## Three things that sound like isolation and are not the same
+
+| Setting | What it controls | Does it hide memories from another bot? |
+|---|---|---|
+| `SLM_AGENT_ID` | **Attribution** — who gets credit for a memory in logs and summaries | **No.** It is metadata, never an authenticated principal (verified in `mcp/agent_context.py`'s own docstring). Any bot that can query the same store can read a memory written under a different `agent_id`. |
+| `SLM_DATA_DIR` (profile root) | **Which database file** the daemon opens | **Yes.** Two bots pointed at different `SLM_DATA_DIR` values have fully separate, independent memory stores — nothing is shared unless you explicitly configure sharing. |
+| `scope` (`personal` / `shared` / `global`, see `slm-scope`) | **Visibility inside one store**, between profiles that share that store | Only the way you set it. `personal` (the default) stays within the writing profile; `shared`/`global` are explicit, user-initiated opt-ins. |
+
+A memory profile (the namespace `profile_id` and `switch_profile` select) is not
+a fourth kind of isolation between bots. Any local caller that can name a profile
+can read it, and `switch_profile` moves the active profile for every bot on the
+computer. Treat profiles as organisation, not privacy.
+
+The practical rule: **`SLM_AGENT_ID` tells you who wrote something; `SLM_DATA_DIR`
+and `scope` decide who can read it.** If two bots on the same Grok Bot computer
+use the same `SLM_DATA_DIR` (the common case — it is a shared filesystem, and
+nothing in Grok Bot's plugin model points different bots at different data
+directories by default), they see each other's `personal`-scope memories too,
+the same way two terminal sessions on one laptop would. Giving two bots
+different `SLM_AGENT_ID` values does not change that — it only changes whose
+name shows up on the memory.
+
+If you need one bot's memories genuinely unreachable from another, that bot
+needs its **own `SLM_DATA_DIR`** (or a store where company mode with roles is
+configured — see `slm-governance`), not just its own `SLM_AGENT_ID` or its own
+profile.
+
+---
+
+## Namespacing that actually works
+
+Use all three dimensions together, each for what it is good at:
+
+1. **`agent_id`** (`SLM_AGENT_ID` env, or the `agent_id` parameter on
+   `remember`/`recall` directly) — so a human or another agent reading
+   `get_memory_summary` or the stored facts later can tell which bot said
+   what. Set it to something stable and specific: `grok_bot_support`,
+   `grok_bot_release_notes`, not a generic `bot`.
+2. **`SLM_DATA_DIR`** — the real isolation boundary. One store per bot that
+   genuinely needs privacy from the others. A `profile_id` inside a shared store
+   groups memories but does not hide them.
+3. **`scope`** (see `slm-scope`) — inside a store two or more bots
+   legitimately share, keep writes `personal` by default and only promote to
+   `shared`/`global` when a fact is meant for every bot on that store.
+
+```
+remember(
+  content="Deploy window for the support bot is Tue/Thu 14:00-16:00 UTC",
+  tags="ops,schedule",
+  agent_id="grok_bot_support",
+  session_id="<sid>",
+)
+```
+
+```
+recall(
+  query="deploy window",
+  agent_id="grok_bot_support",
+  session_id="<sid>",
+)
+```
+
+Recall is not filtered by `agent_id` automatically — it is attribution on the
+written record. If you need "only what this bot wrote", pass
+`saved_by="grok_bot_support"` to `recall` (or `--saved-by` on `slm recall`),
+which keeps only memories saved by that agent id. It filters; it does not
+protect, because another bot can leave it out.
+
+---
+
+## What never goes into memory, on any host
+
+This is not Grok-Bot-specific — it is the baseline for every SLM host — but
+it matters more here because a shared computer means a shared blast radius if
+it is violated:
+
+- **Secrets, API keys, tokens, passwords, certificates.** Never pass them to
+  `remember`, even "just this once" or "temporarily." If a fact needs to
+  reference that a credential exists, store the *fact of its existence and
+  where to rotate it*, never the value.
+- **Personal data about identifiable people** that was not already something
+  the user explicitly asked to be remembered about themselves (names,
+  emails, addresses, health, financial details of third parties).
+- **Anything from Grok Bot's shared filesystem you did not write yourself**
+  and were not asked to remember. "Files are visible to every Bot" on that
+  computer (Grok Bot's own docs) — a file being readable is not the same as
+  having permission to copy its contents into long-term memory that other
+  bots and later sessions will see.
+- **Command-line credentials.** Grok Bot's own docs note these are shared
+  across bots on the computer; SLM must not become a second, more durable
+  copy of them.
+
+If you are unsure whether something is a secret, treat it as one and ask the
+user before storing anything derived from it.
+
+---
+
+## Checklist for a new bot on an existing shared host
+
+1. Confirm `SLM_DATA_DIR` — is this bot meant to share the existing store, or
+   does it need its own? (`slm status --json` on the computer shows `data.base_dir`
+   and `data.db_path`.)
+2. Set a specific `SLM_AGENT_ID` for this bot before the first `remember`.
+3. Read `slm-scope` before writing anything with `scope="shared"` or
+   `scope="global"` — those are machine-wide, not just cross-bot.
+4. Read the "never goes into memory" list above once, out loud if you are
+   unsure, before the first write on this host.
+
+---
+
+## Related skills
+
+- `slm-getting-started-bot` — first-session setup for a headless bot host
+- `slm-scope` — the personal/shared/global visibility model this skill
+  namespaces on top of
+- `slm-profile` — memory profiles versus tool sets, and what switching does
+- `slm-governance` — role-based access when a store has multiple human/bot
+  members and real access control, not just convention
+
+---
+
+*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*

package/hermes-plugin/skills/slm-cache/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: slm-cache
+description: KV cache for repeated reads — call slm_cache_get(key) first; on a miss do the expensive operation then slm_cache_set(key, value, ttl_seconds) to store it; on a hit use the returned value directly; always fail-open (hit:false on any error, never raises); saves tokens when the same file, query result, or tool output is read more than once in a session.
+when_to_use: "cache file, avoid re-reading, repeated read, cache result, cache tool output, save re-read, reuse across session, cache check, cache hit, cache miss"
+allowed-tools: slm_cache_set, slm_cache_get, Bash
+---
+
+# slm-cache — KV Cache for Repeated Reads (Surface B)
+
+## Purpose
+
+When the same file, query result, or expensive tool output is needed more than once in a session, fetching it again wastes tokens and time. `slm_cache_set` stores a result under a stable key; `slm_cache_get` retrieves it on subsequent calls. The cache is agent-scoped (automatically namespaced by tenant/agent ID), TTL-bounded, and fail-open.
+
+This is an agent-routed cache — it caches results the agent explicitly routes through SLM. It cannot cache Claude conversation turns.
+
+## Tool: slm_cache_set
+
+```
+slm_cache_set(
+    key:          str,          # required — cache key (max 512 chars)
+    value:        str,          # required — value to store (max 1 MB)
+    ttl_seconds:  int = 86400,  # time-to-live in seconds (default 24 h)
+) -> dict
+```
+
+### Return dict
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `ok` | bool | `True` on success; `False` on validation error or internal error |
+| `stored` | bool | `True` when the value was written to the cache |
+| `note` | str \| None | Error detail or `None` on success |
+
+Keys are SHA-256-hashed internally per agent so they do not collide across agents. The raw key string you supply is the only handle you need. The namespace is the calling agent (`SLM_AGENT_ID`, or the `/mcp/<agent>` path), not the memory profile, so switching profiles does not give you a fresh cache. A caller on another computer gets its own namespace, keyed by its access key, and can never see a local agent's entries.
+
+## Tool: slm_cache_get
+
+```
+slm_cache_get(
+    key: str,   # required — same key used in slm_cache_set
+) -> dict
+```
+
+### Return dict
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `ok` | bool | `True` on clean execution (including miss); `False` on internal error |
+| `hit` | bool | `True` when the key exists and has not expired |
+| `value` | str \| None | The stored value on a hit; `None` on miss |
+| `note` | str \| None | Error detail or `None` |
+
+`value` is the string you stored. A miss returns `{"ok": true, "hit": false, "value": null, "note": null}`. `ok: false` means something went wrong internally but the miss behaviour is the same — treat both as a cache miss and proceed with the real fetch.
+
+## Standard Pattern: Cache-Aside
+
+Always check the cache first, then fill on miss:
+
+```python
+# 1. Check cache
+cached = await slm_cache_get(key="file:/absolute/path/to/config.json")
+
+if cached["hit"]:
+    content = cached["value"]
+else:
+    # 2. Expensive operation (file read, search, API call)
+    content = read_file("/absolute/path/to/config.json")
+
+    # 3. Store for the rest of the session
+    await slm_cache_set(
+        key="file:/absolute/path/to/config.json",
+        value=content,
+        ttl_seconds=3600,   # 1 h — adjust to data volatility
+    )
+
+# 4. Use content
+```
+
+## Key Naming Convention
+
+Use a stable, human-readable prefix so keys are recognisable in stats and won't collide accidentally:
+
+| Content type | Suggested prefix | Example |
+|---|---|---|
+| File read | `file:` | `file:/repo/src/config.py` |
+| Search result | `search:` | `search:recall:session_init_context` |
+| Tool output | `tool:` | `tool:build_code_graph:/repo` |
+| External fetch | `url:` | `url:https://api.example.com/v1/data` |
+
+Key length cap: 512 characters. Keys longer than that are rejected (`ok: false`).
+
+## When Caching Pays Off
+
+**Cache when:**
+- You will read the same file more than once in a session.
+- A search or recall result is reused across multiple reasoning steps.
+- An expensive MCP tool call (graph build, semantic search) produces output that is stable for the session duration.
+
+**Do NOT cache:**
+- Volatile data (live API responses that change minute-to-minute, current timestamps, streaming output).
+- Secrets, credentials, tokens, or `ccr_id` values (CCR already handles its own storage).
+- Data that must be fresh for correctness — a stale cache is worse than a cache miss.
+- Intermediate scratchpad text you will discard.
+
+## Fail-Open Guarantee
+
+Neither tool raises an exception. On any internal error:
+
+- `slm_cache_get` returns `{"ok": false, "hit": false, "value": null, ...}` — treat as a miss and proceed with the real fetch.
+- `slm_cache_set` returns `{"ok": false, "stored": false, ...}` — log the note if useful, but continue; the value is still available in memory this step.
+
+Never block a task on a cache failure.
+
+## TTL Guidance
+
+| Data type | Suggested TTL |
+|---|---|
+| Static config / generated file | 86400 s (24 h — the default) |
+| Session-specific tool output | 3600 s (1 h) |
+| Rapidly changing API data | Do not cache, or 60–300 s |
+
+Set `ttl_seconds` to match how long the data remains valid. After expiry `slm_cache_get` returns a miss automatically.
+
+## Secondary CLI (fallback when MCP is unavailable)
+
+Prefer the MCP tools above. If you must use the command line:
+
+```bash
+slm cache status [--json] [--tenant default]
+slm cache clear [--json] [--tenant default]
+slm cache invalidate --tag <tag> [--json] [--tenant default]
+slm cache ttl --set <seconds> [--semantic <seconds>] [--json] [--tenant default]
+slm cache semantic on|off [--json] [--tenant default]
+```
+
+These subcommands control daemon-level cache settings and bulk removal. They do not read or write individual entries — use the MCP tools for that. Entries written by `slm_cache_set` carry the tag `mcp-kv`, so `slm cache invalidate --tag mcp-kv` removes them, and `slm cache clear` deletes every entry for the tenant.
+
+---
+
+## Related skills
+
+- `slm-compress` — for large content reduction; cache and compress work together
+- `slm-status` — view `cache_kv_hits`/`cache_kv_misses` counters (daemon-persisted totals) from `slm_optimize_stats`
+
+---
+
+SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later