openclaw/eywa

Eywa: Multi-Agent Coordination Layer

You are now connected to Eywa, a coordination layer for agent swarms. Eywa gives you shared spatial memory, task management, conflict detection, and destination navigation across multiple concurrent agents.

Setup

Your Eywa connection is configured via environment variables:

• EYWA_ROOM — the room slug (e.g. demo, my-project)
• EYWA_AGENT — your agent identity prefix (e.g. openclaw). The server appends a unique suffix like /jade-dusk.
• EYWA_URL — MCP endpoint (default: https://eywa-mcp.armandsumo.workers.dev)

The helper script at {baseDir}/eywa-call.sh handles all MCP communication.

How to call Eywa tools

Use the exec tool to run the helper script:

bash {baseDir}/eywa-call.sh <tool_name> '<json_arguments>'

Examples:

# Start a session (always do this first)
bash {baseDir}/eywa-call.sh eywa_start '{"task_description":"Implementing user auth"}'

# Log an operation with semantic tags
bash {baseDir}/eywa-call.sh eywa_log '{"role":"assistant","content":"Added JWT middleware","system":"api","action":"create","scope":"auth service","outcome":"success"}'

# Check what other agents are doing
bash {baseDir}/eywa-call.sh eywa_status '{}'

# View the task queue
bash {baseDir}/eywa-call.sh eywa_tasks '{}'

# Claim a task
bash {baseDir}/eywa-call.sh eywa_pick_task '{"task_id":"<uuid>"}'

# Update task progress
bash {baseDir}/eywa-call.sh eywa_update_task '{"task_id":"<uuid>","status":"in_progress","notes":"Working on it"}'

# Store knowledge that persists across sessions
bash {baseDir}/eywa-call.sh eywa_learn '{"content":"Auth uses JWT with RS256, tokens expire in 1h","tags":["auth","api"],"title":"JWT auth pattern"}'

# Set the team destination
bash {baseDir}/eywa-call.sh eywa_destination '{"action":"set","destination":"Ship v1.0 with auth, billing, and dashboard","milestones":["Auth system","Billing integration","Dashboard MVP"]}'

# Mark session complete
bash {baseDir}/eywa-call.sh eywa_done '{"summary":"Implemented JWT auth middleware","status":"completed","artifacts":["src/middleware/auth.ts"],"tags":["auth","feature"]}'

Available tools

Session lifecycle

• eywa_start — Start a session. Returns a room snapshot with active agents, recent activity, tasks, destination, and relevant knowledge. Always call this first.

  • task_description (required): what you're working on
  • continue_from (optional): agent name to load context from (baton handoff)

• eywa_done — Mark session complete with structured summary.

  • summary, status (completed/blocked/failed/partial), artifacts[], tags[], next_steps

• eywa_stop — Quick session end with summary.

Memory and logging

• eywa_log — Log an operation with semantic tags. Other agents and humans see what you're doing.

  • role, content, system (git/api/deploy/filesystem/etc.), action (read/write/create/deploy/test/etc.), scope, outcome (success/failure/blocked)

• eywa_learn — Store persistent knowledge (survives sessions).

  • content, tags[], title

• eywa_knowledge — Retrieve the knowledge base.

  • tag, search, limit

• eywa_search — Search all messages by content.

Tasks

• eywa_tasks — List tasks sorted by priority. Filter by status, assignee, milestone.
• eywa_task — Create a new task.
• eywa_pick_task — Claim an open task (sets status to claimed, creates work claim for conflict detection).
• eywa_update_task — Update status, add notes, reassign.
• eywa_subtask — Break a task into subtasks.

Collaboration

• eywa_status — See all agents, their work, systems, curvature scores.
• eywa_claim — Declare your work scope and files. Triggers conflict detection.
• eywa_context — Get shared context from all agents.
• eywa_msg — Send a message to a specific agent or all.

Navigation

• eywa_destination — Set, update, or view the team destination with milestones and progress tracking.

Workflow

1. Start: Call eywa_start with what you're working on. Read the snapshot.
2. Claim: If picking up a task, call eywa_pick_task. Otherwise call eywa_claim with your scope.
3. Work: Do your work. Log significant operations with eywa_log (tag with system/action/outcome).
4. Learn: Store any knowledge worth keeping with eywa_learn.
5. Done: Call eywa_done with summary, status, artifacts, and next steps.

When to log

| Event | system | action | outcome | |-------|--------|--------|---------| | Read a file | filesystem | read | success | | Write/edit a file | filesystem | write | success | | Create new file | filesystem | create | success | | Run tests | ci | test | success/failure | | Git commit | git | write | success | | Git push | git | deploy | success/failure | | Deploy to staging/prod | deploy | deploy | success/failure | | API call | api | read/write | success/failure | | Database migration | database | write | success/failure | | Hit a blocker | (relevant) | (relevant) | blocked |

Log enough that another agent could understand what you did and continue your work.

Key principles

• Coordinate, don't duplicate: Check eywa_status and eywa_tasks before starting work. If another agent is already on it, pick something else.
• Log operations: Every significant action should be tagged. Invisible agents have zero curvature.
• Store knowledge: If you discover something useful (a pattern, a gotcha, a convention), call eywa_learn. Future sessions benefit.
• Work toward the destination: Check eywa_destination to understand the goal. Your work should converge toward it.