superlocalmemory 3.6.13 → 3.6.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.6.13",
+  "version": "3.6.14",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",
@@ -46,10 +46,12 @@
     "superlocalmemory": "./bin/slm-npm"
   },
   "scripts": {
-    "prepack": "node scripts/prepack.js",
+    "build:plugin": "node scripts/build-plugin.js",
+    "check:plugin": "node scripts/build-plugin.js --check",
+    "prepack": "node scripts/build-plugin.js && node scripts/prepack.js",
     "postinstall": "node scripts/postinstall.js",
     "preuninstall": "node scripts/preuninstall.js",
-    "test": "echo \"Run: npm install -g . && slm status\" && exit 0"
+    "test": "node --test 'tests/ui/*.mjs'"
   },
   "engines": {
     "node": ">=18.0.0",
@@ -65,7 +67,9 @@
     "src/",
     "ide/",
     "scripts/",
-    "skills/",
+    ".claude-plugin/",
+    "plugin/",
+    "plugin-src/",
     "pyproject.toml",
     "README.md",
     "LICENSE",
@@ -87,5 +91,8 @@
   ],
   "dependencies": {
     "docx": "^9.5.1"
+  },
+  "devDependencies": {
+    "jsdom": "^29.1.1"
   }
-}
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "author": {
+    "name": "Qualixar",
+    "url": "https://github.com/qualixar/superlocalmemory"
+  },
+  "description": "Local-first agent memory + reversible context compression and KV cache, as an MCP server. 20-tool code profile with graph intelligence.",
+  "displayName": "SuperLocalMemory",
+  "hooks": "./hooks/hooks.json",
+  "keywords": [
+    "memory",
+    "mcp",
+    "agents",
+    "local-first",
+    "context-compression"
+  ],
+  "mcpServers": "./.mcp.json",
+  "name": "superlocalmemory",
+  "repository": "https://github.com/qualixar/superlocalmemory",
+  "version": "3.6.14"
+}

package/plugin/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/slm-launch",
+      "args": [],
+      "env": {
+        "SLM_MCP_PROFILE": "code",
+        "SLM_DATA_DIR": "${CLAUDE_PLUGIN_DATA}"
+      }
+    }
+  }
+}

package/plugin/CLAUDE.md

@@ -0,0 +1,43 @@
+<!-- BEGIN SuperLocalMemory v3.6.14 -->
+
+## SuperLocalMemory (SLM) — Agent Rules
+
+SLM is local-first memory for agents. All tools run on the user's machine; no cloud calls.
+
+### Session start
+Call `session_init(project_path, query)` ONCE per fresh session before any recall/remember. Never twice.
+
+### Remember
+- Atomic durable facts only (decisions, conventions, constraints, gotchas). One fact per call.
+- Recall-before-remember: `recall(query, 5)` first; use `update_memory` if near-match found.
+- Always supply tags + project + importance (7–10 for blockers/security/architecture).
+- Never dump a whole file; never claim "saved" without success:true.
+
+### Recall
+- `recall` for conceptual/semantic queries; `search` for exact keywords.
+- Phrase as concepts; pass session_id when available. Never fabricate.
+
+### Optimize (fail-open)
+- Output >2000 chars → `slm_compress(mode="auto", reversible=True)`; keep ccr_id if lossy.
+- Repeated reads → `slm_cache_get("file:<path>")` first; on miss cache with ttl=1800.
+- NEVER compress/cache: code-for-edit, JSON-to-parse, secrets, ccr_ids, <500 chars.
+- If ok:false → continue with original; never block the task.
+
+### Session end
+`close_session(session_id)` when work is meaningfully complete.
+
+### CLI fallback (MCP down)
+`slm recall "<q>" --limit N` · `slm search "<q>"` · `slm remember "<c>" --tags t --importance N` · `slm list --limit N` · `slm forget` (preview first) · `slm status` · `slm optimize status`
+
+### Skills
+slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-compress · slm-graph
+
+### Commands
+/superlocalmemory:slm-recall · /superlocalmemory:slm-remember · /superlocalmemory:slm-session · /superlocalmemory:slm-status · /superlocalmemory:slm-cache · /superlocalmemory:slm-compress · /superlocalmemory:slm-graph
+
+### Subagents
+slm-memory-advisor (memory decisions, session hygiene) · slm-optimize-advisor (context compression + KV cache)
+
+<!-- END SuperLocalMemory v3.6.14 -->
+
+SuperLocalMemory v3.6.14 · Qualixar · AGPL-3.0-or-later

package/plugin/_GENERATED.md

@@ -0,0 +1,6 @@
+# _GENERATED — DO NOT HAND-EDIT
+
+This directory is generated by `scripts/build-plugin.js` from `plugin-src/`.
+Run `npm run build:plugin` to regenerate.
+Run `npm run check:plugin` (or `--check`) in CI to verify in-sync.
+Source of truth: `plugin-src/skills/`, `plugin-src/manifest.json`.

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

@@ -0,0 +1,43 @@
+---
+name: slm-memory-advisor
+description: >
+  Advises the main agent on using SuperLocalMemory well — when to call
+  session_init, remember, recall, and search; how to phrase queries; and how
+  to keep memory clean. Delegate here for any "should I save/recall this?"
+  decision or when memory results look wrong.
+tools: session_init, recall, search, remember, update_memory, forget, list_recent, Read
+model: inherit
+---
+
+# Role
+You are the SuperLocalMemory (SLM) memory advisor. You help the main agent use the local-first memory system correctly across a session. You do not do the user's primary task — you make memory usage disciplined: the right thing saved, the right thing recalled, nothing duplicated, nothing lost between sessions. SLM is 100% local; every tool runs on the user's machine.
+
+# When to act
+When the main agent: starts a session and hasn't loaded project context; is about to or just made a decision worth persisting; asks "what did we decide about X"; gets recall results that look irrelevant/empty.
+
+# Tools you may use (real SLM MCP tools, core profile)
+- `session_init(project_path, query, max_results, max_age_days)` — ONCE at session start; returns recent decisions + relevant memories.
+- `recall(query, limit, session_id, fast)` — multi-channel semantic retrieval (default limit 10).
+- `search(query, limit, profile_id)` — exact keyword / FTS5 BM25.
+- `remember(content, tags, project, importance, session_id)` — store atomic fact; importance 1-10.
+- `update_memory(fact_id, content)` — correct by exact id.
+- `forget(profile_id, dry_run)` — decay cycle; ALWAYS dry_run=True first, report, never apply blind.
+- `list_recent(limit)` — newest first.
+- `Read` — inspect a file before deciding what to remember.
+
+# Decision rules
+1. SESSION_INIT FIRST — once, before any recall/remember in a fresh session. Never skip; never twice.
+2. RECALL BEFORE REMEMBER — if it exists, update_memory instead of duplicating.
+3. REMEMBER ATOMIC DURABLE FACTS ONLY — decisions/conventions/constraints/gotchas/stable prefs; one per call; add tags+project; importance 7-10 for blockers/security/architecture.
+4. QUERY PHRASING — concept phrases not vague words; pass session_id when available.
+5. recall vs search — recall for conceptual; search for literal keyword.
+6. EMPTY/LOW results → broaden, try search, or list_recent; never fabricate.
+7. SESSION END — close_session(session_id) when work meaningfully complete.
+
+# CLI fallback (MCP unavailable)
+recall→`slm recall "<q>" --limit N` · search→`slm search "<q>"` · remember→`slm remember "<c>" --tags a,b --project p --importance N` · list→`slm list --limit N` · forget→`slm forget` (preview first) · status→`slm status`. session_init/close_session are daemon-implicit (no CLI verb) — skip on MCP-down.
+
+# 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.
+
+SuperLocalMemory v3.6.14 · Qualixar · AGPL-3.0-or-later

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

@@ -0,0 +1,38 @@
+---
+name: slm-optimize-advisor
+description: >
+  Applies SuperLocalMemory's context-optimization rules — reversible
+  compression of large tool output and KV-caching of repeated reads/searches —
+  to stretch the context window with no proxy. Delegate here when context is
+  filling up or the same files/searches are read repeatedly. Strictly advisory
+  and fail-open: optimization must never block the primary task.
+tools: slm_compress, slm_retrieve, slm_cache_set, slm_cache_get, slm_optimize_stats, Read, Bash
+model: inherit
+---
+
+# Role
+You are the SLM optimize advisor. You reduce context-window pressure using Surface-B tools: reversible compression (CCR) and a per-agent KV cache. No proxy; full 1M window preserved on any plan. You apply the same rules as the slm-compress and slm-cache skills. You cannot cache the primary Claude turn (needs a proxy) — only content the agent routes through SLM.
+
+# When to act
+Tool/file read >~2000 chars; same file or bash/web search about to be re-read; user asks how much context saved; context tight with large outputs sitting in window.
+
+# Tools (real SLM MCP tools, code profile)
+slm_compress(content,mode,reversible,ttl_seconds)→compressed,lossy,ccr_id (mode normalize|auto|aggressive); slm_retrieve(ccr_id); slm_cache_set(key,value,ttl_seconds); slm_cache_get(key)→hit,value; slm_optimize_stats(); Read/Bash to fetch content.
+
+# Decision rules (the 8 — apply automatically)
+1. CLAUDE.md >3000 chars → slm_compress(mode="normalize", reversible=False), use compressed IN CONTEXT ONLY; never modify the file.
+2. Tool output >2000 chars → slm_compress(mode="auto", reversible=True); work from compressed; keep ccr_id if lossy.
+3. Repeated file reads → slm_cache_get("file:<path>") first; on miss Read then slm_cache_set("file:<path>", ttl 1800); invalidate on Edit/Write.
+4. Repeated bash/web → slm_cache_set("bash:<cmd[:64]>", ttl 600); web ttl 3600.
+5. Retrieve original only when byte-identical needed.
+6. NEVER compress/cache: code for Edit/Write; JSON to parse; secrets/keys/tokens; ccr_ids; <500 chars.
+7. Stats → slm_optimize_stats() (KV this-session; proxy/compress daemon-persisted).
+8. FAIL-OPEN: ok:false → continue with original, no retry, don't surface unless asked. Never block the task.
+
+# CLI fallback
+stats→`slm optimize status`/`savings` · compress→`slm compress` · cache→`slm cache ...`. If CLI also fails, drop optimization silently (rule 8).
+
+# 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 %.
+
+SuperLocalMemory v3.6.14 · Qualixar · AGPL-3.0-or-later

package/plugin/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/ensure-venv.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/requirements.txt

@@ -0,0 +1 @@
+superlocalmemory==3.6.14

package/plugin/scripts/ensure-venv.bat

@@ -0,0 +1,122 @@
+@echo off
+:: ensure-venv.bat — WP-F SuperLocalMemory plugin venv bootstrap (Windows)
+::
+:: Windows equivalent of ensure-venv.sh. Called by Claude Code SessionStart hook
+:: on Windows hosts. Idempotent: fast-path exits quickly when requirements.txt
+:: is unchanged (sentinel file guards reinstall).
+::
+:: Environment (set by Claude Code plugin runtime):
+::   CLAUDE_PLUGIN_ROOT  — plugin installation dir (ephemeral, contains scripts\ + requirements.txt)
+::   CLAUDE_PLUGIN_DATA  — persistent data dir (venv lives here, survives plugin updates)
+::
+:: Exit codes: 0 = venv ready   non-0 = failure (logged to stderr)
+:: All informational output goes to stderr (stdout reserved for MCP stdio protocol).
+::
+:: Requires: Python 3.11+ on PATH, pip, standard Windows cmd.exe
+
+setlocal EnableDelayedExpansion
+
+:: ---------------------------------------------------------------------------
+:: Guard: required env vars must be set
+:: ---------------------------------------------------------------------------
+if not defined CLAUDE_PLUGIN_ROOT (
+    echo ERROR: CLAUDE_PLUGIN_ROOT must be set ^(plugin installation directory^) >&2
+    exit /b 1
+)
+if not defined CLAUDE_PLUGIN_DATA (
+    echo ERROR: CLAUDE_PLUGIN_DATA must be set ^(plugin persistent data directory^) >&2
+    exit /b 1
+)
+
+:: ---------------------------------------------------------------------------
+:: Python >= 3.11 guard
+:: ---------------------------------------------------------------------------
+python -c "import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)" 2>nul
+if errorlevel 1 (
+    for /f "tokens=*" %%v in ('python --version 2^>^&1') do set PY_VER=%%v
+    echo ERROR: SuperLocalMemory plugin requires Python ^>= 3.11, found: !PY_VER! >&2
+    echo Install Python 3.11+ and ensure it is first on PATH. >&2
+    exit /b 1
+)
+
+:: ---------------------------------------------------------------------------
+:: Paths
+:: ---------------------------------------------------------------------------
+set "REQ=%CLAUDE_PLUGIN_ROOT%\requirements.txt"
+set "VENV=%CLAUDE_PLUGIN_DATA%\venv"
+set "VENV_SCRIPTS=%VENV%\Scripts"
+set "SENTINEL=%CLAUDE_PLUGIN_DATA%\.venv-reqs.sha256"
+set "VENV_TMP=%CLAUDE_PLUGIN_DATA%\venv.tmp"
+
+:: ---------------------------------------------------------------------------
+:: Compute sha256 of requirements.txt using PowerShell (built-in on Windows 10+)
+:: Output: hex string of SHA256 hash
+:: ---------------------------------------------------------------------------
+for /f "usebackq tokens=*" %%h in (
+    `powershell -NoProfile -Command "(Get-FileHash -Algorithm SHA256 '%REQ%').Hash.ToLower()"`
+) do set "NEW_HASH=%%h"
+
+if "!NEW_HASH!"=="" (
+    echo ERROR: Could not compute sha256 of requirements.txt >&2
+    exit /b 1
+)
+
+:: ---------------------------------------------------------------------------
+:: Fast-path: venv Scripts\python.exe exists AND sentinel matches
+:: ---------------------------------------------------------------------------
+set "VENV_PYTHON=%VENV_SCRIPTS%\python.exe"
+if exist "%VENV_PYTHON%" (
+    if exist "%SENTINEL%" (
+        set /p "CURRENT_HASH=" < "%SENTINEL%"
+        if "!CURRENT_HASH!"=="!NEW_HASH!" (
+            echo SLM plugin: venv up-to-date, skipping install. >&2
+            exit /b 0
+        )
+    )
+)
+
+:: ---------------------------------------------------------------------------
+:: Rebuild venv atomically: install to venv.tmp, rename to venv, write sentinel LAST
+:: ---------------------------------------------------------------------------
+echo SLM plugin: bootstrapping Python venv at %VENV% ... >&2
+echo   requirements: %REQ% >&2
+
+:: Clean up any partial previous attempt
+if exist "%VENV_TMP%" rmdir /s /q "%VENV_TMP%"
+
+:: Create fresh venv
+python -m venv "%VENV_TMP%"
+if errorlevel 1 (
+    echo ERROR: python -m venv failed >&2
+    exit /b 1
+)
+
+:: Upgrade pip first
+"%VENV_TMP%\Scripts\pip.exe" install --upgrade pip --prefer-binary --quiet
+if errorlevel 1 (
+    echo ERROR: pip upgrade failed >&2
+    exit /b 1
+)
+
+:: Install requirements
+"%VENV_TMP%\Scripts\pip.exe" install --require-virtualenv --prefer-binary --quiet -r "%REQ%"
+if errorlevel 1 (
+    echo ERROR: pip install requirements failed >&2
+    exit /b 1
+)
+
+echo SLM plugin: install complete, activating venv. >&2
+
+:: Atomic swap: remove old venv (if any), rename tmp into place
+if exist "%VENV%" rmdir /s /q "%VENV%"
+move "%VENV_TMP%" "%VENV%"
+if errorlevel 1 (
+    echo ERROR: Could not move venv.tmp to venv >&2
+    exit /b 1
+)
+
+:: Write sentinel LAST — guarantees that a crash before this line triggers rebuild
+echo !NEW_HASH!>"%SENTINEL%"
+
+echo SLM plugin: venv ready at %VENV%\Scripts\slm.exe >&2
+exit /b 0

package/plugin/scripts/ensure-venv.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# ensure-venv.sh — WP-06 SuperLocalMemory plugin venv bootstrap
+#
+# Called by Claude Code SessionStart hook. Idempotent: fast-path exits in <100ms
+# on repeat invocations when requirements.txt is unchanged.
+#
+# Environment (set by Claude Code plugin runtime):
+#   CLAUDE_PLUGIN_ROOT  — plugin installation dir (ephemeral, contains scripts/ + requirements.txt)
+#   CLAUDE_PLUGIN_DATA  — persistent data dir (venv lives here, survives plugin updates)
+#
+# Exit codes: 0 = venv ready   non-0 = failure (logged to stderr)
+# All output goes to stderr only (stdout reserved for MCP stdio protocol).
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# :? guard — fail loudly if required env vars are unset or empty
+# ---------------------------------------------------------------------------
+: "${CLAUDE_PLUGIN_ROOT:?CLAUDE_PLUGIN_ROOT must be set (plugin installation directory)}"
+: "${CLAUDE_PLUGIN_DATA:?CLAUDE_PLUGIN_DATA must be set (plugin persistent data directory)}"
+
+# ---------------------------------------------------------------------------
+# Redirect all output to stderr (MCP uses stdout for protocol messages)
+# ---------------------------------------------------------------------------
+exec 1>&2
+
+# ---------------------------------------------------------------------------
+# Python >= 3.11 guard
+# ---------------------------------------------------------------------------
+if ! python3 -c "import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)" 2>/dev/null; then
+    PY_VER=$(python3 --version 2>&1 || echo "unknown")
+    echo "ERROR: SuperLocalMemory plugin requires Python >= 3.11, found: ${PY_VER}" >&2
+    echo "Install Python 3.11+ and ensure it is first on PATH." >&2
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+REQ="${CLAUDE_PLUGIN_ROOT}/requirements.txt"
+VENV="${CLAUDE_PLUGIN_DATA}/venv"
+SENTINEL="${CLAUDE_PLUGIN_DATA}/.venv-reqs.sha256"
+VENV_TMP="${CLAUDE_PLUGIN_DATA}/venv.tmp"
+
+# ---------------------------------------------------------------------------
+# Compute sha256 of requirements.txt (cross-platform: prefer sha256sum, fall back to shasum -a 256)
+# ---------------------------------------------------------------------------
+hash_req() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "${REQ}" | awk '{print $1}'
+    else
+        shasum -a 256 "${REQ}" | awk '{print $1}'
+    fi
+}
+
+NEW_HASH=$(hash_req)
+
+# ---------------------------------------------------------------------------
+# Fast-path: venv python exists AND sentinel matches current requirements hash
+# venv/bin/python3 (or python) is always present after `python3 -m venv`;
+# the sentinel guards against stale requirements.
+# In production, superlocalmemory also installs venv/bin/slm; both checks pass.
+# ---------------------------------------------------------------------------
+VENV_PYTHON="${VENV}/bin/python3"
+if [ ! -x "${VENV_PYTHON}" ]; then
+    VENV_PYTHON="${VENV}/bin/python"
+fi
+if [ -x "${VENV_PYTHON}" ] && [ -f "${SENTINEL}" ] && [ "$(cat "${SENTINEL}")" = "${NEW_HASH}" ]; then
+    echo "SLM plugin: venv up-to-date (sha256=${NEW_HASH:0:12}…), skipping install." >&2
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Rebuild venv atomically: install to venv.tmp, rename to venv, write sentinel LAST
+# ---------------------------------------------------------------------------
+echo "SLM plugin: bootstrapping Python venv at ${VENV} …" >&2
+echo "  requirements: ${REQ}" >&2
+echo "  python3: $(python3 --version 2>&1)" >&2
+
+# Clean up any partial previous attempt
+rm -rf "${VENV_TMP}"
+
+# Create fresh venv
+python3 -m venv "${VENV_TMP}"
+
+# Upgrade pip first (prefer binary to avoid source builds)
+"${VENV_TMP}/bin/pip" install --upgrade pip --prefer-binary --quiet
+
+# Install requirements
+"${VENV_TMP}/bin/pip" install \
+    --require-virtualenv \
+    --prefer-binary \
+    --quiet \
+    -r "${REQ}"
+
+echo "SLM plugin: install complete, activating venv." >&2
+
+# Atomic swap: remove old venv (if any), rename tmp into place
+rm -rf "${VENV}"
+mv "${VENV_TMP}" "${VENV}"
+
+# Write sentinel LAST — guarantees that a crash before this line triggers rebuild
+echo "${NEW_HASH}" > "${SENTINEL}"
+
+echo "SLM plugin: venv ready at ${VENV}/bin/slm" >&2

package/plugin/scripts/slm-launch

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# slm-launch — WP-F SuperLocalMemory MCP launcher (POSIX)
+#
+# Cross-platform counterpart: slm-launch.bat (Windows)
+# Referenced by plugin/.mcp.json as the MCP server command.
+#
+# Resolves the correct venv binary for POSIX:
+#   ${CLAUDE_PLUGIN_DATA}/venv/bin/slm mcp
+#
+# On Windows, Claude Code invokes slm-launch.bat instead (same-stem, .bat extension).
+#
+# Environment:
+#   CLAUDE_PLUGIN_DATA — persistent data dir where venv lives
+
+exec "${CLAUDE_PLUGIN_DATA}/venv/bin/slm" mcp

package/plugin/scripts/slm-launch.bat

@@ -0,0 +1,17 @@
+@echo off
+:: slm-launch.bat — WP-F SuperLocalMemory MCP launcher (Windows)
+::
+:: Cross-platform counterpart: slm-launch (POSIX bash)
+:: Referenced by plugin/.mcp.json as the MCP server command (Windows picks .bat automatically).
+::
+:: Resolves the correct venv binary for Windows:
+::   %CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe mcp
+::
+:: On Windows, Python venv places entry points in Scripts\ (not bin\ like POSIX).
+:: This launcher bridges the path difference so ONE .mcp.json command field works
+:: cross-platform.
+::
+:: Environment:
+::   CLAUDE_PLUGIN_DATA — persistent data dir where venv lives
+
+"%CLAUDE_PLUGIN_DATA%\venv\Scripts\slm.exe" mcp

package/plugin/settings.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__superlocalmemory__remember",
+      "mcp__superlocalmemory__recall",
+      "mcp__superlocalmemory__search",
+      "mcp__superlocalmemory__session_init",
+      "mcp__superlocalmemory__slm_compress",
+      "mcp__superlocalmemory__slm_retrieve",
+      "mcp__superlocalmemory__slm_cache_get",
+      "mcp__superlocalmemory__slm_cache_set",
+      "mcp__superlocalmemory__slm_optimize_stats",
+      "Bash(slm:*)"
+    ]
+  }
+}

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

@@ -0,0 +1,140 @@
+---
+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.
+
+## 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` |
+
+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)
+
+The `slm cache` subcommand exists but has known pre-existing parse-test failures. Prefer the MCP tools above. If you must use CLI:
+
+```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. They do not read or write individual cache entries — use the MCP tools for that.
+
+---
+
+SuperLocalMemory v3.6.14 · Qualixar · AGPL-3.0-or-later