MINDSTACK_ARCH: QonQrete Brain Stack Architecture

This document provides a high-level architectural overview of the QonQrete brain stack, focusing on how skeletons, contexts, memories, and “briqs” (though briqs’ specific usage is still to be fully defined) are utilized by the orchestration layer and AI agents. The diagram below illustrates the flow and relationships between these components.

Architectural Diagram

graph TD
    subgraph "External World"
        USER[User Interaction] -- QONQ_WORKSPACE --> WQ(Worqspace Root)
        CODEBASE(Raw Codebase/Files) -- initial --> QY(qodeyard/)
    end

    subgraph "QonQrete Core Orchestration"
        Q(Qrane Orchestrator)
        PM[PathManager]
        LI[lib_ai]
    end

    subgraph "Knowledge / Memory Layers"
        BD[bloq.d (Structural Memory - Skeletons)]
        QD[qontext.d (Semantic Memory - Contexts)]
        RD[reqap.d/ (Operational Memory/Feedback)]
        TD[tasq.d/ (Current Task/Directive)]
        ED[exeq.d/ (Execution Summaries)]
        BRD[briq.d/ (Reusable Components?)]
    end

    subgraph "QonQrete Agents (worqer/)"
        QOM[Qompressor Agent]
        QON[Qontextor Agent]
        INST[Instruqtor Agent]
        CALQ[Calqulator Agent]
        CONST[Construqtor Agent]
        INSP[Inspeqtor Agent]
        GPT[LLM Provider - OpenAI/Gemini/DeepSeek/Qwen]
    end

    subgraph "External AI Providers"
        DS[DeepSeek Provider]
        OA[OpenAI Provider]
        GM[Gemini Provider]
        ANT[Anthropic Provider]
        QW[Qwen Provider]
    end


    QY -- processed by --> QOM
    QOM -- generates --> BD

    QY -- processed by (optionally compressed via QOM) --> QON
    QON -- queries --> GPT
    QON -- generates --> QD

    Q -- orchestrates agents --> INST
    Q -- orchestrates agents --> CALQ
    Q -- orchestrates agents --> CONST
    Q -- orchestrates agents --> INSP
    Q -- orchestrates agents --> QOM
    Q -- orchestrates agents --> QON

    INST -- task from --> TD
    CALQ -- uses --> BD & QD
    CONST -- uses --> BD & QD
    INSP -- assesses --> RD

    Q --- PM
    PM -- manages paths for --> QY, BD, QD, RD, TD, ED, BRD

    QOM -- structural input --> Q
    QON -- semantic input --> Q

    Q --- LI
    LI -- builds prompt for --> GPT
    LI -- integrates --> QD, BD, QONQ_PREVIOUS_LOG(Env Var), TD

    GPT -- via --> DS, OA, GM, ANT, QW

    INST, CALQ, CONST, INSP, QOM, QON -- generate output --> RD
    RD -- promotes to --> TD
    INST, CALQ, CONST, INSP, QOM, QON -- logs --> ED

    Q --- USER
    USER -- manual review/edit --> RD
    RD -- informs --> Q (via cheqpoint)

    click QY "https://github.com/qonqrete/qonqrete/tree/main/qodeyard" "Go to qodeyard folder"
    click BD "https://github.com/qonqrete/qonqrete/tree/main/bloq.d" "Go to bloq.d folder"
    click QD "https://github.com/qonqrete/qonqrete/tree/main/qontext.d" "Go to qontext.d folder"
    click RD "https://github.com/qonqrete/qonqrete/tree/main/reqap.d" "Go to reqap.d folder"
    click TD "https://github.com/qonqrete/qonqrete/tree/main/tasq.d" "Go to tasq.d folder"
    click ED "https://github.com/qonqrete/qonqrete/tree/main/exeq.d" "Go to exeq.d folder"
    click BRD "https://github.com/qonqrete/qonqrete/tree/main/briq.d" "Go to briq.d folder"

Explanation of Components

QonQrete Core Orchestration

Qrane Orchestrator (qrane.py): The central control unit. It manages the entire workflow, sequencing agent execution, handling “cheqpoints,” and interfacing with the user.
PathManager (qrane/paths.py): Provides a centralized way to manage all file paths within the worqspace, ensuring consistency and discoverability of knowledge artifacts.
lib_ai (worqer/lib_ai.py): The AI abstraction layer. It handles communication with various LLM providers, constructs rich prompts by integrating different context layers, and manages streaming responses.

Knowledge / Memory Layers

These are file-system based directories within the worqspace/ that store the system’s knowledge:

qodeyard/: The raw, unadulterated codebase or initial input files provided by the user. It’s the source of truth for all processing.
bloq.d/ (Structural Memory / Skeletons): Contains “qompressed” (skeletonized) code, representing the architectural structure of the codebase without implementation details. Generated by Qompressor.
qontext.d/ (Semantic Memory / Contexts): Stores AI-generated YAML summaries and structured semantic information about files (e.g., symbol definitions, purposes, dependencies). Generated by Qontextor.
reqap.d/ (Operational Memory / Feedback): Holds “reQap” files, which are assessments and outputs from previous agent runs. Used for feedback loops and human intervention.
tasq.d/ (Current Task / Directive): Contains the tasq.md files that specify the current objective and instructions for the agents in a given cycle. Typically derived from promoted reQaps.
exeq.d/ (Execution Summaries): Stores logs and summaries of agent executions, providing a historical record.
briq.d/ (Reusable Components): A placeholder for reusable code “briqs” or modules. Its exact usage and lifecycle are currently less defined but likely involves construqtor or other agents for generation and calqulator or inspeqtor for consumption.

QonQrete Agents (`worqer/`)

These are specialized Python scripts that perform specific tasks:

Qompressor Agent (qompressor.py): Responsible for code skeletonization, generating bloq.d from qodeyard.
Qontextor Agent (qontextor.py): Responsible for semantic indexing, generating qontext.d from qodeyard (potentially using bloq.d and LLMs).
Instruqtor Agent: Likely responsible for interpreting tasq.md and breaking it down into actionable steps for other agents.
Calqulator Agent: Implied to perform calculations or estimations, possibly using bloq.d and qontext.d.
Construqtor Agent: Implied to construct or generate code/configurations based on instructions, using the knowledge layers.
Inspeqtor Agent: Implied to inspect or review generated code/outputs, producing reQaps.

External AI Providers

This section represents the various Large Language Model APIs that lib_ai can interface with, including DeepSeek, OpenAI, Gemini, and Anthropic.

Workflow Summary

Initialization: The Qrane Orchestrator starts, reads config.yaml, and if qodeyard/ is present, it initiates a “warmup.”
Warmup: Qompressor processes qodeyard/ to create bloq.d (skeletons). Qontextor then processes qodeyard/ (leveraging bloq.d and LLMs via lib_ai) to create qontext.d (semantic contexts).
Cyclical Execution: In each cycle, Qrane retrieves the current tasq.md directive. It then orchestrates a sequence of agents (e.g., Instruqtor, Calqulator, Construqtor, Inspeqtor) based on pipeline_config.yaml.
Agent Interaction with LLMs: When an agent needs to use an LLM, it calls lib_ai.run_ai_completion. lib_ai constructs a rich prompt by combining the agent’s base prompt with relevant information from tasq.d, bloq.d, qontext.d, and the QONQ_PREVIOUS_LOG (operational memory). This prompt is sent to the configured LLM provider.
Feedback Loop: Agent outputs and assessments are captured in reqap.d. At cheqpoints, Qrane either autonomously promotes the reQap to form the next tasq.md or allows user intervention to review and edit it, closing the feedback loop.
Continuous Improvement: Qontextor also performs update scans, ensuring that the semantic context in qontext.d remains current with changes in qodeyard.

This architecture ensures that AI agents are provided with a structured, layered, and token-optimized understanding of the project, enabling them to operate more efficiently and effectively.