superlocalmemory 4.1.21 → 4.1.22

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

@@ -0,0 +1,138 @@
+---
+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`, 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`.
+
+---
+
+## 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` that comes back marked
+`"incomplete"` or with a channel reporting not-ready in that window is not a
+bug; it means the embedding worker had not finished loading yet. 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.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-governance/SKILL.md

@@ -245,4 +245,4 @@ Before running any destructive operation (`forget`, `compact_memories`):
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-graph/SKILL.md

@@ -312,4 +312,4 @@ profile. See `slm-profile` for the full profile switching workflow.
 
 ---
 
-SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-loop/SKILL.md

@@ -96,4 +96,4 @@ paused, name the approval needed; when errored, quote the short detail.
 
 ---
 
-SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-mesh/SKILL.md

@@ -279,4 +279,4 @@ mesh availability.
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-profile/SKILL.md

@@ -99,7 +99,8 @@ configured MCP server instance.
 
 ## Configuring the initial profile
 
-In your `.mcp.json` (Claude Code) or `.codex/config.toml` (Codex):
+Set it where your host defines the MCP server's environment — `.mcp.json` (Claude
+Code), `.codex/config.toml` (Codex), or `mcp.cursor.json` (Cursor / Grok Bot):
 
 ```json
 "env": {
@@ -146,4 +147,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-recall/SKILL.md

@@ -330,4 +330,4 @@ before recalling, then switch back. See `slm-profile` for workspace switching.
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-remember/SKILL.md

@@ -270,4 +270,4 @@ different workspace, use `switch_profile` first. See `slm-profile`.
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-scope/SKILL.md

@@ -173,4 +173,4 @@ to review the impact. See `slm-remember` for the full deletion discipline.
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-session/SKILL.md

@@ -268,4 +268,4 @@ explicitly and call `recall` with `include_global`/`include_shared` after
 
 ---
 
-*SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later*

package/plugin-src/skills/slm-status/SKILL.md

@@ -163,4 +163,4 @@ multi-profile setup. To switch the active profile, see `slm-profile`.
 
 ---
 
-SuperLocalMemory v4.1.21 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.22 · Qualixar · AGPL-3.0-or-later

package/scripts/postinstall.js

@@ -21,6 +21,12 @@ const MIN_PYTHON = Object.freeze([3, 12]);
 const MAX_PYTHON_EXCLUSIVE = Object.freeze([3, 15]);
 const INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
 
+// The official CPU-only wheel index (https://pytorch.org/get-started/locally/,
+// fetched 2026-10-06). PyPI's plain `torch` wheel is CPU-only on macOS/Windows but
+// a CUDA build on Linux (torch + triton + ~18 nvidia-* packages, ~2.6 GiB) even
+// with no GPU present to use it.
+const TORCH_CPU_INDEX_URL = 'https://download.pytorch.org/whl/cpu';
+
 function parsePythonVersion(output) {
   const match = String(output || '').match(/Python\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
   if (!match) return null;
@@ -107,6 +113,72 @@ function findSupportedPython() {
   return null;
 }
 
+/**
+ * Is an NVIDIA GPU visible on this host? Linux-only signal: the three cheap,
+ * side-effect-free checks pip itself has no equivalent for. False on any
+ * error — a check that cannot tell is not evidence of a GPU.
+ * @param {string} platform
+ * @returns {boolean}
+ */
+function hasNvidiaGpu(platform = os.platform()) {
+  if (platform !== 'linux') return false;
+  if (fs.existsSync('/proc/driver/nvidia/version') || fs.existsSync('/dev/nvidia0')) {
+    return true;
+  }
+  try {
+    const probe = spawnSync('nvidia-smi', [], { stdio: 'ignore', timeout: 2000 });
+    return probe.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Should this install pre-fetch the CPU-only torch wheel before the
+ * main package? Mirrors plugin-src/scripts/torch-cpu-resolve.sh's
+ * `torch_cpu_should_force` (same questions, same answers, separate runtime).
+ * False 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.
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} platform
+ * @param {(platform: string) => boolean} gpuCheck injected for testing
+ * @returns {boolean}
+ */
+function shouldForceCpuTorch(env = process.env, platform = os.platform(), gpuCheck = hasNvidiaGpu) {
+  if (platform !== 'linux') return false;
+
+  const backend = String(env.SLM_TORCH_BACKEND || '').trim();
+  if (backend === 'cpu') return true;
+  if (backend) return false; // cuda / cuXXX / auto / ... — the user already decided
+
+  if (env.PIP_INDEX_URL || env.PIP_EXTRA_INDEX_URL) return false;
+
+  return !gpuCheck(platform);
+}
+
+/**
+ * Read the `torch==X.Y.Z` pin shipped at plugin/requirements-cpu-torch.txt
+ * (kept equal to pyproject.toml's torch pin by
+ * tests/test_plugin_src/test_torch_cpu_pin_matches_pyproject.py). Returns
+ * null — fail-open — when the file is missing or has no such line, so a
+ * missing/stale pin file can never block an install that would otherwise
+ * succeed; it only means this optimization is skipped for this run.
+ * @param {string} packageRoot
+ * @returns {string | null}
+ */
+function cpuTorchPin(packageRoot) {
+  const pinFile = path.join(packageRoot, 'plugin', 'requirements-cpu-torch.txt');
+  let content;
+  try {
+    content = fs.readFileSync(pinFile, 'utf8');
+  } catch {
+    return null;
+  }
+  const match = content.match(/^torch==\S+/m);
+  return match ? match[0].trim() : null;
+}
+
 function runtimePythonPath(packageRoot, platform = os.platform()) {
   return platform === 'win32'
     ? path.join(packageRoot, '.slm-venv', 'Scripts', 'python.exe')
@@ -244,6 +316,37 @@ function main(argv = process.argv.slice(2)) {
   }
 
   const runtimePython = runtimePythonPath(packageRoot);
+
+  // Pre-install the pinned CPU-only torch wheel so the main install
+  // below finds it already satisfied and never resolves the CUDA build.
+  // Best-effort: a failure here just means this run keeps the default
+  // resolution (and therefore the CUDA wheels on Linux) — it must never be
+  // the reason the whole install fails.
+  if (shouldForceCpuTorch()) {
+    const torchPin = cpuTorchPin(packageRoot);
+    if (torchPin) {
+      console.log(`  Linux, no GPU detected — installing ${torchPin} from ${TORCH_CPU_INDEX_URL}`);
+      console.log('  (set SLM_TORCH_BACKEND=cuda to opt out).');
+      const installTorch = spawnSync(
+        runtimePython,
+        [
+          '-m', 'pip', 'install',
+          '--disable-pip-version-check',
+          '--no-input',
+          '--index-url', TORCH_CPU_INDEX_URL,
+          torchPin,
+        ],
+        { stdio: 'inherit', timeout: INSTALL_TIMEOUT_MS, env: process.env },
+      );
+      if (installTorch.status !== 0) {
+        console.error(
+          `SuperLocalMemory: CPU-only torch pre-install failed (${failureDetail(installTorch)}); `
+          + 'continuing with the default index.',
+        );
+      }
+    }
+  }
+
   const installPackage = spawnSync(
     runtimePython,
     [
@@ -322,7 +425,9 @@ if (require.main === module) {
 }
 
 module.exports = {
+  cpuTorchPin,
   findSupportedPython,
+  hasNvidiaGpu,
   isSupportedPython,
   main,
   parsePythonVersion,
@@ -330,5 +435,7 @@ module.exports = {
   pypiSpecifier,
   pythonCandidates,
   runtimePythonPath,
+  shouldForceCpuTorch,
+  TORCH_CPU_INDEX_URL,
   validateRuntimeLocation,
 };