superlocalmemory 4.1.21 → 4.1.23

package/plugin/scripts/torch-cpu-resolve.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# torch-cpu-resolve.sh — should this install force a CPU-only torch wheel?
+#
+# PyPI ships CPU-only torch wheels for macOS and Windows, but on Linux the
+# plain `torch==X.Y.Z` wheel pulls the CUDA runtime plus ~18 nvidia-* packages
+# (triton included) — about 2.6 GiB on a host that may have no GPU at all
+# (reference: https://docs.astral.sh/uv/guides/integration/pytorch/, which
+# documents the same PyPI default for `uv pip`; plain pip resolves the same
+# index). The official CPU-only index is documented at
+# https://pytorch.org/get-started/locally/ as:
+#   pip install torch --index-url https://download.pytorch.org/whl/cpu
+#
+# Sourced by ensure-venv.sh (never run directly). Pure decision logic — makes
+# makes no HTTP request and runs no pip — so it is unit-testable without the 2 GiB
+# download it exists to avoid (tests/test_plugin_src/test_torch_cpu_resolve.sh).
+#
+# Environment (all optional):
+#   SLM_TORCH_BACKEND   cpu  — force the CPU index regardless of GPU detection
+#                        <anything else, e.g. cuda/cu124/auto> — leave pip's
+#                        default resolution alone; the user has already decided
+#   PIP_INDEX_URL / PIP_EXTRA_INDEX_URL — if the user already points pip at
+#                        their own index, this never overrides it
+#
+# Safe under `set -euo pipefail`: every variable read has a default.
+
+TORCH_CPU_INDEX_URL="https://download.pytorch.org/whl/cpu"
+
+# torch_cpu_should_force — exit 0 (true, in bash's backwards convention) when
+# this host should get the CPU-only wheel instead of whatever pip would
+# otherwise pick. False (exit 1) covers: not Linux, a GPU is visible, or the
+# user already steered pip (their own index) or torch (SLM_TORCH_BACKEND set
+# to anything but "cpu") themselves.
+torch_cpu_should_force() {
+    local platform
+    platform="$(uname -s 2>/dev/null || echo unknown)"
+    if [ "${platform}" != "Linux" ]; then
+        # macOS (Darwin) already gets CPU-only wheels from plain PyPI; Windows
+        # too. Nothing to override there.
+        return 1
+    fi
+
+    case "${SLM_TORCH_BACKEND:-}" in
+        cpu)
+            return 0
+            ;;
+        "")
+            : # unset — fall through to auto-detection below
+            ;;
+        *)
+            # cuda / cuXXX / auto / anything else: the user already decided.
+            return 1
+            ;;
+    esac
+
+    if [ -n "${PIP_INDEX_URL:-}" ] || [ -n "${PIP_EXTRA_INDEX_URL:-}" ]; then
+        # The user already pointed pip somewhere specific. Do not fight it.
+        return 1
+    fi
+
+    if command -v nvidia-smi >/dev/null 2>&1; then
+        return 1
+    fi
+    if [ -e /proc/driver/nvidia/version ] || [ -e /dev/nvidia0 ]; then
+        return 1
+    fi
+
+    return 0
+}
+
+# torch_cpu_pin <pin_file> — print the "torch==X.Y.Z" line from pin_file.
+# Returns 1 (and prints nothing) when the file is missing or has no such
+# line: fail-open, so a missing/stale pin file can never block an install
+# that would otherwise succeed — it just means pip falls back to its
+# ordinary resolution (the CUDA wheel on Linux) for this run.
+torch_cpu_pin() {
+    local pin_file="$1"
+    if [ ! -f "${pin_file}" ]; then
+        return 1
+    fi
+    local line
+    line="$(grep -m1 '^torch==' "${pin_file}" 2>/dev/null || true)"
+    if [ -z "${line}" ]; then
+        return 1
+    fi
+    printf '%s\n' "${line}"
+}

package/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/plugin/skills/slm-cache/SKILL.md

@@ -31,7 +31,7 @@ slm_cache_set(
 | `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.
+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
 
@@ -50,7 +50,7 @@ slm_cache_get(
 | `value` | str \| None | The stored value on a hit; `None` on miss |
 | `note` | str \| None | Error detail or `None` |
 
-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.
+`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
 
@@ -123,7 +123,7 @@ Set `ttl_seconds` to match how long the data remains valid. After expiry `slm_ca
 
 ## Secondary CLI (fallback when MCP is unavailable)
 
-The `slm cache` subcommand exists but has known pre-existing parse-test failures. Prefer the MCP tools above. If you must use CLI:
+Prefer the MCP tools above. If you must use the command line:
 
 ```bash
 slm cache status [--json] [--tenant default]
@@ -133,16 +133,15 @@ 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. They do not read or write individual cache entries — use the MCP tools for that.
+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 from `slm_optimize_stats`
-- `slm-profile` — cache entries are namespaced per profile; switching profiles gives a fresh cache namespace
+- `slm-status` — view `cache_kv_hits`/`cache_kv_misses` counters (daemon-persisted totals) from `slm_optimize_stats`
 
 ---
 
-SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-compress/SKILL.md

@@ -61,7 +61,7 @@ slm_retrieve(ccr_id: str) -> dict
 
 ### CCR security rule
 
-`ccr_id` values are **unguessable session tokens**. Treat them like short-lived credentials:
+`ccr_id` values are **unguessable session tokens**, and the stored original can be read back only by the same agent (or, for a remote caller, the same access key) that compressed it. Treat them like short-lived credentials:
 - Never log them.
 - Never share them across agents.
 - Never pass them as tool arguments to any tool other than `slm_retrieve`.
@@ -121,7 +121,7 @@ if ccr_id:
 
 ## Secondary CLI (fallback when MCP is unavailable)
 
-The `slm compress` subcommand exists but has known pre-existing parse-test failures. Prefer the MCP tools above. If you must use CLI:
+Prefer the MCP tools above. If you must use the command line:
 
 ```bash
 slm compress status [--json]
@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later

package/plugin/skills/slm-getting-started-bot/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: slm-getting-started-bot
+description: First-session orientation for SuperLocalMemory on a headless bot host (Grok Bot, or any Cursor-format plugin install with no hooks, no dashboard, and no interactive setup wizard). What is different here vs. Claude Code/Codex, which 18 tools are actually available, and the first three calls to make.
+when_to_use: |
+  - The very first session after SLM is installed as a Grok Bot / Cursor plugin
+  - "What can I do with SuperLocalMemory here?"
+  - A recall or remember call fails and you are not sure why on this host
+  - Comparing what works here vs. what the other skills describe for Claude Code
+allowed-tools: session_init, remember, recall, switch_profile
+---
+
+# slm-getting-started-bot — First Session on a Headless Bot Host
+
+You are talking to SuperLocalMemory through its MCP server, started as
+`uvx --from superlocalmemory==<version> slm mcp` by the plugin manifest. This
+skill is for the ways that is different from a Claude Code or Codex install —
+read it once per new host, not once per session.
+
+---
+
+## What is NOT available here
+
+Grok Bot (and Cursor's plugin host generally) reads only two parts of a
+plugin: `mcpServers` and `skills`. It does not run:
+
+- **Hooks** — no automatic session-start context load, no automatic
+  checkpoint on session end. Call `session_init` yourself at the start of a
+  session if you want prior context; nothing injects it for you.
+- **Slash commands or sub-agents** — the `commands/` and `agents/` components
+  other SLM plugins ship are Claude-Code-shaped and are not part of this
+  install. Everything you can do here, you do through the MCP tools
+  directly.
+- **A dashboard.** There is no browser UI to check on this host. `slm status`
+  style information comes back from the tools themselves (`session_init`'s
+  response, or asking `recall` for recent memories) — there is nothing to
+  click.
+- **`ANTHROPIC_BASE_URL` or any Claude-specific proxy behavior.** SLM does not
+  depend on it anywhere; nothing to configure here either way.
+
+None of this is a degraded mode — it is the whole surface. Do not tell the
+user a feature is "missing" when it was simply never wired to this host
+format in the first place.
+
+---
+
+## What IS available: the core profile (18 tools)
+
+This plugin sets `SLM_MCP_PROFILE=core`, the smallest tool tier, on purpose —
+a shared, memory-tight computer should not load tool descriptions or RAM for
+tiers it will not use. The 18 tools:
+
+`remember`, `recall`, `search`, `fetch`, `list_recent`, `update_memory`,
+`forget`, `session_init`, `close_session`, `slm_compress`, `slm_retrieve`,
+`slm_cache_set`, `slm_cache_get`, `slm_optimize_stats`, `review_correction`,
+`list_corrections`, `get_memory_summary`, `switch_profile`.
+
+If you are looking at another skill that mentions a tool NOT in this list
+(`build_code_graph`, `mesh_send`, `report_outcome`, `delete_memory`,
+`set_memory_kind`, anything governance/compliance-shaped), that skill describes
+a different, larger profile (`code`, `full`, `power`) — it is accurate for Claude
+Code or Codex installs, not for this one, unless someone has deliberately
+reconfigured `SLM_MCP_PROFILE`. Skip those steps rather than reporting an error.
+
+Two things the core set does cover that other skills explain: `remember` takes
+`kind` and `replaces` (a newer version of a memory should be saved with
+`replaces=<fact_id>`; see `slm-remember`), and `list_corrections` /
+`review_correction` handle the review of an `update_memory` edit. A bot with
+no one to review should prefer `replaces` over `update_memory`.
+
+---
+
+## The first three calls on a new host
+
+1. **`session_init`** — nothing runs this automatically here (no hooks), so
+   call it yourself at the start of the first real session:
+   ```
+   session_init(project_path="<where you are working>", query="")
+   ```
+   Returns recent relevant memories and a session id to pass to later calls.
+
+2. **`remember`** one real fact, before doing anything else, as a smoke test:
+   ```
+   remember(content="First session on this host, verifying setup.", tags="setup", session_id="<sid>")
+   ```
+
+3. **`recall`** it back:
+   ```
+   recall(query="first session verifying setup", session_id="<sid>")
+   ```
+   If this returns the fact, the daemon, the embedding path, and the
+   CPU-only torch install all worked. If it does not, the result still tells
+   you something — see Troubleshooting below.
+
+---
+
+## Cold start is slower here than on a warm laptop
+
+The first `remember`/`recall` on a fresh `SLM_DATA_DIR` has to: resolve
+`uvx`'s pinned `superlocalmemory` package, start the daemon, and warm an
+embedding model (and, unless this is the lite profile, a reranker model) —
+tens of seconds, not milliseconds. A `recall` whose `channel_status` shows
+`warming` (or `no_embedding`) for some channels in that window is not a bug; it
+means the embedding model had not finished loading yet, and the answer is
+incomplete rather than empty. Retry once rather than assuming something is
+broken.
+
+---
+
+## This host already runs the lite bot-host profile
+
+Unless something overrode it, `mcp.cursor.json` sets `SLM_RERANKER_ENABLED=
+false`, `SLM_RERANKER_IDLE_TIMEOUT=120`, and `SLM_MAX_EMBEDDING_WORKERS=1` —
+the RAM-conscious default for a computer shared by every bot on it. Recall
+still runs every other channel (BM25, semantic, entity graph, temporal,
+spreading activation, Hopfield) and fuses them; it just skips the
+cross-encoder re-ranking pass. If recall quality seems to matter more than
+RAM headroom for your use case, the user can set `SLM_RERANKER_ENABLED=true`
+in the manifest's env block — ask before changing it, since it trades RAM for
+quality on a shared box.
+
+---
+
+## Troubleshooting
+
+- **A tool call returns a "profile" or "tool not available" style error** —
+  you are probably calling a tool outside the 18-tool core set. Check the
+  list above before assuming the server is broken.
+- **Everything times out on the very first call of a session** — likely the
+  cold-start warmup described above. Wait and retry once before reporting a
+  failure.
+- **You are not sure whether another bot on this computer can see what you
+  just stored** — read `slm-bot-memory` before storing anything you would
+  not want another bot on this machine to read.
+
+---
+
+## Related skills
+
+- `slm-bot-memory` — cross-bot namespacing and what must never be stored
+- `slm-remember` / `slm-recall` — full parameter reference for the two tools
+  you will use the most
+- `slm-session` — what `session_init`/`close_session` actually do
+
+---
+
+*SuperLocalMemory v4.1.23 · Qualixar · AGPL-3.0-or-later*