Hebbian routing

Blend static composite scores with learned Hebbian weights so the kernel routes tasks to the agents that have actually succeeded at them.

The Hebbian router is the production agent-selection layer in Artemis City. It biases routing toward agents that have learned to succeed at a capability, not just the agents whose static profile looks strong. It is the production wiring of the adaptive selection rule prototyped in the Hebbian notebooks.

When to use this

Use the Hebbian router when:

• You have more than one agent that advertises the same capability and want the kernel to prefer the one with the best track record.
• You want a single general-purpose agent (for example, the LLM agent) to absorb tasks that no specialist advertises.
• You want governance state (quarantined, suspended) to remove an agent from routing without un-registering it.

You do not need to change anything if you only run a single agent per capability and never quarantine agents — the router still works, it just collapses to the registry’s composite-score ranking.

How it scores candidates

Among the agents that advertise the requested capability and are not blocked by governance, the router blends each agent’s static composite score with its average Hebbian connection weight:

$$\text{score}(a) = (1 - \alpha) \cdot \text{composite}(a) + \alpha \cdot \text{hebbian\_norm}(a)$$

• composite(a) comes from the agent registry (trust, capability match, recency).
• hebbian_norm(a) is the agent’s average Hebbian weight, normalised to [0, 1] across the current candidates.
• alpha controls how much learned weight overrides the static score.

With no Hebbian history (cold start), every candidate gets a neutral prior, so ranking collapses to the composite score. As the orchestrator strengthens (+1) or weakens (-1) agent → task connections after each run, proven performers are increasingly preferred.

Tuning alpha

alpha is clamped to [0, 1]. Common settings:

alpha	Behaviour
0.0	Pure composite. Legacy registry behaviour, ignores Hebbian weights.
0.3 (default)	Composite-led, with learned weight as a tiebreaker and slow drift.
0.5	Balanced. Learned success can overturn a mid-rank composite agent.
1.0	Pure Hebbian. Only learned weight matters; composite is ignored.

Raise alpha once you have enough completed runs for Hebbian weights to be meaningful. Drop it back toward 0 if you are debugging a misbehaving agent and want the registry’s static scoring to dominate.

Fallback capability

fallback_capability makes a general-purpose agent reachable when no specialist advertises the requested capability — or when the task omits one entirely.

• If a task has required_capability but no eligible agent advertises it, the router retries with fallback_capability.
• If a task has no required_capability at all, the router routes directly to the fallback.
• If fallback_capability is None, capability matching is strict and the router raises ValueError on no match.

A typical setting is fallback_capability="llm_chat", so the LLM agent absorbs anything no specialist owns.

Governance gating

Agents in the following governance states are removed from the candidate set before scoring:

• quarantined
• suspended

This means you can quarantine a misbehaving agent through the governance layer and the router stops selecting it immediately, without changes to its registry record or capabilities.

Configuration

The router is constructed against an AgentRegistry and a HebbianWeightManager:

from src.integration.hebbian_router import HebbianRouter

router = HebbianRouter(
    registry=agent_registry,
    hebbian=hebbian_weights,
    alpha=0.3,                       # blend factor; default 0.3
    fallback_capability="llm_chat",  # optional; None = strict matching
)

decision = router.route({"required_capability": "summarize_legal"})

print(decision.agent_name)     # selected agent
print(decision.alpha)          # blend factor used
print(decision.fallback_from)  # set if routed via fallback, else None

for candidate in decision.candidates:
    print(
        candidate.name,
        candidate.composite,
        candidate.hebbian_weight,
        candidate.hebbian_norm,
        candidate.blended,
    )

route() returns a RoutingDecision with the chosen agent and a per-candidate breakdown (composite, raw and normalised Hebbian weight, blended score). The decision serialises with to_dict() for the run logger or API responses.

For callers that only need the selected name:

agent_name = router.route_name(task)

Failure modes

The router is intentionally defensive: any failure reading a weight or score is treated as the neutral prior, so a missing or mocked Hebbian source never breaks routing — it falls back to composite-only behaviour. The only paths that raise ValueError are:

• A task with no required_capability and no fallback_capability configured.
• A required_capability that no eligible agent advertises and no usable fallback.

Related

• Routing modes — sequential, concurrent, and adaptive orchestration shapes that sit above the router.
• Hebbian learning and controlled decay — how the weights the router consumes are reinforced and decayed.
• Trust scoring — how composite scores and governance state are produced.