superlocalmemory 3.7.0 → 3.7.2

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.18 · Qualixar · AGPL-3.0-or-later

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

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

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