Vitruvyan — Epistemic Operating System

What Is Vitruvyan?

Vitruvyan is a modular cognitive architecture for building AI systems that can perceive, reason, remember, communicate, and self-govern. It is not an application — it is the substrate on which domain-specific intelligent agents are built.

Note (Feb 14, 2026): this page is an architectural overview. Some parts describe design intent (target), while others reflect current runtime. For the most precise “what is active today”, use docs/foundational/VITRUVYAN_PIPELINE_WALKTHROUGH.md.

Think of it this way:

• Linux is an operating system for hardware. It provides processes, memory management, filesystems, and IPC — but knows nothing about what applications you run on it.
• Vitruvyan is an operating system for cognition. It provides perception, memory, reasoning, discourse, and truth governance — but knows nothing about the domain you apply it to.

The first domain specialization (codename Mercator) is financial analysis. But the architecture is deliberately domain-agnostic: the same modules could power a medical diagnostic advisor, a legal research agent, or an industrial monitoring system.

Architecture at a Glance

graph TB
    subgraph PERCEPTION["🔭 PERCEPTION — Babel Gardens · Codex Hunters · Pattern Weavers"]
        direction TB
        TRACKER["Tracker<br/><i>multi-source data collection</i>"]
        RESTORER["Restorer<br/><i>dedup, clean, normalize</i>"]
        BINDER["Binder<br/><i>dual-write PostgreSQL + Qdrant</i>"]
        SCRIBE["Scribe<br/><i>derived indicators</i>"]
        CARTOGRAPHER["Cartographer<br/><i>consistency audits</i>"]
        LEADER["Expedition Leader<br/><i>coordination</i>"]
        WEAVERS_P["Pattern Weavers<br/><i>ontology resolution</i>"]
 
        TRACKER --> RESTORER --> BINDER
        BINDER --> SCRIBE
        BINDER --> CARTOGRAPHER
        LEADER -.->|orchestrates| TRACKER
    end
 
    subgraph MEMORY["🧠 MEMORY — Memory Orders · Vault Keepers"]
        direction TB
        PG[("PostgreSQL<br/><i>relational truth</i>")]
        QD[("Qdrant<br/><i>semantic vectors</i>")]
        PGA[PostgresAgent]
        QDA[QdrantAgent]
        MO["Memory Orders<br/><i>sync & coherence</i>"]
 
        PGA --> PG
        QDA --> QD
        MO -.->|reconciles| PG
        MO -.->|reconciles| QD
    end
 
    subgraph REASON["⚙️ REASON — Neural Engine"]
        direction TB
        NE["Neural Engine<br/><i>factor evaluation<br/>normalize → aggregate → rank</i><br/>(vertical hook: EXEC_DOMAIN)"]
        PLAST["Plasticity<br/><i>bounded adaptation</i>"]
    end
 
    subgraph DISCOURSE["💬 DISCOURSE — Conversational Layer"]
        direction TB
        BABEL["Babel Gardens<br/><i>semantic fusion<br/>sentiment · embeddings<br/>84 languages</i>"]
        WEAVERS["Pattern Weavers<br/><i>contextual enrichment<br/>vague → structured</i>"]
        VEE["VEE<br/><i>3-level explainability</i>"]
        CAN["CAN Node<br/><i>conversational response</i>"]
    end
 
    subgraph TRUTH["🛡️ TRUTH — Orthodoxy Wardens"]
        direction TB
        ORTHO["Orthodoxy Wardens<br/><i>epistemic validation</i>"]
        VAULT["Vault Keepers<br/><i>immutable archive</i>"]
    end
 
    subgraph BUS["🔴 Cognitive Bus — Synaptic Conclave"]
        direction LR
        REDIS["Redis Streams<br/><i>durable · ordered · causal</i>"]
    end
 
    subgraph ORCHESTRATION["🎯 LangGraph — Central Nervous System"]
        direction LR
        GRAPH["StateGraph<br/><i>19 nodes (full graph) · ~80 state fields<br/>conditional routing</i>"]
    end
 
    %% Data flows
    PERCEPTION -->|raw data| BUS
    BUS -->|events| DISCOURSE
    BUS -->|events| MEMORY
    BUS -->|events| TRUTH
 
    GRAPH -->|REST API| PERCEPTION
    GRAPH -->|REST API| REASON
    GRAPH -->|REST API| DISCOURSE
    GRAPH -->|state passed| TRUTH
 
    MEMORY ---|canonical access| PERCEPTION
    MEMORY ---|canonical access| REASON
    MEMORY ---|canonical access| DISCOURSE
 
    %% Styling
    style PERCEPTION fill:#1a365d,stroke:#2b6cb0,color:#fff
    style MEMORY fill:#2d3748,stroke:#4a5568,color:#fff
    style REASON fill:#553c9a,stroke:#6b46c1,color:#fff
    style DISCOURSE fill:#2c5282,stroke:#3182ce,color:#fff
    style TRUTH fill:#742a2a,stroke:#c53030,color:#fff
    style BUS fill:#c53030,stroke:#e53e3e,color:#fff
    style ORCHESTRATION fill:#2f855a,stroke:#38a169,color:#fff

The Five Sacred Orders

Vitruvyan organizes all components into five epistemic orders — each responsible for a distinct cognitive function. This is not just labeling; it is an architectural constraint: modules respect their order's boundaries, and cross-order communication follows strict protocols.

1. Perception — "What is out there?"

Codex Hunters are a team of specialized agents that collect, clean, and persist data:

2. Memory — "What do I already know?"

Two canonical storage systems with mandatory access patterns:

• PostgreSQL — Relational source of truth. Accessed exclusively through PostgresAgent. Direct psycopg2.connect() calls are forbidden.
• Qdrant — Vector semantic memory (384-dim embeddings). Accessed exclusively through QdrantAgent. Every point must carry a valid ISO 639-1 language tag — the agent rejects null, unknown, or auto.
• Memory Orders — A reconciliation service that keeps PostgreSQL and Qdrant in sync (drift monitoring, periodic sync).

3. Reason — "What can I deduce?"

• Neural Engine — A domain-agnostic evaluation substrate. Defines three abstract contracts:

  • AbstractFactor: computes a signal for an entity (e.g., momentum, risk, quality)
  • NormalizerStrategy: makes heterogeneous values comparable (z-score, rank, min-max)
  • AggregationProfile: weights factors into a composite score

  The EvaluationOrchestrator executes the pipeline: compute → normalize (cross-entity) → aggregate → package. The core knows nothing about what an "entity" or "factor" means in your domain — that knowledge lives in verticals.

• Execution wiring note (runtime): the LangGraph exec step in core is currently domain-neutral (a stub/passthrough). A vertical is expected to provide the domain execution hook (e.g., call Neural Engine, tools, or a domain service) and/or enable the MCP dispatcher path.

• Plasticity — Bounded adaptive learning. System parameters (thresholds, weights) can evolve, but within structural limits with full audit trail. Not unsupervised ML — governed adaptation.

4. Discourse — "How do I explain this?"

• Babel Gardens — Multilingual semantic fusion engine (84 languages). Combines multiple AI models (FinBERT, Gemma, MiniLM) into unified semantic representations. Handles sentiment analysis, language detection, and embedding generation through a single API.

• Pattern Weavers — Contextual enrichment via vector search. Transforms vague human queries into structured context: "analyze European banks" becomes {concepts: ["Banking"], regions: ["Europe"], countries: [IT, FR, DE...]}. Reduces conversational friction by 50-66%.

  Note: Pattern Weavers is architecturally a Perception Sacred Order (ontology resolution via taxonomy matching), but appears in the Discourse layer during conversational understanding. This dual-use reflects its role: pure semantic mapping (Perception) applied to conversational enrichment (Discourse).

• VEE (Vitruvyan Explainability Engine) — Three-level narrative generation:

  1. Summary: Plain language, zero jargon
  2. Detailed: Operational depth, strategy implications
  3. Technical: Raw scores, factor convergence, full transparency

• CAN (Conversational Agent Node) — Generates natural-language responses with anti-hallucination validation via MCP bridge.

5. Truth — "Is this correct? Is it coherent?"

• Orthodoxy Wardens — Every output is validated before reaching the user. Verdicts: blessed (clean), purified (corrected with warnings), heretical (rejected).
• Vault Keepers — Immutable versioned archive of significant events. The governance layer can emit archival directives that include a blockchain destination, but chain anchoring is an optional/vertical-specific integration (not guaranteed by the core runtime).

Note: Sentinel (risk monitoring) is a finance vertical extension, not part of the domain-agnostic core V1.0. See Appendix D for vertical-specific governance patterns.

The Cognitive Bus (Synaptic Conclave)

The nervous system that connects all orders. Built on Redis Streams with durable, ordered, causally-linked delivery.

Bio-inspired design:

• Modeled after the octopus nervous system: 2/3 of neurons reside in the arms (local autonomy), only 1/3 in the brain (minimal governance)
• Modeled after fungal mycelial networks: no central processor, emergent routing, topological resilience

Four sacred invariants — the bus is deliberately unintelligent:

1. Never inspects payloads
2. Never correlates events
3. Never performs semantic routing
4. Never synthesizes or transforms data

Intelligence belongs in consumers, not the network.

Communication pattern:

Publisher → Herald.publish("channel.name", event_data)
               │
               ▼
         Redis Streams (durable, ordered)
               │
               ▼
Consumer ← StreamBus.consume("channel.name", group, consumer_id)
               │
               ▼
         bus.acknowledge(event)  ← mandatory

Events use dot notation (codex.discovery.mapped, babel.sentiment.fused) and carry: event_id, event_type, causation_id (optional, for causal chains), timestamp, data, metadata.

LangGraph — The Orchestrator

A StateGraph manages the full cognitive pipeline.

Current runtime (Feb 14, 2026):

• Full graph: 19 nodes
• Minimal graph: 4 nodes (feature-flagged)

graph LR
    A[parse] --> B["intent<br/>detection"]
    B --> C["pattern<br/>weavers"]
    C --> D["entity<br/>resolver"]
    D --> E["babel<br/>emotion"]
    E --> F["semantic<br/>grounding"]
    F --> G["params<br/>extraction"]
    G --> H{decide}
 
    H -->|exec| I[exec]
    H -->|qdrant| J[qdrant]
    H -->|llm_soft| K[llm_soft]
    H -->|codex| M["codex<br/>hunters"]
    H -->|mcp| N[llm_mcp]
 
    I --> O["output<br/>normalizer"]
    J --> O
    K --> O
    M -.->|error| O
    N --> O
 
    O --> P["orthodoxy<br/>wardens"]
    P --> Q["vault<br/>keepers"]
    H -->|slot_filler| R[compose]
    Q --> R
    R --> S[CAN]
    S --> T((END))
 
    style H fill:#e53e3e,stroke:#c53030,color:#fff
    style T fill:#2f855a,stroke:#276749,color:#fff

Key design decisions:

• Sacred Flow: analysis results pass through orthodoxy → vault → compose → CAN before reaching the user — every output is validated and archived
• Codex conditional routing (updated Dec 27, 2025): Codex Hunters success routes directly to END (background work bypass), but errors route through output_normalizer → Sacred Flow for governance validation
• Hook injection points (runtime): entity_resolver and exec are domain-agnostic and routed via registries (hook pattern). Without a configured vertical they degrade to stub behavior; with a vertical they execute domain logic.
• USE_MCP flag: can route execution through the MCP bridge for tool calling

How Services Communicate

Services never import each other's code. Three communication channels:

Each major service runs in its own Docker container on a shared network (vitruvyan_omni_net).

Domain Specialization: Verticals

The core framework is domain-agnostic. Verticals inject domain knowledge:

┌──────────────────────────────────────────────────┐
│              VITRUVYAN CORE                       │
│  Perception · Memory · Reason · Discourse · Truth │
│  ──────────────────────────────────────────────── │
│  Domain-agnostic substrate                        │
└──────────────────────┬───────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │ Mercator │ │ (future) │ │ (future) │
    │ Finance  │ │ Medical  │ │ Legal    │
    │          │ │          │ │          │
    │ Factors: │ │ Factors: │ │ Factors: │
    │ momentum │ │ BP risk  │ │ citation │
    │ trend    │ │ biomark. │ │ preceden │
    │ volatilit│ │ family h.│ │ jurisdic │
    │ sentim.  │ │ symptoms │ │ relevance│
    └──────────┘ └──────────┘ └──────────┘

A vertical provides:

• Factors for the Neural Engine (what to compute)
• Data sources for Codex Hunters (where to look)
• Weaving rules for Pattern Weavers (domain concepts and taxonomies)
• Narrative templates for VEE (how to explain results)
• Validation rules for Orthodoxy Wardens (domain-specific correctness)

The core never changes. The vertical plugs in.

Key Architectural Principles

Quick Reference: Service Map

TL;DR

Vitruvyan is a cognitive operating system that separates how to think from what to think about. Five epistemic orders (Perception, Memory, Reason, Discourse, Truth) communicate through a deliberately unintelligent event bus. A domain-neutral LangGraph pipeline orchestrates 19 nodes (full graph). Domain knowledge is injected through verticals, not hardcoded. Every output is validated, archived, and explainable at three depth levels.