Skip to main content
After hybrid search disambiguates a starting item, agents traverse its connected facts using SPARQL (SPARQL Protocol and RDF Query Language). This is the W3C standard for knowledge graphs.

​
SPARQL reasoning

SPARQL matches patterns against facts, follows relationships, and returns exact results. It does not rely on probabilistic guessing.

​
Symbolic logic

Given triples such as user:person wazoo:uses wazoo:worlds, query for the resource:

​
Neuro-symbolic reasoning

Worlds fuses semantic discovery with symbolic logic. Hybrid search disambiguates the natural language intent into a specific starting item, while SPARQL executes the deterministic traversal across verified facts. The Worlds API provides an external source of truth that an agent can deterministically verify. In practice, an LLM accesses this source of truth via tool calling, which lets it ground its responses in verified facts rather than probabilistic weights.

​
LLM inference vs. graph queries

LLM inference predicts the next token from model weights and prompt context. That makes it useful for language, synthesis, and planning, but weak as a source of truth. SPARQL queries a graph of stored facts. When an agent asks Worlds a question, the model can use a tool call to retrieve facts instead of relying only on probabilistic generation. In practice, the LLM decides what to ask. Worlds answers from the graph. The final response can still be natural language, but the facts come from a deterministic query path.

​
Operational tradeoff

Graph grounding changes where the system spends resources. Instead of paying the model to reconstruct facts from long prompts on every answer, you store and index facts once, then retrieve them through short queries. This tradeoff is deliberate. The system uses storage and indexes to reduce repeated inference cost and keeps an inspectable path back to the source facts.

​
Caching hot reads

After facts move into a graph, caching can optimize repeated reads. A cache stores derived query results or materialized views for hot paths, while the graph remains the authoritative state.

​
High-stakes context

Standard RAG struggles with evolving facts and complex relational queries. Worlds maintains a living knowledge graph and resolves contradictions at the data layer.

​
The evolving fact

Consider a scenario where information changes rapidly:
  1. Monday: “I am working on Project Apollo.”
  2. Wednesday: “I am pausing Apollo to focus on Project Hermes.”
  3. Friday: “What am I working on?”
Traditional RAG retrieves both contradictory chunks, which forces the LLM to guess. Worlds updates the specific graph relationship, so the agent only retrieves the current state.

​
Grounding agents in ontologies

By running bounded SELECT queries with the executeSparql tool from @wazoo/tools (e.g., SELECT ?class WHERE { ?class a rdfs:Class } LIMIT 50), agents discover the world’s ontology before attempting to query it.
  1. Discovery: Agent discovers the world’s ontology via SPARQL.
  2. Mapping: Agent maps intent to specific RDF classes and predicates.
  3. Querying: Agent executes precise SPARQL queries instead of depending solely on vector similarity.

​
Preference-aware retrieval

While standard SPARQL is strictly deterministic, feedback can further align retrieval with human intent. When a query results in multiple valid paths, the engine uses the reshaped probability landscape to prefer the path that has historically yielded high-reward results. Feedback moves the system from deterministic reasoning to intentional agency.

​
Hosted engine architecture

The hosted Worlds Data API at data.wazoo.dev runs a WazooSparqlEngine instance over a D1RdfjsStore — an RDF/JS Store adapter backed by a shared Cloudflare D1 database. When a SPARQL request arrives:
  1. The Worker resolves the world’s metadata from D1.
  2. A WorldsSdk is initialized (and cached per world) with:
    • D1QuadStore — quad storage with D1-backed hexastore indexes.
    • CloudflareSearchIndex — FTS5 keyword search projected into D1.
    • WazooSparqlEngine — the SPARQL evaluator, wired to a D1RdfjsStore that streams quads from D1 via paginated queries (no in-memory hydration).
  3. The engine evaluates the SPARQL query against quads streamed from D1.
  4. Results are bounded by configurable limits (SPARQL_MAX_RESULTS, SPARQL_TIMEOUT_MS) and returned as a JSON SPARQL response.
SPARQL UPDATE operations use a D1Transaction that buffers insertions and deletions, then commits them atomically in a single db.batch() call. This architecture keeps all graph data durable in D1 while running query evaluation in the Worker isolate. For self-hosting with other backends (LibSQL, PostgreSQL, SQLite), see Self-host.