SwarmAI is a self-evolving Agent OS — every interaction sharpens how the system judges, not just what it knows.

Why an Agent OS

Every other AI tool starts each session from zero. SwarmAI doesn't — value compounds. A model answers; a mind persists: continuous across sessions, self-correcting, forgetting what stopped mattering, sharpening its judgment with use. Not a bigger model — the operating system around one.

The Four Ideas

Everything in SwarmAI serves one of four:

🧬 Self-Evolution — it upgrades its own judgment

Most agent-memory projects pile up entries. SwarmAI separates cognition (the OS) from knowledge (the disk): one edited line in SOUL.md shifts judgment more than a thousand memory rows — and every change is a git diff. A recurring mistake doesn't become one more logged lesson; it becomes a gate — a path where the wrong move can't happen. Not aspirational: a dozen-plus live guards sit in security_hooks.py (commit gate, pytest guard, dangerous-command gate). Read the file — the wrong move is blocked in code, not in a guideline. Progress isn't a growing correction count; it's an error class that stops recurring.

🧠 Brain-first — every project is a domain brain

A project isn't a folder of files — it's a brain with one six-section structure (Identity · Knowledge · Gates · Capabilities · Delivery · Refresher), the same for every user and domain. Only what it governs varies: 0..N assets of any kind — a code repo, a data source, a document corpus, a process, or nothing at all. A codebase, a research topic, a consultant's client, even "my wedding" get the same brain. Knowledge sediments in as you work; knowledge that stops mattering decays and dies. Accumulation without elimination is how every memory system rots.

⚙️ Agent OS — the cognition lives between sessions, not in them

Sessions are discontinuous; intelligence shouldn't be. Hooks fire between sessions so the next one starts warm. The system self-heals when a session breaks, cultivates and decays its knowledge on a schedule, and rebuilds each system prompt fresh from governed context files.

🖐️ Proprioception — it inhabits its body, not just answers through it

The desktop app isn't a frontend the agent talks to — it's a body it senses and drives. SwarmAI reads its own live UI state (which overlay is open, which tab is active, what's on the Canvas) and acts on it: opens its own Brain Hub, pushes a report onto the Canvas, flags a decision to your attention channel. It's inspectable in return — TSCC (Thread-Scoped Cognitive Context) shows the real cognition behind a turn: which files loaded, the token budget, every recall hit and its score, the security scan, the full prompt. Most agents are black boxes you send text to; this one has a body you watch move — and inspect while it does.

Quick Start

git clone https://github.com/xg-gh-25/SwarmAI.git && cd SwarmAI
cd backend && uv sync && cp .env.example .env   # edit with your API key
cd ../desktop && npm install && npm run tauri:dev

macOS (Apple Silicon): Or download .dmg from Releases

Requires: Node.js 18+, Python 3.11+, Rust, uv, Claude Code CLI

📖 Full setup guide: QUICK_START.md

Architecture

┌─────────────────────────────────────────────────────────────┐
│  DELIVERY ENGINES        Pipeline · Pollinate · Eval        │
├─────────────────────────────────────────────────────────────┤
│  KNOWLEDGE LAYER         DDD (brains) · Memory · Evolution  │
├─────────────────────────────────────────────────────────────┤
│  AGENT HARNESS           Context · Sessions · Hooks · Jobs  │
└─────────────────────────────────────────────────────────────┘

Each engine is independently useful; together they form the loop that makes the system sharper with use. (Click code to read the engine itself — the implementation is the documentation.)

The compound loop: Memory → Pipeline judgment → DDD brains → Evolution → Gates → Memory. Remove one, the rest weaken.

🤖 For AI Agents

Coding in this repo? Start with AGENTS.md — data flow, process topology, conventions, and invariants. It's the agent-facing entry point; this README is the human one.

Design Philosophy

1. One-shot qualified delivery is the real token optimization. Cheap models iterate 5×, costing more than one correct pass. Code and content are a black box: input → qualified output.
2. Division of labor is a workaround for limited human bandwidth, not good design. One agent, many roles, one knowledge layer. (Sub-agents for adversarial checks ≠ division of labor.)
3. Knowledge must eliminate itself. Darwinian decay: unreferenced knowledge retires. A system that can forget beats one that can only remember.
4. Evolution is cognitive patching, not data accumulation. We change rules you can git diff. "Thinks differently" ≠ "knows more."
5. Quality converges, not just improves. Error classes decrease monotonically. Carefulness doesn't scale; gates do.
6. Sessions are discontinuous. Intelligence shouldn't be. Hooks fire between sessions. It gets better through use, not updates.
7. If you can't measure it, you didn't build it. Eval + golden set + change-triggered regression, proven in git.

📖 Full thesis + case study: docs/THESIS.md

Stack

Tauri 2.0 (Rust) · React 19 · FastAPI · Claude Agent SDK + Bedrock · SQLite (WAL + FTS5)

Four-platform backend (compile-time isolation): macOS daemon (prebuilt .dmg) · Hive (EC2) · Windows · Linux (source-build).

Resources

MIT License