superlocalmemory 3.6.13 → 3.6.15

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

@@ -0,0 +1,194 @@
+---
+name: slm-remember
+description: Capture durable facts, decisions, constraints, and gotchas into SuperLocalMemory. Use when the user says "remember that", "save this decision", "note this constraint", or when a session produces a conclusion worth persisting across sessions. Always recall first to avoid duplicates.
+when_to_use: |
+  - "Remember that we use JWT with 1h expiry"
+  - "Save this architectural decision"
+  - "Store the constraint that X must not Y"
+  - "Note this as a gotcha / blocker / convention"
+  - After making a non-obvious decision during a coding session
+  - After resolving a bug whose root cause should be persisted
+allowed-tools: remember, recall, update_memory, Bash
+---
+
+# slm-remember — Capture Durable Facts
+
+Store atomic, durable facts into SuperLocalMemory for retrieval in future
+sessions. One fact per call. Recall before you remember.
+
+---
+
+## What to store (and what not to)
+
+**Store:**
+- Architectural decisions ("Decided to use Postgres not MySQL — reason: JSONB support")
+- Project conventions ("All API routes follow /api/v1/resource/{id} pattern")
+- Hard constraints ("Never expose raw SQL errors to the HTTP response")
+- Resolved gotchas ("Ollama needs keep_alive=-1 or it unloads the model between calls")
+- Security rules ("Rate limit all public endpoints at 100 req/min")
+
+**Do not store:**
+- Transient context that is only relevant within this conversation
+- Large blobs of code or full file contents (those belong in the project, not memory)
+- Facts the project README already captures
+
+---
+
+## Recall-before-remember (mandatory discipline)
+
+Before calling `remember`, always call `recall` first with the core terms of
+what you are about to store. If a near-duplicate exists:
+
+- Use `update_memory(fact_id, content)` to refine the existing fact instead
+  of creating a new one.
+- Only call `remember` when no sufficiently similar fact is found.
+
+Duplicates degrade retrieval quality for every future session.
+
+---
+
+## MCP-first workflow
+
+### 1. Check for duplicates first
+
+```
+recall(query="JWT token expiry auth", limit=5, session_id="<sid>")
+```
+
+If a near-duplicate is returned:
+
+```
+update_memory(
+  fact_id="f8a2bc91",
+  content="JWT tokens use 1h expiry for API access tokens; refresh tokens 30d (updated 2026-06-16)",
+)
+```
+
+`update_memory` returns `{"success": true, "fact_id": "f8a2bc91", "content": "..."}`.
+
+### 2. Store a new fact
+
+```
+remember(
+  content="Decided to use JWT with 1h expiry for API auth; refresh tokens persist 30 days",
+  tags="auth,security,decision",
+  project="superlocalmemory",
+  importance=8,
+  session_id="<sid>",
+)
+```
+
+Real response shape:
+```json
+{
+  "success": true,
+  "fact_ids": ["c9d4e112"],
+  "count": 1,
+  "pending": false,
+  "message": "Stored (recallable now; enriching async)."
+}
+```
+
+When `pending: true`, the daemon was offline at save time; the fact enters a
+pending queue and becomes recallable once the daemon is back. Do not re-save.
+
+**Never claim "saved" unless `success: true` is in the response.**
+
+### 3. Parameter reference
+
+```
+remember(
+  content: str,       # required — the atomic fact to store
+  tags: str = "",     # comma-separated tags, e.g. "auth,security,gotcha"
+  project: str = "",  # project scope, e.g. "superlocalmemory"
+  importance: int = 5,# 1–10; see scale below
+  session_id: str = "",# from session_init; attributes the write to this session
+  scope: str = None,   # v3.6.15 multi-scope: "personal" (default) | "shared" | "global"
+  shared_with: str = "",# comma-separated profile_ids for scope="shared"
+)
+```
+
+> **Multi-scope (v3.6.15, opt-in):** leave `scope` unset for `personal` (private to
+> this profile — the default, identical to 3.6.14). `"global"` is visible to every
+> profile on the machine; `"shared"` is visible to the profiles in `shared_with`.
+> See [docs/shared-memory.md](../../../docs/shared-memory.md).
+
+**importance scale:**
+- 1–3: Low — passing notes, ideas, soft preferences
+- 4–6: Normal — patterns, conventions, standard decisions (default: 5)
+- 7–8: High — architectural decisions, integration contracts, known gotchas
+- 9–10: Critical — security rules, blockers, irreversible decisions
+
+Use 7–10 only for facts that would cause real damage if forgotten.
+
+### 4. One fact per call
+
+Store one atomic fact per `remember` call. Do not concatenate multiple unrelated
+points into a single content string — they will be hard to update individually
+and harder to retrieve cleanly. If you have three separate decisions, make three
+calls.
+
+### 5. Always set tags and project
+
+Untagged, unscoped facts are harder to retrieve and harder to manage. Minimum:
+set `tags` to one or two relevant terms and `project` to the repo/product name.
+
+---
+
+## Deleting stale facts via CLI
+
+For deletion, the CLI is the authoritative surface. The MCP `forget` tool in
+v3.6.14 runs an Ebbinghaus decay cycle — it does NOT delete by query. For
+targeted deletion, use the CLI:
+
+```bash
+# Preview what would be deleted (always do this first)
+slm forget "<query>" --dry-run [--json]
+
+# Execute deletion after confirming the preview
+slm forget "<query>" --yes [--json]
+
+# Delete a specific fact by exact ID (use when you have the fact_id)
+slm delete <fact_id> --yes [--json]
+```
+
+Flags verified in source (main.py):
+- `slm forget`: positional `query`, `--dry-run`, `--yes` / `-y`, `--json`
+- `slm delete`: positional `fact_id`, `--yes` / `-y`, `--json`
+
+Always run `--dry-run` first and review the preview before passing `--yes`.
+
+---
+
+## CLI fallback (when MCP is unavailable)
+
+```bash
+# Store a fact
+slm remember "<content>" [--tags a,b,c] [--json]
+
+# Store a shared/global fact (v3.6.15, opt-in)
+slm remember "<content>" --scope global
+slm remember "<content>" --scope shared --shared-with alice,bob
+
+# Flags verified in source (main.py): --tags, --json, --sync, --scope, --shared-with
+# --sync: wait for full enrichment before returning (default is async)
+# --scope: personal (default) | shared | global ; --shared-with: profile ids for shared
+```
+
+**Flags that do NOT exist** on `slm remember`:
+`--importance`, `--project`, `--format` — these are MCP-only params or fabricated.
+
+---
+
+## Update vs forget discipline
+
+| Scenario | Action |
+|----------|--------|
+| Fact is still true but needs refinement | `update_memory(fact_id, new_content)` |
+| Fact is superseded or wrong | `slm forget "<query>" --dry-run` then `--yes` |
+| Duplicate found that matches recall result | `update_memory` on the existing one |
+| Fact has a known ID and is clearly obsolete | `slm delete <fact_id> --yes` |
+
+---
+
+*SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,207 @@
+---
+name: slm-session
+description: Manage SuperLocalMemory session lifecycle — call session_init once at the start of every fresh session to load relevant project context and get a session_id; call close_session when work is meaningfully complete to commit temporal summaries. Correct lifecycle hygiene is what makes SLM's learning loop work.
+when_to_use: |
+  - At the start of every session (auto-trigger on first user message in a project context)
+  - When the user says "start a new session" or "initialize memory"
+  - When meaningful work completes and context should be committed
+  - When the user says "close session" or "end session"
+allowed-tools: session_init, close_session, Bash
+---
+
+# slm-session — Session Lifecycle Hygiene
+
+Session lifecycle is the mechanism that makes SuperLocalMemory's learning loop
+work. Without it, recall signals are not attributed and temporal summaries are
+not written. This is not optional housekeeping — it is load-bearing.
+
+---
+
+## The lifecycle in one diagram
+
+```
+Session starts
+     |
+     v
+session_init(project_path, query)
+     |--- returns session_id, context, memories
+     |
+     v
+Use session_id in every recall() and remember() call
+     |
+     v
+Work completes
+     |
+     v
+close_session(session_id)
+     |--- writes temporal summaries to DB
+```
+
+---
+
+## session_init — call once per fresh session
+
+### When to call
+
+Call `session_init` exactly once at the start of every fresh session, before
+any `recall` or `remember`. Never call it twice in a session — the second call
+would generate a new `session_id` and break signal attribution for any prior
+recalls or remembers in that session.
+
+### Signature
+
+```
+session_init(
+  project_path: str = "",  # working directory path, e.g. "/Users/me/projects/foo"
+  query: str = "",         # topic override; if omitted, derived from project_path
+  max_results: int = 10,   # max memories to return (default: 10)
+  max_age_days: int = 30,  # suppress memories older than N days unless score >= 0.7
+                           # set to 0 to disable the age gate entirely
+)
+```
+
+### What it does
+
+1. Derives a search query from `project_path` (or uses your explicit `query`).
+2. Runs a 2-tier recall: full 6-channel via daemon (primary) or FTS5 BM25
+   (emergency fallback if daemon is unreachable).
+3. Merges any pinned "core memory" facts with the recall results.
+4. Applies an age gate — memories older than `max_age_days` are suppressed
+   unless their relevance score is 0.70 or above (architectural decisions that
+   remain permanently relevant still surface).
+5. Returns a pre-formatted `context` block and a structured `memories` array
+   for your session.
+6. Generates a stable `session_id` (`slm-YYYYMMDD-<8hex>`) and returns it.
+
+### Real response shape
+
+```json
+{
+  "success": true,
+  "session_id": "slm-20260616-a3f8c1d2",
+  "context": "# Relevant Memory Context\n\n- JWT tokens use 1h expiry ...",
+  "memories": [
+    {
+      "fact_id": "f8a2bc91",
+      "content": "JWT tokens use 1h expiry for API auth (2026-06-10)",
+      "score": 0.87,
+      "is_core": false
+    }
+  ],
+  "memory_count": 3,
+  "core_memory": [],
+  "degraded_mode": false,
+  "retrieval_mode": "full_6_channel",
+  "learning": {
+    "feedback_signals": 37,
+    "phase": 1,
+    "status": "collecting"
+  }
+}
+```
+
+**Check `degraded_mode`.** When `true`, the daemon was unreachable and only
+FTS5 BM25 was used — semantic, graph, temporal, and structural channels were
+unavailable. The context is still usable; note the degradation if relevant.
+
+**Check `learning.phase`:**
+- Phase 1 (< 50 signals): collecting baseline feedback
+- Phase 2 (50–199 signals): active learning
+- Phase 3 (≥ 200 signals): full ML-driven ranking
+
+### How to use the returned session_id
+
+Store it and thread it into every `recall` and `remember` call in this session:
+
+```
+session_id = "<value from session_init>"
+
+recall(query="auth strategy", session_id=session_id, limit=10)
+remember(content="...", session_id=session_id, tags="auth,decision", project="myapp")
+```
+
+This attribution is what allows the ranker to learn which recalls led to useful
+outcomes for this project.
+
+---
+
+## close_session — call when work is meaningfully complete
+
+### When to call
+
+Call `close_session` when a meaningful unit of work is done — end of a coding
+session, after shipping a feature, after a design review. You do not need to
+call it after every small interaction. The signal is "this session's work is
+committed and should be summarised."
+
+Do not call it at the start of a new session as a cleanup step — `session_init`
+is the correct opener and it does not require a prior close.
+
+### Signature
+
+```
+close_session(
+  session_id: str = "",  # the session_id from session_init; if omitted,
+                         # the system queries the DB for the most recent session
+)
+```
+
+### What it does
+
+Aggregates facts written during the session into per-entity temporal summary
+events. These summaries enable future queries like "what happened during session
+X?" and contribute to the temporal channel in retrieval.
+
+### Real response shape
+
+```json
+{
+  "success": true,
+  "session_id": "slm-20260616-a3f8c1d2",
+  "summary_events_created": 4
+}
+```
+
+`summary_events_created: 0` is normal for short sessions where no new facts
+were written. It is not an error.
+
+---
+
+## Why this matters
+
+Every `recall` call with a `session_id` enqueues engagement signals — which
+results were shown, which were acted on. The learning ranker processes these
+signals to gradually up-weight channels and facts that prove useful for your
+project. Without `session_id`, signals land on a fallback identifier and are
+never attributed to a project or agent. Over many sessions this compounds:
+projects where lifecycle is respected have measurably better retrieval quality
+than projects where session_init is skipped.
+
+---
+
+## CLI fallback (when MCP is unavailable)
+
+There are no direct `session_init` or `close_session` CLI subcommands.
+When MCP is unavailable, use `slm status` to check system health and
+`slm recall` / `slm remember` directly. Session attribution will not be
+available in degraded CLI-only mode.
+
+```bash
+slm status [--json]    # check mode, profile, DB size, fact count
+slm doctor [--json]    # preflight check including daemon and embedding worker
+```
+
+---
+
+## Common mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Calling `session_init` twice in one session | Two session IDs; signals split across them | Call once; store the returned ID |
+| Omitting `session_id` from `recall` / `remember` | No learning attribution | Always pass the stored `session_id` |
+| Never calling `close_session` | Temporal summaries not written | Call at end of each meaningful work unit |
+| Calling `close_session` without a `session_id` when no prior writes exist | Returns error "No session_id found" | Pass the explicit `session_id` from `session_init` |
+
+---
+
+*SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later*

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

@@ -0,0 +1,149 @@
+---
+name: slm-status
+description: Health and optimization stats for SuperLocalMemory — call slm_optimize_stats() for live compression and cache counters (compress_runs, tokens_saved_compress, cache_proxy_hits, cache_proxy_misses, cache_kv_hits, cache_kv_misses); run slm status [--json] for system state (mode, profile, DB size, fact/entity/edge counts) and slm doctor [--json] for preflight including the "Optimize (Surface B)" health line; use together to confirm optimization is actually saving tokens.
+when_to_use: "check slm status, health check, is slm working, optimize stats, tokens saved, cache hits, compress runs, slm doctor, preflight, db size, slm info, diagnose slm"
+allowed-tools: slm_optimize_stats, Bash
+---
+
+# slm-status — Health and Optimize Stats
+
+## Purpose
+
+Use this skill to answer: "Is SLM healthy?", "Is compression/caching actually saving tokens?", and "What does the system look like right now?" It covers three surfaces: the MCP stats tool, the `slm status` CLI, and the `slm doctor` preflight.
+
+## Primary MCP Tool: slm_optimize_stats
+
+```
+slm_optimize_stats() -> dict
+```
+
+No arguments. Returns counters from the current daemon and MCP process session.
+
+### Return dict (all keys always present)
+
+| Key | Type | Meaning |
+|-----|------|---------|
+| `ok` | bool | `True` on success; `False` on internal error |
+| `compress_runs` | int | Total compress calls recorded by the daemon (persisted across restarts) |
+| `tokens_saved_compress` | int | Cumulative tokens saved by compression (daemon-persisted) |
+| `cache_proxy_hits` | int | Proxy-layer cache hits (daemon-persisted) |
+| `cache_proxy_misses` | int | Proxy-layer cache misses (daemon-persisted) |
+| `cache_kv_hits` | int | MCP KV cache hits — **this MCP process session only**, resets on restart |
+| `cache_kv_misses` | int | MCP KV cache misses — **this MCP process session only**, resets on restart |
+| `ccr_note` | str \| None | Note about CCR entry count (not tracked per-session; see daemon `/api/v1/metrics`) |
+| `note` | str \| None | Scope clarification or error detail |
+
+### Important scope distinction
+
+`compress_runs`, `tokens_saved_compress`, `cache_proxy_hits`, and `cache_proxy_misses` are **daemon-persisted** — they survive MCP restarts and accumulate over the full install lifetime.
+
+`cache_kv_hits` and `cache_kv_misses` are **in-process counters** — they reset to 0 each time the MCP server starts. Use them to gauge cache effectiveness within the current session only.
+
+### Reading whether optimization is saving tokens
+
+```python
+stats = await slm_optimize_stats()
+if stats["ok"]:
+    savings = stats["tokens_saved_compress"]
+    kv_hit_rate = (
+        stats["cache_kv_hits"] / max(stats["cache_kv_hits"] + stats["cache_kv_misses"], 1)
+    )
+    # savings > 0 and kv_hit_rate > 0.5 means Surface B is actively reducing costs
+```
+
+If `compress_runs` is 0 after several sessions, compression is not being triggered — check daemon config and whether `slm_compress` is being called.
+
+If `cache_kv_hits` is 0 after repeated work, verify key naming consistency (the same key string must be used for set and get).
+
+## Secondary CLI: slm status
+
+```bash
+slm status [--json] [--verbose]
+```
+
+Reports system-level state — not optimization counters. Canonical fields (WP-02):
+
+- **mode** — active operation mode (e.g. `local`)
+- **profile** — current memory profile name
+- **DB size** — database file size on disk
+- **fact count** — number of stored memory facts
+- **entity count** — entity graph node count
+- **edge count** — entity graph edge count
+
+`--verbose` / `-v` adds: migration log, daemon port, disabled marker, last version.
+
+`--json` outputs a machine-readable dict with the same fields — preferred for agent consumption.
+
+Example agent-native invocation:
+
+```bash
+slm status --json
+```
+
+Typical JSON shape (exact field names depend on runtime; use `--json` and read what arrives):
+
+```json
+{
+  "mode": "local",
+  "profile": "code",
+  "db_size_mb": 12.4,
+  "facts": 384,
+  "entities": 201,
+  "edges": 519
+}
+```
+
+Do not rely on the human-readable format for parsing — always use `--json` when the output feeds another tool.
+
+## Secondary CLI: slm doctor
+
+```bash
+slm doctor [--json] [--quick]
+```
+
+Preflight check covering dependencies, embedding worker, daemon connectivity, and Surface B health. The **"Optimize (Surface B)"** line (WP-03) confirms whether the compression and cache subsystem initialised correctly.
+
+`--quick` skips the daemon and embedding probes — runs only dependency and config checks; faster but incomplete.
+
+`--json` outputs structured results per check — use this in automated health pipelines.
+
+A passing doctor output confirms:
+- Python deps present
+- Embedding worker reachable
+- Daemon responding
+- Surface B (Optimize) initialised
+
+A failing "Optimize (Surface B)" line means `slm_compress`, `slm_cache_set`, and `slm_cache_get` may not function correctly — investigate daemon config before relying on those tools.
+
+## Secondary CLI: slm optimize status
+
+```bash
+slm optimize status [--json]
+```
+
+Shows whether the Optimize module (cache + compress) is currently enabled or disabled at the daemon level. Available subcommands also include `optimize on`, `optimize off`, and `optimize savings`.
+
+The `optimize savings` subcommand accepts:
+
+```bash
+slm optimize savings [--since <days>] [--provider anthropic|openai|gemini] [--json]
+```
+
+`--since` defaults to 7 days. `--provider` filters by the target AI provider.
+
+Note: the `slm optimize` subcommands have known pre-existing parse-test failures — if a subcommand errors, use `slm_optimize_stats()` via MCP as the authoritative source.
+
+## Recommended Health Workflow
+
+1. Run `slm doctor --json` at session start to confirm all subsystems are up.
+2. Call `slm_optimize_stats()` after a batch of work to check token savings.
+3. Run `slm status --json` when you need DB size or memory counts.
+4. If `ok: false` on any MCP tool — check `note` field, then run `slm doctor` to isolate the failure.
+
+## Fail-Open
+
+`slm_optimize_stats()` never raises. On internal error it returns `ok: false` with all counters at 0. Continue the session — stats unavailability does not affect compression or caching operations.
+
+---
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later

package/plugin-src/.mcp.json

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

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

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

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

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

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

@@ -0,0 +1,22 @@
+---
+description: Apply SLM context-optimization (compress large output / cache repeats) and report savings.
+argument-hint: [stats]
+allowed-tools: slm_compress, slm_cache_set, slm_cache_get, slm_optimize_stats, Bash
+---
+
+Apply SuperLocalMemory context-optimization. Arguments: $ARGUMENTS
+
+If arguments are empty or "stats":
+- Call `slm_optimize_stats()` and report: cache_kv_hits, compress_runs, tokens_saved_compress.
+
+If there is large output to compress (>2000 chars):
+- Call `slm_compress(content=<output>, mode="auto", reversible=True)`.
+- Work from the compressed form; retain ccr_id if the result is lossy.
+
+Rules (apply strictly):
+- Rule 6 — NEVER compress/cache: code intended for Edit/Write; JSON being parsed; secrets/keys/tokens; ccr_ids; content <500 chars.
+- Rule 8 — FAIL-OPEN: if ok:false, continue with original; do not retry; do not surface the error unless the user asks.
+
+MCP unavailable → CLI fallback: `slm optimize status`.
+
+SuperLocalMemory v3.6.15 · Qualixar · AGPL-3.0-or-later