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

> The neuro-symbolic components of verifiable context.

A world is a stateful knowledge graph engine that functions as an agent's
verifiable context.

<div align="center">
  ```mermaid theme={null}
  graph LR
      Agent([AI agent]) -->|query / update| W[(World)]
      subgraph W [World]
          direction TB
          RDF[RDF graph]
          SEARCH[Search index]
      end
  ```
</div>

A world is made of items made of facts.

## Items

Worlds represent everything as an item, including the types themselves. This
recursive structure enables granular, multi-hop reasoning.

An item is...

* Assigned a unique
  [IRI](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier).
* Defined by one or more facts.
* Any "thing" in your world, including documents, people, physical objects, and
  abstract concepts.

## Properties

Properties connect items. They define actions or attributes, such as `worksFor`
or `givenName`. The set of valid properties forms the graph's vocabulary,
enabling agents to navigate and mutate state with precision.

## Facts

A fact is a unit of data expressed as a structured statement that connects two
items using a property. Every fact is inherently bound to the dimension of time.
Worlds maintains an append-only, chronological ledger of facts, allowing agents
to understand exactly how state and information evolve.

Conceptually, a fact functions exactly like a structured assertion. For example,
the assertion "Ethan is a person" can be represented as:

<div align="center">
  ```mermaid theme={null}
  graph LR
      A((Ethan)) -->|is a| B((Person))
      style A fill:#FF9800,stroke:#F57C00,color:#fff
      style B fill:#FF9800,stroke:#F57C00,color:#fff
  ```
</div>

## Triples

Computers store facts in a data structure called the triple, which is built from
three components called terms.

### Anatomy

<Frame caption="Analogy between triples and molecules">
  <img src="https://mintcdn.com/wazoo/J0bxm5Gd3BcIN5Yg/images/rdf-molecules.png?fit=max&auto=format&n=J0bxm5Gd3BcIN5Yg&q=85&s=3eb72ec7a7b8628bcd67781db99d30c9" alt="Anatomy of an RDF triple" width="1024" height="559" data-path="images/rdf-molecules.png" />
</Frame>

<ResponseField name="Subject" type="Term">
  The item you are describing e.g., `user:person`
</ResponseField>

<ResponseField name="Predicate" type="Term">
  The structural representation of a property e.g., `rdf:type`
</ResponseField>

<ResponseField name="Object" type="Term">
  Another item or a raw data value e.g., `schema:Person`
</ResponseField>

### Topography

The Object of a triple determines how the graph grows. Facts branch into two
types:

* Item-to-item: Connects two distinct items e.g., `user:person` ->
  `schema:worksFor` -> `wazoo:organization`
* Item-to-value: Connects an item to a raw data value, adding searchable detail
  but acting as a terminal point e.g., `user:person` -> `schema:givenName` ->
  `"Ethan"`

<div align="center">
  ```mermaid theme={null}
  graph LR
      subgraph "Memory graph"
      A((user:person)) -->|schema:worksFor| B((wazoo:organization))
      A -->|schema:givenName| C[/"Ethan"/]
      end
      style A fill:#FF9800,stroke:#F57C00,color:#fff
      style B fill:#FF9800,stroke:#F57C00,color:#fff
      style C fill:#FFB74D,stroke:#FF9800,color:#000
  ```
</div>

### Serialization

To codify knowledge, Worlds standard RDF serialization formats for expressing
triples in plain text.

To assert "Ethan is a Person", the syntax goes:

<CodeGroup>
  ```turtle Turtle theme={null}
  @prefix user: <https://etok.me/#> .
  @prefix schema: <https://schema.org/> .

  user:person a schema:Person .
  ```

  ```json JSON-LD theme={null}
  {
    "@context": {
      "user": "https://etok.me/#",
      "schema": "https://schema.org/"
    },
    "@id": "user:person",
    "@type": "schema:Person"
  }
  ```

  ```turtle N-Triples theme={null}
  <https://etok.me/#person> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/Person> .
  ```

  ```html Microdata theme={null}
  <div
    itemscope
    itemid="http://corp.example/acme"
    itemtype="https://schema.org/Organization"
  >
    <!-- Additional facts go here -->
  </div>
  ```
</CodeGroup>

Items can consolidate multiple facts into a single structure. Here, we assert
that Ethan is a person with the given name "Ethan":

<CodeGroup>
  ```turtle Turtle theme={null}
  @prefix user: <https://etok.me/#> .
  @prefix schema: <https://schema.org/> .

  user:person a schema:Person ;
    schema:givenName "Ethan" .
  ```

  ```json JSON-LD theme={null}
  {
    "@context": {
      "user": "https://etok.me/#",
      "schema": "https://schema.org/"
    },
    "@id": "user:person",
    "@type": "schema:Person",
    "schema:givenName": "Ethan"
  }
  ```

  ```turtle N-Triples theme={null}
  <https://etok.me/#person> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/Person> .
  <https://etok.me/#person> <https://schema.org/givenName> "Ethan" .
  ```

  ```html Microdata theme={null}
  <div
    itemscope
    itemid="http://corp.example/acme"
    itemtype="https://schema.org/Organization"
  >
    <span itemprop="https://schema.org/legalName">Acme Corp</span>
  </div>
  ```
</CodeGroup>

## Verification

To verify a fact, Worlds uses the SPARQL ASK query. This provides a
deterministic boolean answer without probabilistic guessing.

For example, to verify if "Ethan works at Wazoo", use:

```sparql SPARQL theme={null}
PREFIX wazoo: <https://wazoo.dev/#>

ASK WHERE {
  <https://etok.me/#person> wazoo:worksFor <https://wazoo.dev/#organization> .
}
```

In the API, use the `sparql` method to perform this check:

```typescript TypeScript theme={null}
// worlds.sparql accepts either a world ID or a human-readable slug.
const result = await worlds.sparql(
  "my-world-slug",
  "PREFIX corp: <http://corp.example/> ASK WHERE { corp:acme corp:ownedBy corp:parent . }",
);

if (result.boolean) {
  // Fact is verified
}
```

## Why care?

Worlds is built on standard knowledge representation formats. This provides
autonomous agents with an established, interoperable foundation for reasoning.