/slm-cache

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:*)

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. The namespace is the calling agent (`SLM_AGENT_ID`, or the `/mcp/<agent>` path), not the memory profile, so switching profiles does not give you a fresh cache. A caller on another computer gets its own namespace, keyed by its access key, and can never see a local agent's entries.

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` |

`value` is the string you stored. 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:

# 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)

Prefer the MCP tools above. If you must use the command line:

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 and bulk removal. They do not read or write individual entries — use the MCP tools for that. Entries written by `slm_cache_set` carry the tag `mcp-kv`, so `slm cache invalidate --t