Skip to content

Architecture

AEGIS is built in layers. Each layer has a defined scope, and nothing crosses the boundary without going through the interface designed for it.

The big picture

┌─────────────────────────────────────────────────────────────────────────┐
│                         AEGIS — Control Plane                           │
│                                                                         │
│          Orchestrator → Service Registry → Permission System            │
│              Module Loader ↔ Tool Manager ↔ Event Bus                   │
│                                                                         │
│   ┌──────────────────────────────────────────────────────────────────┐  │
│   │                       Cognitive Layer                            │  │
│   │       Engine Interface (think · plan · reason · embed …)         │  │
│   │  Engine Manager (hardware probe · capability scoring · failover) │  │
│   │        Memory (identity · goals · projects · relations)          │  │
│   │        Knowledge Graph                    Safety Layer           │  │
│   └──────────────────────────────────────────────────────────────────┘  │
│                                                                         │
│   ┌──────────────────────────────────────────────────────────────────┐  │
│   │                   Execution Graph (DAG Engine)                   │  │
│   │               Compiler → Executor → State → Resume               │  │
│   └──────────────────────────────────────────────────────────────────┘  │
│                                                                         │
│            Agents ←→ Shared Services ←→ Modules ←→ API Gateway          │
└─────────────────────────────────────────────────────────────────────────┘
                                         │
                               Runtime Adapter Layer
                                         │
                        ┌────────────────┴────────────────┐
                        │   Odysseus (initial runtime)    │   ← separate process,
                        │   Ollama · OpenAI · Anthropic   │     network boundary,
                        │   vLLM · Whisper · Vision …     │     fully replaceable
                        └─────────────────────────────────┘
AEGIS System Architecture — layer stack diagram

Layer by layer

Control Plane (Phase 2)

The central nervous system. Five components work together to coordinate everything:

  • Orchestrator — intake, routing, and coordination. Every request enters here; nothing bypasses it.
  • Service Registry — the only place modules look up shared resources. Direct module-to-module calls are not allowed.
  • Permission System — every cross-component access is checked here before it happens.
  • Module Loader — handles the lifecycle of installable modules: load, validate, start, stop, unload.
  • Tool Manager — a unified registry of every tool available to any component in the system.
  • Event Bus — asynchronous communication between components without tight coupling.

Cognitive Layer (Phase 3)

How AEGIS thinks.

  • Engine Interface — a fixed vocabulary of capabilities: think, plan, summarize, extract_entities, classify, call_tools, stream, embed, transcribe, vision, speech. Every AI engine is accessed through this interface. Adapters translate; they never decide.
  • Engine Manager — at startup, probes your hardware (GPU, VRAM, RAM) and scores every available model as locally runnable, borderline, or cloud-only. Routes work to the best available engine for each capability, with automatic failover.
  • Memory — a multi-layer, persistent knowledge store: identity, goals, active projects, relationships, embeddings. Not a conversation log. Built with ask-before-store consent and versioned human-readable export.
  • Knowledge Graph — structured relationships between entities across memory layers.
  • Safety Layer — policy enforcement that runs before any engine call leaves the system.

Execution Graph / DAG Engine (Phase 4)

How AEGIS executes complex work.

All non-trivial execution runs as a Directed Acyclic Graph: a plan that can be compiled, executed step by step, persisted at any point, and resumed after interruption. If the system is shut down mid-task, it picks up exactly where it left off.

Agent System (Phase 5)

Autonomous workers that operate on the DAG engine: a base agent framework, eight role agents (Memory, Planner, Researcher, Teacher, Reviewer, Coach, Project Manager, Creativity), agent-to-agent messaging, and agents as DAG nodes.

Shared Services + API (Phase 6)

  • Shared Services — Document Vault, OCR, Knowledge Base (full-text search), Semantic Search, Notifications, Calendar, API Connectors, and universal Token Usage Tracking — available to any module through the Service Registry, never by direct import.
  • API Gateway — authenticated HTTP interface (fail-closed Bearer auth) with request telemetry, exposing usage, search, memory, and service-registry endpoints.

Web App (Phase 8)

A React app served by the API gateway itself — one process, one port, fail-closed key auth. Chat is agentic (the model can invoke module tools), with effort levels controlling reasoning depth, a model picker spanning cloud and local engines, persistent conversations, memory management, and cost/context instrumentation (daily token budget, window gauges). Built as a static bundle so the Phase 10 desktop/Android shells wrap it unchanged.

Module System (Phase 7)

  • Modules — installable/uninstallable departments and add-ins with validated manifests, loaded dynamically and permission-gated: a module can only reach services it declared. New capability arrives as a module; core never grows.
  • HEPHAESTUS — the guided module builder (ADR-0006). Interviews the user, or reads a description file, and generates a standard template-shaped module — validated, installed, and enabled through the same gates as hand-written ones.

Marketplace (Phase 9)

  • Registry — a module catalog in its own repository (ADR-0009), fetched over HTTPS with an offline cache. The Marketplace panel shows every module's requested permissions before any code is downloaded.
  • Safe install — consent-gated (ADR-0010): a plain-language review, SHA-256 integrity verification against the published catalog (tampered packages are refused outright), and a static code scan whose findings the user sees before approving.
  • Sandboxed execution — marketplace modules run in isolated worker processes (ADR-0011): no secrets in their environment, no memory access to AEGIS, service calls gated by the Permission System over a narrow channel, and file/network/subprocess guards inside the worker. A crashing or hanging module is killed; AEGIS keeps running.

Production Hardening (Phase 10)

  • CI — every push runs the full test suite on two OS/Python combinations, a compile gate, the web-app build, and a Docker image smoke test.
  • Observability — every API request carries a short tracing ID through all layers; a /metrics endpoint and System panel show uptime, latencies, memory, tokens, and log volume live.
  • Deployment + hardware profiles — docker compose up runs AEGIS anywhere, with state on persistent volumes. At startup AEGIS selects a capability profile (Edge / Standard / Workstation) from detected hardware (ADR-0012): the same kernel on a Raspberry Pi and a GPU server, with capacity — not architecture — changing.
  • Interview System — nine guided onboarding sessions that fill AEGIS's long-term memory; the identity layer always accompanies chat context.
  • Deterministic commands — "/" commands in the web app invoke module tools directly, with no LLM in the loop.

Desktop + Mobile Apps (Phase 11)

  • Desktop app (Tauri) — the Phase 8 React web app wrapped in a Rust-core native shell. Produces a Windows NSIS installer and a Linux AppImage/deb. The Tauri shell is ~10 MB; all UI logic is the same code as the browser build. Auto-update mechanism built in; CI builds Linux installers on every push to desktop/.
  • Android app (Capacitor) — the same web app wrapped for Android. Connects to a running AEGIS server on the local network (or over Tailscale). Same codebase as desktop and browser.
  • Voice layer — Whisper STT (cloud or local faster-whisper) + Piper neural TTS, echo-cancelled microphone, 8-second follow-up conversation window, spoken stop commands.
  • Wake word — Vosk local keyword model on desktop/web; Porcupine foreground service on Android (listens with screen off).
  • Memory Fabric — every memory gains entity extraction, explicit links (supports/contradicts/elaborates/supersedes), about-time, lifecycle, recall strength, pin, and confidence + provenance metadata.
  • Avatar presence — animated shield on the Dashboard (idle breathe, think pulse, speech throb); floating presence dock on every tab.

Design principles

Runtime isolation. No AI engine code lives in this repo. Engines run as separate processes behind the Cognitive Engine Interface. AEGIS speaks to them over a network API through adapters. Swap an engine, the system keeps running.

Modules never talk directly. All cross-module communication flows through the Service Registry or Orchestrator, gated by the Permission System. Isolation is enforced, not asked for.

Everything is a plugin. Modules, engines, services, and skills are versioned, installable, and replaceable. No component is load-bearing by identity — only by interface.

Memory is a first-class primitive. Not a feature, a system layer. Ask-before-store consent, selective retrieval, versioned export, and multi-layer structure are built in from the start.

Architecture Decision Records

The full rationale behind every major architectural choice is recorded in the repo's ADR directory. Key decisions:

ADR Decision
ADR-0001 Layered control-plane architecture — why wrap a runtime rather than rebuild from scratch
ADR-0002 Runtime boundary — Odysseus runs as a separate service; AEGIS never vendors its code
ADR-0003 Scaffold-and-replace — Odysseus as temporary scaffolding, retired capability by capability
ADR-0004 License — AGPL-3.0 chosen before first external contributor; dual-license path reserved
ADR-0005 Hardware-aware capability scoring — Engine Manager probes GPU/VRAM/RAM at startup
ADR-0006 HEPHAESTUS guided module builder — no-code module creation on top of the template (Phase 7)
ADR-0007 Projects as a scoping primitive — conversations and context grouped per project
ADR-0008 Complexity-scored auto-routing — model selection matches task complexity
ADR-0009 Marketplace registry — module catalog in its own repository (Phase 9)
ADR-0010 Install safety — consent gate + SHA-256 integrity + static code checks (Phase 9)
ADR-0011 Sandboxed execution — marketplace modules in isolated worker processes (Phase 9)
ADR-0012 Containers + hardware capability profiles — Compose primary, same kernel from Pi to server (Phase 10)

See the GitHub repository for the full ADR archive.