superlocalmemory 4.1.18 → 4.1.20

package/plugin/scripts/slm-run

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# slm-run — run slm for a plugin hook, using the slm the MCP server uses.
+#
+#   "${CLAUDE_PLUGIN_ROOT}/scripts/slm-run" hook <name>
+#
+# Hooks used to call a bare `slm`, so on a machine where SuperLocalMemory lives
+# only in the plugin venv every hook was "command not found" — and the error was
+# thrown away, so memory capture stopped with nothing to say why. This wrapper
+# resolves slm with the launcher's own code (slm-resolve.sh), honours the same
+# SLM_LAUNCHER, and passes stdin, stdout and the arguments straight through.
+#
+# A hook must never break the session that runs it, so this ALWAYS exits 0
+# (Claude Code reads exit 2 as "block"). When slm cannot be found, or fails, the
+# reason goes to
+#     ${SLM_DATA_DIR:-~/.superlocalmemory}/logs/plugin-hooks.log
+# and one line naming that file goes to stderr. A hook that succeeds is silent:
+# whatever slm wrote to stderr is discarded, exactly as before.
+
+_slm_args="$*"
+_log_dir="${SLM_DATA_DIR:-${HOME}/.superlocalmemory}/logs"
+_log="${_log_dir}/plugin-hooks.log"
+_LOG_MAX_BYTES=1048576
+
+# Append one entry. Best effort: an unwritable log must not fail the hook.
+_log_entry() {
+    {
+        mkdir -p "${_log_dir}" || return 1
+        if [ -f "${_log}" ] && [ "$(wc -c < "${_log}")" -gt "${_LOG_MAX_BYTES}" ]; then
+            mv -f "${_log}" "${_log}.1"
+        fi
+        printf '%s slm %s: %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "${_slm_args}" "$1" >> "${_log}"
+    } 2>/dev/null
+}
+
+# Record a failure, tell stderr where to look, and leave the session alone.
+_give_up() {
+    if _log_entry "$1"; then
+        echo "SLM plugin: hook 'slm ${_slm_args}' did not run cleanly; see ${_log}" >&2
+    else
+        echo "SLM plugin: hook 'slm ${_slm_args}' did not run cleanly: $1" >&2
+    fi
+    exit 0
+}
+
+_here="${BASH_SOURCE[0]%/*}"
+[ "${_here}" = "${BASH_SOURCE[0]}" ] && _here=.
+# shellcheck source=slm-resolve.sh
+if ! . "${_here}/slm-resolve.sh" 2>/dev/null; then
+    _give_up "the plugin is incomplete: ${_here}/slm-resolve.sh is missing"
+fi
+
+if ! slm_choose; then
+    _give_up "$(printf '%s' "${SLM_RESOLVE_ERROR}" | tr '\n' ' ')"
+fi
+
+if [ "${SLM_CHOICE_READY}" -ne 1 ]; then
+    if [ "${SLM_LAUNCHER:-auto}" = "auto" ]; then
+        _give_up "$(slm_not_found_message | tr '\n' ' ') (A plugin venv is built by SessionStart; the first session can run its hooks before it exists.)"
+    fi
+    _give_up "${SLM_CHOICE} slm is not executable: ${SLM_CHOICE_BIN}"
+fi
+
+# slm's stderr is kept only long enough to report a failure. The trap removes
+# it however this script ends, including a host timeout killing the hook.
+_err="$(mktemp "${TMPDIR:-/tmp}/slm-hook.XXXXXX" 2>/dev/null)" || _err=/dev/null
+trap '[ "${_err}" = /dev/null ] || rm -f "${_err}"' EXIT
+trap 'exit 0' HUP INT TERM
+
+"${SLM_CHOICE_BIN}" "$@" 2>"${_err}"
+_rc=$?
+if [ "${_rc}" -ne 0 ]; then
+    _detail=""
+    [ "${_err}" = /dev/null ] || _detail="$(tail -n 5 "${_err}" 2>/dev/null | tr '\n' ' ')"
+    _give_up "exit ${_rc} from ${SLM_CHOICE_BIN} (${SLM_CHOICE})${_detail:+: ${_detail}}"
+fi
+exit 0

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

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

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

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

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

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

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

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

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

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

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

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

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

@@ -31,9 +31,9 @@ project, a client engagement, a production vs staging environment.
 | Profile | Tools | When to use |
 |---------|-------|-------------|
 | `core` | 18 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
-| `code` | 34 tools — core + portable Brain evidence + code graph + profile switching + bounded loops | Default for IDE/coding agents |
-| `full` | 50 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
-| `power` | 62 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
+| `code` | 38 tools — core + portable Brain evidence + code graph + profile switching + bounded loops + memory-kind management | Default for IDE/coding agents |
+| `full` | 54 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
+| `power` | 66 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
 | `mesh` | 8 tools — mesh coordination only | Lightweight cross-session signalling |
 
 The profile is set at MCP server startup via `SLM_MCP_PROFILE` in the MCP config.
@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later*

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

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

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

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

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

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

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

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

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

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

package/plugin-src/agents/slm-memory-advisor.md

@@ -47,4 +47,4 @@ slm-recall · slm-remember · slm-session · slm-scope · slm-profile · slm-gov
 # What NOT to do
 Never session_init twice; never forget dry_run=False without reporting preview; never dump a whole file into remember; never invent a memory; never claim "saved" without success:true / clean CLI exit; never bypass scope or governance restrictions.
 
-SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

package/plugin-src/agents/slm-optimize-advisor.md

@@ -41,4 +41,4 @@ slm-compress · slm-cache · slm-status · slm-profile
 # What NOT to do
 Never compress code-for-edit/JSON-to-parse/<500 chars; never store secrets/ccr_ids; never let optimize failure block/alter the task; never claim a specific savings %; never carry ccr_ids across profile switches.
 
-SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

package/plugin-src/rules/AGENTS.md

@@ -83,16 +83,27 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 
 ## Tool reference (core profile — 18 tools)
 
-> The MCP config ships `SLM_MCP_PROFILE=code` and `SLM_AGENT_ID=claude_code` (34 tools):
-> the 18 core tools below **plus** 6 code-graph tools (`build_code_graph`,
-> `get_blast_radius`, `query_graph`, `semantic_search_code`, `get_review_context`,
-> `detect_changes`), 5 portable-evidence tools (`get_brain_evidence_status`,
-> `record_agent_experience`, `record_cognitive_turn`, `finalize_cognitive_turn`,
-> `observe_bounded_loop_evidence`), 3 bounded-loop tools (`slm_loop_run`,
-> `slm_loop_history`, `slm_loop_show`) and 2 usefulness reports (`report_outcome`,
-> `report_feedback`).
-> Use `full` (50 tools) to add mesh coordination. Use `power` (62 tools) for governance
-> and audit tools. See slm-profile for profile switching.
+> The MCP config ships only `SLM_AGENT_ID=claude_code` — no `SLM_MCP_PROFILE` —
+> so it falls back to the same no-profile default every install gets: the
+> 54-tool `full` surface. That is the 18 core tools below **plus** mesh
+> coordination (8: `mesh_summary`, `mesh_peers`, `mesh_send`, `mesh_inbox`,
+> `mesh_state`, `mesh_lock`, `mesh_events`, `mesh_status`), portable-evidence
+> tools (5: `get_brain_evidence_status`, `record_agent_experience`,
+> `record_cognitive_turn`, `finalize_cognitive_turn`,
+> `observe_bounded_loop_evidence`), memory-kind tools (4: `set_memory_kind`,
+> `memory_kinds_status`, `review_memory_kinds`, `confirm_memory_kinds`),
+> bounded-loop tools (3: `slm_loop_run`, `slm_loop_history`, `slm_loop_show`),
+> usefulness reports (2: `report_outcome`, `report_feedback`) and 14 more
+> administration/learning tools (`delete_memory`, `get_status`, `observe`,
+> `run_maintenance`, `consolidate_cognitive`, `get_soft_prompts`, `set_mode`,
+> `log_tool_event`, `get_assertions`, `reinforce_assertion`,
+> `contradict_assertion`, `evolve_skill`, `skill_health`, `skill_lineage`).
+> Set `SLM_MCP_PROFILE=code` yourself for the narrower 38-tool `code` surface,
+> which trades mesh and administration tools for 6 code-graph tools
+> (`build_code_graph`, `get_blast_radius`, `query_graph`,
+> `semantic_search_code`, `get_review_context`, `detect_changes`). Use
+> `power` (66 tools) for governance and audit tools. See slm-profile for
+> profile switching.
 
 | Tool               | Signature (key params)                                                                       | Notes                                  |
 |--------------------|----------------------------------------------------------------------------------------------|----------------------------------------|
@@ -138,4 +149,4 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 - **slm-optimize-advisor** — context compression and KV cache
 - **slm-governance-advisor** — scope/role compliance, retention policies, GDPR
 
-SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

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

@@ -145,4 +145,4 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

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

@@ -147,4 +147,4 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

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

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

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

@@ -31,9 +31,9 @@ project, a client engagement, a production vs staging environment.
 | Profile | Tools | When to use |
 |---------|-------|-------------|
 | `core` | 18 tools — remember, recall, search, session, optimize | Minimal footprint, no code tools |
-| `code` | 34 tools — core + portable Brain evidence + code graph + profile switching + bounded loops | Default for IDE/coding agents |
-| `full` | 50 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
-| `power` | 62 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
+| `code` | 38 tools — core + portable Brain evidence + code graph + profile switching + bounded loops + memory-kind management | Default for IDE/coding agents |
+| `full` | 54 tools — code + all memory ops + mesh + bounded loops | Multi-session, team workflows |
+| `power` | 66 tools — full + governance + behavioral tools | Enterprise, admin, audit use cases |
 | `mesh` | 8 tools — mesh coordination only | Lightweight cross-session signalling |
 
 The profile is set at MCP server startup via `SLM_MCP_PROFILE` in the MCP config.
@@ -146,4 +146,4 @@ Name them differently in your MCP config (e.g. `superlocalmemory-personal` and
 
 ---
 
-*SuperLocalMemory v4.1.18 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later*
+*SuperLocalMemory v4.1.20 · 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.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v4.1.20 · Qualixar · AGPL-3.0-or-later

package/scripts/postinstall.js

@@ -17,7 +17,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const MIN_PYTHON = Object.freeze([3, 11]);
+const MIN_PYTHON = Object.freeze([3, 12]);
 const MAX_PYTHON_EXCLUSIVE = Object.freeze([3, 15]);
 const INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
 
@@ -43,12 +43,19 @@ function pythonCandidates(platform = os.platform()) {
       ['py', '-3.14'],
       ['py', '-3.13'],
       ['py', '-3.12'],
-      ['py', '-3.11'],
       ['python3'],
       ['python'],
     ];
   }
+  // Debian 12, Ubuntu 22.04 (with deadsnakes) and RHEL 9 all ship a system
+  // `python3` older than 3.12, with the supported versioned interpreter
+  // installed alongside it, unused. Try the versioned names first so that
+  // interpreter is found before falling back to the bare names and the
+  // fixed absolute paths below.
   return [
+    ['python3.14'],
+    ['python3.13'],
+    ['python3.12'],
     ['python3'],
     ['python'],
     ['/opt/homebrew/bin/python3'],
@@ -57,21 +64,44 @@ function pythonCandidates(platform = os.platform()) {
   ];
 }
 
+function probePython(command, prefixArgs) {
+  try {
+    const result = spawnSync(command, [...prefixArgs, '--version'], {
+      stdio: 'pipe',
+      timeout: 5000,
+      env: process.env,
+    });
+    const output = `${(result.stdout || '').toString()} ${(result.stderr || '').toString()}`;
+    return { status: result.status, version: parsePythonVersion(output) };
+  } catch (error) {
+    return { status: null, version: null, error };
+  }
+}
+
 function findSupportedPython() {
+  const override = String(process.env.SLM_PYTHON || '').trim();
+  if (override) {
+    // The user named this interpreter explicitly (docs/getting-started.md's
+    // escape hatch for a system where no supported `python3` is on PATH, for
+    // example a deadsnakes or pyenv install at a custom path). Honour it,
+    // but still version-check it — and if it fails, say so plainly instead
+    // of silently trying a different interpreter the user did not choose.
+    const probe = probePython(override, []);
+    if (probe.status === 0 && isSupportedPython(probe.version)) {
+      return { command: override, prefixArgs: [], version: probe.version };
+    }
+    const detail = probe.status === 0 && probe.version
+      ? `found Python ${probe.version.join('.')}, which is not supported (need 3.12-3.14)`
+      : 'could not be run (check the path and that it is executable)';
+    console.error(`SuperLocalMemory: SLM_PYTHON=${override} ${detail}.`);
+    console.error('Point SLM_PYTHON at a Python 3.12-3.14 interpreter, or unset it to let the installer search automatically.');
+    return null;
+  }
+
   for (const candidate of pythonCandidates()) {
-    try {
-      const result = spawnSync(candidate[0], [...candidate.slice(1), '--version'], {
-        stdio: 'pipe',
-        timeout: 5000,
-        env: process.env,
-      });
-      const output = `${(result.stdout || '').toString()} ${(result.stderr || '').toString()}`;
-      const version = parsePythonVersion(output);
-      if (result.status === 0 && isSupportedPython(version)) {
-        return { command: candidate[0], prefixArgs: candidate.slice(1), version };
-      }
-    } catch (_error) {
-      // Try the next interpreter without mutating PATH or the machine.
+    const probe = probePython(candidate[0], candidate.slice(1));
+    if (probe.status === 0 && isSupportedPython(probe.version)) {
+      return { command: candidate[0], prefixArgs: candidate.slice(1), version: probe.version };
     }
   }
   return null;
@@ -142,7 +172,7 @@ function validateRuntimeLocation(venvRoot) {
 
 function printPythonGuidance() {
   console.error('');
-  console.error('SuperLocalMemory requires Python 3.11, 3.12, 3.13, or 3.14.');
+  console.error('SuperLocalMemory requires Python 3.12, 3.13, or 3.14.');
   console.error('Install Python from https://www.python.org/downloads/ and rerun:');
   console.error('  npm rebuild superlocalmemory');
   console.error('The npm installer will create a private virtual environment;');
@@ -296,6 +326,7 @@ module.exports = {
   isSupportedPython,
   main,
   parsePythonVersion,
+  probePython,
   pypiSpecifier,
   pythonCandidates,
   runtimePythonPath,