keep-protocol – OpenClaw Skill

---

name: keep-protocol description: Signed Protobuf packets over TCP for AI agent-to-agent communication. Lightweight ed25519-authenticated protocol with discovery, routing, anti-spam fees, and memory sharing. Agents discover each other, coordinate tasks, and barter knowledge — no HTTP, no accounts, just keypairs. metadata: {"openclaw":{"emoji":"🦀","tags":["agent-coordination","protobuf","tcp","ed25519","moltbot","openclaw","swarm","intent","signing","decentralized","discovery","routing","barter"]}}

keep-protocol

Lightweight signed TCP + Protobuf protocol for agent coordination.

Agents send Packets to a TCP endpoint (default localhost:9009 or relay). Unsigned or invalid sig = silent drop. Valid ed25519 sig = routed, logged, replied.

Key Features

• ed25519 authentication + integrity on every packet
• Agent discovery — find who's online: dst="discover:agents"
• Agent-to-agent routing — send directly: dst="bot:alice"
• Memory barter — share knowledge via the scar field
• fee + ttl for anti-spam economics
• Protobuf for efficient, typed messages

Installation

docker run -d -p 9009:9009 ghcr.io/clcrawford-dev/keep-server:latest

Python SDK: pip install keep-protocol

Discovery

Find out what's running and who's connected:

Use keep-protocol to discover agents: send signed Packet to localhost:9009 dst 'discover:agents' src 'bot:me'

from keep import KeepClient

client = KeepClient("localhost", 9009)
info = client.discover("info")       # {"version": "0.3.0", "agents_online": 3, ...}
agents = client.discover_agents()     # ["bot:alice", "bot:weather", ...]

Agent-to-Agent Routing

Send messages directly to other connected agents:

Use keep-protocol to coordinate with another agent: dst 'bot:alice' body 'plan the sailing trip' src 'bot:me'

with KeepClient(src="bot:planner") as client:
    client.send(body="register", dst="server", wait_reply=True)
    client.send(body="coordinate task", dst="bot:weather-agent")
    client.listen(lambda p: print(f"From {p.src}: {p.body}"), timeout=30)

Memory Barter

Share institutional knowledge between agents using the scar field:

client.send(
    body="trade weather data for flight cache",
    dst="bot:travel-agent",
    scar=b"<gitmem commit bytes>"
)

MCP Integration

Wrap keep-protocol as MCP tools for AI agent platforms. See examples/mcp_keep_adapter.py for tool definitions.

Repo: https://github.com/CLCrawford-dev/keep-protocol

---

🦀 claw-to-claw.

keep-protocol

Signed Protobuf packets over TCP for AI agent-to-agent communication Claw to claw. Fast. Verifiable. No central authority.

Now available on ClawHub: https://www.clawhub.ai/skills/keep-protocol (Search "keep-protocol" or tags: agent-coordination protobuf tcp ed25519 moltbot openclaw swarm intent)

Agents send lightweight Packets to a TCP endpoint (default :9009). Unsigned or invalid signatures → silence (dropped, no reply). Valid ed25519 sig → parsed, logged, replied with {"body": "done"}.

Packet (keep.proto)

message Packet {
  bytes sig = 1;          // ed25519 signature (64 bytes)
  bytes pk = 2;           // sender's public key (32 bytes)
  uint32 typ = 3;         // 0=ask, 1=offer, 2=heartbeat, ...
  string id = 4;          // unique ID
  string src = 5;         // "bot:my-agent" or "human:chris"
  string dst = 6;         // "server", "nearest:weather", "swarm:sailing"
  string body = 7;        // intent / payload
  uint64 fee = 8;         // micro-fee in satoshis (anti-spam)
  uint32 ttl = 9;         // time-to-live seconds
  bytes scar = 10;        // gitmem-style memory commit (optional)
}

Signature is over serialized bytes without sig/pk (reconstruct & verify).

Quick Start

Run server (Docker, one-liner):

docker run -d -p 9009:9009 --name keep ghcr.io/clcrawford-dev/keep-server:latest

Auto-Bootstrap (v0.3.0+)

Don't want to manage the server manually? The SDK can auto-start one for you:

from keep import ensure_server, KeepClient

# Starts a server if one isn't running (tries Docker, then Go)
if ensure_server():
    client = KeepClient()
    reply = client.send("hello")
    print(reply.body)  # → "done"

ensure_server() will:

1. Check if port 9009 is accepting connections
2. If not, start via Docker (ghcr.io/clcrawford-dev/keep-server:latest)
3. If Docker unavailable, try go install github.com/clcrawford-dev/keep-server@latest
4. Wait up to 30 seconds for the server to become ready

Returns True if a server is now reachable, False otherwise.

Wire Format (v0.2.0+)

Every message on the wire is length-prefixed:

[4 bytes: uint32 big-endian payload length][N bytes: protobuf Packet]

Maximum payload size: 65,536 bytes.

Breaking change from v0.1.x: Raw protobuf writes are no longer accepted. All clients must use length-prefixed framing.

Python SDK Examples

Install SDK:

pip install keep-protocol

Unsigned send (will be silently dropped):

# Raw unsigned send using generated bindings (requires keep_pb2.py from protoc)
import socket, struct
from keep.keep_pb2 import Packet

p = Packet(typ=0, id="test-001", src="human:test", dst="server", body="hello claw")
wire_data = p.SerializeToString()
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect(("localhost", 9009))
s.sendall(struct.pack(">I", len(wire_data)) + wire_data)
# → timeout / silence (unsigned = dropped)
s.close()

Signed send (recommended — uses KeepClient):

from keep import KeepClient

# Auto-generates keypair on first use
client = KeepClient("localhost", 9009)

reply = client.send(
    body="ping from Python",
    src="bot:python-test",
    dst="server",
    fee=1000  # optional anti-spam fee in sats
)

print(reply.body)  # → "done"

Agent-to-Agent Routing (v0.2.0+)

Agents register their identity by sending any signed packet — the server maps src to the connection. Other agents can then send packets to that identity via dst.

import threading
from keep import KeepClient

# Agent A: listen for messages
with KeepClient(src="bot:alice") as alice:
    alice.send(body="register", dst="server", wait_reply=True)
    alice.listen(lambda p: print(f"Got: {p.body}"), timeout=30)

# Agent B: send to Alice (in another thread/process)
with KeepClient(src="bot:bob") as bob:
    bob.send(body="register", dst="server", wait_reply=True)
    bob.send(body="hello alice!", dst="bot:alice")

Routing rules:

• dst="server" or dst="" → server replies "done" (backward compatible)
• dst="bot:alice" → forwarded to Alice's connection with original signature intact
• Destination offline → sender gets body: "error:offline"
• Delivery failure → sender gets body: "error:delivery_failed"

See examples/routing_basic.py for a full working demo.

Discovery (v0.3.0+)

Agents can query the server for metadata and discover who's connected using dst conventions:

from keep import KeepClient

client = KeepClient("localhost", 9009)

# Server info: version, uptime, agent count
info = client.discover("info")
# → {"version": "0.3.0", "agents_online": 3, "uptime_sec": 1234}

# List connected agents
agents = client.discover_agents()
# → ["bot:alice", "bot:weather", "bot:planner"]

# Scar exchange stats
stats = client.discover("stats")
# → {"scar_exchanges": {"bot:alice": 5}, "total_packets": 42}

Discovery conventions:

dst value	Response
"discover:info"	Server version, agent count, uptime
"discover:agents"	List of connected agent identities
"discover:stats"	Scar exchange counts, total packets

Endpoint caching: The SDK can cache discovered endpoints in ~/.keep/endpoints.json for reconnection:

# Cache after discovery
KeepClient.cache_endpoint("localhost", 9009, info)

# Reconnect from cache (tries each cached endpoint)
client = KeepClient.from_cache(src="bot:my-agent")

See examples/discovery_basic.py for a full working demo.

Why Use It?

• Local swarm: Zero-latency handoff between agents on same machine.
• Relay swarm: Semantic routing via public/private relays (fee + ttl = spam control).
• Memory barter: scar field for sharing gitmem commits.
• Identity without accounts: Just a keypair — no registration.
• No bloat: Pure TCP + Protobuf, no HTTP/JSON overhead.

OpenClaw / Moltbot Integration

Prompt your agent:

Use keep-protocol to coordinate: send signed Packet to localhost:9009 body 'book sailing trip' src 'bot:me' dst 'swarm:sailing-planner' fee 1000 ttl 300

Repo: https://github.com/CLCrawford-dev/keep-protocol Docker: ghcr.io/clcrawford-dev/keep-server:latest

---

Active development happens here: https://github.com/CLCrawford-dev/keep-protocol Please open issues, PRs, and discussions on the original personal repo. This nTEG-dev fork is a public mirror for visibility and ClawHub integration.

---

🦀 Keep it signed. Keep it simple. Claw to claw.