Architecture Overview

Tier 2 Hub | Load for architecture understanding Full Details: ARCHITECTURE.md

Quick Navigation

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    External Interfaces                       │
│   MCP Server │ REST API │ Standalone CLI                    │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                  Orchestration Layer                         │
│   Orchestrator │ Expert Pool │ Event Bus │ Consensus Engine │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                    Execution Layer                           │
│   CLI Adapters │ Model APIs │ Workflow Engine               │
└─────────────────────────────────────────────────────────────┘

Core Components

Agent System

The agent framework provides:

• Orchestrator: Orchestrates expert pool, delegates tasks
• Experts: Specialized domain agents (Code, Security, Architecture, etc.)
• State Machine: idle → thinking → acting → waiting → error

interface IAgent {
  readonly id: string;
  readonly role: AgentRole;
  readonly state: AgentState;
  execute(task: Task): Promise<Result<TaskResult, AgentError>>;
}

Memory System

7-type memory architecture (MIRIX-inspired):

• Core: Agent identity and constraints
• Episodic: Task experiences
• Semantic: Domain knowledge
• Procedural: Skills and workflows
• Resource: External references
• Vault: Cross-session persistence
• Belief: Hindsight belief memory for reasoning (arXiv:2512.12818)

Routing System

CompositeRouter pipeline for intelligent model selection:

Task → BudgetRouter → ZeroRouter → PreferenceRouter → TopsisRouter → LinUCB → Decision

• Budget constraints (tokens, cost, latency)
• Multi-criteria ranking (quality vs cost)
• Contextual learning from outcomes

Adapter Layers

Two adapter layers serve distinct purposes:

These are sequential, not parallel: CompositeRouter selects a CLI → CLI adapter executes the subprocess → response is returned. When model-layer semantics are needed, CliToModelAdapter bridges ICliAdapter → IModelAdapter.

• ResilientAdapter wraps API adapters with lazy init and circuit-breaker failover
• CliCircuitBreaker provides subprocess-level resilience for CLI adapters
• CompositeRouter chains routing stages: Budget → ZeroRouter → Preference → TOPSIS → LinUCB

Consensus Protocols

6 core voting algorithms for multi-agent decisions:

• simple_majority: >50% approval threshold
• supermajority: ≥67% approval threshold
• unanimous: 100% approval required
• proof_of_learning: Weighted by agent performance
• higher_order: Bayesian-optimal aggregation with correlation awareness
• opinion_wise: Opinion-based aggregation

Key Design Decisions

Hybrid Architecture (ADR-001)

Decision: Combine MCP Gateway + Internal Event Bus + Standalone CLI Rationale: Enables Claude CLI integration, peer-to-peer agent coordination, and CI/CD pipelines

Zero-Credential Pattern (ADR-002)

Decision: OAuth for all CLI adapters, no stored credentials Rationale: Security-first, delegates auth to CLI tools

Result<T,E> Error Handling (ADR-003)

Decision: Explicit error types over exceptions Rationale: Type-safe error handling, exhaustive matching

File Map

packages/nexus-agents/src/
├── agents/
│   ├── tech-lead/         # Orchestration
│   ├── experts/           # Domain experts
│   ├── collaboration/     # Consensus protocols
│   └── self-improving/    # SICA implementation
├── cli-adapters/          # External CLI integration
├── context/               # Memory management
├── consensus/             # Voting protocols
├── mcp/                   # MCP server
├── swe-bench/             # SWE-Bench evaluation harness
└── observability/         # Metrics, tracing

Related Documents

• Full Architecture: ARCHITECTURE.md
• Coding Standards: CODING_STANDARDS.md
• Research Index: RESEARCH_INDEX.md
• API Reference: ENTRYPOINTS.md