Skip to main content
Cache-Pot includes a native vector store — you can persist float32 embeddings and search by cosine similarity without standing up a separate database. Vector collections live in the same keyspace as all other data types, so they benefit from the same TTL, snapshot, and AOF support you already know. This makes Cache-Pot a single binary that covers both the caching layer and the semantic search layer of an AI application.

​
Collections

Vectors are grouped into named collections. A collection is a regular Cache-Pot key whose type is vector. Within a collection, every vector must share the same dimension — the dimension is fixed the moment you insert the first vector with VSET, and any subsequent insert with a different number of floats returns an error. Each vector entry has three components:

ID

A unique string identifier within the collection. Re-using an ID overwrites the existing vector.

Float32 array

The vector itself — a space-separated sequence of floating-point values passed directly in the command.

META (optional)

An arbitrary string attached to the vector, such as a document title, URL, or serialised JSON payload.

​
Commands

CommandDescription
VSET key id f1 f2 ... fn [META text]Insert or overwrite the vector id in collection key. The dimension is fixed by the first insert.
VSEARCH key f1 ... fn [TOPK k] [WITHSCORES]Return the top-k nearest neighbours by cosine similarity (default k = 10). Each result includes the ID and META string; add WITHSCORES to include the cosine score.
VDEL key idDelete the vector with the given ID from the collection.
VCARD keyReturn the number of vectors stored in the collection.
VDIM keyReturn the vector dimension of the collection.
1

Store document embeddings

Insert vectors with descriptive metadata. This example uses 4-dimensional vectors for readability; real embeddings typically have 768–3072 dimensions.
VSET docs intro 0.1 0.9 0.2 0.5 META "Introduction to machine learning"
VSET docs adv   0.8 0.1 0.7 0.3 META "Advanced neural networks"
VSET docs nlp   0.2 0.7 0.1 0.8 META "Natural language processing basics"
2

Search for the most similar document

Pass a query vector and request the top-2 results with scores.
VSEARCH docs 0.15 0.85 0.18 0.55 TOPK 2 WITHSCORES
# Returns: 1) "intro" 2) "Introduction to machine learning" 3) "0.9970"
#          4) "nlp"   5) "Natural language processing basics" 6) "0.9430"
3

Inspect collection stats

VCARD docs   # (integer) 3
VDIM  docs   # (integer) 4

​
Using with an embedding model

In a real application, you convert text to vectors using an embedding model before calling VSET or VSEARCH. The example below uses the openai Python library with Cache-Pot’s standard Redis wire protocol. 
import redis
import openai

r = redis.Redis(host='localhost', port=6379)
client = openai.OpenAI()

def embed(text):
    resp = client.embeddings.create(input=text, model='text-embedding-3-small')
    return resp.data[0].embedding

# Store a document embedding
vec = embed('Introduction to machine learning')
args = ['VSET', 'docs', 'intro'] + [str(f) for f in vec] + ['META', 'Introduction to machine learning']
r.execute_command(*args)

# Search for similar documents
q = embed('machine learning basics')
args = ['VSEARCH', 'docs'] + [str(f) for f in q] + ['TOPK', '5', 'WITHSCORES']
results = r.execute_command(*args)
print(results)

​
Cosine similarity scoring

The score returned by VSEARCH is the cosine similarity between the query vector and each stored vector, in the range [-1, 1]:
ScoreMeaning
1.0Vectors point in exactly the same direction
0.9+Very high similarity — nearly identical semantic content
0.7–0.9Moderate similarity — related topic
< 0.7Low similarity — probably unrelated
Vector search uses flat (brute-force) cosine similarity — every vector in the collection is compared against the query. This is optimal for collections up to ~100 K vectors. An HNSW approximate-nearest-neighbour index is planned for a future release.
Vector collections are regular Cache-Pot keys, so you can set a TTL on the whole collection (EXPIRE docs 86400), delete it with DEL docs, check its type with TYPE docs, and scan for it with KEYS *. All standard key operations apply.