# SwarmAI turns recurring mistakes into code gates instead of logged lessons

> An operating system around a model rather than a bigger model, built on four ideas: a mistake that recurs becomes a path the code refuses, every project gets the same six section brain, knowledge that stops being referenced is retired, and hooks run between sessions so the next one starts warm. The desktop application is treated as a body the agent senses and drives, and that body is inspectable while it moves.

**xg-gh-25/SwarmAI** — A self-evolving Agent OS — every interaction sharpens how it judges, not just what it knows. Four ideas: self-evolution (mistakes become code gates, not logged lessons), brain-first domain brains that grow and decay, cognition that persists between sessions, and proprioception — it senses and drives its own body. Human directs. AI delivers.

- Repository: https://github.com/xg-gh-25/SwarmAI
- Website: https://github.com/xg-gh-25
- Stars: 55 · Forks: 7
- Language: Python
- License: MIT
- Published: 2026-08-21 · Updated: 2026-08-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/xg-gh-25-swarmai

## A recurring mistake becomes a path the code refuses

The central claim is a distinction between two kinds of memory. Most agent memory projects pile up entries: something went wrong, here is a note about it. This project argues that a note changes almost nothing, because it lives in the knowledge layer, and that one edited line in the operating system's own file shifts behaviour more than a thousand such rows do. The line that matters is that a recurring mistake should not become one more logged lesson but a gate, meaning a place in the code where the wrong move cannot happen. The documentation is pointed about whether this is real: it points at the hook file and says a dozen or so guards are already live in it, naming a commit gate, a test guard and a dangerous command gate. The measure of progress is not a growing count of corrections. It is an error class that stops recurring.

## One brain structure for a code repo, a research topic or a wedding

The second idea is called brain first, and it is a single structure applied uniformly. Every project gets a brain with six sections, and the sections are the same for everybody: identity, knowledge, gates, capabilities, delivery, and a refresher. What varies is only what the brain governs, and the range of that is deliberately wide. It can hold no assets at all, or any number of assets of any kind. A code repository, a data source, a document collection, a process, and the documentation gives the example of a consultant's client and then, deliberately more absurdly, someone's wedding. If that reads as a gimmick, the design point is that a structure general enough to hold a wedding is also general enough to hold a codebase, and you do not learn two systems. Knowledge settles into the brain as you work inside it.

## Knowledge is supposed to retire, which is the opposite of most memory

The most counter-intuitive idea here is elimination. A typical memory system only appends, and the documentation says plainly that accumulation without elimination is how every memory system rots. Here, knowledge that stops mattering decays and dies, and the design philosophy section states the principle as a numbered rule: knowledge must eliminate itself, unreferenced knowledge retires, and a system that can forget beats one that can only remember. The machinery is described as a cultivation engine with a seven type by three layer ontology and what the documentation calls Darwinian decay, running on a schedule rather than on demand. That scheduling detail matters. If retirement only ran when you thought about it, the knowledge base would grow between cleanups. Running it on a timer is what makes forgetting a property of the system rather than a chore you have to remember.

## Hooks fire between sessions so the next one starts warm

The third idea is that cognition should not live inside a session. Sessions are described as discontinuous while intelligence should not be, and the mechanism is hooks that run between them. There is a whole engine row for this, listing between session hooks plus background intelligence, with the summary that sessions never cold start. Two other behaviours come from the same place. The system self heals when a session breaks, and that engine's row is written to stress that recovery is invisible: sensors, automatic respawn, the user sees nothing. And each system prompt is rebuilt fresh from the governed context files rather than reused, which is what lets the tiered ownership model in the context engine actually mean something. The architecture diagram puts this in the bottom layer with sessions and jobs, below the knowledge layer, which tells you it is infrastructure rather than a feature.

## The desktop application is a body the agent drives and reads back

The fourth idea is called proprioception, and it is the one that makes this project different from a chat wrapper. The desktop application is not a front end the agent talks to, it is a body it senses and drives. The system reads its own live interface state, meaning which overlay is open, which tab is active, what is on its canvas, and then acts on that: it opens its own interface, pushes a report onto the canvas, and flags a decision to your attention channel. The response goes the other way too, through a feature named thread scoped cognitive context, which shows the actual cognition behind a turn: which files were loaded, what the token budget was, every recall hit and its score, the security scan, and the full prompt. The contrast the documentation draws is with agents that are black boxes you send text to. Here you watch the body move and inspect it while it does.

## Ten engines, and the loop claims to be load bearing

The engine table lists ten components, and three of them are documented while the rest are pointed at directly, on the stated principle that the implementation is the documentation. The three layers of the architecture diagram are delivery engines on top, a knowledge layer in the middle, and an agent harness at the bottom. Memory runs a tiered persistence path from daily activity through distillation to compound recall, using full text and ranking over a plain filesystem rather than a database. The context engine manages prompts from governed files with tiered ownership and a budget measured live. Evaluation is decoupled and system level, with a golden set and a regression gate bound to version control. And then there is the compound loop, which is given as an explicit chain and an explicit warning: remove one link and the rest weaken.

```
DELIVERY ENGINES        Pipeline · Pollinate · Eval
KNOWLEDGE LAYER         DDD (brains) · Memory · Evolution
AGENT HARNESS           Context · Sessions · Hooks · Jobs
```

## The delivery engine takes one requirement and returns pushed code

The delivery engines are three siblings built on the same pattern. The pipeline is described as one requirement in and push ready code out, with a stated shape of nine stages, three gates and two modes. A separate content engine takes one message and produces multi format content, and the documentation notes it uses the same domain driven pattern, applied to media instead of code. Evaluation is the third, and it is described as decoupled from both so that the output of one can be judged by the other. The philosophy section explains why the pipeline is shaped that way: the claim is that one shot qualified delivery is the real token optimization, because a cheap model iterating five times costs more than one correct pass, and code is treated as a black box from input to qualified output. Division of labor is explicitly called a workaround for limited human bandwidth rather than good design.

## The root package manifest is empty and the real project is a directory down

A few things in the tree are worth knowing before you start. The package manifest at the repository root contains nothing at all, because the Node project is the desktop application one level down, and the quick start installs there. The stack needs five things and one of them is a specific command line agent tool rather than a model endpoint, which tells you this is a layer around an existing coding agent rather than a standalone runtime. There is a version file at the root and separate development and production shell scripts, so deployment is scripted rather than packaged. Security tooling has left its fingerprints in the tree: a secret scanning baseline file and baselines for two static analysis tools sit at the root, which means the security posture is enforced in continuous integration rather than described in prose. Two directories at the top level look like data stores rather than source, which is consistent with a system whose knowledge layer is on disk.

```
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
```

## Conclusion

Adopt this if your problem is that an agent repeats the same mistake across sessions, since a gate written into the hook file is the only intervention that actually prevents a repeat rather than recording one. Do not adopt it expecting a distributed multi agent system, because the name is misleading and the requirements are a single agent command line tool. Three things to check first. That you are willing to run the desktop shell, since the body and its inspection surface are the point and there is no headless story here. That your recurring failures are of a kind you can express as a guard, because the whole mechanism assumes a check can be written. And that you accept a requirement list rather than a chat interface, since the delivery engine is built around turning one stated requirement into pushed code.

## FAQ

### What does swarm AI do?

This project is not a distributed swarm and does not run many agents in parallel. It is an operating system around a single coding agent, in which recurring mistakes become guards written into a code file, each project holds a structured brain whose unreferenced knowledge retires on a schedule, and hooks run between sessions so a new session does not start cold.

### what is swarm ai

A self evolving agent operating system, released under the MIT licence and written mainly in Python with a desktop shell. It separates the operating system's own judgement from stored knowledge, rebuilds each system prompt from governed files, and adds a pipeline engine that takes one requirement through nine stages and three gates to produce code ready to push.

### how to install swarm ai

Clone the repository, then install the backend dependencies with the Python package manager and copy the environment example to add your API key, then install the desktop dependencies and run its development mode command. The requirements are Node 18 or newer, Python 3.11 or newer, Rust, the package manager itself, and a specific agent command line tool.

### swarm ai vs comfyui

The page contains no comparison with any other project and does not mention that one. What it does say about itself is that it is the layer around a model rather than a model, that a session is warm when it starts because hooks ran in between, and that the desktop application is a body the agent both drives and can be inspected through.

## Sources

- [Official documentation](https://github.com/xg-gh-25)
- [Official README](https://github.com/xg-gh-25/SwarmAI#readme)
- [Project repository](https://github.com/xg-gh-25/SwarmAI)
- [Release notes](https://github.com/xg-gh-25/SwarmAI/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xg-gh-25-swarmai