Meshpocalypse Semantic

@one137th/mesh — Meshpocalypse

Secure agent coordination infrastructure for multi-agent AI teams — works with LangGraph, CrewAI, AutoGen, OpenClaw, or any HTTP client.

For engineers: Semantic mesh layer built on NATS + Oxigraph — TLS + Ed25519 signed envelopes, SPARQL routing, JSON-LD/CRDT bridge, W3C PROV-O provenance, and AI framework adapters. 📖 Plain English Wiki

What is Meshpocalypse?

When your AI agents need to coordinate, they typically do it through the LLM — which is slow (2–10 seconds), burns tokens, and drops around 5% of messages. There's no shared memory, no audit trail, and no way to enforce trust between agents.

Meshpocalypse fixes this. Drop it into any agent framework — LangGraph, CrewAI, AutoGen, or plain HTTP — and your agents get a shared knowledge graph, sub-100ms direct messaging, deterministic routing, and a tamper-proof audit trail.

Capability	Before (LLM round-trip)	After (Meshpocalypse)
Agent-to-agent messaging	2–10s, 1K–3K tokens	Direct via NATS (sub-100ms over direct NATS; see benchmarks/)
Shared knowledge	Each agent isolated	Live SPARQL graph shared across all agents
Finding the right agent	LLM guesses	Deterministic SPARQL query in milliseconds
Trust enforcement	None	5-level ATF framework with SHACL validation
Message delivery guarantee	~95%	>99.9% with ACK + retry + circuit breaker
Audit trail	None	W3C PROV-O tamper-evident chain
Transport security	Plaintext	TLS + Ed25519 signed envelopes

📖 Why Meshpocalypse? See docs/guides/why-meshpocalypse.md for the full comparison against LangGraph, AutoGen, and CrewAI.

Meshpocalypse is infrastructure, not a framework. It sits underneath your orchestration layer — not instead of it.

	Meshpocalypse	LangGraph	AutoGen	CrewAI
What it is	Agent coordination bus	Workflow engine	LLM chat coordination	Agent framework
Routing mechanism	NATS + SPARQL (deterministic)	LLM calls	LLM chat rounds	LLM calls
Agent-to-agent latency	Sub-100ms (NATS direct)	2–10s per hop	2–10s per hop	2–10s per hop
Shared state	CRDT + SPARQL graph	Checkpointing	None built-in	None built-in
Audit trail	W3C PROV-O tamper-evident	None	None	None
Transport security	TLS + Ed25519 signed envelopes	None built-in	None built-in	None built-in
Framework lock-in	None — adapts to any framework	LangGraph only	AutoGen only	CrewAI only
Use together?	✅ Yes — mesh sits underneath	✅ Use LangGraph on top	✅ Use AutoGen on top	✅ Use CrewAI on top

Project Status

Component	Status
NATS transport + Oxigraph SPARQL graph	✅ Production-ready
Security layer (TLS, Ed25519, CRDT signing, CF JWT)	✅ Production-ready (v1.4.0)
HTTP/REST Gateway, SwarmNode API	✅ Production-ready (v1.3.0)
LangGraph / CrewAI / AutoGen adapters	✅ Stable
Cloudflare Durable Objects cloud tier	🔧 Architecture designed; additional implementation work required
LoRa/Meshtastic offline transport	🔬 Architecture-ready; not yet validated on physical Meshtastic hardware
Federated SPARQL (cross-cluster)	📋 Not yet implemented

🎉 v1.4.1 Released — 2026-03-13 — complete security architecture (TLS, Ed25519, CRDT signing, CF JWT), hierarchical capability taxonomy, auction provenance tracing, confidence signal bus, and a Grafana token budget dashboard.

Quick Start

Recommended: use ./scripts/start-local.sh — it starts the full stack and loads the ontology in one command.

git clone https://github.com/one137th/Meshpocalypse.git
cd Meshpocalypse
./scripts/start-local.sh

This starts Oxigraph (SPARQL knowledge graph) + NATS (message broker), loads the ontology, and makes Grafana available at http://localhost:3000.

Platform	Time	Cost	How
Local (Docker)	~2 min	Free	`./scripts/start-local.sh`
Windows (Docker)	~2 min	Free	`scripts\start-local.bat`
Railway	~5 min	Free tier	See docs/guides/deployment.md
Fly.io (production)	~15 min	Pay-as-you-go	See docs/guides/deployment.md

Connect your framework

npm install @one137th/mesh

Four lines of TypeScript. Works with any framework that can call Node.js or HTTP:

import { SwarmNode } from '@one137th/mesh';

const node = new SwarmNode({ agentId: 'my-agent', capabilities: ['summarise', 'search'] });
await node.connect();
await node.publish('task.result', { result: 'done' });
const peers = await node.discoverCapability('search');
await node.disconnect();

Python SDK:

from meshpocalypse import SwarmNode, SwarmNodeConfig

config = SwarmNodeConfig(agent_id="my-agent", capabilities=["summarise", "search"])
async with SwarmNode(config) as node:
    await node.publish("task.result", {"result": "done"})
    peers = await node.discover_capability("search")

Node.js ≥ 20 required. Python SDK (meshpocalypse) and Semantic Kernel adapter are also available — see docs/integrations/.

Framework guides

Framework	Guide	Adapter import
LangGraph	docs/getting-started/langgraph.md	`@one137th/mesh/adapters/langgraph`
CrewAI	docs/getting-started/crewai.md	`@one137th/mesh/adapters/crewai`
AutoGen	docs/getting-started/autogen.md	`@one137th/mesh/adapters/autogen`
HTTP/REST	docs/getting-started/http-rest.md	Any HTTP client
OpenClaw	docs/getting-started/openclaw.md	`@one137th/mesh` (first-class)

How it works

Three components work together:

NATS — the real-time message broker. Every agent message flows through here. It guarantees delivery, retries on failure, and routes to the right agent without involving the LLM.

Oxigraph — the shared knowledge graph. Stores facts about your agents as connected data (RDF triples): their capabilities, current status, trust level, and action history. Agents query this with SPARQL to make routing decisions in milliseconds instead of burning a full LLM call.

The Semantic Layer (this package) — sits on top of NATS and Oxigraph and adds a security layer, SPARQL routing, a shared CRDT team task board, a tamper-proof W3C PROV-O audit trail, a 5-level trust framework, and MCP tool exposure for AI frameworks.

+-----------------------------------------------------------+
|                      AGENT LAYER                          |
|   LangGraph · CrewAI · AutoGen · OpenClaw · HTTP clients  |
+-----------------------------------------------------------+
                    |                    |
         +------------------+  +------------------+
         |  BROKER LAYER    |  |   CLOUD LAYER    |
         |  NATS real-time  |  | CF Durable Objs  |
         |  pub/sub routing |  |  Workers + KV    |
         +------------------+  +------------------+
                    |                    |
+-----------------------------------------------------------+
|                  TRANSPORT ABSTRACTION                     |
|    Protobuf wire format, agent discovery, channel routing  |
+-----------------------------------------------------------+

The semantic layer adds:

+-----------------------------------------------------------+
|              AI FRAMEWORK LAYER                           |
|    LangGraph · CrewAI · AutoGen · Solid/LDP               |
+-----------------------------------------------------------+
                           |
+-----------------------------------------------------------+
|             SEMANTIC LAYER  (this package)                |
|  SemanticModule · MeshGraph · SPARQL Optimizer            |
|  JSON-LD Bridge · PROV-O Provenance · ATF Trust · MCP     |
+-----------------------------------------------------------+
                           |
+-----------------------------------------------------------+
|           SECURITY LAYER  (v1.4.0)                        |
|  TLS (NATS_TLS_MODE) · Subject Validation                 |
|  From-Field Verification · Ed25519 Envelope Signing       |
|  CRDT Signing · CF JWT Validation                         |
+-----------------------------------------------------------+
                           |
+-----------------------------------------------------------+
|        CORE MESH  (@one137th/mesh-network)                |
|   MeshNode · NATS Transport · Routing · Circuit Breaker   |
+-----------------------------------------------------------+

Normal operation: Agent → NATS Broker → Agent (sub-100ms over direct NATS; see benchmarks/) Broker unavailable: Agent → Cloudflare Durable Object (buffer + recovery) ⚠️ additional implementation work required

Feature Flags

All features are off by default — enable only what you need via .env. Production deployments should always set NATS_TLS_MODE=STRICT, MESH_SIGNATURE_ENFORCEMENT=strict, and MESH_CRDT_SIGNING=true.

→ Full reference: docs/reference/feature-flags.md

Documentation

Section	What's in it
docs/getting-started/	Framework-specific setup guides
docs/guides/	Architecture, deployment, observability, troubleshooting, examples
docs/integrations/	Cloudflare, HTTP Gateway, MCP, OpenTelemetry, Python SDK, Semantic Kernel
docs/reference/	API, configuration, job protocol, feature flags, persistence, exports
docs/decisions/	Architecture Decision Records (ADRs)
docs/internal/	Internal working docs (design docs, proposals, code reviews)

Development

npm ci
npm run type-check
npm test
npm run test:coverage

Script	What
`./scripts/start-local.sh`	Start full local stack (Oxigraph + NATS + ontology load)
`npm run dev:semantic:up`	Start Oxigraph + NATS via Docker Compose (manual)
`npm run ontology:load`	Load core ontology into Oxigraph
`npm run ontology:validate`	Validate Turtle syntax (requires Docker)
`npm run test:graph-crdt`	CRDT bridge tests
`npm run test:sparql-routing`	SPARQL routing tests
`npm run test:shacl`	SHACL validation tests
`npm run test:provenance`	Provenance chain tests
`npm run test:security`	Security regression suite (TLS, signing, injection, replay)
`npm run benchmark:routing`	Routing latency benchmark

Ontology: src/ontology/meshpocalypse-core-ontology.ttl · SHACL: src/ontology/shacl-shapes.ttl · JSON-LD: src/ontology/json-ld-context.jsonld