Hebbian routing

Source-level routing behavior: composite scores with optional persisted Hebbian and trust contributions, bounded by governance eligibility.

This page describes committed Artemis City source behavior at dev @ 9d128f7b3acb12a1c6881ed962eff213285b1e58; it is not evidence of a deployed runtime. The router is composite-led: it can blend a static composite score with persisted Hebbian evidence and an optional trust contribution. It is not a pure Hebbian monopoly. See Implementation status for the wider public/private boundary.

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 agents that advertise the requested capability and remain eligible under governance policy, the router starts from a static composite score. Configured Hebbian and trust contributions can then participate in the ranking; either contribution can be inactive.

• Persisted Hebbian updates use a default learning rate of 0.1, a per-outcome decay of 0.99, and a weight floor of 0.01.
• Trust policy is configurable. The default numeric trust blend and trust floor are 0, while governance state can still remove an agent from eligibility.
• With no usable Hebbian evidence, the router retains its composite-led behavior rather than failing or treating Hebbian weight as the only signal.

Configuration boundary

The precise contribution of composite, Hebbian, and trust evidence is configuration-dependent. This documentation intentionally does not promote a universal numeric blend or a pure-Hebbian operating mode. Passive daily trust decay is floored at the existing tier threshold, so passive decay alone cannot demote an agent to a lower tier.

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.

Persisted Sentinel alert and Oracle Watcher boundary

The public source persists a rolling sign-change alert after a 50-sample warm window when the rate is strictly greater than 0.4. That alert is observational only: it does not reroute, down-rank, quarantine, gate, or alter weights or trust.

Do not conflate this historical public “Sentinel” name with Oracle Watcher. Oracle Watcher, its L0–L6 tiers, capability tickets, and CNKD system are live private Oracle work and remain planned/private from this public repository. They are not part of this router’s public source contract.

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,                       # example blend; deployment configuration decides use
    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.