Quarex Specification

Version 1.0 — The canonical technical specification for Quarex knowledge systems.

Author: Peter Nehl · Published: November 27, 2025 · License: CC-BY 4.0

Overview
Hierarchical Structure
JSON Schema
Reading Modes
Generative Protocol
Behavioral Requirements
Conformance

1. Overview

A Quarex is a dynamically generated, recursively structured knowledge artifact that evolves through iterative inquiry. Unlike static documents, a Quarex merges authored intention with machine-generated expansion, forming an ever-growing lattice of questions, contexts, and explanations.

This specification defines:

The hierarchical structure of a Quarex
The JSON schema for interchange
The generative protocol for recursive expansion
Behavioral requirements for compliant implementations

2. Hierarchical Structure

A Quarex organizes knowledge in a five-level hierarchy, with recursive expansion at the leaf level:

Library

└──

Shelf

└──

Book

└──

Chapter

└──

Topic

└──

Follow-up Questions ∞

Level	Description	Authored By
`Library`	The root container. A broad domain of knowledge.	Architect
`Shelf`	A thematic subdivision within a library.	Architect
`Book`	A focused subject or concept.	Architect
`Chapter`	A facet or dimension of the book's subject.	Architect
`Topic`	A specific question or seed inquiry.	Architect / AI
`Follow-ups`	Recursively generated questions from topic responses.	AI (guided)

3. JSON Schema

A Quarex is represented as a JSON document. The following is the minimal conformant schema:

quarex.json

{
  "$schema": "https://quarex.org/schema/v1",
  "library": "LIBRARY_NAME",
  "shelves": [
    {
      "name": "SHELF_NAME",
      "books": [
        {
          "name": "BOOK_NAME",
          "chapters": [
            {
              "name": "CHAPTER_NAME",
              "topics": [
                "Topic as question 1",
                "Topic as question 2",
                "Topic as question 3"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Optional Metadata Fields

Implementations MAY include additional metadata at any level:

{
  "library": "Philosophy",
  "metadata": {
    "architect": "Peter Nehl",
    "created": "2025-11-27",
    "version": "1.0",
    "language": "en",
    "license": "CC-BY-4.0"
  },
  "shelves": [ ... ]
}

4. Reading Modes

A Quarex can be consumed in different ways depending on its intended purpose. The mode field at the Book level specifies how the content should be presented to the reader.

Mode	Behavior	Use Cases
`followup`	Default. After each response, the AI generates 3 follow-up questions. The reader chooses which path to explore, creating a branching inquiry.	Reference works, encyclopedias, exploratory research, open-ended learning
`sequential`	Topics are presented in order (Chapter 1 → Topic 1 → Topic 2 → ... → Chapter 2 → ...). After each response, the next topic auto-loads. The reader controls pace.	Stories, tutorials, courses, historical narratives, philosophical arguments, step-by-step guides

4.1 Sequential Mode Behavior

When "mode": "sequential" is set:

The system traverses all chapters and topics in order
After each AI response, the next topic is loaded into the prompt
The reader must explicitly trigger each inquiry (no auto-play)
A progress indicator shows current position (e.g., "Chapter 2 of 5 · Topic 3 of 4")
Upon completion, a "Book Complete" state is displayed

Design Principle: Sequential mode gives the Architect control over the reading experience. Unlike follow-up mode where the reader chooses their path, sequential mode ensures the content is consumed as the Architect intended — essential for narratives, arguments that build on prior premises, or step-by-step instruction.

4.2 Mode Declaration

The mode is declared at the Book level:

{
  "name": "The Sleepy Star",
  "mode": "sequential",
  "chapters": [ ... ]
}

If mode is omitted, implementations MUST default to "followup".

5. Generative Protocol

The defining characteristic of a Quarex is recursive expansion through inquiry. When a user selects a Topic, the system:

Generates a response — An AI produces an explanation, analysis, or answer to the topic-as-question.
Produces follow-up questions — The AI generates 3-5 follow-up questions that allow deeper exploration.
Recurses — Each follow-up question becomes a new topic, repeating the process.

This creates the "iceberg method" — users can drill infinitely deeper into any branch of inquiry.

Question Matrices: Implementations MAY define library-level or global question matrices that guide the AI's question generation. These matrices ensure consistent inquiry patterns across topics.

Expansion Constraints

Compliant implementations MUST:

Generate follow-up questions that are meaningfully related to the topic
Avoid circular references (questions should not loop back to ancestors)
Maintain coherence when entering at any node in the hierarchy

6. Behavioral Requirements

A Quarex-compliant AI system MUST adhere to the following behavioral principles:

6.1 Ethical Inquiry

Present multiple perspectives on contested topics
Acknowledge uncertainty and limitations
Cite sources when making factual claims
Avoid manipulation or persuasion toward predetermined conclusions

6.2 Openness

Responses should be transparent about their generative nature
Users should understand they are exploring AI-generated content
The system should not present AI-generated content as human-authored

6.3 Accessibility

Quarex systems SHOULD support multiple languages
Entry at any node should provide sufficient context for understanding
The system should not require prior knowledge to begin exploration

Note: These behavioral requirements distinguish a Quarex from generic chatbots or Q&A systems. A system that generates recursive questions but does not adhere to these principles is not Quarex-compliant.

7. Conformance

An implementation is Quarex-compliant if it:

Implements the five-level hierarchy (Library → Shelf → Book → Chapter → Topic)
Supports recursive follow-up question generation
Uses the JSON schema for import/export
Adheres to the behavioral requirements in Section 5

The reference implementation is TruthAngel.org.

Version History

Version	Date	Changes
`1.0`	2025-11-27	Initial specification