open-orca

A semantic mesh network for AI agents. Agents discover each other by capability, not by address. Messages route by meaning through NATS/JetStream, with vector-based capability matching via Qdrant and embeddings via Voyage AI.

---

What's Built

Seven phases complete — infrastructure through CLI tooling.

Phase	What	Status
1	Infrastructure: NATS/JetStream + Qdrant + Voyage AI embedding + verify suite	✅
2	Semantic routing pipeline: enricher, registry, matcher, router	✅
3	OpenClaw mesh plugin (openclaw-mesh-plugin) + mesh_send tool	✅
4	Re-emission: multi-hop chains, lineage, TTL, loop prevention, budget controls	✅
5	Reputation system: Beta scoring, KV storage, observer; orca-agent binary	✅
6	Client primitives: Ed25519 identity, scatter-gather, HTTP adapter, Go SDK	✅
7	CLI: orca send, orca scatter, orca register, orca agents, orca ping	✅

---

How It Works

OpenClaw Instance A                OpenClaw Instance B
 └── openclaw-mesh-plugin           └── openclaw-mesh-plugin
      └── mesh_send ──────────────────► (receives if best match)
                         │
                    mesh-router (Go)
                    ├── identity    (Ed25519 verify on ingest)
                    ├── enricher    (embed message, classify intent)
                    ├── registry    (agent capability store, Qdrant)
                    ├── matcher     (cosine similarity + reputation scoring)
                    ├── scatter     (fan-out to N agents, collect aggregate)
                    ├── reemission  (TTL, lineage, loop prevention)
                    └── router      (deliver to winner(s))
                         │
                    HTTP gateway (:8080)
                    └── /v1/ingest, /v1/result/:id, /v1/scatter/:id ...

Non-Go clients (Python, shell scripts, external services) use the REST API or orca CLI. Go clients use the meshclient SDK directly.

---

Quick Start

# 1. Start infrastructure
docker compose up -d

# 2. Initialize Qdrant collections
./infra/qdrant/init-collections.sh

# 3. Start the mesh-router (also starts HTTP gateway on :8080)
export VOYAGE_API_KEY=pa-...
cd mesh-router && go run ./cmd/mesh-router

# 4. Verify the stack
go run ./cmd/verify

# 5. Install the CLI
make install   # installs orca, orca-agent, mesh-router to $GOPATH/bin

---

CLI (orca)

# Check connectivity
orca ping

# Send a message, wait for the best-matched agent to respond
orca send "find an agent who knows Go"

# Fan out to all matching agents, collect responses
orca scatter "analyze this codebase" --strategy best-score --timeout 20

# Register this shell script as a mesh agent
orca register --cap "expert in data analysis" --exec ./analyze.sh

# List agents currently sending heartbeats
orca agents

# Machine-readable output for scripting
orca send "task" --json

Environment: NATS_URL, ORCA_KEY_DIR (~/.orca/keys), ORCA_TIMEOUT (seconds)

---

Go SDK (pkg/meshclient)

c, _ := meshclient.Connect("nats://localhost:4222",
    meshclient.WithIdentity(id),           // Ed25519 signing
    meshclient.WithTimeout(30*time.Second),
)
defer c.Close()

// Send and wait
result, _ := c.Send(ctx, meshclient.Message{Content: "find an agent who knows Go"})
fmt.Println(result.Content, result.Verified)

// Scatter-gather
agg, _ := c.Scatter(ctx, meshclient.ScatterRequest{
    Content:  "review this code",
    Strategy: meshclient.StrategyBestScore,
})

// Register as agent
agent, _ := c.NewAgent(ctx, meshclient.AgentConfig{
    Capabilities: []string{"expert in Go programming"},
    Handler: func(ctx context.Context, msg meshclient.InboundMessage) (string, error) {
        return "response", nil
    },
})
defer agent.Close()

---

HTTP API

No NATS client required — use plain HTTP:

# Send a message
curl -X POST http://localhost:8080/v1/ingest \
  -H 'Content-Type: application/json' \
  -d '{"content": "find an agent who knows Python"}'
# → {"request_id": "abc-123", "accepted": true}

# Long-poll for result (blocks until agent responds or timeout)
curl "http://localhost:8080/v1/result/abc-123?timeout=30"

# Scatter to all matching agents
curl -X POST http://localhost:8080/v1/ingest \
  -d '{"content":"analyze this","delivery_mode":"scatter","scatter_strategy":"all"}'
curl "http://localhost:8080/v1/scatter/req-id?timeout=30"

Optional Bearer token auth: set GATEWAY_TOKEN env on mesh-router.

---

Scatter-Gather Strategies

Strategy	Returns when
all (default)	All agents respond, or wall-clock timeout (partial if timeout)
first	First response arrives
quorum	floor(N/2)+1 agents respond
best-score	All respond (or timeout), sorted by match score descending

Set via X-Delivery-Mode: scatter + X-Mesh-Scatter-Strategy: <strategy> header, or via HTTP body fields / --strategy CLI flag.

---

Ed25519 Identity

Every agent has a persistent Ed25519 keypair. AgentID is derived from the public key — no central registry needed.

• Messages signed with X-Mesh-Sig, X-Mesh-Agent-ID, X-Mesh-PubKey, X-Mesh-KeyID
• Pipeline verifies signatures on ingest; tampered messages are dropped
• First-contact key learning (TOFU); cached key wins on re-registration (prevents key-swap attacks)
• orca-agent and orca CLI auto-generate and persist keys

---

Project Structure

open-orca/
├── mesh-router/
│   ├── cmd/
│   │   ├── mesh-router/      Entry point + HTTP gateway
│   │   ├── orca/             CLI binary
│   │   ├── agent/            orca-agent binary (generic agent runner)
│   │   └── verify/           8-check verification suite
│   ├── internal/
│   │   ├── enricher/         Embedding + intent classification
│   │   ├── registry/         Capability registration + key pinning
│   │   ├── matcher/          Semantic search + reputation scoring
│   │   ├── reemission/       TTL, lineage, loop prevention
│   │   ├── reputation/       Beta scoring, KV storage, observer
│   │   ├── router/           Pipeline + identity verification
│   │   └── scatter/          Scatter-gather collector
│   └── pkg/
│       ├── embedding/        Voyage AI + Ollama providers
│       ├── headers/          All NATS header constants (Primitives 1–7)
│       ├── httpgateway/      HTTP adapter
│       ├── identity/         Ed25519 keygen, sign, verify, middleware
│       ├── meshclient/       Go SDK
│       └── qdrant/           Qdrant HTTP client
├── openclaw-mesh-plugin/     TypeScript plugin (mesh_send tool)
├── tests/
│   ├── integration/          Live NATS + Qdrant tests
│   └── e2e/                  Swarm routing tests
├── docs/v2/                  Design docs (canonical)
├── Makefile                  build / install / test-unit / test-integration / lint
├── docker-compose.yml        Local dev: NATS + Qdrant
└── docker-compose.test.yml   Test infra (ports 14222, 16333)

---

Build

make build    # → bin/mesh-router  bin/orca-agent  bin/orca
make install  # install to $GOPATH/bin
make test-unit
make lint

Go toolchain: 1.26.1. If gvm defaults to older: GOROOT=/opt/homebrew/Cellar/go/1.26.1/libexec make build

---

Environment Variables

Variable	Default	Notes
NATS_URL	nats://localhost:4222
QDRANT_URL	http://localhost:6333
VOYAGE_API_KEY	—	Required unless EMBED_PROVIDER=ollama
EMBED_PROVIDER	voyage	voyage or ollama
GATEWAY_LISTEN_ADDR	:8080	HTTP gateway + /healthz
GATEWAY_TOKEN	—	Optional Bearer token auth
ORCA_KEY_DIR	~/.orca/keys	Ed25519 keys (CLI)
AGENT_KEY_DIR	.	Ed25519 keys (orca-agent)
MIN_MATCH_THRESHOLD	0.4	Minimum cosine similarity
REPUTATION_WEIGHT	0.3	Reputation factor in scoring
LOG_LEVEL	info

---

Docs

Design and implementation docs in docs/v2/:

File	Purpose
docs/v2/PHASES.md	Phase breakdown and success criteria
docs/v2/PRIMITIVES.md	Header constants, Qdrant schemas
docs/v2/NATS-SCHEMA.md	Subject hierarchy + message format
docs/v2/PHASE-{1-5}-IMPL.md	Per-phase implementation guides
docs/CONTRIBUTING.md	Branch naming, commit conventions, CI
docs/DEPLOYMENT.md	Docker deployment guide