Skip to main content
Cache-Pot provides a built-in vector store. Use VSET to store float32 vectors in a named collection and VSEARCH to find the nearest neighbors by cosine similarity — no separate vector database, sidecar process, or plugin required. Vector collections are first-class Cache-Pot keys: they support TTL, appear in KEYS and SCAN output with type vector, and are included in snapshots and AOF replays.

​
VSET

Stores a vector in a collection, inserting it if the id is new or replacing it if the id already exists. Syntax: VSET key id f1 f2 ... fn [META text]
​
key
string
required
The collection name. This is a standard Cache-Pot key of type vector. It is created automatically on the first VSET.
​
id
string
required
A unique identifier for this vector within the collection.
​
f1 f2 ... fn
float32...
required
The components of the vector. All values are parsed as float32. Every vector in a collection must have the same number of components; the dimension is fixed by the first VSET call on that collection.
​
META text
string
Optional metadata string stored alongside the vector. Retrieve it with VSEARCH. Use it for human-readable labels, JSON payloads, or any context you want returned with search results.
VSET docs intro 0.1 0.9 0.2 0.5 META "Introduction to ML"
VSET docs adv   0.8 0.1 0.7 0.3 META "Advanced neural nets"
# OK
Returns: OK. Returns an error if the vector dimension does not match the collection’s fixed dimension, or if any component cannot be parsed as a float.

​
VSEARCH

Searches a vector collection for the nearest neighbors to a query vector using cosine similarity. Syntax: VSEARCH key f1 f2 ... fn [TOPK k] [WITHSCORES]
​
key
string
required
The collection to search.
​
f1 f2 ... fn
float32...
required
The query vector. Must have the same dimension as the collection.
​
TOPK k
integer
Return at most k results, sorted by descending similarity. Defaults to 10. Must be a positive integer.
​
WITHSCORES
flag
When present, include the cosine similarity score (as a decimal string) for each result.
VSEARCH docs 0.15 0.85 0.18 0.55 TOPK 5 WITHSCORES
# Returns a flat array:
# 1) "intro"
# 2) "Introduction to ML"
# 3) "0.9981"
# 4) "adv"
# 5) "Advanced neural nets"
# 6) "0.6210"
Returns: A flat array. Without WITHSCORES, every two elements form an [id, meta] pair. With WITHSCORES, every three elements form an [id, meta, score] triple. Results are ordered from most similar to least similar.
Cosine similarity ranges from 0.0 (orthogonal) to 1.0 (identical direction). A score above 0.95 generally indicates a very strong semantic match.

​
VDEL

Removes a single vector from a collection by its identifier. Syntax: VDEL key id
​
key
string
required
The collection name.
​
id
string
required
The identifier of the vector to remove.
VDEL docs intro   # (integer) 1
VDEL docs intro   # (integer) 0  — already deleted
Returns: 1 if the vector was found and deleted; 0 if no vector with that id exists in the collection.

​
VCARD

Returns the number of vectors currently stored in a collection. Syntax: VCARD key
​
key
string
required
The collection name.
VCARD docs   # (integer) 2
Returns: An integer count of vectors. Returns 0 if the key does not exist.

​
VDIM

Returns the dimensionality of the vectors in a collection. The dimension is fixed when the first VSET is called on the collection. Syntax: VDIM key
​
key
string
required
The collection name.
VDIM docs   # (integer) 4
Returns: An integer representing the number of float32 components per vector.

​
TTL on vector collections

Vector collections are standard Cache-Pot keys and support all key-expiry commands. Use this to automatically clean up time-bounded embeddings. 
VSET session:abc turn-1 0.3 0.7 0.1 META "User asked about billing"
EXPIRE session:abc 3600    # expire the whole collection after 1 hour
TTL session:abc            # check remaining time-to-live
Apply EXPIRE immediately after creating a collection to prevent unbounded growth. This is especially useful for per-session or per-request embedding caches.