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

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)

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.