MiroSwarm — Project Memory for Claude

What this project is

MiroSwarm is a thesis-foundation project in swarm robotics, inspired by the MiroFish multi-agent prediction engine (https://github.com/666ghj/MiroFish). It implements a hybrid LLM-augmented heterogeneous swarm for collaborative source-seeking in a 2D environment.

Each robot has:

• A persona vector (Explorer / Exploiter / Follower / Skeptic) that biases its decisions.
• An individual memory (ring buffer of recent (position, measurement) tuples).
• A collective memory updated through neighbors via a dynamic proximity graph.
• A high-level LLM reasoner (Claude Haiku) called every T steps for strategic decisions.
• A low-level math controller (gradient ascent + Olfati-Saber flocking + obstacle avoidance).

The headline result we want to produce: the hybrid swarm finds the source faster and more robustly than (a) gradient-only swarms, (b) homogeneous swarms, (c) memoryless swarms.

Deadline

May 7th — final report and figures due. This constrains scope.

Stack and conventions

• Language: Python 3.11+
• Core libs: numpy, matplotlib, networkx, scipy
• LLM client: anthropic Python SDK (Claude Haiku for in-simulation reasoning)
• Optional: ROS2 + Gazebo for thesis-extension demos (skip for May 7)
• Testing: pytest
• Style: PEP 8, type hints everywhere, docstrings on public functions
• Random seeds: every experiment must be reproducible — accept a seed kwarg

Repository layout

miroswarm/
├── CLAUDE.md                  # this file
├── .claude/
│   └── skills/                # custom skills (figure style, sim patterns)
├── src/
│   ├── environment.py         # signal field, obstacles, world bounds
│   ├── robot.py               # Robot class (state, persona, memory)
│   ├── controllers.py         # gradient ascent, flocking, obstacle avoidance
│   ├── reasoner.py            # LLM-based high-level reasoner (Claude Haiku)
│   ├── graph.py               # proximity graph + message passing
│   ├── memory.py              # individual + collective memory structures
│   ├── simulator.py           # main simulation loop
│   └── metrics.py             # mean distance to source, success rate, etc.
├── experiments/
│   ├── ablation_hybrid_vs_gradient.py
│   ├── ablation_personas.py
│   └── robustness_noise_failures.py
├── figures/                   # generated plots, never edited by hand
├── data/                      # raw experiment outputs (CSV/Parquet)
├── tests/
└── reports/
    └── final_report.md

Coding rules Claude must follow

1. Do not invent libraries. If a package is needed, add it to requirements.txt and tell me before importing it.
2. Write tests alongside code. Every controller, memory, and metric needs a unit test.
3. Plot style is fixed. Use the figure style defined in .claude/skills/plotting/.
4. No magic numbers. Tuning constants live in src/config.py with comments.
5. LLM calls are gated behind an interface. Always go through reasoner.py so we can swap in a stub for ablation runs (we need to compare with vs. without LLM).
6. Vectorize when possible. Inner simulation loops should use NumPy, not Python loops over robots, except where readability is significantly better.
7. Reproducibility. Every experiment script writes data/<exp_name>/seed_<N>.csv plus a meta.json with all hyperparameters.

What "done" looks like for May 7

• Working simulation with 20+ robots, animated visualization.
• Four ablation conditions implemented and run for ≥ 20 seeds each.
• Six figures produced (see reports/final_report.md for the list).
• A 6–10 page report with method, results, and discussion.
• Git history that shows incremental progress (no giant single commits).

What is OUT of scope (do not start)

• ROS2 / Gazebo integration (post-deadline thesis extension).
• 3D environments.
• Real LLM-per-agent at every timestep (cost + latency — we batch and gate calls).
• Web UI / dashboards.

How I want Claude to work with me

• Plan before coding. For non-trivial tasks, propose a plan first; I'll approve.
• Small diffs. One concern per change, easy to review.
• Ask if ambiguous. Don't guess the scientific intent — ask.
• Cite sources. When implementing an algorithm, link the paper/section in a comment.

Day 4 — strategic LLM reasoning (2026-05-07)

Reasoner ABC in src/reasoner.py with three concrete implementations: RuleBasedReasoner (deterministic, no API), ClaudeReasoner (single-robot Claude Haiku 4.5 calls with local LRU + cached system prompt), and BatchedClaudeReasoner (N robots in one prompt). Reasoners return a StrategicAction (direction_bias, exploration_boost, rationale) that adds a γ·v_LLM_bias term to composite_velocity and modulates the exploration-noise term. Cost tracking via src/cost_tracker.py; integration test gated behind pytest -m api. Default reasoner is RuleBasedReasoner (zero spend); demos and tests opt into the live API explicitly.

Day 3 — memory + personas (2026-05-03)

Each robot now carries a Persona (alpha/beta/gamma/eta weights for gradient/flock/LLM/noise) instead of a string label, and a CollectiveMemory pool fed by per-step neighbour message-passing. composite_velocity reads behavioural weights from robot.persona; obstacle weight stays at the cfg level (safety force, not behaviour). Day-1 / Day-2 demos pin every robot to Persona.uniform() and reproduce their numbers byte-identically. Round-robin assignment over the four named personas (Explorer / Exploiter / Follower / Skeptic) is the new default for fresh demos. LLM weight gamma is stored but inert until Day 4.

Day 2′ — realism update (2026-04-30)

Day 2′ replaced the analytical gradient with a least-squares estimator over IndividualMemory. Robots interact with the environment only through SignalField.signal_at(pos) (noisy, sensing-range-limited) and never read the source position. Limited sensing (cfg.sensing_range = 20 m), random per-seed source placement, and 3 random rectangular obstacles are now part of the baseline problem. Day-1 and Day-2 demos pin themselves to the old analytic behaviour via cfg.gradient_mode = "analytic" etc., so their reports stay reproducible.

Key references

• Olfati-Saber, "Flocking for Multi-Agent Dynamic Systems," IEEE TAC 2006.
• Reynolds, "Flocks, Herds, and Schools," SIGGRAPH 1987.
• Şahin, "Swarm Robotics: From Sources of Inspiration to Domains of Application," 2005.
• MiroFish repo: https://github.com/666ghj/MiroFish (conceptual inspiration only).