> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wazoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Semantic disambiguation and hybrid retrieval.

Before reasoning about facts, agents must find the correct starting point.
Hybrid search disambiguates natural language queries, resolving them to the
correct semantic entity (IRI) before executing symbolic logic.

## Why not only vector search?

Standard vector search retrieves semantically similar text, but agents require
factual precision. If an agent searches for "Ethan's manager", a pure vector
query might return "Gregory's manager" because their text embeddings are nearly
identical in vector space.

## Hybrid retrieval

Worlds fuses three complementary signals to guarantee retrieval accuracy. By
layering keyword precision and structural graph filters on top of vector
embeddings, hybrid search ensures the agent resolves the exact item it needs.

| Signal        | Technique                    | What it captures         |
| :------------ | :--------------------------- | :----------------------- |
| Semantic      | Vector embeddings (1536-dim) | Conceptual meaning       |
| Keyword       | FTS5 / BM25                  | Exact term matches       |
| Graph context | RDF relationship filters     | Structural relationships |

***

## Reciprocal rank fusion

Results from each signal are merged using Reciprocal Rank Fusion (RRF), an
algorithm that produces a single unified relevance ranking:

$score = \sum_{d \in D} \frac{1}{60 + rank(d)}$

This ensures that a result ranked highly by multiple signals surfaces to the
top, while noise from any single signal is suppressed.

## Execute a search

Use the `worlds.search` method to perform a hybrid retrieval across your world.

```typescript TypeScript theme={null}
import { Worlds } from "@wazoo/worlds-sdk";

const worlds = new Worlds({
  apiKey: process.env.WORLDS_API_KEY,
});

// Search for an item using natural language
const results = await worlds.search("my-world-id", "Ethan's manager", {
  limit: 5,
  types: ["schema:Person"],
});

console.log("Search results:", results);
```