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

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.

Tool: slm_cache_get

slm_cache_get(
    key: str,   # required — same key used in slm_cache_set
) -> dict

Return dict

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:

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

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)

The slm cache subcommand exists but has known pre-existing parse-test failures. Prefer the MCP tools above. If you must use CLI:

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. They do not read or write individual cache entries — use the MCP tools for that.

SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later