# Embeddings explained for beginners

An embedding is a list of numbers that stands in for the meaning of a
piece of text. Text that means similar things gets similar numbers, so you can
find related content by comparing the numbers instead of matching the exact
words. That single idea is what lets search work by meaning rather than by
keyword.

## The one-sentence answer

You turn a sentence into a list of numbers (a vector). Two sentences that
mean the same thing produce vectors that sit close together. To search, you turn
the question into a vector too, then find the stored vectors nearest to it. The
nearest ones are the best matches by meaning.

That is the whole trick. The rest of this guide explains why it works, what
"close together" means in numbers, and how you see it in action without writing
any model-calling code.

## Why doesn't keyword search work?

Keyword search matches the letters you typed. Search a help centre for "cannot
log in" and a perfectly relevant article titled "Resetting a forgotten
password" never appears, because it shares no words with your query. A human
reader knows the two are about the same problem. Keyword search does not.

Embeddings fix this by comparing meaning. "Cannot log in" and "reset a forgotten
password" land near each other in number space because they are about the same
situation, even though they share no words. So the article surfaces.

| Approach | Matches on | Misses |
| --- | --- | --- |
| Keyword search | Exact words and word stems | Synonyms, paraphrases, related ideas |
| Embedding search | Meaning and intent | Exact strings like IDs and error codes |

Neither is strictly better. Keyword search is precise on literal terms;
embedding search understands intent. Strong systems often combine the two, which
the [RAG fundamentals](/guides/rag-fundamentals) guide covers as hybrid search.

## What does it mean to turn meaning into numbers?

Picture a map. Every word or sentence gets a position on it. Things with related
meaning sit in the same neighbourhood: "dog", "puppy", and "golden retriever"
cluster together, while "invoice" sits far away in another part of the map.

A real embedding is the same idea with many more directions than a flat map has.
Instead of two coordinates (left-right and up-down), an embedding has hundreds or
thousands of numbers, one per direction. Each direction captures some shade of
meaning the model learned during training. You never read these numbers by hand.
The point is only that nearby positions mean similar things.

A short, concrete picture of the numbers. Suppose an embedding had only three
directions instead of hundreds. The vectors might look like this:

```bash
# Illustration only. Real embeddings have hundreds of numbers, not three.
"dog"     -> [0.91, 0.10, 0.05]
"puppy"   -> [0.88, 0.14, 0.06]
"invoice" -> [0.02, 0.95, 0.40]
```

"dog" and "puppy" have nearly the same numbers, so they are close. "invoice" has
very different numbers, so it is far. Distance in the list of numbers tracks
distance in meaning.

## How is similarity between two embeddings measured?

You need a way to score how near two vectors are. The standard measure is
cosine similarity. It looks at the angle between two vectors rather than
their raw length. Two vectors pointing the same direction score 1. Two that are
unrelated score around 0. Two pointing opposite ways score -1.

| Cosine score | Meaning | Example pair |
| --- | --- | --- |
| Near 1 | Almost the same meaning | "car" and "automobile" |
| Around 0 | Unrelated | "car" and "photosynthesis" |
| Near -1 | Opposite direction | rare in normal text |

To rank search results, you compute the cosine score between the question vector
and every stored vector, then return the highest scorers first. That is what
"find the nearest matches" means in practice.

## The search flow end to end

Semantic search has two phases. First you prepare your content once. Then you
answer questions against it as many times as you like.

**Prepare once.** Split your documents into passages, turn each passage into a
vector, and store the vector next to its text in a [vector store](/guides/choose-a-vector-database).Beginners often embed a whole long document as one vector. The model averages every topic in it into a single point, so the meaning blurs and nothing ranks well. Split into focused passages of a few sentences each, and embed those. The
[RAG fundamentals](/guides/rag-fundamentals) guide goes deep on how to split text
into good passages.

**Answer many times.** When a question arrives, embed the question with the same
model you used for the documents, find the nearest stored vectors, and return the
text behind them. Those passages are your search results, or the context you hand
to a model to write a grounded answer.

One rule matters: embed your documents and your questions with the same model.
Two different models produce vectors in different number spaces, and comparing
across them gives meaningless scores.The trap is upgrading to a newer embedding model and only running it on new documents, leaving the old ones embedded by the previous model. The two batches now live in incompatible number spaces, so cosine scores rank them at random and your index quietly rots. Whenever you change models, re-embed every document, not only the recent ones.

## See it without writing model code

You do not need to write any code that calls a model to work with embeddings.
The Claude Code CLI can connect to a search tool through MCP (Model Context
Protocol), and that tool handles the embedding and the vector math for you. Claude
sends a query, the server returns the nearest passages, and Claude reads them.

Start by checking what is connected:

```bash
claude mcp list
```

A search server is configured in JSON like the snippet below. This wires up a
fictional documentation-search server so Claude can query it. Replace the command
and path with the real server you use.

```json
{
  "mcpServers": {
    "docs-search": {
      "command": "npx",
      "args": ["-y", "docs-search-mcp", "--root", "src/docs"]
    }
  }
}
```

With that connected, you ask in plain language and the server does the embedding
and ranking behind the scenes:

```text
Search the docs-search server for how a user resets a forgotten password,
then summarize the steps and cite the file each step came from.
```

Claude embeds your request through the server, gets back the closest passages
even if they never use the word "reset", and answers from them. For the deeper
mechanics of wiring tools to Claude, read [MCP fundamentals](/guides/mcp-fundamentals).
To point Claude at your own writing this way, see
[connect Claude to your notes](/guides/connect-claude-to-your-notes).

## How do I choose an embedding model?

You choose an embedding model the way you choose any tool: by fit, not by
fashion. Three factors decide it.

- **Language and domain.** A model trained on broad web text handles general
  prose well. Specialised content, such as legal or medical text, can need a
  model tuned for that domain.
- **Vector size.** More numbers per vector can capture finer shades of meaning,
  but each vector costs more to store and compare. Smaller vectors are cheaper
  and faster to search. Pick the smallest size that still ranks results well for
  your data.
- **Where it runs.** Some models run as a hosted service you call over the
  network. Others run on your own hardware, which keeps private text in house.

Whatever you pick, use the same model for documents and questions, and re-embed
everything if you ever switch models. A mixed index returns nonsense.

## Where beginners trip up

These are the misunderstandings that cause the most confusion early on.

- **An embedding is not the text.** It is a numeric stand-in for meaning. You
  always store the original passage next to its vector so you can show the real
  text to the reader.
- **Bigger vectors are not always better.** Past a point, extra numbers add cost
  and storage without improving how results rank. Test on your own content.
- **Exact strings can slip through.** Pure embedding search can miss an order ID
  or an error code, because those carry little meaning to compare. Combine
  embedding search with keyword search when literal matches matter.
- **Stale vectors give stale answers.** Vectors reflect your documents at the
  moment you embedded them. When a document changes, re-embed it so its vector
  matches the new text.
- **Scores are relative, not absolute.** A cosine score of 0.7 is not a fixed
  grade. Compare scores within one result set to rank them; do not read a single
  number as a universal measure of quality.

## The takeaway

An embedding turns text into a position in meaning space. Similar meanings sit
close, so you search by turning the question into a position and finding the
nearest stored ones. That is why a help article about resetting a password can
answer "I cannot log in" without sharing a single word.

From here, [RAG fundamentals](/guides/rag-fundamentals) shows how embeddings feed
a full retrieve-and-answer pipeline, and
[how LLMs predict the next word](/guides/how-llms-predict-the-next-word) explains
the model that produces the answer once the right passages are in hand.