What are embeddings? Search, RAG, and coding agents

An embedding is a list of numbers that stands in for a piece of text. Similar texts land close together. Dissimilar texts land far apart. Search, clustering, and retrieval all use that distance.

This is a different job from the chat model that writes code. An embedding model reads text and returns the list. It does not write the answer. The RAG chunking post is where chunk size, overlap, and the storage cost of those lists are worked out. This entry is the definition, and where the four coding tools do and don’t use one.

How embeddings work

You split a document into passages small enough that one vector still means one idea. The embedding model turns each passage into a vector. Later you embed the question with the same model, and you keep the passages whose vectors are nearest.

Those passages then go into the context window of the model that writes the answer. The embedding step picked them. The chat model still has to read them as tokens.

A token embedding inside a transformer is the same kind of object, at a smaller scale. The embedding map in Language Model Builder is that view: a learned vector per token, drawn on a map. Retrieval embeddings are the view you store and search.

Embeddings in each tool

None of the four coding agents is an embeddings product. Two of the companies sell an embeddings API beside the agent. Cursor’s current search docs describe a local exact-match index and say they do not store embeddings of your codebase for search.

Claude Code

The Claude Code docs index has no embeddings page, and the commands list has no embeddings command. If you need vectors, you call an embeddings API from your own code. Claude Code can edit that code. It is not the index.

See the Claude Code docs index.

OpenAI Codex

The Codex CLI command reference doesn’t include an embeddings command. OpenAI documents embeddings as their own API. The guide says text embeddings measure how related two strings are, and that an embedding is a vector of floating point numbers. Small distance means high relatedness. Requests are billed on the number of input tokens.

The guide’s example model is text-embedding-3-small. You send the string and the model name to the embeddings endpoint. Codex can run that call for you if you ask it to. The call is still the API, not a Codex slash command.

See the OpenAI embeddings guide.

Cursor

Cursor’s search docs describe Instant Grep. Agent uses it for an exact match: a function name, an error string, or a regex. The index is built and queried on your machine. The same page says Cursor does not upload file paths or code to build a search index, and it does not store embeddings of your codebase for search.

When Agent opens a match, that file can still be sent to the model. That is a normal context include, not a vector lookup.

See Cursor search.

Grok Build

The Grok Build command list has no embeddings command. The xAI API has Collections beside the chat API. A collection is a group of files with an embedding index. The management example sets the index model to grok-embedding-small, with a chunk size and an overlap counted in tokens. Search takes a query string, embeds it with the same model used for the collection, and returns matches.

That is an API you call with a key. It is not a /embeddings command inside grok.

See Collections and collection search.

Details checked against each vendor’s documentation in November 2026.

A real example

You want the three handbook sections closest to a question, and then a model can answer from those sections only. OpenAI’s docs do it with one call. The input here is a real question. The vector comes back on data[0].embedding.

import OpenAI from 'openai'

const openai = new OpenAI()

const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'How does prompt caching change the cost of a long coding session?',
  encoding_format: 'float',
})

console.log(embedding.data[0].embedding.length)

Store that list next to the passage it came from. Embed the reader’s question with the same model, and keep the passages with the smallest distance. The RAG chunking post is the rest of that pipeline: how big each passage should be, and what the vectors cost to keep.

The Workers AI post shows the same shape on Cloudflare’s binding, a text-in, vectors-out call, next to the text and image models.

When to use embeddings

Use them when the question is “which passage is about this,” and a regex would miss the wording. A glossary, a handbook, or a pile of support notes are the usual fit. The RAG chunk calculator is the tool on this site for chunk count, embedding cost, and whether the retrieved text still fits in the window.

Skip them when you know the symbol. A function name is a grep. Cursor’s own agent search is built that way on purpose. Skip them when the corpus is one file you were going to paste anyway. The embedding call, the stored vectors, and the second model call cost more than reading the file.

Pitfalls

Two vectors are comparable only when the same model produced them. The xAI search API embeds the query with the model that indexed the collection. Mixing text-embedding-3-small vectors with another model’s vectors gives you a nearest-neighbor list that isn’t about meaning.

A long passage becomes one blurry vector. The chunking post is the warning: if the piece is too big, retrieval gets worse. Overlap and chunk size are the knobs, and they also decide how many tokens you embed and store.

Cursor will not semantic-search your repo through a hidden embedding index, according to the current search doc. If a prompt says “use embeddings to find the function,” you want a grep, or an index you built yourself. Don’t expect Agent’s search tool to be that index.

The distance is not a citation. Nearest still means you should read the passage before the chat model quotes it.

Related on flaviocopes.com

• RAG chunking explained is the cost and chunk-size walkthrough, with the RAG chunk calculator.
• Cloudflare Workers AI includes an embedding call beside text generation.
• Language Model Builder’s embedding map is the token-vector map inside a small transformer, which is the other meaning of the word.

Related glossary entries

• Context window: The context window is everything a coding agent can see at once. How to check it, free it and keep it small in Claude Code, Codex, Cursor and Grok Build.
• Tokens and usage limits: A token is the unit a model reads and writes. A usage limit is how much of that work a plan includes. How Claude Code, Codex, Cursor and Grok count it.

All AI glossary entries →

Want me to talk about your product? You can sponsor this site.