Recall

Ranking is token overlap, normalised by the smaller side, with paraphrases of one fact collapsed to their best-scoring instance. No model and no embedding service is involved, anywhere in the path.

const { results, empty } = await memory.recall.search({  query: "where do we deploy",  limit: 8})

Normalising by the smaller side rather than the larger is what makes a short query score sensibly against a long fact. Cosine, Jaccard and overlap-ratio all rank these pairs differently, and the one that divides by the longer string systematically under-ranks short stored facts against long queries — which is most of them.

Collapsing paraphrases to their best-scoring instance happens before the limit is applied, so limit: 8 means eight distinct facts rather than eight ways of saying one.

A semantic index earns its keep on fuzzy paraphrase over very large corpora. The register an agent actually stores is URLs, build ids, ports, paths and conventions — where exact tokens are both faster and more precise, and where an embedding adds latency, cost, and a failure mode at the one moment you cannot afford one: mid-conversation.

So the trade is: worse at paraphrase, better at everything else. A question that says “where does staging live” will not match a memory that says ZQ7X4M2K, and no embedding would have rescued that either. A question that says “what’s our deploy host” will match a memory containing internal-hbr-2291.pineapple.example on the word deploy if it has one, and a model-free index cannot fail to be available when the provider is not.

Recall quality is a property of the deployment rather than of the provider. A question that shares no words with a memory will not match it — which is why the index is pre-staged into every prompt as well. A memory you never had to ask for is a memory that cannot be missed.

That pairing is the actual design: cheap broad coverage from the index line, exact retrieval from recall, and a full body only when the message named something concrete. Neither mechanism has to be good at the other’s job.

An empty result returns empty: true rather than an empty array. The distinction is the point: a search that ran and found nothing is a fact about your store, and a caller that cannot tell it from a search that failed will invent something to fill the gap.

The SDK turns that into “if you were not told, say so rather than guessing”, because a silent miss is how a language model invents a fact it was never given.

The recall inspector names the terms that matched for any query, which is the fastest way to understand why something ranked. It is also the honest answer to “why did this come back” — a list of overlapping tokens, not a score pretending to be a reason.

limit defaults to COGNITIVE_MEMORY_DEFAULT_RECALL_LIMIT, which is 8. A recall is not usually the thing standing between you and a correct answer — the context build is — so this is not the number to raise first.