slm-mesh

Files (1)

• SKILL.md

SKILL.md (first lines)

# slm-mesh — Cross-Session Peer Coordination

The mesh network lets multiple AI agent sessions on the same machine discover
each other and coordinate in real time — without writing to the persistent
memory store. Mesh messages are transient (48-hour TTL); they complement memory
(which is durable) rather than replacing it.

By default the mesh is local: the SLM daemon on this machine is the broker and
nothing leaves it. Two machines can be joined only if the user sets
`SLM_MESH_PEER_URL` and `SLM_MESH_SHARED_SECRET` for their daemons; then peers and
messages cross to the other machine. Do not configure that yourself.

---

## Profile requirement

Mesh tools are registered in the `full`, `power` and `mesh` MCP tool sets and in
the default set that applies when the host configures none. They are not in
`core` or `code`. The tool set is fixed when the MCP server starts, and
`switch_profile` cannot change it (it changes the active memory profile). If the
tools are missing, check `SLM_MCP_PROFILE` in the host's MCP config and ask the
user before changing it. See `slm-profile`.

---

## Tool reference

### 1. `mesh_summary` — announce what this session is doing

```
mesh_summary(summary: str = "") -> dict
```

Call at session start to register on the mesh and announce your purpose. Other
sessions can see your summary via `mesh_peers`. The session stays alive via
automatic heartbeat.

```
mesh_summary(summary="Refactoring auth module in api/src/auth/")
```

Response: `{peer_id, summary, project_path, registered, heartbeat_active, broker_response}`

Call this once at the start of any session that will participate in the mesh.
The peer registration happens automatically at MCP startup, but calling
`mesh_summary` sets the human-readable description that other agents see.

---

### 2. `mesh_peers` — list active sessions

```
mesh_peers() -> dict
```

Returns all active peer sessions on this machine.

```
mesh_peers()
```

Response: `{peers: [{peer_id, summary, project_path, last_seen}], count, my_peer_id}`

Use this to discover other sessions before sending a message or checking for
conflicts.

---

### 3. `mesh_send` — send a message to another session

```
mesh_send(
  to: str,       # peer_id | "broadcast" | "project:/path/to/dir"
  message: str,  # max 4 KB — use file paths for large data
) -> dict
```

Send a targeted, broadcast, or project-wide message.

```
# Direct message to a specific peer
peers = await mesh_peers()
target_id = peers["peers"][0]["peer_id"]
mesh_send(to=target_id, message="I'm starting work on auth/handler.py — please hold off")

# Broadcast to all sessions
mesh_send(to="broadcast", message="Deploying to staging in 5 minutes")

# Message all sessions working in the same project
mesh_send(to="project:~/myproject", message="Tests are green on main")
```

**4 KB message cap.** For large payloads (diffs, file contents), write to a file
and send the path instead. The circuit breaker opens automatically if the daemon
is repeatedly unreachable — `mesh_send` returns `ok: false` in that case.

Two optional arguments: `refs` (up to 8 references to the owner's own items,
written `fact:<id>`, `doc:<id>` or `media:<id>`) and `reply_to` (the id of the
message this one answers).

```
mesh_send(to=target_id, message="The screenshot is saved", refs=["media:<media_id>"])
```

---

### 4. `mesh_inbox` — read messages sent to this session

```
mesh_inbox(ack: list[int] | None = None) -> dict
```

Returns unread messages (direct, broadcast, and project-targeted). For a local
session, messages are marked as read when returned and `ack` is ignored. A
connected web app uses `ack`; see "Web apps on the mesh" below.

```
inbox = await mesh_inbox()
for msg in inbox["messages"]:

From qualixar/superlocalmemory, AGPL-3.0.

More from qualixar/superlocalmemory