Skip to main content
Autonomous agents write new facts into the graph to evolve the world. Worlds supports multiple strategies for ingesting and synchronizing knowledge within a stateful context.

State mutations

A world mutates its state using RDF patches, which are additions and deletions of facts. A world stores current state: a deleted fact is removed, and Worlds does not keep a history of earlier states yet. Fact-level history is planned as an append-only change log that records every patch beside the current state (worlds-sdk-ts#221).

Import quads

The hosted API has two mutation paths: the import endpoint and SPARQL UPDATE through SPARQL. Both require an API key with the data:write scope. To add facts, send quads to import:
The import above asserts that wazoo:worlds is a schema:SoftwareApplication. Set contentType to text/plain to ingest unstructured text chunks instead.

Mutation and state

Every update to a world is a transaction that adds and removes facts. You can query the current state; earlier states are not retained. To keep a record of how information changed, write it as facts, for example a timestamp or a superseded-by property.

RDF patches

An RDF patch is a structured set of additions and deletions. When you update a relationship, the engine performs a patch:
  1. Deletion: Remove the outdated triple.
  2. Addition: Insert the new triple.
This process is atomic. Worlds does not validate patches against SHACL shapes yet; validate before import, for example with the Wiki CLI. Validation on write is planned (worlds-sdk-ts#151).

Update strategies

Worlds supports multiple methods for mutating state, depending on the required precision and automation level.

Feedback ingestion

Intentional agency requires a bridge between human preferences and graph state. RLHF enables this by treating feedback as a first-class mutation.

Capturing rewards

When a user or supervisor provides feedback (e.g., a thumbs up or a specific correction), the API records this as a preference item connected to the original fact.

Recursive learning

As preferences accumulate, the world’s probability landscape is reshaped. Historical reward signals boost retrieval results, which creates a recursive loop where the system learns which triples are most useful or truthful for the agent’s context. Preference facts stay in the graph until you remove them, so this preference data can guide future queries. Learn more about preference-aware retrieval.