The Embedding Prefix Your Model Card Requires and Ollama's Example Leaves Off

nomic-embed-text's model card says every text you embed "must" carry a task prefix — search_document: on your notes, search_query: on your questions. Ollama adds nothing. It embeds exactly the string it receives, so your notes app, plugin or script decides. Whether the prefix helps your notes is a measurement, not a rule.

That answer is less tidy than it should be. The model card is written by the people who trained the model, and it is unambiguous. The runtime's own library page for the same model shows an example call with no prefix at all — on a page that counts more than 96 million downloads. Between the two sits whatever tool turns your notes into vectors, and most of those tools never say which string they send.

Then there is the evidence. Three independent measurements of "prefix versus no prefix" on this model exist, and they point three ways — a small loss, no detectable difference, a modest gain. This post lays out each model's contract and shows the receipt that the runtime adds nothing. It puts the three measurements side by side with their sample sizes. Then it ends with a test you can run on five of your own notes in a few minutes.

The problem in concrete terms: one model, two instructions

The nomic-embed-text model card tells you to prefix every input. Ollama's library page for the same model, with more than 96 million downloads, embeds "Why is the sky blue?" with no prefix. Neither is wrong — the card describes how the model was trained, the page shows how to call an API. The caller fills the gap.

Here is the card, in Nomic's own emphasis: "Important: the text prompt must include a task instruction prefix, instructing the model which task is being performed." It then gives the retrieval case directly: "For example, if you are implementing a RAG application, you embed your documents as search_document: <text here> and embed your user queries as search_query: <text here>."¹

And here is the first usage example on Ollama's page for nomic-embed-text, which listed 96.3M downloads when we fetched it on 7 November 2026:²

curl http://localhost:11434/api/embed \
  -d '{
    "model": "nomic-embed-text",
    "input": "Why is the sky blue?"
  }'

That is a question, embedded with no search_query: in front of it. The example exists to show the API shape — not a retrieval recipe. Still, it is the snippet a person copies first.

The convention is not settled even on one page. Ollama's mxbai-embed-large page (16.7M downloads) opens with the same unprefixed "Why is the sky blue?" call. An older usage section lower down adds mxbai's query prompt — to the sentence "The sky is blue because of Rayleigh scattering", which reads as a passage, not a question.³

The gap is not hypothetical. Between July and September 2026, issues and pull requests on several open-source search tools raised the same gap. Two of the titles: "Ollama: nomic-embed-text is used without search_query/search_document task prefixes" and "Add nomic search_query:/search_document: prefixes + recalibrate thresholds".⁴

Why the prefix exists: one encoder, two jobs

A retrieval embedding model uses one network for two different kinds of text: short questions and the longer passages that answer them. The prefix tells the model which side of the search a text is on. Without it, training gives the model contradictory goals, because "similar to this question" and "answers this question" are different relationships.

Nomic's technical report states the reason in one sentence: "Without prefixes, the model receives conflicting reward signal."⁵ Its example is the query "What is the capital of France?" set against two candidates — a rephrasing of the same question, and the sentence that Paris is the capital of France. A similarity task should rank the rephrasing first; a question-answering task should rank the answer first. Same encoder, opposite verdicts.

The prefix resolves that. Nomic trained with search_query and search_document, plus classification and clustering for other tasks, so the model learns that a question marked as a query should land near passages that answer it.⁵

The idea predates Nomic — Microsoft's E5 paper describes the same move: "We use a shared encoder for all input texts and break the symmetry by adding two prefix identifiers “query:” and “passage:”".⁶ The strings differ by family. The principle does not.

So the prefix is not decoration. It is part of the input the model saw during training — which is exactly why its absence might matter, and exactly why it is worth checking whether it does.

Five model cards, five different contracts

There is no single prefix rule. Each model family publishes its own contract — nomic wants a prefix on both sides, E5 a different pair, mxbai and Qwen3 one on the query only, and BGE calls it optional. The prefix belongs to the model, so it travels with the model, never with the app.

The E5 card answers the obvious question in its own FAQ. Asked "Do I need to add the prefix "query: " and "passage: " to input texts?", it replies: "Yes, this is how the model is trained, otherwise you will see a performance degradation."⁷

Mixedbread is just as direct about which side gets the prompt: "Please note that you have to provide the prompt Represent this sentence for searching relevant passages: for query if you want to use it for retrieval. Besides that you don't need any prompt."⁸

Qwen's card frames instructions as an aggregate gain: "using instructions (instruct) typically yields an improvement of 1% to 5% compared to not using them", for most downstream tasks.⁹ Its example code marks documents with "No need to add instruction for retrieval documents".

The BGE card is the one that sounds like an engineer — not a manual. It says that "No instruction only has a slight degradation in retrieval performance compared with using instruction", and then, in bold: "The best method to decide whether to add instructions for queries is choosing the setting that achieves better performance on your task."¹⁰

A model vendor telling you to measure is the thesis of this post in someone else's words.

The table has one practical consequence. A tool that switches models also switches contracts. That is the same trap as switching models without re-embedding, covered in Your Note Search Index Has a Shelf Life — except here the model stays the same and only the input string changes.¹¹

Who adds the prefix? Not the runtime

Ollama does not add an embedding prefix. Its package for nomic-embed-text carries no prompt template, the model file passes text through unchanged, and the token count shows nothing extra arrives. Common Python tooling stores prompts but applies none by default. Whatever calls the model — your app, plugin or script — decides.

We checked this four ways on 7 November 2026, against Ollama v0.40.15.¹²

1. The package. Ollama's registry lists exactly what a model ships with. nomic-embed-text:latest has three layers: the model weights (274,290,656 bytes), a licence, and a 17-byte parameters file — and no template layer.

curl -s -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  https://registry.ollama.ai/v2/library/nomic-embed-text/manifests/latest

# layers (abridged):
#   application/vnd.ollama.image.model    274290656
#   application/vnd.ollama.image.license      11357
#   application/vnd.ollama.image.params         17   -> {"num_ctx":8192}

2. The model file. ollama show nomic-embed-text --modelfile prints TEMPLATE {{ .Prompt }} — the text you send, unchanged — and PARAMETER num_ctx 8192.

3. The token count. The /api/embed response reports prompt_eval_count, the number of tokens the model actually read. We embedded three strings:

curl -s http://localhost:11434/api/embed \
  -d '{"model": "nomic-embed-text", "input": "hello"}' | grep -o '"prompt_eval_count":[0-9]*'
# "hello"                  -> 3
# "search_query: hello"    -> 7
# "search_document: hello" -> 7

Three tokens for "hello" is the word plus the model's start and end markers. If the runtime had added a prefix, the bare word would cost as much as the prefixed one. It does not.

4. The source. A search of the v0.40.15 Go source for search_query, search_document and Represent this sentence returns no relevant hits. The embedding handler in server/routes.go adds the start and end tokens and truncates long input — nothing else.¹³ Truncation is a separate failure with its own limits — mxbai's package sets num_ctx to 512, nomic's to 8192. That axis is covered in Your Local Model's Context Window Has a RAM Price.¹⁴

Ollama is not the exception. In sentence-transformers, mxbai and Qwen3 store their query prompts in a config file with "default_prompt_name": null.¹⁵ The prompt is applied only when the calling code asks for it by name. No common runtime applies the prefix by default.

That is a reasonable design — a runtime cannot know whether a string is a note or a question. Only the caller does.

Does the prefix help? Three measurements disagree

Three public measurements compare nomic-embed-text with and without its prefixes. A 15-question journal test found a small loss; our 300-claim test found no detectable difference; a 553-query re-ranking test found a gain of 5.6 points in top-1. Each is real. None is large enough or close enough to your notes to settle it.

The small loss: two of fifteen questions

MindSage's author wrote 18 short journal entries on distinct subjects and 15 questions, each hand-labelled with the entry that answers it. With the prefixes added, every number got worse: "precision@1 dropped from 0.467 to 0.333 and MRR from 0.644 to 0.544."¹⁶

At fifteen questions, 0.467 is 7 correct top hits and 0.333 is 5. The difference is two questions — a real observation, and a small one. It should be read at that size: "two of fifteen", not a percentage.

The author was candid about the open question: "My best guess is that the way the model is packaged already handles this, but I didn't dig further. What matters is that the "obvious fix" from the docs would have shipped a regression without this test."¹⁶

The second sentence is exactly right — it is the method this post recommends. The guess, though, does not hold for Ollama's package. MindSage's model tag (nomic-embed-text:v1.5) and its 274 MB on-disk size match Ollama's package, and that package adds no prefix (previous section). So the negative result is not explained by the prefix being added twice. It stands as what it is: a careful test on a small set where the prefix happened to lose.

The gain: 553 queries, re-ranking only

KMSmcp's maintainer re-ranked production's own candidate pools for 553 graded queries, comparing raw text against nomic's prefixes. The result: "top-1 is a grade-2 candidate: +0.056, 95% CI [+0.024, +0.088]", and "nDCG@5: +0.014, CI [+0.004, +0.025]".¹⁷

This is the largest sample — and the only one with a confidence interval that excludes zero. It is also narrower than it looks. The prefixes re-ordered candidates that first-stage retrieval had already found — they never got the chance to find different ones. The issue says so itself: "Not urgent. Unverified end to end: only the re-ranking effect has been measured."¹⁷

The null: 23 of 300 top hits flipped, in both directions

We ran nomic-embed-text through Ollama on the SciFact test set from the BEIR benchmark: 300 queries against 983 documents (all 283 relevant ones plus 700 random distractors).¹² Without prefixes, nDCG@10 was 0.8366. With both prefixes it was 0.8250. The paired difference was −0.0116, with a bootstrap 95% interval of [−0.0274, +0.0038]. The interval includes zero.

The average hides the most useful detail. Adding the prefixes flipped whether a relevant document came first for 23 of the 300 queries — 10 gained a correct top hit, 13 lost one. The prefix is not inert. It moves individual answers in both directions, and on this set the moves nearly cancel.

The partial variants told the same story. Query prefix only: −0.0045 [−0.0157, +0.0065], with 6 queries gained and 6 lost at top-1. Document prefix only: −0.0083 [−0.0187, +0.0020]. We also ran mxbai-embed-large with its query prompt, as its card prescribes: −0.0007 [−0.0100, +0.0083], top-1 hits 232 → 229.

Two limits matter. SciFact's queries are scientific claims written as statements — "Statins decrease blood cholesterol." is one of the 23 that flipped — not the short questions people type into a notes search. A query prefix plausibly matters least for statement-shaped queries. And the 983-document subset inflates absolute scores, so 0.8366 must never be compared with a leaderboard. Only the paired difference is the finding.

So the honest summary is narrow. On 300 claims, the prefixes flipped whether the first result was right for 23 of them, both ways, and the average moved by less than the noise. That does not refute the model card. It shows the effect is small enough that your own notes decide.

The check: what your tool sends, then five questions both ways

The check has three steps. Find out what your notes tool actually sends to the embedding model. Run five questions you already know the answers to, with and without the card's prefixes. Re-embed only if the prefix wins, and then re-embed everything. It takes minutes, and it needs a local Ollama and Python's standard library.

flowchart TD
    A[Find what your tool<br/>sends to the model] --> B[Run five known questions<br/>with and without prefix]
    B --> C{Prefix wins<br/>clearly?}
    C -->|Yes| D[Re-embed every note<br/>with the prefix]
    D --> E[Record the scheme<br/>never mix vectors]
    C -->|No or a tie| F[Keep the current index]

Figure: the three-step prefix check. Inspect what your tool sends, compare the two settings on questions with known answers, and only rebuild the index when the prefix clearly wins.

In words: the first box tells you which side you are on today. The comparison tells you whether switching is worth it. A rebuild is the only path that changes anything, and it must cover every note, because a half-prefixed index compares vectors made two different ways.

Before any of this, make sure retrieval is happening at all. A planted fact you can search for, as in Bury a Canary in Your Notes to Test Your RAG, is the step before this one.¹⁸

Step 1: find what your tool sends

Start with the tool's settings and documentation. Some expose a prefix or "instruction" field per model — others document what they send. If neither tells you, watch the request. Point the tool's Ollama address at a small listener for a minute, trigger one search, and read what arrives:

# peek.py: print the exact text your notes tool sends for embedding. Python stdlib only.
import http.server, json

class Peek(http.server.BaseHTTPRequestHandler):
    def do_POST(self):
        body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        texts = body.get("input") or body.get("prompt")
        for t in texts if isinstance(texts, list) else [texts]:
            print(self.path, "|", repr(t[:80]), flush=True)
        self.send_response(503)   # refuse on purpose: nothing gets indexed
        self.end_headers()

http.server.HTTPServer(("127.0.0.1", 11435), Peek).serve_forever()

Run python3 peek.py, set the tool's Ollama URL to http://127.0.0.1:11435, and search for anything. Each line shows the endpoint and the first 80 characters of a string the tool tried to embed. A line starting 'search_query: means the prefix is there; a bare question means it is not.

The listener refuses every request, so the tool will report an error and index nothing — deliberately. Put the address back to http://localhost:11434 when you are done.

Step 2: run five questions both ways

Copy five to ten notes into a folder. Write five questions whose correct note you already know. Then run this script, which embeds the notes and questions twice — once bare, once with the card's prefixes — and prints which note ranks first each time:

# five_questions.py: does the prefix help on YOUR notes? Needs a local Ollama. Python stdlib only.
import json, math, sys, urllib.request
MODEL, DOC_P, Q_P = "nomic-embed-text", "search_document: ", "search_query: "
NOTES = {n: open(n, encoding="utf-8").read() for n in sys.argv[1:]}   # 5+ of your note files
QUESTIONS = {"What did the dentist say?": "dentist.md"}               # question -> the note that answers it

def embed(texts):
    req = urllib.request.Request("http://localhost:11434/api/embed",
          json.dumps({"model": MODEL, "input": texts}).encode(), {"Content-Type": "application/json"})
    return json.load(urllib.request.urlopen(req))["embeddings"]

def cos(a, b): return sum(x * y for x, y in zip(a, b)) / math.sqrt(sum(x * x for x in a) * sum(y * y for y in b))

for label, dp, qp in [("no prefix", "", ""), ("prefix", DOC_P, Q_P)]:
    names = list(NOTES); docs = embed([dp + NOTES[n] for n in names])
    hits = 0
    for q, want in QUESTIONS.items():
        qv = embed([qp + q])[0]
        top = max(range(len(names)), key=lambda i: cos(qv, docs[i]))
        hits += names[top] == want
        print(f"{label:9} | {q[:40]:40} -> {names[top]}")
    print(f"{label:9} | right note first: {hits}/{len(QUESTIONS)}\n")

Fill QUESTIONS with your five or more pairs. Run it from inside the notes folder — python3 /path/to/five_questions.py *.md — because the script matches answers by the file names you pass. For a different model, change the three values on the MODEL line to that model's contract from the table above; for mxbai-embed-large, DOC_P is empty.

Here is one run on five short hand-written notes. It is an illustration of the output, not a result — five questions cannot settle anything:

no prefix | What did the dentist say?                -> dentist.md
no prefix | How is my knee?                          -> running.md
no prefix | What is mum up to?                       -> mum.md
no prefix | Anything I cooked?                       -> dal.md
no prefix | What broke at work?                      -> deploy.md
no prefix | right note first: 5/5

prefix    | What did the dentist say?                -> dentist.md
prefix    | How is my knee?                          -> running.md
prefix    | What is mum up to?                       -> mum.md
prefix    | Anything I cooked?                       -> mum.md
prefix    | What broke at work?                      -> deploy.md
prefix    | right note first: 4/5

The one miss sent "Anything I cooked?" to a note about a pottery class ("She made a lopsided bowl") instead of the dal recipe. MindSage's baseline table — run without prefixes — shows the same confusion. Its question "Anything about cooking or food I made" went to the pottery class.¹⁶

Making things with your hands sits close to cooking in embedding space — with or without a prefix. Your notes will have their own near-neighbours. That is why the test uses them.

Step 3: re-embed everything, or nothing

If the prefix wins clearly and repeatably on your questions, rebuild the whole index with prefixed notes, and prefix every query from then on. Never add the prefix to new notes only. A note embedded bare and a question embedded with search_query: are compared as if they were made the same way, and they were not.

KMSmcp's plan for the same change is a good template. Re-embed the index, and "bump embedderId so mixed-prefix vectors are never compared". Then re-measure any similarity cut-offs before trusting them, because the score scale may shift.¹⁷ Write the scheme down next to the model name. The record that tells you which model built an index should also say which string it was fed.¹¹

Trade-offs, and what nobody has measured yet

The check costs a few minutes; a rebuild costs more. Every public measurement is small, made on text unlike your notes, or partial. No one has published a large evaluation of prefix versus no prefix through Ollama on short, question-style personal notes. Until someone does, the model card is a strong prior, and your five questions are the evidence.

Small samples everywhere. MindSage's result rests on two questions. Our five-note demo rests on one question. Our 300-claim run has an interval that spans a 2.7-point loss to a 0.4-point gain in nDCG@10.

The wrong kind of query. SciFact's claims are statements. Personal-note searches are short questions like "How is my knee?" — plausibly the case where a query prefix matters most. Our null does not cover it.

Partial evidence. KMSmcp's gain is the strongest number here — and it measures only re-ranking.

Vendor aggregates are aggregates. Qwen's "1% to 5%" is an average over downstream tasks.⁹ BGE's "slight degradation" without instruction is a vendor's own hedge.¹⁰ Neither says what happens on your notes.

A rebuild costs time. MindSage reports a full re-index of 5,000 entries at 8.8 minutes for nomic-embed-text.¹⁶ Any tuned similarity threshold has to be checked again afterwards.

What could go wrong in production. A tool update that quietly starts or stops adding the prefix produces exactly the mixed index Step 3 warns about, with no error anywhere. Re-running peek.py after a major update is the cheapest guard against it.

Frequently Asked Questions

Do I need to add search_query / search_document prefixes when I embed my notes with nomic-embed-text in Ollama?

The model card says yes: search_document: on every note and search_query: on every question. Ollama will not add them, so your tool must. Whether they improve results on your notes is less certain — three public measurements disagree — so run the five-question test both ways before rebuilding an index.

Does Ollama add the nomic-embed-text prefix automatically?

No. Ollama's package for nomic-embed-text has no prompt template, its model file passes text through unchanged (TEMPLATE {{ .Prompt }}), and the token count for "hello" is 3 versus 7 for "search_query: hello". The embedding handler in Ollama v0.40.15 adds only start and end tokens and truncation.

Do I need to add the prefix "query: " and "passage: " to input texts?

For E5 models, yes. The e5-small-v2 card answers it directly: "Yes, this is how the model is trained, otherwise you will see a performance degradation." Prefix strings differ by model family, so use E5's query: and passage: only with E5 models, and nomic's own pair with nomic.

When does the query instruction need to be used?

It depends on the model. mxbai-embed-large needs its prompt on queries only. BGE v1.5 calls the instruction optional and advises "choosing the setting that achieves better performance on your task." Qwen3-Embedding reports a typical 1% to 5% gain from instructions. Documents need no instruction for any of these three.

Will adding the prefix to new notes only break my search?

It can. Notes embedded with and without the prefix are compared as if they were made the same way, and they were not. If you switch, re-embed every note, prefix every query, and record the scheme alongside the model name so mixed-prefix vectors are never compared.

How do I check which prefix my notes app sends?

Check its settings and documentation first. If neither says, point the app's Ollama address at a small local listener, trigger one search, and read the text that arrives. A string beginning search_query: means the prefix is sent; a bare question means it is not. Restore the address afterwards.

Does mxbai-embed-large need a prefix on documents?

No. Mixedbread's card says the prompt Represent this sentence for searching relevant passages: is for queries in retrieval, and "Besides that you don't need any prompt." Stored notes are embedded as plain text. Ollama's mxbai package also adds nothing, and it sets a 512-token context limit.

A model card tells you how a model was trained. Only your own notes can tell you how it should be called.

MNMNOTE keeps notes in open Markdown, stored locally on your own device — plain text you can export and point a five-question test at. mnmnote.com

References