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
bash {baseDir}/eywa-call.sh <tool_name> '<json_arguments>'
```

Examples:

```bash
# 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.