slm-status

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

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

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:

slm status --json

Typical JSON shape (exact field names depend on runtime; use --json and read what arrives):

{
  "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

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

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:

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