Vector cookbook: indexes, embeddings and search in every language
Since 0.6.0 the whole vector loop works from the query languages too: create a vector index, add embeddings, search, list what still needs a vector, and drop the index. This page is a set of samples you can copy. Every Cypher, SPARQL and Python sample here was run against the published 0.6.0 package. Why the search works the way it does is explained in Vector memory that remembers when.
Install:
cargo add tiramemsu # Rust
pip install tiramemsu # Python
npm install @tiramemsu/node # Node.js
cargo install tiramemsu-mcp # MCP server for agents
One idea: the index is the model
A vector index in tiramemsu is an embedding model: an IRI with three settings, stored as ordinary sys: statements on it.
| Setting | Values | Default |
|---|---|---|
| dimensions | 1 to 16 384 | required |
| metric | cosine, dot, l2 (Neo4j's euclidean means l2) | cosine |
| encoding | f32, f16 (half the size) | f32 |
Search is exact, so creating an index builds no extra structure. It only fixes what the vectors look like. A vector belongs to one statement (a fact, a relationship, a note), and the store never computes vectors: your application calls its embedding model and hands over the numbers.
Names. In Cypher a short name resolves through the default vocabulary, so the index minilm is the IRI urn:tiramemsu:v:minilm, written v:minilm in SPARQL. Use a backticked IRI in Cypher (`urn:example:minilm`) to name any other IRI. Python and Node accept a plain IRI string.
Create an index
Cypher:
CREATE VECTOR INDEX minilm IF NOT EXISTS
OPTIONS {dimensions: 384, metric: 'cosine', encoding: 'f32'}
// Neo4j's spelling works too
CREATE VECTOR INDEX minilm
OPTIONS {indexConfig: {`vector.dimensions`: 384, `vector.similarity_function`: 'cosine'}}
// or pass the options as a parameter
CREATE VECTOR INDEX minilm OPTIONS $options
Without IF NOT EXISTS an existing index is an error. With it, the same definition is a no-op and a different one is still an error, because stored vectors depend on it.
SPARQL Update writes the definition as the statements it is stored as. Only sys:dimensions is required:
PREFIX sys: <urn:tiramemsu:sys:>
INSERT DATA {
<urn:example:minilm> sys:dimensions 384 ; sys:metric "cosine" ; sys:vectorEncoding "f32" }
Rust, Python and Node.js:
// Rust
db.transact(TxOptions::default(), |tx| {
tx.define_embedding_model(Value::iri("urn:example:minilm"), &EmbeddingModel {
dimensions: 384, metric: Metric::Cosine, encoding: VectorEncoding::F32,
})?;
Ok(())
})?;
# Python
with db.transact() as tx:
tx.define_embedding_model("urn:example:minilm", 384, metric="cosine", encoding="f32")
// Node.js
db.transact((tx) => tx.defineEmbeddingModel("urn:example:minilm", 384, { metric: "cosine" }));
Add vectors
Cypher has a write procedure. The first argument is a relationship (or a statement node), and stored is true when the vector is new and false when the same vector was already there:
MATCH (:Person {name: 'Alice'})-[r:visited]->(:City {name: 'Lisbon'})
CALL tiramemsu.vector.setEmbedding(r, 'minilm', $vector) YIELD stored
RETURN stored
Many at once, from a parameter list:
UNWIND $rows AS row
MATCH (a:Trip {name: row.name})-[r:note]->()
CALL tiramemsu.vector.setEmbedding(r, 'notes', row.vector) YIELD stored
RETURN row.name AS name, stored
SPARQL Update uses two predicates on the statement: tm:vectorEmbedding (the vector as a JSON array in a string) and tm:vectorModel. The annotation syntax asserts a fact and embeds it in one go, and one request can also define the model:
PREFIX sys: <urn:tiramemsu:sys:>
INSERT DATA {
<urn:example:minilm> sys:dimensions 3 ; sys:metric "cosine" .
v:alice v:note "met Alice at the Lisbon offsite"
{| tm:vectorEmbedding "[0.8, 0.2, 0.0]" ; tm:vectorModel <urn:example:minilm> |} }
To embed statements that are already stored, bind them with ~ ?e in WHERE:
INSERT { ?e tm:vectorEmbedding "[0.1, 0.9, 0.0]" ; tm:vectorModel v:minilm }
WHERE { ?p v:visited ?c ~ ?e . ?c v:name "Oslo" }
The subject can be a bound ?e, a statement IRI (<urn:tiramemsu:stmt:42>), or the reifier of a triple inserted in the same request. Anything else is an error.
Rust, Python, Node.js, with embed standing for your model call:
// Rust
db.transact(TxOptions::default(), |tx| {
let e = tx.assert(v("alice"), v("note"), Value::str(text), Valid::ALWAYS)?.eid();
tx.set_embedding(e, model.clone(), &embed(text))?; // true: stored
Ok(())
})?;
# Python
with db.transact() as tx:
e = tx.assert_(alice, note, text)
tx.set_embedding(e, "urn:example:minilm", embed(text))
// Node.js
db.transact((tx) => {
const e = tx.assert(alice, note, text);
tx.setEmbedding(e, "urn:example:minilm", embed(text));
});
A vector is written in the same transaction as everything else, so it rolls back with it. Writing the same vector again changes nothing. A different vector for the same index and statement is refused (EmbeddingConflict): vectors are history, and to improve them you define a new index.
Search
Cypher: the options are limit (default 10), graphs and predicates, and the procedure joins each hit with its statement:
CALL tiramemsu.vector.search('minilm', $vector, {limit: 5, predicates: ['visited']})
YIELD subject, predicate, object, similarity, rank, confidence
RETURN predicate, similarity, rank
// follow a hit into the graph
CALL tiramemsu.vector.search('notes', $vector, {limit: 1}) YIELD statement, similarity
MATCH (a)-[r]->() WHERE r = statement
RETURN a.name, similarity
SPARQL: a group of tm:vector* patterns on one variable is one search. tm:vectorMatch and tm:vectorModel are required, the rest bind or filter:
SELECT ?o ?sim ?rank WHERE {
?e tm:vectorMatch "[1, 0, 0]" ; tm:vectorModel <urn:example:minilm> ;
tm:vectorSimilarity ?sim ; tm:vectorRank ?rank ; tm:vectorLimit 10 ;
tm:vectorPredicate v:note . # optional, repeatable
?s ?p ?o ~ ?e }
ORDER BY ?rank
GRAPH <g> { … } around the group searches one graph. tm:vectorConfidence ?c binds the hit's confidence.
Rust, Python, Node.js:
// Rust
let m = db.now().encode(&model)?.unwrap();
let r = db.now().vector_search(&VectorQuery { limit: Some(5), ..VectorQuery::new(m, embed("trip to Portugal")) })?;
for hit in &r.hits { println!("{} {:.3}", hit.rank, hit.similarity); }
# Python
for hit in db.now().vector_search("urn:example:minilm", embed("trip to Portugal"), limit=5):
print(hit.rank, hit.similarity, hit.o)
// Node.js
const { hits, exact } = db.now().vectorSearch("urn:example:minilm", embed("trip to Portugal"), { limit: 5 });
Words and meaning together, fused by rank, with context from each hit's layers:
CALL tiramemsu.recall({text: 'lisbon offsite', model: 'minilm', vector: $v, expand: 2})
YIELD statement, object, score, rank, via
# Python
db.now().recall("lisbon offsite", model="urn:example:minilm", vector=embed("lisbon offsite"), expand=2)
Hybrid recall is covered in Words, meaning and evidence.
Search in the past
Every search runs inside a view. An as-of view sees only the statements and the vectors that existed then, so an old question keeps its old answer:
USE AS OF 41
CALL tiramemsu.vector.search('notes', $vector) YIELD statement, rank
RETURN statement, rank
SELECT ?e WHERE { SERVICE <urn:tiramemsu:tm:asOf/41> {
?e tm:vectorMatch "[1, 0, 0]" ; tm:vectorModel v:notes } }
# Python
db.as_of(tx=41).vector_search("urn:tiramemsu:v:notes", query)
A vector stored after transaction 41 is invisible as of 41, even if its statement existed then. The index definition is read in the view too: as of a time before the index was created, a search is an error.
Find what still needs a vector
A corrected (superseded) statement gets a new id and no vector. unembedded lists the statements of a view that have none, in id order, which is the work list of an embedding job:
# Python
for eid in db.now().unembedded("urn:example:minilm", limit=500):
... # read the statement, embed it, set_embedding(eid, ...)
// Node.js
const todo = db.now().unembedded("urn:example:minilm", 500);
It lists every statement without a vector, including properties and labels, so filter for the predicates you embed.
List and drop indexes
SHOW VECTOR INDEXES
// name model dimensions metric encoding
// minilm urn:tiramemsu:v:minilm 384 cosine f32
DROP INDEX minilm IF EXISTS
In SPARQL, deleting a live definition statement drops the whole index; a value that does not match is a no-op, like deleting any absent triple. In Rust, tx.drop_embedding_model(model) returns whether it was defined.
PREFIX sys: <urn:tiramemsu:sys:>
DELETE DATA { <urn:example:minilm> sys:dimensions 384 }
What a drop does, and does not do:
- Now, the index is gone: searching it or adding vectors to it is an error.
- The vectors stay. Nothing is deleted in tiramemsu. A search as of a time before the drop still returns what it returned then.
- Create it again identically and the stored vectors are back.
- A name keeps one definition for good. Re-creating a dropped index with other dimensions or another metric is refused. Use a new name.
For agents, over MCP
The tiramemsu-mcp server gives an agent the same loop as tools: define_embedding_model and set_embedding to write, vector_search, recall and unembedded to read. In read-only mode the writing tools are hidden. The query tool runs the SPARQL and Cypher searches above.
{"name": "set_embedding", "arguments": {"eid": 42, "model": "urn:example:minilm", "vector": [0.1, 0.9, 0.0]}}
{"name": "vector_search", "arguments": {"model": "urn:example:minilm", "vector": [1, 0, 0], "limit": 5}}
Rules and errors at a glance
| You do | You get |
|---|---|
| Vector of the wrong length, a NaN, or all zeros under cosine | InvalidQuery |
| A different vector for the same index and statement | EmbeddingConflict |
| Embed a retracted statement | NotLive |
| Search or embed with an undefined or dropped index | InvalidQuery |
| Redefine an index differently, even after a drop | InvalidQuery |
SPARQL delete of tm:vectorEmbedding | Unsupported (vectors are append-only) |
Vector templates inside a SPARQL GRAPH block | InvalidQuery |
CREATE VECTOR INDEX … FOR (n:Label) ON (n.prop) | Unsupported (vectors belong to statements) |
Index commands or setEmbedding on a read-only view | Unsupported |
Everything here runs the same exact, view-aware search: the hits are always the nearest statements the view can see, natively and in the browser.
← Vector memory that remembers when · Words, meaning and evidence: hybrid recall →