eywa

多智能体协调、空间记忆和群体导航。连接到 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.

---

## 中文说明

# Eywa：多智能体协调层

你现在已连接到 Eywa，一个面向智能体群体的协调层。Eywa 在多个并发智能体之间为你提供共享的空间记忆、任务管理、冲突检测和目的地导航。

## 设置

你的 Eywa 连接通过环境变量进行配置：

- `EYWA_ROOM` — 房间标识（slug，例如 `demo`、`my-project`）
- `EYWA_AGENT` — 你的智能体身份前缀（例如 `openclaw`）。服务器会追加一个唯一后缀，如 `/jade-dusk`。
- `EYWA_URL` — MCP 端点（默认：`https://eywa-mcp.armandsumo.workers.dev`）

位于 `{baseDir}/eywa-call.sh` 的辅助脚本负责处理所有 MCP 通信。

## 如何调用 Eywa 工具

使用 `exec` 工具运行辅助脚本：

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

示例：

```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"]}'
```

## 可用工具

### 会话生命周期
- **eywa_start** — 启动一个会话。返回房间快照，包含活跃智能体、近期活动、任务、目的地以及相关知识。始终先调用此工具。
  - `task_description`（必填）：你正在处理的工作
  - `continue_from`（可选）：从中加载上下文的智能体名称（接力交接）

- **eywa_done** — 以结构化摘要标记会话完成。
  - `summary`、`status`（completed/blocked/failed/partial）、`artifacts[]`、`tags[]`、`next_steps`

- **eywa_stop** — 用摘要快速结束会话。

### 记忆与日志
- **eywa_log** — 用语义标签记录一次操作。其他智能体和人类可以看到你在做什么。
  - `role`、`content`、`system`（git/api/deploy/filesystem/等）、`action`（read/write/create/deploy/test/等）、`scope`、`outcome`（success/fail