Conservation spectral framework: persistent multi-agent AI with spectral resource management
SuperInstance is the main Python SDK for building persistent, multi-agent AI systems. It provides agents with long-term memory (stored as markdown files), fleet management for coordinating multiple agents, and a spectral conservation framework that treats agent resources (compute, attention, memory) as conserved quantities governed by spectral laws.
Think of a fleet of agents like a physical system: there's a total "energy budget" that's conserved. When one agent consumes more resources, others get less. The spectral framework tracks this through eigenvalues of the agent-resource matrix — dominant eigenvalues indicate overloaded agents, spectral gaps indicate good load distribution. This isn't a metaphor; it's enforced mathematically.
pip install superinstancefrom superinstance.agent import Agent, AgentConfig
from superinstance.fleet import Fleet
from superinstance.memory import AgentMemory
# Create an agent with persistent memory
config = AgentConfig(
name="researcher",
model="gpt-4",
temperature=0.7,
max_tokens=4096,
)
agent = Agent(config)
# The agent remembers across sessions (stored at ~/.superinstance/agents/researcher/)
agent.remember("User prefers concise summaries")
# Create a fleet
fleet = Fleet(name="analysis-team")
fleet.add_agent(agent)
fleet.add_agent(Agent(AgentConfig(name="coder", model="gpt-4")))
# Dispatch a task
result = fleet.dispatch("Analyze this dataset and write a summary")
print(result)
# Check spectral balance
balance = fleet.spectral_balance()
print(f"Spectral gap: {balance.gap}")
print(f"Dominant agent: {balance.dominant_agent}")| Type | Description |
|---|---|
AgentConfig { name, model, temperature, max_tokens } |
Agent configuration. |
Agent(config) |
Create a new agent. Memory auto-loads from disk. |
send(message) |
Send a message, get a response. |
remember(fact) |
Store a fact in long-term memory (persisted to ~/.superinstance/agents/{name}/memory.md). |
recall(query) |
Retrieve relevant memories. |
spawn_sub_agent(name) |
Create a child agent that inherits context. |
| Type | Description |
|---|---|
Fleet(name) |
Create a named fleet. |
add_agent(agent) |
Add an agent to the fleet. |
dispatch(task) |
Dispatch a task to the best-suited agent. |
broadcast(message) |
Send to all agents. |
spectral_balance() |
Returns SpectralBalance { gap, dominant_agent, eigenvalues }. |
| Type | Description |
|---|---|
AgentMemory(name) |
Persistent memory manager for an agent. |
store(key, value) |
Store a key-value pair. |
retrieve(key) |
Get a stored value. |
search(query) |
Semantic search over memories. |
path |
File path: ~/.superinstance/agents/{name}/. |
| Exception | When |
|---|---|
SuperInstanceError |
Base error. |
AgentNotFoundError |
Referenced agent doesn't exist. |
FleetConnectionError |
Can't reach an agent in the fleet. |
- Agent Creation: Each agent gets a directory at
~/.superinstance/agents/{name}/with amemory.mdfile for long-term memory. - Memory: Facts are stored as markdown. On startup, the agent loads its memory file. The
remember()method appends entries. - Fleet Coordination: The
Fleetmaintains a spectral model of agent capabilities. When a task arrives, it's routed to the agent whose capability eigenvalue best matches the task's spectral profile. - Conservation: Total fleet resources are tracked. The spectral balance method computes the eigenvalue gap — a large gap means one agent dominates, which triggers rebalancing.
Tests covering:
- Agent lifecycle (create, send, remember, recall)
- Memory persistence across sessions
- Fleet dispatch and broadcast
- Spectral balance computation
- Sub-agent spawning
- Exception handling
MIT