Skip to main content
The semantic cache commands let you cache LLM responses by meaning rather than by exact string match. When you call SCACHE.GET with a prompt like “Tell me about Go”, Cache-Pot can return a cached response originally stored for “What is Go?” — as long as the two prompts are semantically similar enough. This requires an embedding endpoint to be configured via the CACHEPOT_EMBED_URL environment variable.
Both SCACHE.SET and SCACHE.GET call your configured embedding endpoint to vectorize the prompt text. If CACHEPOT_EMBED_URL is not set, both commands return an error. Cache-Pot stores semantic cache entries in an internal vector collection named __scache__, which is snapshotted and AOF-replayed like any other key.

​
SCACHE.SET

Stores a prompt-response pair in the semantic cache. Cache-Pot calls your embedding endpoint to convert the prompt into a vector, then stores that vector alongside the response. Syntax: SCACHE.SET prompt response [TTL seconds]
​
prompt
string
required
The user query or input text to cache. This is vectorized via your embedding endpoint.
​
response
string
required
The LLM response or any string value to associate with this prompt.
​
TTL seconds
integer
Optional expiry time in seconds. After this duration, the cached entry is treated as a miss and automatically evicted on next access. Omit this argument to cache the entry indefinitely.
SCACHE.SET "What is Go?" "Go is a compiled, statically typed language." 3600
# OK

SCACHE.SET "Explain TCP/IP" "TCP/IP is a suite of communication protocols..."
# OK (no TTL — cached indefinitely)
Returns: OK on success.
When a TTL is specified, Cache-Pot stores the absolute expiry timestamp inside the entry’s metadata. The TTL is enforced lazily at read time by SCACHE.GET, not by the key-expiry subsystem. This means the entry occupies memory until it is accessed and evicted. To proactively expire the underlying vector collection, use EXPIRE __scache__ <seconds> — but note that this evicts all semantic cache entries at once.
SCACHE.SET requires CACHEPOT_EMBED_URL to be set. If no embedding client is configured, the command returns ERR embed: no client configured (or a similar provider-specific message).

​
SCACHE.GET

Retrieves a cached response by semantic similarity. Cache-Pot embeds the incoming prompt and searches the semantic cache for the closest stored prompt. If the best match meets or exceeds the similarity threshold, the associated response is returned; otherwise nil is returned. Syntax: SCACHE.GET prompt [THRESHOLD x]
​
prompt
string
required
The query text to look up. Cache-Pot vectorizes this and performs a cosine similarity search against all stored prompts.
​
THRESHOLD x
float
Minimum cosine similarity score (between 0.0 and 1.0) required to count as a cache hit. Defaults to 0.90. Lower values return more hits but risk returning responses to loosely related prompts.
# Exact semantic match — will likely hit
SCACHE.GET "Tell me about the Go programming language"
# "Go is a compiled, statically typed language."

# Near-identical phrasing — hits at default threshold
SCACHE.GET "What's Go?"
# "Go is a compiled, statically typed language."

# Lower threshold to catch looser paraphrases
SCACHE.GET "What's Go?" THRESHOLD 0.85
# "Go is a compiled, statically typed language."

# Unrelated query — no match above threshold
SCACHE.GET "What is Python?" THRESHOLD 0.95
# (nil)
Returns: The cached response as a bulk string on a hit, or nil on a miss (no match above the threshold, an expired entry, or an empty cache).
Start with the default threshold of 0.90. If you see too many cache misses for near-identical phrasings from the same user, lower it to 0.85. If you see responses being returned for clearly different questions, raise it to 0.95.
Cache hits and misses are counted and surfaced in the INFO output under # Stats (semantic_cache_hits, semantic_cache_misses, semantic_cache_hit_ratio) and on the built-in dashboard at http://localhost:8080.

​
Dollar-savings example

Every cache hit is an LLM call you avoided paying for. You can estimate savings by tracking the hit ratio over time. 
# Store a response that cost $0.01 to generate
SCACHE.SET "Summarize the BSD-3 license" "<summary text>" TTL 86400

# A user asks the same question in different words — cache hit, $0.01 saved
SCACHE.GET "Give me a summary of the BSD 3-clause license"
# "<summary text>"

# Check the running hit ratio
INFO
# semantic_cache_hits:214
# semantic_cache_misses:36
# semantic_cache_hit_ratio:0.8559
Always set a TTL with SCACHE.SET for responses that may become stale — for example, documentation summaries, pricing information, or any content tied to a specific version. Indefinitely cached responses can drift out of date as the underlying content changes.