superlocalmemory 3.6.23 → 3.7.0

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

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