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 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:
# 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.Common gotchaBeginners 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 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.Common gotchaThe 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:
claude mcp listA 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.
{
"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:
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. To point Claude at your own writing this way, see 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 shows how embeddings feed a full retrieve-and-answer pipeline, and how LLMs predict the next word explains the model that produces the answer once the right passages are in hand.