> ## 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.

# Worlds

> Worlds gives agents infinite context through verifiable knowledge graphs.

Worlds is Wazoo's context engine. It stores facts as knowledge graphs, exposes
search and SPARQL query paths, and provides APIs that let agents retrieve and
update verifiable context. Worlds lets models use tool calls to retrieve facts
from a graph rather than infer them from model weights.

Worlds is designed for curated memory. Store durable facts in a world and
discard the rest, instead of keeping every message.

## What Worlds provides

* **Graph storage**: RDF triples and named graphs for durable facts.
* **Hybrid search**: Keyword and vector retrieval over graph literals.
* **SPARQL queries**: Declarative graph traversal and reasoning.
* **API and CLI surfaces**: Programmatic and terminal workflows for creating,
  importing, exporting, searching, and querying worlds.
* **Edge-ready adapters**: LibSQL/Turso backends for durable deployments.

## Repositories

| Repository                                                              | Purpose                           |
| ----------------------------------------------------------------------- | --------------------------------- |
| [worlds-client-ts](https://github.com/wazootech/worlds-client-ts)       | Core client and in-memory backend |
| [worlds-libsql](https://github.com/wazootech/worlds-libsql)             | LibSQL/Turso adapter              |
| [worlds-api](https://github.com/wazootech/worlds-api)                   | Hosted Worlds Data API            |
| [worlds-client-evals](https://github.com/wazootech/worlds-client-evals) | Agent evaluation harness          |

## Quickstart

Start with the hosted API when you want managed storage, or use the embedded
`@worlds/client` when you want in-memory graph memory during development.

Hosted Worlds has two surfaces:

* The Wazoo Platform API (`@wazoo/client`) manages platform resources such as
  user-owned Worlds and tokens.
* The Worlds Data API, hosted at `worlds-api.wazoo.dev`, handles graph data
  through import, export, search, and SPARQL operations.

### Prerequisites

1. [Get access to the hosted Wazoo private beta](/platform/private-beta).
2. Generate a platform token (`wzp_`) from the
   [Console tokens page](/console/tokens).
3. Save it as `WAZOO_PLATFORM_TOKEN`.

### Create a world

```bash theme={null}
curl -s -X POST "https://api.wazoo.dev/v1/worlds" \
  -H "Authorization: Bearer $WAZOO_PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "worldId": "quickstart-cloud",
    "world": { "displayName": "My First World", "region": "auto" }
  }'
```

### Mint a world token

Data-plane requests use a `wzw_` token scoped to a single world. Save the
returned secret immediately; it is shown only once:

```bash theme={null}
curl -s -X POST "https://api.wazoo.dev/v1/worlds/quickstart-cloud/auth/tokens" \
  -H "Authorization: Bearer $WAZOO_PLATFORM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "quickstart" }'
```

Save it as `WORLDS_TOKEN`.

### Import, search, and query

```bash theme={null}
curl -s -X POST "https://worlds-api.wazoo.dev/worlds/quickstart-cloud/import" \
  -H "Authorization: Bearer $WORLDS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "application/json",
    "data": "[{\"subject\":\"urn:user:person\",\"predicate\":\"https://wazoo.dev/#uses\",\"object\":\"urn:wazoo:worlds\"}]"
  }'
```

```bash theme={null}
curl -s -X POST "https://worlds-api.wazoo.dev/worlds/quickstart-cloud/search" \
  -H "Authorization: Bearer $WORLDS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "worlds",
    "limit": 5
  }'
```

```bash theme={null}
curl -s -X POST "https://worlds-api.wazoo.dev/worlds/quickstart-cloud/sparql" \
  -H "Authorization: Bearer $WORLDS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX wazoo: <https://wazoo.dev/#> SELECT ?resource WHERE { <urn:user:person> wazoo:uses ?resource }"
  }'
```

To provision hosted resources programmatically, use the
[Platform TypeScript SDK](/platform/typescript-sdk).

### Embedded client

For in-memory graph memory during development, wire the core adapters into a
`Client` from `@worlds/client`:

<CodeGroup>
  ```bash npm theme={null}
  npx jsr add @worlds/client
  ```

  ```bash deno theme={null}
  deno add jsr:@worlds/client
  ```

  ```bash pnpm theme={null}
  pnpm dlx jsr add @worlds/client
  ```

  ```bash yarn theme={null}
  yarn dlx jsr add @worlds/client
  ```

  ```bash bun theme={null}
  bunx jsr add @worlds/client
  ```
</CodeGroup>

```typescript index.ts theme={null}
import { Client } from "@worlds/client";
import { ComunicaSparqlEngine } from "@worlds/client/comunica";
import { RdfjsQuadStore, RdfjsSearchIndex } from "@worlds/client/rdfjs";
import { QueryEngine } from "@comunica/query-sparql-rdfjs-lite";
import { Store } from "n3";

const store = new Store();
const client = new Client({
  quadStore: new RdfjsQuadStore({ store }),
  searchIndex: new RdfjsSearchIndex(store),
  sparqlEngine: new ComunicaSparqlEngine({
    queryEngine: new QueryEngine(),
    store,
  }),
});

await client.import({
  source: {
    kind: "serialized",
    data: "<urn:user:person> <https://wazoo.dev/#uses> <urn:wazoo:worlds> .",
    contentType: "text/turtle",
  },
});

const results = await client.search({ query: "worlds" });
const response = await client.sparql({
  query:
    "SELECT ?resource WHERE { <urn:user:person> <https://wazoo.dev/#uses> ?resource }",
});
```

Durable embedded backends are published as separate packages, including
`@worlds/libsql` (LibSQL/Turso) and `@worlds/postgres`.

### Next steps

* [Search](/worlds/search)
* [Query](/worlds/query)
* [Update](/worlds/update)
* [Worlds API](/reference)