superlocalmemory 3.6.13 → 3.6.15

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

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

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

@@ -0,0 +1,204 @@
+---
+name: slm-recall
+description: Search and retrieve facts, decisions, and past context from SuperLocalMemory. Use when the user asks to recall, find, search, or "what did we decide/say about X". Triggers multi-channel semantic retrieval with reranking; always call before storing anything new.
+when_to_use: |
+  - "What did we decide about X?"
+  - "Recall anything about Y"
+  - "Do we have context on the Z feature?"
+  - "Find stored information about authentication / the database / error handling"
+  - "Search for what I said about Y"
+  - Automatically before any non-trivial task, to surface prior context
+allowed-tools: recall, search, fetch, list_recent, Bash
+---
+
+# slm-recall — Search & Retrieve Memory
+
+Retrieve stored facts, decisions, and past context from SuperLocalMemory using
+multi-channel retrieval. The golden rule: **recall before you remember**.
+
+---
+
+## When to use recall vs search vs fetch vs list_recent
+
+| Situation | Tool |
+|-----------|------|
+| Conceptual or paraphrase query ("what did we agree on for auth?") | `recall` — full multi-channel retrieval + rerank |
+| Exact keyword match needed ("find facts containing BM25") | `search` — FTS5 BM25 only, lower latency |
+| You have a specific `fact_id` from a prior result | `fetch` — exact lookup, full detail |
+| Browse newest entries without a query | `list_recent` |
+
+Use `recall` as the default. `search` is a fallback for zero-result recall on a
+known exact term. `fetch` is for when you already know the ID.
+
+---
+
+## Recall-before-remember discipline
+
+Before storing anything new, always call `recall` first. If a near-duplicate
+fact already exists, call `update_memory(fact_id, content)` to refine it
+rather than creating a duplicate. Duplicates degrade retrieval quality for
+every future session.
+
+---
+
+## MCP-first workflow
+
+### 1. Standard recall
+
+```
+recall(
+  query="authentication strategy decision",
+  limit=20,            # default 20; reduce to 5 for quick pre-task checks
+  session_id="<sid>",  # pass the session_id returned by session_init
+  fast=False,          # default False; True skips SpreadingActivation channel
+)
+```
+
+Real response shape (`--json` equivalent):
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "fact_id": "f8a2bc91",
+      "content": "Decided to use JWT with 1h expiry for API auth (2026-06-10)",
+      "score": 0.87,
+      "confidence": 0.91,
+      "trust_score": 0.84,
+      "fact_type": "decision",
+      "channel_scores": {
+        "semantic": 0.88,
+        "lexical": 0.61,
+        "temporal": 0.72,
+        "structural": 0.55
+      }
+    }
+  ],
+  "count": 1,
+  "query_type": "semantic",
+  "channel_weights": {
+    "semantic": 0.4,
+    "lexical": 0.2,
+    "temporal": 0.2,
+    "structural": 0.2
+  },
+  "retrieval_time_ms": 134,
+  "no_confident_match": false
+}
+```
+
+**Always check `no_confident_match`.** When `true`, no result cleared the
+evidence floor. Do not invent a memory — tell the user nothing was found and
+offer to search more broadly or store a new fact.
+
+### 2. Passing session_id
+
+Pass the `session_id` returned by `session_init`. It threads engagement signals
+through to the ranker so each recall contributes to improving retrieval for
+your project over time. Omitting it degrades the learning loop — recall works
+correctly, but feedback is not attributed to the session.
+
+### 3. Fast mode
+
+Use `fast=True` for pre-tool-call checks where sub-second response matters.
+This skips the SpreadingActivation channel. The remaining channels — semantic,
+lexical, temporal, and structural — still run.
+
+```
+recall(query="rate limiting approach", limit=5, session_id="<sid>", fast=True)
+```
+
+### 4. Keyword fallback via search
+
+When `recall` returns zero results on a specific term, try `search`:
+
+```
+search(query="BM25 indexing", limit=10, profile_id="")
+```
+
+`profile_id=""` uses the active profile. Response has `success`, `results`,
+and `count` but no `channel_scores` or `query_type`.
+
+### 5. Pull full detail for a known fact
+
+```
+fetch(fact_ids="f8a2bc91,d4c1e203")
+```
+
+Returns the full record for each ID: `entities`, `lifecycle`, `access_count`,
+`importance`, `observation_date`, `referenced_date`. Use this when the recall
+summary (120-char truncation in `list_recent`) is not enough.
+
+### 6. Browse recent memories
+
+```
+list_recent(limit=20, profile_id="")
+```
+
+Returns facts newest-first. Content is truncated to 120 chars. Use `fetch`
+once you have the `fact_id` for full content.
+
+---
+
+## How multi-channel retrieval works
+
+`recall` runs four channels in parallel — semantic vector similarity, lexical
+BM25, temporal recency, and structural/graph — then fuses them with Reciprocal
+Rank Fusion (RRF) and applies a reranker. The `channel_weights` field in the
+response shows how each channel contributed for that query. Weights adapt over
+time based on engagement signals attributed via `session_id`.
+
+To inspect per-channel scores for a real query against your own data:
+
+```bash
+slm trace "<query>" [--limit N] [--json]
+```
+
+No benchmark numbers are cited here; performance is workload-dependent.
+
+---
+
+## CLI fallback (when MCP is unavailable)
+
+```bash
+# Multi-channel semantic recall
+slm recall "<query>" [--limit N] [--fast] [--json]
+
+# Opt into shared/global facts for one query (v3.6.15 — off by default)
+slm recall "<query>" --include-global --include-shared
+
+# Keyword/FTS5 search (alias: slm search)
+slm search "<query>" [--limit N] [--json]
+
+# Per-channel score breakdown
+slm trace "<query>" [--limit N] [--json]
+
+# Browse recent memories
+slm list [--limit N] [--json]
+```
+
+Flags verified in source (main.py):
+- `slm recall`: `--limit`, `--fast`, `--json`, `--include-global` / `--no-global`, `--include-shared` / `--no-shared`
+- `slm search`: `--limit`, `--json`
+- `slm trace`: `--limit`, `--json`
+- `slm list`: `--limit` / `-n`, `--json`
+
+> **Multi-scope (v3.6.15, opt-in):** recall is shared-OFF by default — it returns only
+> this profile's facts. Pass `--include-global` / `--include-shared` (or the MCP
+> `include_global` / `include_shared` args) to opt in for a query, or set the defaults in
+> your `mode_a/b/c.json` config. See [docs/shared-memory.md](../../../docs/shared-memory.md).
+
+**Flags that do NOT exist** (fabricated in old skills — never write these):
+`--min-score`, `--format`, `--project`, `--tags` on recall or search.
+
+---
+
+## Never fabricate a memory
+
+If `results` is empty or `no_confident_match` is `true`, report it plainly.
+Never construct a response as if a memory was found when it was not. The user
+trusts that what you surface came from the store.
+
+---
+
+*SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later*