superlocalmemory 3.6.22 → 3.7.0

package/plugin-src/scripts/slm-launch

@@ -1,15 +0,0 @@
-#!/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

@@ -1,17 +0,0 @@
-@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

@@ -1,16 +0,0 @@
-{
-  "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

@@ -1,140 +0,0 @@
----
-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.18 · Qualixar · AGPL-3.0-or-later

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

@@ -1,143 +0,0 @@
----
-name: slm-compress
-description: Compress large text, tool output, or transcripts to reduce context-window usage while keeping the full 1M window intact — call slm_compress(content, mode, reversible, ttl_seconds) to shrink content; if the result is lossy a ccr_id is returned so you can call slm_retrieve(ccr_id) later to recover the exact original; always fail-open (ok:false → continue with the original).
-when_to_use: "compress context, shrink output, save tokens, context window full, long transcript, compress tool result, reduce tokens, large output, compress text"
-allowed-tools: slm_compress, slm_retrieve, Bash
----
-
-# slm-compress — Reversible Context Compression (Surface B)
-
-## Purpose
-
-When a tool output, transcript, or accumulated context grows large enough to crowd out working space, `slm_compress` reduces it in-place. The compressed form is used for the remainder of the session; the exact original is recoverable on demand via `slm_retrieve`. This works without a proxy and without touching `ANTHROPIC_BASE_URL`, so the full 1M context window is never sacrificed.
-
-## Primary MCP Tool: slm_compress
-
-```
-slm_compress(
-    content:      str,          # required — text to compress (max 1 MB)
-    mode:         str = "auto",  # "normalize" | "auto" | "aggressive"
-    reversible:   bool = True,  # store original in CCR for later retrieval
-    ttl_seconds:  int = 86400,  # CCR lifetime in seconds (default 24 h)
-) -> dict
-```
-
-### Return dict (all keys always present)
-
-| Key | Type | Meaning |
-|-----|------|---------|
-| `ok` | bool | `True` on success; `False` on internal error or empty input |
-| `compressed` | str | Compressed text (or original on failure) |
-| `strategy` | str | Which strategy was applied (e.g. `"normalize"`, `"none"`) |
-| `tokens_before` | int | Word-count estimate of the input |
-| `tokens_after` | int | Word-count estimate of the output |
-| `ratio` | float | `tokens_after / tokens_before` (lower = more compact) |
-| `lossy` | bool | Whether information was removed |
-| `ccr_id` | str \| None | UUID4 session token; present only when `lossy=True` and `reversible=True` |
-| `note` | str \| None | Human-readable note (e.g. warnings, recovery hint) |
-
-### Mode semantics (verified from source)
-
-- **`"normalize"`** — lossless whitespace collapse; no daemon dependency; `lossy: false`, `ccr_id: null`.
-- **`"auto"`** — delegates to `CompressRouter`; may be lossy depending on daemon config; default.
-- **`"aggressive"`** — requests aggressive compression from the daemon; daemon must have `compress_mode=aggressive` set in config; note field will warn if daemon config does not match.
-
-## Recovery Tool: slm_retrieve
-
-When `slm_compress` returns `lossy: true`, the original is stored under the `ccr_id`. Use `slm_retrieve` to get it back:
-
-```
-slm_retrieve(ccr_id: str) -> dict
-```
-
-| Key | Type | Meaning |
-|-----|------|---------|
-| `ok` | bool | `True` when content was found |
-| `content` | str \| None | Original text, decoded from UTF-8 (or Latin-1 fallback) |
-| `size_bytes` | int | Byte length of the stored original |
-| `error` | str \| None | Error message on failure; `None` on success |
-
-`ccr_id` must be a valid UUID4. Non-UUID4 strings return `ok: false` immediately.
-
-### CCR security rule
-
-`ccr_id` values are **unguessable session tokens**. Treat them like short-lived credentials:
-- Never log them.
-- Never share them across agents.
-- Never pass them as tool arguments to any tool other than `slm_retrieve`.
-- Never compress a `ccr_id` string itself.
-- They expire after `ttl_seconds` (default 24 h); `slm_retrieve` returns `ok: false` after expiry.
-
-## Decision: When to Compress
-
-**Compress when:**
-- A single tool output or transcript exceeds approximately 2 000 characters.
-- You are accumulating repeated context (e.g. full file reads across multiple steps).
-- Context is nearing the point where recall quality or response quality degrades.
-
-**Do NOT compress:**
-- Code you are about to read, edit, or diff — you need every character.
-- JSON you will parse programmatically — compression may alter structure.
-- Secrets, credentials, or `ccr_id` strings.
-- Anything under ~500 characters — overhead exceeds benefit.
-- The compressed form of content already compressed this session.
-
-## Fail-Open Guarantee
-
-`slm_compress` never raises an exception. On any internal error it returns:
-
-```json
-{ "ok": false, "compressed": "<original input>", "ratio": 1.0, ... }
-```
-
-**When `ok` is `false`, continue with the original content.** Never block a task waiting for compression to succeed.
-
-## Worked Example
-
-```python
-# Step 1: compress a large tool output
-result = await slm_compress(
-    content=long_log_text,
-    mode="auto",
-    reversible=True,
-    ttl_seconds=3600,
-)
-
-if result["ok"]:
-    working_text = result["compressed"]
-    ccr_id = result["ccr_id"]   # None if lossless
-else:
-    working_text = long_log_text  # fail-open
-    ccr_id = None
-
-# ... work with working_text ...
-
-# Step 2: restore original when needed (e.g. before final summary)
-if ccr_id:
-    restore = await slm_retrieve(ccr_id=ccr_id)
-    if restore["ok"]:
-        original_text = restore["content"]
-```
-
-## Secondary CLI (fallback when MCP is unavailable)
-
-The `slm compress` subcommand exists but has known pre-existing parse-test failures. Prefer the MCP tools above. If you must use CLI:
-
-```bash
-slm compress status [--json]
-slm compress mode safe|aggressive [--json]
-slm compress code on|off [--json]
-slm compress prose on|off [--json]
-slm compress ccr on|off [--json]
-slm compress align on|off [--json]
-```
-
-These subcommands control daemon-level compression settings — they do not compress content inline. For inline compression, use `slm_compress` via MCP.
-
-## Size Cap
-
-Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is forced to `False` and `ccr_id` will be `None`. The `note` field will state `"content over 1MB: ccr skipped"`.
-
----
-
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later

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

@@ -1,300 +0,0 @@
----
-name: slm-graph
-description: >
-  Index and query a codebase as a structural graph — build the code graph, trace blast radius of a
-  change, find callers/callees/inheritors, semantic code search by meaning, assemble PR review
-  context, and detect what changed since last index. Use when the user asks how code connects, what
-  breaks if X changes, what calls a function, what a class inherits from, how to navigate an
-  unfamiliar codebase, or to understand risk before editing.
-when_to_use: |
-  - what calls X
-  - what breaks if I change Y
-  - what does Z inherit from
-  - find code that handles authentication
-  - impact analysis before editing
-  - code navigation in unfamiliar repos
-  - blast radius before a PR
-  - pre-commit change detection
-allowed-tools: build_code_graph, query_graph, get_blast_radius, semantic_search_code, get_review_context, detect_changes, Bash
----
-
-# slm-graph — Code Intelligence Skill
-
-Index any repo as a code knowledge graph and answer structural questions about it: callers, callees, impact radius, semantic search, and review context. Requires the `code` MCP profile (set `SLM_MCP_PROFILE=code` in your plugin `.mcp.json`).
-
-**Prerequisite rule:** every tool except `build_code_graph` self-guards — if the graph is not built it returns `{"success": false, "error": "Code graph not built. Run build_code_graph first."}`. Always index first.
-
----
-
-## Tool Reference
-
-### 1. `build_code_graph` — index a repository
-
-```
-build_code_graph(
-    repo_path: str,
-    languages: str = "",
-    exclude_patterns: str = "",
-) -> {success, files_parsed, nodes, edges, flows, communities, duration_ms}
-```
-
-Parses all supported source files, extracts functions/classes/imports, builds the call graph, detects execution flows, and identifies code communities. Replaces any previous index for the same repo.
-
-- `repo_path` — absolute path to the repository root. Must exist.
-- `languages` — comma-separated language filter, e.g. `"python,typescript"`. Empty string = index all supported languages.
-- `exclude_patterns` — comma-separated glob patterns to exclude, e.g. `"**/node_modules/**,**/.venv/**"`. Empty = no exclusions.
-
-When to (re)build:
-- Before using any other graph tool for the first time on a repo.
-- After significant changes to the codebase (pull, merge, large refactor).
-- When `detect_changes` or `query_graph` returns stale/unexpected results.
-- Rebuild is safe and idempotent — it replaces the previous index atomically per file.
-
-```
-# Index the full repo
-build_code_graph(repo_path="/abs/path/to/myrepo")
-
-# Index only Python, skip tests and generated code
-build_code_graph(
-    repo_path="/abs/path/to/myrepo",
-    languages="python",
-    exclude_patterns="**/tests/**,**/generated/**"
-)
-```
-
----
-
-### 2. `query_graph` — traverse relationships
-
-```
-query_graph(
-    pattern: str,
-    target: str = "",
-    limit: int = 20,
-) -> {success, pattern, target, results: [{qualified_name, kind, file_path, name}]}
-```
-
-Query the graph for structural relationships. `pattern` is required and must be one of the eight valid values below. `target` is a qualified name, partial name, or node ID — matched with exact-then-LIKE fallback.
-
-Valid patterns:
-
-| pattern | returns |
-|---|---|
-| `callers_of` | functions/methods that call `target` |
-| `callees_of` | functions/methods that `target` calls |
-| `imports_of` | modules/symbols that `target` imports |
-| `imported_by` | who imports `target` |
-| `tests_for` | test nodes associated with `target` |
-| `inherits_from` | base classes of `target` |
-| `inherited_by` | subclasses of `target` |
-| `contains` | symbols defined inside `target` (e.g. methods in a class) |
-
-```
-# Who calls the auth handler?
-query_graph(pattern="callers_of", target="authenticate_user")
-
-# What does the payment processor import?
-query_graph(pattern="imports_of", target="PaymentProcessor", limit=30)
-
-# What classes inherit from BaseModel?
-query_graph(pattern="inherited_by", target="BaseModel")
-```
-
----
-
-### 3. `get_blast_radius` — impact analysis
-
-```
-get_blast_radius(
-    changed_files: str,
-    max_depth: int = 2,
-    max_nodes: int = 500,
-) -> {success, changed_nodes, impacted_nodes, impacted_files, edges, depth_reached, truncated}
-```
-
-Computes the full impact radius for one or more changed files using bidirectional BFS (callers and callees). Returns every node and file reachable within `max_depth` hops. Use this before editing to understand risk surface.
-
-- `changed_files` — comma-separated file paths relative to the repo root, e.g. `"src/auth/handler.py,src/auth/models.py"`.
-- `max_depth` — BFS depth. Default 2. Increase to 3–4 for deep call chains; lower to 1 for a quick first-degree check.
-- `max_nodes` — caps the result set. If `truncated=true` in the response, the real blast radius is larger.
-
-```
-# What breaks if I change the auth handler?
-get_blast_radius(changed_files="src/auth/handler.py")
-
-# Deeper analysis across two files
-get_blast_radius(
-    changed_files="src/payments/gateway.py,src/payments/models.py",
-    max_depth=3,
-    max_nodes=200
-)
-```
-
-If `truncated` is `true`, narrow the scope with `max_nodes` or reduce `max_depth` to get a reliable result.
-
----
-
-### 4. `semantic_search_code` — find code by meaning
-
-```
-semantic_search_code(
-    query: str,
-    kind: str = "",
-    limit: int = 20,
-) -> {success, results: [{qualified_name, kind, file_path, score, line_start, name}]}
-```
-
-Hybrid FTS5 + vector search over all indexed code entities. Use when you know what the code *does* but not what it's *called*.
-
-- `query` — natural language description, e.g. `"retry logic for HTTP requests"` or `"parse JWT token from header"`.
-- `kind` — optional filter: `"Function"`, `"Class"`, `"File"`, or `"Test"`. Empty = all kinds. Case-insensitive match in the engine.
-- `limit` — max results. Default 20.
-
-Results include a `score` field (higher = more relevant).
-
-```
-# Find where authentication is handled
-semantic_search_code(query="authenticate user from request token")
-
-# Find only test functions that cover database writes
-semantic_search_code(query="database write transaction rollback", kind="Test")
-
-# Find the rate limiter class
-semantic_search_code(query="rate limiting middleware", kind="Class", limit=5)
-```
-
----
-
-### 5. `get_review_context` — assemble PR review context
-
-```
-get_review_context(
-    changed_files: str,
-    include_source: bool = True,
-) -> {success, summary, review_items, test_gaps, risk_score}
-```
-
-Produces a token-optimized review package for a set of changed files: a plain-language summary, a ranked list of review items with per-node risk scores, and a list of changed symbols that have no associated test coverage.
-
-- `changed_files` — comma-separated file paths relative to the repo root.
-- `include_source` — whether to include source code snippets in the context (default `True`). Set `False` to reduce token usage when you only need the risk analysis.
-
-`risk_score` is a float 0–1 on the overall changeset. `review_items[].risk_score` is per-node.
-
-```
-# Get review context for a PR touching two files
-get_review_context(changed_files="src/auth/handler.py,src/auth/utils.py")
-
-# Risk summary only, no source snippets
-get_review_context(
-    changed_files="src/payments/gateway.py",
-    include_source=False
-)
-```
-
----
-
-### 6. `detect_changes` — what changed since last index
-
-```
-detect_changes(
-    base: str = "HEAD~1",
-) -> {success, summary, risk_score, changed_functions, test_gaps, review_priorities}
-```
-
-Runs `git diff` against `base`, maps the changed hunks to graph nodes, and returns a risk-scored list of changed functions, test gaps, and review priorities. Requires the repo to be a git repository.
-
-- `base` — git ref to diff against. Default `"HEAD~1"` (one commit back). Any valid git ref works: `"main"`, `"v3.6.13"`, a commit SHA, etc.
-
-```
-# What changed in the last commit?
-detect_changes()
-
-# What changed since the release branch?
-detect_changes(base="release/v3.6.13")
-
-# What changed relative to main?
-detect_changes(base="main")
-```
-
-Returns `error` if the repo root is not a git repository or if git is not available.
-
----
-
-## Realistic Workflow
-
-### Explore an unfamiliar codebase
-
-```
-# 1. Index it
-build_code_graph(repo_path="/abs/path/to/repo")
-
-# 2. Find the entry point by meaning
-semantic_search_code(query="request router entry point", kind="Function")
-
-# 3. Trace what it calls
-query_graph(pattern="callees_of", target="handle_request")
-
-# 4. See who else calls the same core function
-query_graph(pattern="callers_of", target="authenticate_user")
-```
-
-### Before editing a function
-
-```
-# 1. Know what you are touching
-semantic_search_code(query="retry HTTP requests with backoff")
-
-# 2. Understand blast radius before making the change
-get_blast_radius(changed_files="src/http/client.py")
-
-# 3. Check test gaps
-get_review_context(changed_files="src/http/client.py")
-```
-
-### Pre-commit / PR review
-
-```
-# 1. What changed in this branch vs main?
-detect_changes(base="main")
-
-# 2. Full impact analysis for the changed files
-get_blast_radius(changed_files="src/auth/handler.py,src/auth/models.py")
-
-# 3. Assemble review context
-get_review_context(changed_files="src/auth/handler.py,src/auth/models.py")
-```
-
----
-
-## Error Handling
-
-All tools return `{"success": false, "error": "<message>"}` on failure — they never raise.
-
-| Error message | Cause | Fix |
-|---|---|---|
-| `Code graph not built. Run build_code_graph first.` | No index exists | Call `build_code_graph(repo_path=...)` first |
-| `Repository path does not exist: <path>` | Bad `repo_path` in build | Pass an absolute path that exists |
-| `Git not available or not a git repository: ...` | `detect_changes` needs git | Only works in git repos with git installed |
-| `Invalid pattern '...'` | Wrong `pattern` in `query_graph` | Use one of the 8 valid pattern strings |
-| `No node found matching '<target>'` | Target not in index | Rebuild or check the qualified name via `semantic_search_code` |
-
-If `build_code_graph` returns `files_parsed: 0`, no supported source files were found — check `repo_path` and `exclude_patterns`.
-
----
-
-## Profile Requirement
-
-This skill uses graph tools that are only active under the `code` MCP profile. Your plugin `.mcp.json` must include:
-
-```json
-"env": {
-  "SLM_MCP_PROFILE": "code"
-}
-```
-
-Without this, the six graph tools are not registered and will appear as unknown tools. Run `slm status` to confirm the active profile.
-
----
-
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later