Agentic OS Architecture

1. Executive Summary

SwarmAI is a desktop application that wraps Claude's Agent SDK inside a harness — a structured layer of context management, persistent memory, self-evolution, and safety controls that transforms a stateless large language model into a persistent, evolving personal AI agent.

The core thesis is simple: most AI tools reset when you close them. Context is lost, decisions are forgotten, and users re-explain the same things session after session. SwarmAI solves this structurally, not through fine-tuning but through engineered knowledge persistence.

Key Metrics (as of March 2026)

2. Architecture Overview

2.1 Six-Layer Architecture

SwarmAI's architecture is organized into six horizontal layers. Each layer has a clear responsibility boundary and communicates with adjacent layers through well-defined interfaces. The Harness layer (Layer 3) is the core innovation — it is what differentiates SwarmAI from a simple LLM wrapper.

2.2 The Compound Loop

The defining characteristic of SwarmAI's architecture is the compound loop — a feedback cycle where every session's output becomes the next session's input:

1. Session executes — user interacts with the agent, decisions are made, code is written, files are created
2. Hooks fire — 7 post-session hooks automatically capture: DailyActivity (raw logs), auto-commit (workspace changes), distillation (promote to memory), evolution (skill/correction updates), context-health (validate integrity), improvement (DDD writeback), evolution-trigger (gap detection)
3. Memory updates — DailyActivity files accumulate; when ≥3 unprocessed files exist, distillation promotes recurring themes, key decisions, and corrections to MEMORY.md
4. Context enriched — next session's system prompt is assembled from the updated 11-file chain, now containing the latest memory, evolution state, and project context
5. Agent is smarter — the next session starts with full awareness of everything that happened, mistakes to avoid, and capabilities to leverage

3. The Harness — Core Innovation

The Harness is what makes SwarmAI more than a ChatGPT wrapper. It is a structured layer of engineering between the user interface and the raw LLM that provides four critical capabilities: context continuity, memory persistence, self-improvement, and safety. Without the Harness, Claude is a stateless function. With it, Claude becomes a persistent, evolving agent that compounds value across sessions.

3.1 Context Engineering

Most AI tools assemble a single system prompt and send it with every request. SwarmAI maintains an 11-file priority chain (P0–P10) that is assembled, cached, and budget-managed through a multi-stage pipeline. This is the most token-intensive subsystem and the one with the highest impact on agent quality.

Priority Chain

Assembly Pipeline

1. ContextDirectoryLoader.ensure_directory() — provisions/updates .context/ files from source templates
2. ContextDirectoryLoader.load_all() — L1 cache check (git-first freshness), assemble from sources if stale
3. PromptBuilder.build_system_prompt() — adds BOOTSTRAP.md, DailyActivity (today + yesterday), session briefing, metadata
4. SystemPromptBuilder.build() — adds identity, safety rules, workspace info, datetime, runtime context
5. Token Budget Engine — enforces budget (100K tokens for 1M context models), truncates P10–P3 as needed, never touches P0–P2

Key Design Decisions

• Session-type-aware loading — Channel DMs skip EVOLUTION.md, PROJECTS.md, DailyActivity, and briefing (~9K tokens / 30% savings for quick exchanges)
• L0/L1 cache — L1 uses git-first freshness (falls back to mtime); L0 is an AI-summarized compact version for constrained models
• Head-trimming for agent-owned files — MEMORY.md and EVOLUTION.md keep the newest content; old entries trim from the top. This ensures recent context always wins.

3.2 Memory Pipeline

The memory pipeline is a three-layer distillation system that converts raw session activity into durable, curated knowledge. It solves the fundamental problem of AI amnesia: without this pipeline, every session starts from zero.

Three Layers

Git Cross-Reference

This is a critical safety mechanism born from a real Sev-2 incident (COE C005). The distillation hook verifies all implementation claims against git log before promoting them to MEMORY.md. Without this, a mid-session DailyActivity snapshot captured before later commits can create false memories that compound across sessions. Claims that fail verification are tagged [UNVERIFIED] rather than promoted as fact.

Weekly LLM Maintenance

A scheduled background job (self-tune) performs weekly maintenance: prune resolved Open Threads, archive stale Recent Context entries (>30 days), verify Key Decisions still reflect reality. This prevents memory bloat and ensures the agent's knowledge stays current.

3.3 Self-Evolution

Self-evolution is the capability that makes SwarmAI get better over time. When the agent encounters a capability gap, it doesn't just fail — it can build a new skill, test it, and register it for future sessions. When the user corrects a mistake, the correction is captured permanently so the same class of error never recurs.

EVOLUTION.md Registry

The persistent registry tracks five categories of evolutionary data:

Gap Detection (Reactive + Proactive)

• Reactive: s_self-evolution skill (always-active) detects capability gaps in real-time during sessions, orchestrates up to 3 build attempts
• Proactive: Weekly maintenance scans DailyActivity for recurring error patterns and surfaces them in session briefings as capability gaps to address

3.4 Safety & Self-Harness

Safety is not a feature — it is a structural property of the architecture. SwarmAI implements defense-in-depth through multiple independent safety layers:

The Self-Harness subsystem (context_health_hook.py) performs continuous validation: checking that all 11 context files exist and parse correctly, detecting DDD document staleness, auto-refreshing KNOWLEDGE.md and PROJECTS.md indexes, and auto-committing workspace changes.

4. Intelligence Layer

The Intelligence layer sits above the Harness and provides proactive awareness, autonomous execution capabilities, and background automation. While the Harness ensures the agent remembers and improves, the Intelligence layer ensures it anticipates, acts, and automates.

4.1 Autonomous Pipeline

The autonomous pipeline drives the full development lifecycle from a one-sentence requirement to a PR-ready delivery. It is the implementation of AIDLC Phase 3 (AI-Management) where AI makes autonomous decisions and humans step in only when needed.

Eight Stages

Methodology Stack: DDD + SDD + TDD

Three methodologies form a closed loop: DDD (4 project documents) provides autonomous judgment — "should we build this?". SDD (design doc with acceptance criteria) produces specs — "here's exactly what to build". TDD (tests before code) verifies delivery — "proof we built it correctly". The key insight: when no human reviews every line, the test suite IS the quality gate.

4.2 Proactive Intelligence

The proactive intelligence subsystem (1,142 lines, 106+ tests) provides session-start briefings and suggestions through four levels of analysis:

4.3 Job System

The job system provides background automation that runs independently of chat sessions. Jobs are scheduled via macOS launchd and execute as headless Claude CLI processes with full MCP tool access.

• System jobs (read-only): self-tune, signal-fetch, signal-digest — maintain the agent's autonomous capabilities
• User jobs (configurable): morning inbox triage, weekly summaries, monitoring — defined in user-jobs.yaml
• Job types: agent (headless Claude), signal (fetch/digest pipeline), script (arbitrary command)

5. Session Architecture

The session layer manages the lifecycle of Claude subprocess instances. It replaced a monolithic AgentManager (5,428 lines) with four focused components during the v7 re-architecture in March 2026. The decomposition was driven by a real need: supporting parallel chat tabs and dedicated channel slots without resource exhaustion.

5.1 Multi-Tab Parallel Sessions

Four Components

Key Invariants

• Protected states (STREAMING, WAITING_INPUT) are never evicted
• Subprocess spawn serialized via module-level _spawn_lock + _env_lock
• Retry uses --resume flag to restore conversation context across crashes
• Hooks fire via BackgroundHookExecutor — never block the request path
• One dedicated slot always reserved for channels (min_tabs = 2)

5.2 Swarm Brain — Multi-Channel

The Swarm Brain architecture ensures that regardless of which channel the user communicates through — desktop chat tab, Slack, or future platforms — it is always the same Swarm, same memory, same context.

Three Layers of Continuity

Adding a new channel: Write an adapter (~250 lines implementing ChannelAdapterBase), register in the gateway, map user identity. Zero architecture change required.

6. Interface Layer

6.1 Three-Column Command Center

The interface is designed as a single integrated system where the Chat Center orchestrates everything. The three columns are not independent panels — they are views into one unified workspace connected by drag-to-chat context injection.

7. Core Engine & Growth Trajectory

The Swarm Core Engine is the meta-architecture that ties all six flywheels together. Each flywheel feeds the others, creating compound growth: memory informs context, context improves sessions, sessions trigger evolution, evolution builds skills, skills improve memory capture, and the cycle continues.

Growth Trajectory

8. Key Design Decisions & Tradeoffs

9. Competitive Positioning

SwarmAI occupies a unique position in the AI tooling landscape: it is not a code editor (Cursor/Windsurf), not an IDE (Kiro), not a CLI agent (Claude Code), and not a multi-platform connector (OpenClaw). It is an agentic operating system that optimizes for depth over breadth.

10. Future Roadmap