Content
# TopoSwarm
[](https://doi.org/10.5281/zenodo.18072858)
[](https://www.gnu.org/licenses/agpl-3.0)
**A micro-scale quaternionic toroidal swarm agent for tool-use reasoning.**
Trained in 3 epochs on ToolBench with low loss. The router is crystallised and can be extended to any tool domain — including offensive security via the [LazyOwn MCP](https://github.com/grisuno/LazyOwn) integration.
---
## Architecture
```
User prompt (NL)
│
▼
TopoSwarmModel (~2M params, d=64, 4 layers)
├── Quaternionic torus topology (4 angular × 2 radial nodes)
├── Spectral autoencoder bottleneck (function-call filter)
├── HRM fast/slow reasoning (L=action, H=strategy)
└── ACT halt (Hamilton-product norm confidence)
│
▼ (tool_name, tool_arg)
ToolRegistry ──→ real tool execution
│
▼
Pass-2 generation ──→ final NL answer
```
**Swarm**: `N=3` agent instances share weights but carry distinct Berry-phase offsets on the torus, producing specialisation across disjoint API subsets.
**Training**: Phase-0 kernel calibration → Phase-1 grokking-aware main training (kappa coherence) → Phase-2 annealing. Checkpoint: safetensors + JSON metadata.
---
## Files
| File | Purpose |
|---|---|
| `topo_swarm_agent.py` | Core model, training pipeline, `SwarmOrchestrator` |
| `toposwarm_infer.py` | Inference engine with built-in tools (weather, search, calc, datetime, translate, news) |
| `toposwarm_hybrid.py` | Router + external language backend (TinyStories / custom checkpoint) |
| `toposwarm_lazyown_orchestrator.py` | **LazyOwn MCP integration** — routes NL pentesting prompts to LazyOwn tools |
| `lazyown_dataset_generator.py` | Rich ToolBench-format dataset: 422 examples across all 80 LazyOwn tools |
| `toposwarm_continual_trainer.py` | **EWC + Experience Replay** continual learning — fine-tune without catastrophic forgetting |
| `skills/toposwarm.md` | Operator guide loaded as MCP context |
| `.claude/settings.json` | MCP server registration for Claude Code |
---
## Quick start
```bash
pip install torch safetensors tiktoken numpy
# Train (downloads ToolBench from HuggingFace, ~5M tokens, 3 epochs)
python topo_swarm_agent.py
# Inference
python toposwarm_infer.py --prompt "What is the weather in Santiago?"
python toposwarm_infer.py --prompt "Calculate 17 * 89 + 42"
python toposwarm_infer.py --list-tools
# Hybrid mode (TopoSwarm router + TinyStories language backend)
python toposwarm_hybrid.py --backend-type tinystories \
--backend-model roneneldan/TinyStories-33M \
--prompt "weather in Buenos Aires"
```
---
## LazyOwn MCP Orchestrator
TopoSwarm acts as the **AI router** for [LazyOwn](https://github.com/grisuno/LazyOwn)'s full pentesting framework, routing natural-language security goals to the correct LazyOwn tool automatically.
### Setup
```bash
# Clone LazyOwn next to toposwarm
git clone https://github.com/grisuno/LazyOwn.git ../../../LazyOwn
cd ../../../LazyOwn && pip install lupa # core dep
# Or point to your existing LazyOwn install
export LAZYOWN_DIR=/path/to/LazyOwn
```
### Usage
```bash
# Single prompt — keyword router (no GPU needed)
python toposwarm_lazyown_orchestrator.py \
--prompt "scan for open ports on 10.10.11.78" \
--no-model
# Full model inference (loads checkpoint)
python toposwarm_lazyown_orchestrator.py \
--prompt "analyze vulnerabilities on 10.10.11.78"
# List all 50+ registered LazyOwn tools
python toposwarm_lazyown_orchestrator.py --list-tools --no-model
# MCP stdio server for Claude Code / Claude Web
python toposwarm_lazyown_orchestrator.py --mcp
# Generate fine-tuning dataset (34 LazyOwn traces in ToolBench format)
python toposwarm_lazyown_orchestrator.py --gen-dataset
# Fine-tune router on LazyOwn traces (1 epoch, LR=3e-5)
python toposwarm_lazyown_orchestrator.py --finetune
```
### Routing examples
| Prompt | Routed tool | Argument |
|---|---|---|
| `scan for open ports on 10.10.11.78` | `lazyown_run_command` | `set rhost 10.10.11.78\nlazynmap` |
| `show collected credentials` | `lazyown_credentials` | — |
| `analyze vulnerabilities on target` | `lazyown_c2_vuln_analysis` | target |
| `what should be the next step?` | `lazyown_recommend_next` | — |
| `search for SMB exploitation techniques` | `lazyown_c2_search_agent` | query |
| `generate a sitrep` | `lazyown_campaign_sitrep` | — |
### LazyOwn tools covered
`lazyown_run_command` · `lazyown_set_config` · `lazyown_get_config` · `lazyown_list_modules` · `lazyown_get_beacons` · `lazyown_c2_command` · `lazyown_list_sessions` · `lazyown_c2_status` · `lazyown_add_target` · `lazyown_list_targets` · `lazyown_set_active_target` · `lazyown_run_agent` · `lazyown_agent_status` · `lazyown_agent_result` · `lazyown_list_agents` · `lazyown_c2_search_agent` · `lazyown_recommend_next` · `lazyown_phase_guide` · `lazyown_campaign_sitrep` · `lazyown_c2_vuln_analysis` · `lazyown_c2_redop` · `lazyown_c2_adversary` · `lazyown_poll_events` · `lazyown_ack_event` · `lazyown_add_rule` · `lazyown_list_event_rules` · `lazyown_heartbeat_status` · `lazyown_report_update` · `lazyown_campaign_lessons` · `lazyown_c2_notes` · `lazyown_credentials` · `lazyown_timeline` · `lazyown_auto_loop` · `lazyown_auto_populate` · `lazyown_session_init` · `lazyown_session_state` · `lazyown_llm_ask` · `lazyown_create_tool` · `lazyown_inject_objective` · `lazyown_next_objective` · `lazyown_read_prompt` · `lazyown_create_addon` · `lazyown_list_addons` · `lazyown_list_plugins` · `lazyown_read_session_file` · `lazyown_run_api` · `lazyown_c2_script` · `lazyown_policy_status` · `lazyown_command_help` · `lazyown_discover_commands`
### MCP config for Claude Code
Add to `.claude/settings.json`:
```json
{
"mcpServers": {
"toposwarm-lazyown": {
"command": "python",
"args": ["/path/to/toposwarm/toposwarm_lazyown_orchestrator.py", "--mcp"],
"env": {
"LAZYOWN_DIR": "/path/to/LazyOwn"
}
}
}
}
```
---
## Continual Learning — EWC + Experience Replay
The recommended way to fine-tune TopoSwarm on LazyOwn without losing ToolBench generalisation.
### Strategy
Two complementary techniques run together every training step:
| Technique | What it does | Why |
|---|---|---|
| **EWC** (Elastic Weight Consolidation) | Computes Fisher diagonal on ToolBench; adds quadratic penalty `λ/2·Σ F_i·(θ_i−θ*_i)²` | Anchors weights critical for weather/calc/search routing |
| **Experience Replay** | 20% of every batch = real ToolBench samples | Exact gradient signal from the original task distribution |
| **LR = 2e-5** | 15× lower than pretraining (3e-4) | Conservative updates preserve existing representations |
### Quick start
```bash
# Full pipeline in one command
python toposwarm_continual_trainer.py --full
# Step by step
python toposwarm_continual_trainer.py --gen-dataset # 422 LazyOwn examples
python toposwarm_continual_trainer.py --compute-fisher # Fisher diagonal on ToolBench
python toposwarm_continual_trainer.py --train # EWC + Replay fine-tuning
python toposwarm_continual_trainer.py --eval # routing accuracy on both datasets
# Tune the anti-forgetting strength
python toposwarm_continual_trainer.py --full --ewc-lambda 600 --replay-ratio 0.25
```
### Dataset
`lazyown_dataset_generator.py` generates **422 ToolBench-format examples** across all 80 LazyOwn MCP tools:
```bash
python lazyown_dataset_generator.py --stats
```
```
Total examples : 422 Unique tools : 80
By domain:
Security/Intel 74 Security/Report 53
Security/Config 38 Security/Execution 37
Security/C2 36 Security/Hive 32
Security/Events 26 Security/Automation 25
Security/Agents 24 Security/Autonomous 21
```
Each tool has 5–10 phrasings covering: expert language, beginner language, Spanish, context-aware post-action prompts (`"vsftpd exploit worked, I have a shell — dump credentials"`), and multi-step chain examples (`recon → exploit → creds → AD → report`).
### Why EWC over LoRA?
LoRA adds rank-decomposed adapters and freezes base weights — ideal for 7B+ transformers. For a 2M-param model trained from scratch, EWC achieves the same "protect original weights" goal via a loss penalty with zero architectural overhead. Combined with replay, it outperforms LoRA on small custom models.
---
## Requirements
```
torch>=2.0
safetensors
tiktoken
numpy
```
Optional (for LazyOwn orchestrator):
```
mcp # for --mcp server mode
lupa # LazyOwn core dependency
```
---
## License
AGPL v3 — Gris Iscomeback
## Wiki
[https://deepwiki.com/grisuno/toposwarm](https://deepwiki.com/grisuno/toposwarm)
## Previous work
### TopoGPT2
- [https://github.com/grisuno/TopoGPT2](https://github.com/grisuno/TopoGPT2)
### Algorithmic Induction via Structural Weight Transfer
- [https://doi.org/10.5281/zenodo.18072858](https://doi.org/10.5281/zenodo.18072858)
### From Boltzmann Stochasticity to Hamiltonian Integrability: Emergence of Topological Crystals and Synthetic Planck Constants
- [https://doi.org/10.5281/zenodo.18407920](https://doi.org/10.5281/zenodo.18407920)
### The Dirac Discrete Crystal
- [https://doi.org/10.5281/zenodo.18810160](https://doi.org/10.5281/zenodo.18810160)
### Schrödinger Topological Crystallization: Phase Space Discovery in Hamiltonian Neural Networks
- [https://doi.org/10.5281/zenodo.18725428](https://doi.org/10.5281/zenodo.18725428)
### Constraint Preservation in a Neural Quantum Simulator
- [https://doi.org/10.5281/zenodo.18795537](https://doi.org/10.5281/zenodo.18795537)
   [](https://www.gnu.org/licenses/agpl-3.0)
[](https://ko-fi.com/Y8Y2Z73AV)
