Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

TOOL.CACHE.SET

Last updated 
TOOL.CACHE.SET namespace key value [TTL seconds] [MODEL model [INPUT n] [OUTPUT n] [CACHEREAD n] [CACHEWRITE5M n] [CACHEWRITE1H n]]
Group
Keyed caches
Complexity
O(1)
Arity
-4 (at least 4 words, counting the command name)
Flags
write, fast
Keys
first 1, last 1, step 1
HotKV Cloud
Performance and Scale
On-Premise
requires the tool-cache license feature

The tool cache memoizes the results of deterministic tool or function calls an agent makes, keyed by a deterministic string built from the call (for example the tool name and its arguments). TOOL.CACHE.SET stores value under key (the deterministic input string) in namespace. If the key is already cached, its value, usage and expiry are replaced. The namespace must exist (see TOOL.CACHE.CREATE).

Options

Section titled “Options”
Option Effect
TTL seconds Time to live for this entry. 0 or omitted uses the namespace’s default TTL.
MODEL model The model that produced the response. Required when you pass any token count below.
INPUT n Uncached input tokens the original call used.
OUTPUT n Output tokens the original call used.
CACHEREAD n Provider cache-read tokens the original call used.
CACHEWRITE5M n Tokens the original call wrote to a 5-minute provider cache.
CACHEWRITE1H n Tokens the original call wrote to a 1-hour provider cache.

Options come in name and value pairs after value, in any order.

The usage options record what the original, uncached model call consumed. Every later hit on the entry adds those tokens to the namespace’s usage_saved_* counters, and when the model has a price (built in, or set with LLMSTATS.PRICE) it also adds the cost those tokens would have had to usage_saved_cost_usd. Token counts are non-negative integers. Passing a token count without MODEL is rejected.

Return value

Section titled “Return value”
Case RESP2 RESP3
Entry stored Simple string OK Same

Errors:

  • ERR namespace not found if the namespace does not exist.
  • ERR syntax error if an option has no value.
  • ERR unknown option for any other option name.
  • ERR invalid TTL if TTL is not a non-negative integer.
  • ERR usage token counts (INPUT, OUTPUT, CACHEREAD, CACHEWRITE5M, CACHEWRITE1H) need MODEL if you pass a token count without MODEL.
  • ERR invalid INPUT, ERR invalid OUTPUT, ERR invalid CACHEREAD, ERR invalid CACHEWRITE5M or ERR invalid CACHEWRITE1H if a token count is not a non-negative integer.
  • ERR wrong number of arguments for 'tool.cache.set' command if the argument count is wrong.
  • NOLICENSE tool-cache requires a HotKV license. Contact sales@hotkv.com if your license does not include the tool-cache feature.

Examples

Section titled “Examples”
127.0.0.1:6379> TOOL.CACHE.SET sqltool "SELECT 1" "[[1]]"
OK
127.0.0.1:6379> TOOL.CACHE.SET sqltool "SELECT 2" "[[1]]" TTL 120
OK

Compatibility

Section titled “Compatibility”

HotKV-only command. Redis and Valkey have no equivalent.

See also

Section titled “See also”

TOOL.CACHE.CREATE, TOOL.CACHE.GET, TOOL.CACHE.DEL, TOOL.CACHE.STATS, TOOL.CACHE.FLUSH, TOOL.CACHE.DROP, TOOL.CACHE.LIST, AI features guide