README.md

---
title: SignalMesh — Ambient Context Protocol for AI Agent Fleets
emoji: 📡
colorFrom: pink
colorTo: yellow
sdk: docker
app_port: 7860
pinned: true
tags:
  - ai-agents
  - llm
  - multi-agent
  - context-protocol
  - no-tool-calls
  - broadcast
  - ambient-context
  - agent-infrastructure
  - signalmesh
  - sovereign-liquid-matrix
---

# 📡 SignalMesh

> **Context finds the agent. Not the other way around.**

SignalMesh is an ambient context protocol for LLM multi-agent systems.
It eliminates the overhead of read-only tool calls by inverting the
context-acquisition model: instead of agents polling for information,
information is broadcast onto spatial frequencies that agents passively receive.

---

## 🌐 Live API (hosted)

The mesh is **live and hosted** — you don't need to run it locally to integrate:

```
Base URL:   https://acecalisto3-signalmesh.hf.space
Auth:       X-SignalMesh-Key: smesh-free-demo      (free tier · 200 calls / 24h)
Docs:       https://acecalisto3-signalmesh.hf.space/docs
```

**Chat with the mesh** — `POST /api/chat` answers a message with multi-provider
failover (groq → gemini → opencode_zen → huggingface → xai), hydrated with live
mesh context. No per-app provider keys required:

```bash
curl -X POST https://acecalisto3-signalmesh.hf.space/api/chat \
  -H "X-SignalMesh-Key: smesh-free-demo" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"demo","message":"What can the mesh do?"}'
# → {"reply":"...","provider":"groq:llama-3.1-8b-instant","active_signals":[...],"history_len":1}
```

**Tune in / broadcast** against the live mesh:

```bash
curl -X POST https://acecalisto3-signalmesh.hf.space/api/tune_in \
  -H "X-SignalMesh-Key: smesh-free-demo" -H "Content-Type: application/json" \
  -d '{"keywords":["ai-engineer","python-pro"]}'

curl -X POST https://acecalisto3-signalmesh.hf.space/api/broadcast \
  -H "X-SignalMesh-Key: smesh-free-demo" -H "Content-Type: application/json" \
  -d '{"frequency":"my_agent","content":"hello mesh","source_type":"demo"}'
```

> The `localhost:7475` examples further down are for **local development**. For hosted use, swap in the Base URL above.

---

## The Problem with Current Multi-Agent Frameworks

Every major agent framework today — LangGraph, AutoGen, CrewAI, OpenManus —
treats context acquisition as a **tool call**:

```
Agent:    "I need to know the current system errors."
          → calls get_system_errors()  [+1 inference round-trip]
Agent:    "I need the architecture patterns."
          → calls get_architecture_docs()  [+1 inference round-trip]
Agent:    "I need active signal feeds."
          → calls get_active_signals()  [+1 inference round-trip]
Agent:    "Now I can work."
```

Each tool call costs:
- **1 extra LLM inference invocation** (~$0.001–0.01, ~800ms latency)
- **Tool schema tokens** injected into every context window (~80 tok/tool)
- **Call/result wrapper overhead** per invocation (~40 tok/call)
- **Sequential blocking** — agents wait for each fetch before proceeding

In a fleet of 5 agents each needing 3 context fetches, this overhead
compounds to **4,200 wasted scaffold tokens** and **25 eliminated inference calls**.

---

## The Antennae Model

SignalMesh inverts this with three primitives:

```
[Data Source: logs, RSS, agent outputs]
          │
          ▼
    signal_registry.broadcast("frequency_name", content)
          │
          ├──► Agent A: tune_in(["python-pro", "error"])  ← catches it
          ├──► Agent B: tune_in(["architecture"])          ← catches it
          └──► Agent C: tune_in(["financial"])             ← misses (wrong freq)
```

Agents are **antennae**, not search engines. Context arrives at their frequency.
No tool call. No round-trip. No schema overhead. The framework intercepts the
system prompt before execution and hydrates it with matched signals.

---

## Benchmark

Identical informational content, measured across both modes.
Token approximation: `len(string) / 4` (consistent; delta is exact).

| Metric | Tool-Call Mode | SignalMesh Mode | Delta |
|--------|---------------|-----------------|-------|
| Total context tokens | 514 | 266 | **▼48%** |
| Scaffolding overhead tokens | 280 | 34 | **▼88%** |
| — Schema definitions | 168 | 0 | **▼100%** |
| — Call/result wrappers | 112 | 0 | **▼100%** |
| Inference round-trips | 2 | 1 | **▼50%** |
| Tool calls fired | 3 | 0 | **▼100%** |
| `tune_in()` latency | n/a | **1.69 µs** | — |

**Fleet projection (5 agents × 3 context fetches each):**

| Metric | Tool-Call | SignalMesh | Savings |
|--------|-----------|------------|---------|
| Overhead tokens (fleet) | 4,200 | 170 | **−4,030 tok** |
| Inference trips | 30 | 5 | **−25 trips** |
| Overhead reduction | — | — | **96%** |

> Run `python signalmesh_benchmark.py` to reproduce on your hardware.

---

## Three Named Innovations

### 1. The Antennae Model
Agents declare their frequency via keywords (`id`, `cluster`, `name`).
The framework calls `tune_in(keywords)` before each agent invocation and
appends matched signals to the system prompt. **Zero explicit tool calls
for read-only context.**

### 2. Spatial Signal Indexing
A 9×8 grid (72 nodes) maps agent roles by cluster row and seniority column.
External URIs are hashed via SHA-256 and mapped to the nearest grid node,
deterministically routing live data to the most relevant agent domain.
No vector database, no embedding inference — sub-millisecond lookup via Python dict.

```
SHA-256(uri) % 72  →  (row, col)  →  agent keyword  →  prompt hydration
```

Grid layout (54 agents, 72 nodes):
```
       Col0          Col1          Col2    ...  Col7
Row0:  backend-arch  frontend-dev  mobile  ...  [overflow]   ← ARC cluster
Row1:  python-pro    javascript    golang  ...  physics-sim  ← LEG cluster
Row2:  cloud-arch    terraform     network ...  [overflow]   ← INF cluster
Row3:  devops        incident-res  db-adm  ...  [overflow]   ← OPS cluster
Row4:  ai-engineer   ml-engineer   mlops   ...  [empty]      ← DATA cluster
Row5:  security-aud  hardening     review  ...  [empty]      ← QUAL cluster
Row6:  biz-analyst   quant         risk    ...  [empty]      ← BIZ cluster
Row7:  content-mkt   sales-auto    support ...  [empty]      ← GROW cluster
Row8:  context-mgr   prompt-eng    search  ...  [empty]      ← UTIL cluster
```

### 3. Frequency Gate Protocol
Broadcasts on sensitive frequencies (`security_*`, `sql_*`, `auth_*`, `key_*`)
are staged into a quarantine buffer rather than committed to the live mesh.
A designated `SEC-Ω` warden reviews before any signal propagates.
Trust is a **first-class property of the broadcast path**.

```python
# Sensitive broadcast → quarantine, not live mesh
signal_broadcast.execute(topic="security_vulns", content="CVE-2024-XYZ found")
# → staged at sec_quarantine_security_vulns
# → SEC-Ω approves: signal_broadcast.execute(..., bypass_gate=True)
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         SignalMesh                              │
│                                                                 │
│  [Sources]          [Registry]           [Antennae]            │
│                                                                 │
│  Logger.ERROR  ───► broadcast()  ◄───  RSS/API feeds           │
│  Agent outputs ───►    │         ◄───  Context discovery       │
│                        │                                        │
│              tune_in(keywords)  ← 1.69 µs avg                  │
│                        │                                        │
│              ┌─────────┴──────────┐                            │
│         System Prompt          Grid Node                        │
│         (hydrated,             (spatial_index.json)            │
│          zero tool calls)                                       │
│                                                                 │
│  [Gate]   SEC-Ω quarantine for protected frequencies           │
└─────────────────────────────────────────────────────────────────┘
```

---

## Quickstart

```bash
# Clone
git clone https://github.com/Ig0tU/SignalMesh
cd SignalMesh

# Run the integration test (no LLM required)
python demo_signal_mesh_action.py

# Run the benchmark
python signalmesh_benchmark.py

# Launch the live web visualiser
python signalmesh_viz_server.py
# → open http://localhost:7474

# Inspect the spatial grid layout
python utils/spatial_grid.py --visualize
```

---

## File Map

```
core/
├── signal_registry.py      # Singleton broadcast/tune-in hub
└── spatial_grid.py         # 9×8 SHA-256 URI indexer

tools/
├── context_discovery.py    # Auto-scan workspace for feed URLs
├── rss_matrix_sync.py      # RSS → spatial grid node sync
└── signal_broadcast.py     # Agent write-back with SEC-Ω gate

agents/
└── matrix_agents.py        # Dynamic ToolCallAgent antennae

marketing/
└── visual_scan.py          # Live grid visualiser (terminal + web)

signalmesh_benchmark.py     # Reproducible benchmark (no API key needed)
signalmesh_viz_server.py    # FastAPI live grid server (port 7474)
signalmesh_viz.html         # Web UI — real-time pulsing grid
demo_signal_mesh_action.py  # Full 5-phase integration smoke test
```

---

## Comparison with Related Work

| Approach | Context Delivery | Overhead | Latency |
|----------|-----------------|----------|---------|
| LangGraph tool nodes | Explicit tool call | High (schema + call + result) | ~800ms API |
| LlamaIndex RAG | Query-time retrieval | Medium (embedding inference) | ~100ms |
| AutoGen context vars | Manual orchestrator injection | Low | ~0ms |
| MemGPT archival memory | Paged memory retrieval | Medium (LLM-driven) | ~500ms |
| **SignalMesh** | **Ambient broadcast** | **Minimal (34 tok formatting)** | **1.69 µs** |

**Key distinction from AutoGen context variables**: SignalMesh is bidirectional.
Agents are both consumers (`tune_in`) and producers (`broadcast`) — any agent
can update the ambient context available to all others. AutoGen variables are
set by the orchestrator only. SignalMesh creates a **self-updating intelligence loop**.

---

## External API — SLM Gateway

SignalMesh exposes a REST API so external AI systems can join the Sovereign Liquid Matrix —
broadcasting signals in and tuning into live ambient context without running their own mesh.

```bash
# Install deps
pip install fastapi uvicorn

# Start the gateway
python signalmesh_api.py
# → http://localhost:7475
# → interactive docs at http://localhost:7475/docs
```

**30-second integration:**
```bash
# Tune in — get hydrated context for your agent's system prompt
curl -X POST http://localhost:7475/api/tune_in \
  -H "X-SignalMesh-Key: slm-dev-key-2026" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["ai-engineer", "python-pro"]}'

# Broadcast a signal onto the mesh
curl -X POST http://localhost:7475/api/broadcast \
  -H "X-SignalMesh-Key: slm-dev-key-2026" \
  -H "Content-Type: application/json" \
  -d '{"frequency": "python-pro", "content": "Your agent finding here"}'
```

See **[SLM_INTEGRATION.md](SLM_INTEGRATION.md)** for the full integration guide,
frequency naming conventions, SEC-Ω trust tiers, and production access.

For the philosophy behind the architecture: **[SIGNAL_MANIFESTO.md](SIGNAL_MANIFESTO.md)**

---

## Citation

```bibtex
@misc{signalmesh2026,
  title  = {Active Antennae: Ambient Context Hydration for LLM Agent Networks
             Without Tool Overhead},
  year   = {2026},
  url    = {https://github.com/Ig0tU/SignalMesh},
}
```

---

📡 *Context finds the agent.*