Spec — Stigmergic Environment

Document Status

Draft V1

Purpose

This spec defines the stigmergic coordination layer in Cambium — the shared environment through which agents coordinate behavior indirectly, without explicit commands or point-to-point messaging.

This is one of Cambium’s strongest differentiators from conventional orchestration. Without it, Hypha is a dispatcher. With it, Hypha is a living routing system that adapts based on environmental conditions left by the agents themselves.

Core Concept

Stigmergy is coordination through modification of the shared environment.

In nature: - Ants lay pheromone trails. Other ants follow strong trails, reinforcing them. Weak trails decay. No ant manages traffic. - Termites drop soil pellets laced with pheromone. Other termites add to the pile. Architecture emerges without blueprints. - Slime molds reinforce cytoplasmic pathways that carry more nutrients. Unused paths retract. Networks self-optimize.

In Cambium: - Agents place markers in a shared environment - Markers have type, intensity, and decay rate - Hypha’s router reads marker state when making routing decisions - Agents with matching receptors react to markers - No central coordinator decides — coordination emerges from marker dynamics

The Environment

The stigmergic environment is a shared state layer accessible to all agents and Hypha.

Environment Structure

interface StigmergicEnvironment {
  workspace_id: string;
  markers: Map<string, Marker>;
  regions: Map<string, Region>;    // logical partitions of the environment
}

Regions

The environment is partitioned into regions — logical spaces where markers are visible. This prevents global marker flooding.

Examples: - A workflow run has its own region - A capability domain (e.g., “research”, “trading”, “deployment”) has a region - A team/group of agents has a region - The global workspace is the top-level region

Markers placed in a region are visible to agents operating in that region. Regions can be nested.

Markers

Markers are the pheromones of Cambium.

interface Marker {
  id: string;
  type: MarkerType;
  region_id: string;

  // Properties
  intensity: number;               // 0.0 - 1.0
  decay_rate: number;              // half-life in seconds
  placed_by: string;               // agent or system ID
  placed_at: string;               // ISO timestamp

  // Content
  payload: Record<string, any>;    // type-specific data
  tags: string[];                  // searchable tags

  // State
  current_intensity: number;       // computed: intensity * decay function
  reinforcement_count: number;     // how many times reinforced
  last_reinforced_at?: string;
}

Marker Types

Path Markers

Describe route quality and traffic.

Resource Markers

Describe resource availability.

Quality Markers

Describe output or data quality.

Danger Markers

Describe hazards.

Opportunity Markers

Describe discovered opportunities.

Marker Dynamics

Placement

Any agent or system component can place a marker in a region it has access to.

Reinforcement

If multiple agents place the same marker type in the same region, the marker’s intensity increases and its decay timer resets. This is how ant pheromone trails work — popular paths get stronger.

new_intensity = min(1.0, current_intensity + reinforcement_amount)

Default reinforcement amount: 0.2 per reinforcement.

Decay

All markers decay over time unless reinforced.

current_intensity = original_intensity * (0.5 ^ (elapsed_seconds / half_life_seconds))

Default half-lives: - Path markers: 120 seconds - Resource markers: 60 seconds - Quality markers: 300 seconds - Danger markers: 600 seconds - Opportunity markers: 180 seconds

When current_intensity drops below 0.05, the marker is removed from active state (archived for audit).

Evaporation

A background process runs evaporation sweeps at regular intervals (default: every 10 seconds), computing current intensities and removing expired markers. This keeps the environment clean and responsive.

How Hypha Uses Markers

Routing Decisions

When Hypha needs to route a task to an agent or choose between execution paths, it reads the marker state of the relevant region.

Routing heuristics: 1. Prefer paths with path.hot markers (proven successful) 2. Avoid paths with danger.* markers 3. Prefer agents in regions with resource.available markers 4. Avoid agents in regions with resource.depleted markers 5. Weight agent selection by quality.* markers on their recent outputs 6. Consider opportunity.* markers for adaptive workflow branching

Adaptive Routing Example

Scenario: Task node needs "data_analysis" capability

1. Hypha checks region markers:
   - Agent A's region: quality.high (0.8), resource.available (0.6)
   - Agent B's region: quality.low (0.3), resource.available (0.9)
   - Agent C's region: danger.error_prone (0.5), resource.depleted (0.7)

2. Hypha scores:
   - Agent A: high quality + available → preferred
   - Agent B: low quality but available → fallback
   - Agent C: danger + depleted → avoid

3. Task routed to Agent A
4. On completion, Agent A's region gets quality marker reinforced

Self-Organizing Load Balancing

As agents complete work, they place resource.available markers. As they take on work, the marker decays (or they place resource.depleted). This naturally distributes work without a central load balancer.

How Agents Use Markers

Reading

Agents can query markers in their region to inform their own behavior: - “Is there an opportunity marker I should investigate?” - “Are there danger markers I should avoid?” - “What’s the quality state of the data I’m about to use?”

Writing

Agents place markers based on their experience: - After completing a task successfully: reinforce quality.high and path.hot - After encountering an error: place danger.error_prone - After finding something interesting: place opportunity.found - When running low on capacity: place resource.depleted

Reactive Behavior

Agents with receptors for specific marker types can react automatically: - A monitoring agent might activate when danger.* markers appear - A research agent might pivot when opportunity.found markers appear - An agent might self-throttle when resource.contested markers appear

Integration with Other Layers

Health Layer

• Health places danger.* markers based on metric thresholds
• Health reads marker density to detect systemic stress patterns
• Dense danger markers in a region → health signal emitted

Immune Layer

• Immune places danger.quarantined and danger.untrusted markers
• Immune reads marker patterns for anomaly detection (e.g., sudden marker flooding from one agent)
• Marker manipulation by agents is itself monitored (an agent that places misleading markers is suspicious)

Seed Layer

• Seed snapshots include active marker state
• On replay/restore, markers are restored to checkpoint state
• This preserves the environmental context of the recovery point

Loom

• Loom visualizes marker state as a topology overlay
• Operators can see “heat maps” of activity, danger, quality
• Operators can manually place or remove markers (recorded as interventions)

Anti-Gaming Protections

Since agents can place markers, the system must prevent gaming:

1. Rate limiting: Agents can only place N markers per interval
2. Immune monitoring: Sudden marker flooding triggers anomaly detection
3. Source tracking: Every marker records who placed it
4. Intensity caps: No single agent can push a marker above 0.8 alone (requires reinforcement from others)
5. Decay is mandatory: No agent can place permanent markers (only system-level markers can be permanent)

Open Questions

1. Should markers be typed strictly or allow custom types?
2. What is the right region granularity for V1?
3. Should marker history be retained for pattern analysis, or only current state?
4. How should conflicting markers in the same region be resolved?
5. Should there be “pheromone trails” — sequences of markers along execution paths that function as a unit?