Tiramemsu

Words, meaning and evidence: hybrid recall

Tiramemsu articles · 11 October 2026

An agent asked “what do I know about the Lisbon offsite?” should find the note that says “Lisbon offsite”, the note that says “team week in Portugal”, and the reason it believes each of them. The first is a match by words. The second is a match by meaning. The third is evidence: who wrote it, how sure they were, where it came from.

Tiramemsu already had text recall for words and vector recall for meaning. Hybrid recall is one call that runs both over the same view, fuses the results, and can bring each hit's evidence along. It shipped in 0.5.0, with storage format 5. This article is for developers building agents: how it works, how to call it from each language, how we test it, what it costs and where it stops.

Why one channel is not enough

Text search is precise about names, codes and rare words. It finds “Lisbon” every time and never finds “Portugal” for it. Vector search is good at paraphrase and other languages, but it is vague about exact names: two different offsites in two different cities can sit very close together. An agent that uses only one of them misses things the other would have found.

And an agent must be able to say why it believes something. A recall result that is only a chunk of text and a number is not enough. In tiramemsu every hit is a statement with its own id, so it can carry its confidence, its confirmations, its authors, its source and its history. Hybrid recall keeps that, and adds where each hit came from: which channel found it, at which rank, and, for context it brought along, which hit led to it.

How fusion works

Each channel ranks its own candidates. Text recall scores with bm25; vector recall scores with similarity. Those two numbers are on different scales and mean different things: a bm25 of 7.2 and a cosine of 0.81 cannot be added, and any weight you choose to make them comparable is a guess that breaks on the next query. So hybrid recall never compares scores across channels. It uses only ranks.

The method is reciprocal rank fusion (Cormack, Clarke and Büttcher, SIGIR 2009). A statement gets 1 / (60 + rank) from each list it appears in, and the parts add up. The constant 60 keeps the first few places from dominating, so a statement that both channels rank well beats one that a single channel ranks first.

A small example. The agent asks about the Lisbon offsite, with the text “lisbon offsite” and an embedding of the same words:

 text channel                      vector channel
  1  N1 "met Alice at the Lisbon offsite"     1  N4 "team week in Portugal, May"
  2  N2 "Lisbon flights booked"               2  N3 "offsite agenda: Lisbon, day 2"
  3  N3 "offsite agenda: Lisbon, day 2"       3  N1 "met Alice at the Lisbon offsite"

 fused                     score
  1  N1   1/61 + 1/63   = 0.03227   both channels
  2  N3   1/63 + 1/62   = 0.03200   both channels
  3  N4   1/61          = 0.01639   vector only
  4  N2   1/62          = 0.01613   text only

N3 was third in one list and second in the other, and it ends up above N4, which was first in a list. Agreement wins. Each hit keeps text_rank and vector_rank, and lexical and similarity, the channels' own scores, each absent when that channel did not find it. So the agent sees that N4 is there only because of its meaning.

To give agreement a chance, each channel fetches more than you ask for: depth candidates, by default max(4 × limit, 50). A statement at rank 30 in one channel can still rise if the other ranks it well. Then the fused list is cut to limit, 10 by default.

Ties are broken by evidence, never by invented scores

Fused scores tie more often than you might think: two statements with mirrored ranks, or several copies of the same note written by different agents. Tiramemsu does not invent a score to break the tie. It uses the evidence it actually holds, in a fixed order:

  1. higher confidence first, no confidence last;
  2. more confirmations;
  3. more distinct authors;
  4. newer first;
  5. finally the statement id, so the order is always the same.

This is the same tie-break text and vector recall use. Evidence a statement does not have is reported as absent, never estimated. The whole order has a name, tiramemsu-recall-rank/1; if it ever changes, the name changes too.

Expansion: bring the reasons along

A hit tells the agent what matched. Often it also needs what surrounds it. With expand: n, after the fused hits, recall adds for each hit, in rank order:

Expanded statements come after every fused hit, with score 0 and via set to the hit they were reached from. Context is never mistaken for a match, and no statement appears twice. An agent can answer “I remember the Lisbon offsite (from chat 12, confidence 0.9), and that Alice leads the data team” from one call.

Expansion ignores the graphs and predicates filters on purpose. Those filters choose which statements may match. But layers such as a source or a confidence are rarely members of the graph the fact is in, so a graph filter would hide exactly the context you asked for. The view still applies: expansion never reaches a statement the view cannot see, retracted or not yet written. Each distinct subject is read once per call.

Recall in the past

Every recall runs in a view. now() sees what the agent believes today. as_of(t) sees what it believed at transaction t, and valid_at(d) what was true on date d. Both channels and the expansion run in that view, in one snapshot. See Time travel, explained for the two clocks.

The vectors have a clock too. As of t, recall sees only the embeddings stored by t. If you embed an old note today, a recall as of last week still does not find it by meaning, because last week the agent could not have. A past recall therefore gives the same answer forever, which is what makes saved answers on past views safe. And because both searches are exact over the visible statements, going back in time never silently shortens the list; the vector memory article explains why approximate indexes fail here.

One recall, everywhere

Every surface calls the same operation, so the hits and their order are identical. In the snippets, embed is your own call to an embedding model; the store never calls one. The text half needs the text index (open the database with it, or start the MCP server with --text-index). A vector-only recall does not.

Rust:

let model_id = db.now().encode(&model)?.expect("model defined");
let q = RecallQuery {
    text: Some(TextQuery::new("lisbon offsite")),
    vector: Some(VectorQuery::new(model_id, embed("lisbon offsite"))),
    expand: 2,
    ..RecallQuery::default()
};
for hit in db.now().recall(&q)? {
    println!("{} {:.4} {:?} {:?} via {:?}", hit.rank, hit.score, hit.text_rank, hit.vector_rank, hit.via);
}
let then = db.as_of(TimeRef::Tx(150)).recall(&q)?;   // what the agent could recall at transaction 150

Python:

v = embed("lisbon offsite")
for hit in db.now().recall("lisbon offsite", model="urn:example:minilm", vector=v, expand=2):
    print(hit.rank, hit.score, hit.text_rank, hit.vector_rank, hit.evidence.confidence, hit.via)

SPARQL. The tm:recall* patterns on one variable are one recall. It needs tm:recallText, or tm:recallVector with tm:recallModel, or both. GRAPH <g> restricts it, SERVICE <tm:asOf/…> times it, and tm:recallVia stays unbound for fused hits:

SELECT ?e ?score ?via WHERE {
  ?e tm:recallText "lisbon offsite" ; tm:recallVector "[0.12, -0.4, …]" ;
     tm:recallModel <urn:example:minilm> ; tm:recallMode "any" ;
     tm:recallLimit 10 ; tm:recallExpand 2 ;
     tm:recallScore ?score ; tm:recallRank ?r ; tm:recallVia ?via }
ORDER BY ?r

Cypher. One procedure with one map; the time clauses apply, and via is null for fused hits:

CALL tiramemsu.recall({text: 'lisbon offsite', model: 'minilm', vector: $v,
                       mode: 'any', limit: 10, expand: 2, graphs: ['trip']})
YIELD statement, subject, predicate, object, score, rank, via

MCP. An agent in Claude Code or Claude Desktop calls the recall tool (see Give your agent a memory over MCP). It takes text, mode, model, vector, graphs, predicates, limit, depth, expand and view:

{ "name": "recall",
  "arguments": { "text": "lisbon offsite", "model": "urn:example:minilm",
                 "vector": [0.12, -0.4, …], "expand": 2,
                 "view": { "kind": "asOf", "tx": 150 } } }

The server now has 19 tools. Next to recall are vector_search, unembedded (the statements that still need a vector), and two writers, define_embedding_model and set_embedding, which read-only mode hides with every other writing tool. Node.js has View.recall({text, mode, model, vector, limit, depth, expand, graphs, predicates}), and the JSON bridge has recall.

Give only text or only a vector, and recall becomes that one channel, in that channel's own order, with the same hit shape. A recall with neither is an error.

How we know it works

Ranking code is easy to get almost right. These are the checks that run on every build:

What we measured

Hybrid recall over notes with text and 384-dimension vectors, text index on, a query word that matches 2 % of notes, on an Apple laptop:

StatementsText + vectorWith expand: 2Text only
10 00010.0 ms15.2 ms0.49 ms
100 00090.7 ms112.4 ms7.6 ms

Almost all of the time is the vector half, an exact scan over every visible vector. That is fine for an agent's memory of tens of thousands of statements, and the cost grows in a straight line from there.

Vector search also has an opt-in prefilter that first compares one sign bit per dimension, then scores only the closest n exactly. We measured it on real vectors (GloVe-100 from ann-benchmarks, 200 queries), and it is weaker than we hoped. Recall@10 against the exact answer:

n100 000 vectors200 000 vectors
2000.5440.515
1 0000.7850.754
5 0000.9450.913
10 0000.9790.961

Exact search took 44.5 ms and 89.9 ms. The bit scan alone costs about 28 and 58 ms, because it still visits every vector, so the best speed-up is about 1.5×, and only while losing three or more of the true ten. At 95 % recall it is no faster than exact search. GloVe has only 100 dimensions, so only 100 bits per vector; 384- and 768-dimension sentence models should do better, but we have not measured them. Exact search stays the default, and hybrid recall uses it.

Storage, measured after VACUUM: a 768-dimension f32 vector adds about 4.2 KB to the file, mostly because only one such row fits in a 4 KB page. Half precision, or 384 dimensions, adds about 2.1 KB. The vector memory article has the full numbers.

Limits and what is next

Hybrid recall answers by words and by meaning, orders ties by evidence the store actually holds, brings the reasons along marked as context, and gives the same answer about the past every time it is asked.

← Vector memory that remembers when · Time travel, explained →