πŸ—οΈ Architecture & Core Concepts

Understand the t-minus protocol, fleet coordination, bottles, and the conservation law that governs it all.

Docs β€Ί Concepts

🧠 The Big Picture

SuperInstance is a conservation spectral framework for persistent multi-agent AI. It treats a fleet of agents like a physical system where total "energy" is conserved. When one agent consumes more resources, others get less. This isn't a metaphor β€” it's enforced mathematically through spectral analysis.

The framework provides:

⏱️ T-Minus Protocol

The t-minus protocol is SuperInstance's coordination mechanism. It uses temporal cueing with offsets to schedule and route tasks between agents through a WebSocket dispatcher.

Negative Offsets β†’ Head Starts

A negative offset gives an agent a head start. The task is dispatched immediately β€” or even "retroactively" β€” so the agent begins work before the nominal time.

client.cue("beta", -1, "analyze", payload)

Positive Offsets β†’ Countdowns

A positive offset creates a countdown. The task is queued and delivered after the specified delay, useful for staggered execution.

client.cue("gamma", 5, "report", payload)

Zero Offset β†’ Immediate

An offset of zero means immediate dispatch. The task is sent to the target agent right now, no delay.

client.cue("alpha", 0, "compute", payload)

The lifecycle is: register β†’ subscribe β†’ cue/dispatch β†’ complete β†’ result. Agents register their capabilities, subscribe to channels, and the dispatcher routes tasks based on capability matching and spectral load.

πŸ›³οΈ Fleet & Vessels

A fleet is a named group of coordinated agents. Each agent in the fleet is called a vessel. The fleet maintains a spectral model of each vessel's capabilities.

Spectral Load Balancing

When a task arrives, the fleet computes which agent's capability eigenvalue best matches the task's spectral profile. Tasks are routed to the best-matched vessel β€” not round-robin, not random, but mathematically optimal based on the agent-resource matrix.

fleet = Fleet(name="analysis-team")
fleet.add_agent(agent)
result = fleet.dispatch("Analyze this dataset")

Methods: add_agent(), dispatch(task), broadcast(message), spectral_balance().

🍢 Bottles

Bottles are encapsulated message containers that preserve state across agent handoffs. When a task moves from one agent to another, the bottle carries the full context β€” input, intermediate results, metadata β€” so the receiving agent has everything it needs.

Key property: Bottles are immutable once sealed. This guarantees that handoff state is consistent and race-free.

Bottles enable:

βš–οΈ Conservation Law

This is the core invariant of the framework. Total fleet resources are conserved.

Ξ³ + Ξ· = C
where Ξ³ = spectral load, Ξ· = spectral gap, C = total fleet capacity

What this means in practice:

When one agent consumes more resources (Ξ³ increases for that agent), the conservation law means other agents get less. The spectral gap Ξ· reveals the distribution β€” a large gap signals imbalance, triggering automatic rebalancing.

Spectral Balance Check

balance = fleet.spectral_balance()
print(f"Spectral gap: {balance.gap}")
print(f"Dominant agent: {balance.dominant_agent}")
print(f"Eigenvalues: {balance.eigenvalues}")
This isn't a metaphor. The conservation law is enforced mathematically. The fleet computes the eigenvalue decomposition of the agent-resource matrix and ensures the total spectral energy remains constant.

πŸ”„ How It Fits Together

  1. Agent creation β€” each agent gets a directory at ~/.superinstance/agents/{name}/ with a memory.md file
  2. Memory β€” facts stored as markdown, loaded on startup, appended via remember()
  3. Fleet coordination β€” the fleet maintains a spectral model; tasks route to the best-matched vessel
  4. Conservation β€” total resources tracked via eigenvalues; large spectral gaps trigger rebalancing
  5. Bottles β€” immutable containers carry state across agent handoffs

πŸ—ΊοΈ Explore More