Skip to main content
For agents and developers: the exact rules search by meaning follows. For what search does and how to ask, read Search. Inside a workspace, search understands meaning as well as words. A search for “how do we handle auth failures” can surface a passage about “retry strategy for expired credentials”, with no shared keywords required. Each result comes back with its best passages, so an agent can read the answer without opening every document.

What gets indexed

When the server has an embedding provider, every text document in a workspace (markdown, HTML, code, plain text) is indexed by meaning automatically, when it is written: on publish, on a new version, and when a standalone document or folder is adopted into the workspace. There is nothing to switch on per document or folder. Documents outside workspaces are not indexed by meaning. Searching them ranks by keyword, as it always has.

How a workspace search ranks

Scope a search to a workspace with --workspace-id (REST and MCP: workspaceId). The search then ranks by keywords and meaning together, and the response reports mode: hybrid. Exact terms still count: a document that uses your words and means what you asked ranks highest. The response’s mode tells you how the results were ranked: There is no mode to choose: the server picks the best ranking it can and says which one it used.

Found by words or by meaning

Search by meaning has no similarity floor: it returns the closest documents even when none contains your words. Each result’s matchedBy says how it was found: words when its text holds the query’s words, meaning when meaning alone found it (the CLI marks it (meaning only)). To find an exact identifier, such as a ticket number or a function name, and nothing else, send match: words (--match words on the CLI): only documents whose text holds the words come back, ranked by keyword, and none when none does.

Passages

Each result of a workspace search carries passages: up to three of the document’s best chunks, best first. A passage has its section heading, its full text, and its position in the document.

Asking a single document a question

Scope a search to one artifact to get its most relevant passages:
The response holds that one document, with up to --limit passages. A document in a workspace is ranked by keywords and meaning; a standalone document by keyword.

Pending

A workspace search also returns pending: how many chunks of the documents you can read in that scope are not yet searchable by meaning. Indexing starts the moment content is written and usually finishes within seconds, so a non-zero count means something was just published. Those chunks still match by keyword in the meantime.

Who sees what

Meaning-ranking follows the same access rules as every other read. Every member of a workspace searches all of its documents, and no one else gets passages, results or pending counts from them. Documents in the trash never appear. See the search API reference and the rip search command. On MCP, use the search tool with workspaceId or artifactId.