superlocalmemory 3.6.13 → 3.6.15

package/plugin-src/commands/slm-recall.md

@@ -0,0 +1,16 @@
+---
+description: Recall relevant facts and decisions from SuperLocalMemory by query.
+argument-hint: <what to recall>
+allowed-tools: recall, search, Bash
+---
+
+Recall from SuperLocalMemory using the query: $ARGUMENTS
+
+1. Call `recall(query="$ARGUMENTS", limit=10)` via MCP.
+2. If no confident match or count==0, also call `search("$ARGUMENTS", 10)`.
+3. Present results concisely — fact, tags, importance, date. Never invent or fabricate a memory.
+4. If MCP is unavailable, fall back to CLI:
+   - `slm recall "$ARGUMENTS" --limit 10`
+   - then `slm search "$ARGUMENTS"`
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later

package/plugin-src/commands/slm-remember.md

@@ -0,0 +1,16 @@
+---
+description: Save an atomic fact or decision to SuperLocalMemory.
+argument-hint: <the fact> [#tag1,tag2]
+allowed-tools: recall, remember, Bash
+---
+
+Save to SuperLocalMemory: $ARGUMENTS
+
+1. First call `recall("$ARGUMENTS", 5)` — dedupe check. If a near-identical memory exists, tell the user and stop; delegate to slm-memory-advisor to update_memory if a correction is needed.
+2. Extract tags from any trailing `#tag1,tag2` pattern in the arguments.
+3. Determine importance: use 8 for blockers/security/architecture decisions; use 7 for conventions and constraints; use 5 for general facts.
+4. Call `remember(content="$ARGUMENTS", tags=<extracted tags>, importance=<n>)`.
+5. Confirm only on success:true. If success is not true, report the error — never claim "saved."
+6. MCP unavailable → CLI fallback: `slm remember "$ARGUMENTS" --tags <tags>` (note: `--importance` is MCP-only, not a CLI flag).
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later

package/plugin-src/commands/slm-status.md

@@ -0,0 +1,15 @@
+---
+description: Show SuperLocalMemory health and optimization counters.
+argument-hint: (no arguments)
+allowed-tools: slm_optimize_stats, Bash
+---
+
+Show SuperLocalMemory status and optimization counters.
+
+1. Run `slm status` via Bash — this is the canonical health check (memory count, profile, daemon state, integrity).
+2. Also call `slm_optimize_stats()` via MCP for Surface-B counters (cache_kv_hits, compress_runs, tokens_saved_compress). If ok:false, omit silently — do not surface the error.
+3. Summarize both outputs in a concise report. Flag any integrity warnings from `slm status`.
+
+Note: MCP get_status is intentionally NOT used here — it is outside the core profile and would error. Use `slm status` (CLI) + `slm_optimize_stats` (MCP) only.
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later

package/plugin-src/hooks/hooks.json

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

package/plugin-src/manifest.json

@@ -0,0 +1,25 @@
+{
+  "version": "3.6.15",
+  "pluginName": "superlocalmemory",
+  "displayName": "SuperLocalMemory",
+  "repository": "https://github.com/qualixar/superlocalmemory",
+  "keywords": ["memory", "mcp", "agents", "local-first", "context-compression"],
+  "skills": [
+    { "name": "slm-cache", "hasReadme": false },
+    { "name": "slm-compress", "hasReadme": false },
+    { "name": "slm-graph", "hasReadme": false },
+    { "name": "slm-recall", "hasReadme": false },
+    { "name": "slm-remember", "hasReadme": false },
+    { "name": "slm-session", "hasReadme": false },
+    { "name": "slm-status", "hasReadme": false }
+  ],
+  "targets": {
+    "plugin": "plugin/.claude-plugin/plugin.json"
+  },
+  "marketplace": {
+    "owner": "qualixar",
+    "ownerEmail": "varun.pratap.bhardwaj@gmail.com",
+    "repo": "superlocalmemory",
+    "description": "Local-first agent memory + reversible context compression and KV cache, as an MCP server. 20-tool code profile with graph intelligence."
+  }
+}

package/plugin-src/requirements.txt

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

package/plugin-src/rules/AGENTS.md

@@ -0,0 +1,91 @@
+# SuperLocalMemory — Agent Rules
+
+> Drop into any IDE agent config or AGENTS.md to give agents disciplined SLM usage.
+> SLM is local-first: every MCP tool runs on the user's machine, zero cloud calls.
+> Prefer MCP tools when the server is running; use the CLI fallback table when not.
+
+---
+
+## Session start
+
+Call `session_init(project_path, query, max_results, max_age_days)` **once** at the start of every new session before any `recall` or `remember` calls. Never call it twice in the same session. `session_init` loads recent decisions and relevant memories into context automatically.
+
+---
+
+## Remember discipline
+
+- **Atomic durable facts only** — decisions, conventions, constraints, gotchas, stable preferences. One fact per `remember` call.
+- **Recall before remember** — call `recall(query, 5)` first. If a near-identical memory exists, use `update_memory(fact_id, content)` to correct it; never duplicate.
+- **Tags + project + importance** — always supply meaningful tags and the project name. Use importance 7–10 for blockers, security findings, and architecture decisions; 5 for general facts.
+- **Never dump a whole file** — extract only the durable decision or constraint; store the path reference if needed.
+- **Scope is opt-in (v3.6.15)** — memories are `personal` (private to this profile) by default. Only pass `scope="shared"/"global"` (or recall's `include_global`/`include_shared`) when the user EXPLICITLY asks to share across local profiles. Never opt in on your own; the default is identical to single-profile SLM.
+
+---
+
+## Recall discipline
+
+- **recall for concepts, search for keywords** — use `recall(query, limit)` for conceptual / semantic queries; use `search(query, limit)` for exact keyword / FTS5 matches.
+- **Concept phrasing** — phrase queries as concepts, not vague words ("database migration strategy" not "database").
+- **Pass session_id** when available to narrow results to the current session.
+- **Empty / low results** — broaden the query, try `search`, or fall back to `list_recent`. Never fabricate a memory.
+
+---
+
+## Optimize rules
+
+Apply automatically when context pressure builds:
+
+1. Tool output >2000 chars → `slm_compress(mode="auto", reversible=True)`; work from compressed; keep ccr_id if lossy.
+2. Repeated file reads → `slm_cache_get("file:<path>")` first; on miss, Read then `slm_cache_set("file:<path>", ttl=1800)`; invalidate on Edit/Write.
+3. Repeated bash/web → `slm_cache_set("bash:<cmd[:64]>", ttl=600)`; web ttl=3600.
+4. **NEVER** compress/cache: code for Edit/Write; JSON to parse; secrets/keys/tokens; ccr_ids; content <500 chars.
+5. **FAIL-OPEN** — if any optimize call returns ok:false, continue with the original content, no retry, don't surface the error.
+
+---
+
+## Session end
+
+Call `close_session(session_id)` when the work in the session is meaningfully complete. This finalises session metadata and allows the next session to find this one via `session_init`.
+
+---
+
+## CLI fallback table
+
+When the SLM MCP server is unavailable, use these CLI equivalents:
+
+| MCP tool               | CLI fallback                                              |
+|------------------------|-----------------------------------------------------------|
+| `recall`               | `slm recall "<query>" --limit N`                          |
+| `search`               | `slm search "<query>"`                                    |
+| `remember`             | `slm remember "<content>" --tags a,b` (project/importance are MCP-only) |
+| `list_recent`          | `slm list --limit N`                                      |
+| `forget`               | `slm forget` (always preview first)                       |
+| `slm_optimize_stats`   | `slm optimize status` / `slm optimize savings`            |
+| `slm_compress`         | `slm compress`                                            |
+| `slm_cache_*`          | `slm cache ...`                                           |
+| `slm status` (health)  | `slm status`                                              |
+| `session_init`         | daemon-implicit — skip when MCP is down                   |
+| `close_session`        | daemon-implicit — skip when MCP is down                   |
+
+---
+
+## Tool reference (core profile — 14 tools)
+
+| Tool               | Signature (key params)                                                         | Notes                              |
+|--------------------|--------------------------------------------------------------------------------|------------------------------------|
+| `remember`         | `content, tags="", project="", importance=5, session_id="", scope="personal", shared_with=""` | Store atomic fact. `scope` opt-in (personal default) |
+| `recall`           | `query, limit=10, agent_id, session_id="", fast=False, include_global, include_shared`         | Multi-channel retrieval. Scope flags off by default |
+| `search`           | `query, limit=10, profile_id=""`                                               | FTS5 BM25 keyword search           |
+| `fetch`            | `url, ...`                                                                     | Fetch remote content               |
+| `list_recent`      | `limit=20, profile_id=""`                                                      | Newest memories first              |
+| `update_memory`    | `fact_id, content, agent_id`                                                   | Correct an existing memory by id   |
+| `forget`           | `profile_id="", dry_run=True`                                                  | Decay cycle; always dry_run first  |
+| `session_init`     | `project_path="", query="", max_results=10, max_age_days=30`                   | Once per session; loads context    |
+| `close_session`    | `session_id=""`                                                                | Finalise session                   |
+| `slm_compress`     | `content, mode="auto", reversible=True, ttl_seconds=86400`                     | Returns compressed, lossy, ccr_id  |
+| `slm_retrieve`     | `ccr_id`                                                                       | Retrieve original from ccr_id      |
+| `slm_cache_set`    | `key, value, ttl_seconds=86400`                                                | KV cache set                       |
+| `slm_cache_get`    | `key`                                                                          | KV cache get; returns hit, value   |
+| `slm_optimize_stats` | `()`                                                                         | Returns compress_runs, tokens_saved_compress, cache_kv_hits |
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later

package/plugin-src/rules/CLAUDE.md.fragment

@@ -0,0 +1,44 @@
+<!-- BEGIN SuperLocalMemory v3.6.15 -->
+
+## 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.
+- Scope is opt-in (v3.6.15): writes are `personal`/private by default. Only use `scope="shared"/"global"` (or recall's `include_global`/`include_shared`) when the user explicitly asks to share across local profiles.
+
+### 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` · `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.15 -->
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later

package/plugin-src/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-src/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-src/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-src/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-src/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-src/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.15 · Qualixar · AGPL-3.0-or-later