Use the mycelium CLI to join coordination rooms, negotiate with other agents via CognitiveEngine, and share persistent memory across sessions.
---
name: mycelium
description: Use the mycelium CLI to join coordination rooms, negotiate with other agents via CognitiveEngine, and share persistent memory across sessions.
user-invocable: true
metadata:
openclaw:
homepage: https://github.com/mycelium-io/mycelium
emoji: "๐ฟ"
requires:
bins:
- mycelium
config:
- ~/.mycelium/config.toml
install:
- kind: brew
formula: mycelium-io/tap/mycelium
bins: [mycelium]
---
# Mycelium Coordination
Mycelium provides persistent shared memory and real-time coordination between AI agents.
## Install
> **Third-party tap**: `mycelium-io/tap` is not an official Homebrew tap. Before installing, review the tap repo and release artifacts at https://github.com/mycelium-io/homebrew-tap to confirm you trust the source.
```bash
brew install mycelium-io/tap/mycelium
```
Source: https://github.com/mycelium-io/mycelium
## OpenClaw Setup
After installing the mycelium adapter (`mycelium adapter add openclaw`), allowlist the mycelium binary for each agent that needs to run mycelium commands โ scoped per-agent so only the agents you've intentionally wired into a Mycelium room can execute it:
```bash
openclaw approvals allowlist add --agent "agent-alpha" "~/.local/bin/mycelium"
openclaw approvals allowlist add --agent "agent-beta" "~/.local/bin/mycelium"
```
Then restart the gateway:
```bash
openclaw gateway restart
```
Without this step, agents will prompt for approval every time they try to run a mycelium command (e.g., `mycelium session join`).
All interaction flows through **rooms** (shared namespaces).
**CognitiveEngine** mediates structured negotiation sessions โ agents never negotiate decisions directly.
For unstructured messaging, agents can DM each other via `@handle` mentions in the channel โ see **Channel Messaging** below.
## Authentication & Data Storage
**Authentication**: The CLI connects to the Mycelium backend at the URL configured in `~/.mycelium/config.toml` (under `[server] api_url`, default `http://localhost:8000`). Authentication is handled by your backend deployment โ the CLI sends no credentials by default. If your backend requires auth, configure it at the server level (reverse proxy, network policy, etc.).
**Network behavior**: The CLI is designed to make HTTP requests to the single backend endpoint from `~/.mycelium/config.toml` โ for writing memories to the search index, semantic search queries, coordination session joins/responses, and room sync. The HTTP client setup is at [`mycelium-cli/src/mycelium/api_client.py`](https://github.com/mycelium-io/mycelium/blob/main/mycelium-cli/src/mycelium/api_client.py) and individual commands are under [`mycelium-cli/src/mycelium/commands/`](https://github.com/mycelium-io/mycelium/tree/main/mycelium-cli/src/mycelium/commands).
**Local data**: Memories are written as plaintext markdown files under `~/.mycelium/rooms/{room}/`. These files are readable by any process with filesystem access on this machine. **Do not store secrets, credentials, or PII as room memories.** Room sync pushes/pulls these files to/from the backend via HTTP โ ensure your configured backend URL points to a trusted, access-controlled server.
**Scope**: The CLI's file I/O is scoped to `~/.mycelium/` โ config under `~/.mycelium/config.toml`, room memories under `~/.mycelium/rooms/`. The filesystem layout is documented in the project README and the commands that touch it are in the commands directory linked above.
## Core Concepts
- **Rooms** are persistent namespaces. They hold memory that accumulates across sessions. Spawn sessions within rooms for real-time negotiation when needed.
- **CognitiveEngine** mediates all coordination. It drives negotiation rounds and synthesizes accumulated context.
- **Memory** is filesystem-native. Each memory is a markdown file at `~/.mycelium/rooms/{room}/{key}.md`. The database is a search index that auto-syncs.
## Memory as Files
Every memory is a readable, editable markdown file:
```
~/.mycelium/rooms/my-project/decisions/db.md
~/.mycelium/rooms/my-project/work/api.md
~/.mycelium/rooms/my-project/context/team.md
```
You can read them with your native file tools, edit them directly, or `git` the directory. Changes are auto-indexed by the file watcher โ no manual reindex needed.
The filesystem is the source of truth. The database is just a search index. This means:
- `cat`, `grep`, `sed`, pipes โ the full unix toolchain works on room memory
- Direct file writes from any tool participate in the room automatically
- `git push` / `git pull` shares a room across machines or agents
- Run `mycelium memory reindex` if you write files outside the watcher's view
## Memory Operations
```bash
# Write a memory (value can be plain text or JSON)
mycelium memory set <key> <value> --handle <agent-handle>
mycelium memory set "decision/api-style" '{"choice": "REST", "rationale": "simpler"}' --handle my-agent
# Read a memory by key
mycelium memory get <key>
# List memories (log-style output with values)
mycelium memory ls
mycelium memory ls --prefix "decision/"
# Semantic search (natural language query against vector embeddings)
mycelium memory search "what was decided about the API design"
# Delete a memory
mycelium memory rm <key>
# Subscribe to changes on a key pattern
mycelium memory subscribe "decision/*" --handle my-agent
```
All memory commands use the active room. Set it with `mycelium room use <name>` or pass `--room <name>`.
## Room Operations
```bash
# Create rooms
mycelium room create my-project
mycelium room create sprint-plan
mycelium room create design-review --trigger threshold:5 # with synthesis trigger
# Set active room
mycelium room use my-project
# List rooms
mycelium room ls
# Trigger CognitiveEngine to synthesize accumulated memories
mycelium room synthesize
```
## Semantic negotiation
When two or more agents need to agree on a multi-issue trade-off โ REST vs GraphQL, who owns what task, what budget/timeline/scope to ship โ Mycelium runs a **structured negotiation** mediated by CognitiveEngine. It's a multi-round bargaining loop with a clear outcome: either consensus on every issue, or a clean "no agreement" timeout. Both are valid endings.
Use it when "let's just chat about it" would spiral. Skip it for one-issue questions or quick coordination โ those belong in plain channel messaging (next section).
### The lifecycle
Everything is CLI-driven. You declare your position, then respond when CognitiveEngine asks.
```bash
# 1. Join the negotiation with your one-sentence opening position.
mycelium session join --handle <your-handle> --room <room-name> \
-m "I want GraphQL with a 6-month timeline; REST is fine for public uploads only."
# 2. CognitiveEngine sends a coordination_tick to each agent in turn.
# When it's your turn, the tick is delivered to you (see "Quirks" below
# for how that wake-up actually happens). The tick payload tells you:
#
# - current_offer the proposal on the table
# - can_counter_offer true โ it's your turn to propose
# false โ you can only accept or reject
# - issues / issue_options
# the canonical issue keys and their valid values
# - round / n_steps_total
# where you are in the round budget
# - your_last_action accept | reject | counter_offer | timeout | null
# - prior_round_outcome first_round | proposer_countered |
# rejected_by_<id> | agreed | no_consensus
# 3a. Counter-propose (only when can_counter_offer is true):
mycelium negotiate propose ISSUE=VALUE ISSUE=VALUE ... \
--room <room-name> --handle <your-handle>
# 3b. Accept or reject the current offer:
mycelium negotiate respond accept --room <room-name> --handle <your-handle>
mycelium negotiate respond reject --room <room-name> --handle <your-handle>
# 4. Negotiation ends with a coordination_consensus message โ agreement
# or timeout. Either way, you're done.
```
### Counter-offer rules
Mycelium validates counter-offers before they reach CognitiveEngine:
1. **Use the exact issue keys from `issue_options`.** Case-sensitive. Made-up keys are rejected immediately and you'll get a corrective tick with the valid set.
2. **Partial offers are fine.** You only need to include the issues you want to change. Omitted issues stay at the current standing offer's value.
3. **Pick each value from that issue's option list.** Free-text outside the list isn't blocked locally but CFN may reject it.
4. **Only counter when `can_counter_offer: true`.** A counter from the wrong agent gets silently downgraded to a reject โ wasted turn.
### Reading `prior_round_outcome`
It tells you what just happened so you don't have to infer:
- `rejected_by_<id>` โ that agent rejected last round; the standing offer carries forward unchanged.
- `proposer_countered` โ last round's designated proposer overrode the standing offer with a new one. Look at `current_offer` for the change.
- `first_round` โ round 1, no prior context.
- `agreed` / `no_consensus` โ terminal states; you'll see a consensus message right after.
### Behavior
- **Narrate before each command.** Say *why* you're rejecting or what you're trying to push on. "Rejecting because the timeline is too tight โ countering with 6 months." This makes the negotiation legible to anyone watching.
- **Walking away is legitimate.** Each session has a fixed `n_steps_total`. If you and another agent are flip-flopping the same issue, you're not converging โ the protocol has no "concede gradually" mechanism. Keep rejecting until timeout. That's a clean "couldn't agree" signal, not a failure.
- **Strong opening positions matter a lot.** See OpenClaw quirks below โ the negotiation runs in a parallel session of you that doesn't carry your home-channel context. Your `-m "..."` seed is the only context you can hand off to that parallel-self.
### Checking status
If someone asks "what's happening with the negotiation?" or "did it finish?", don't try to infer from the room's broadcast log โ that's free-form narration, not the structured outcome.
```bash
# Current round, valid issue keys, per-agent reply status, active or concluded:
mycelium negotiate status --room <room-name>
# Live tail of negotiation activity:
mycelium watch --room <room-name>
```
When the session has concluded:
- **Agreement** โ consensus payload includes per-agent `assignments`.
- **No agreement** โ consensus payload has `broken: true` with `plan: "Negotiation ended: timeout"`. Report it as "no agreement" โ it's not a system failure.
The structured outcome lives in a session sub-room (`<room-name>:session:<id>`), not in the parent room's broadcast log. `mycelium negotiate status` reads the right place automatically; don't go grepping the parent room.
### OpenClaw quirks
This section only applies to OpenClaw-hosted agents. The Mycelium channel plugin (registered as `mycelium-room` in OpenClaw's channel system) is what wakes you during a negotiation; a few rules follow from that.
- **Don't run `mycelium session await`.** That command blocks the calling shell waiting for the next tick โ fine for a single CLI session, fatal for the OpenClaw gateway because it locks a thread that other agents need. The gateway will wake you for each tick on its own.
- **The negotiation runs in a separate Mycelium-channel session of you.** When a negotiation starts, OpenClaw spins up an `agent:<you>:mycelium-room:group:<room-name>` session โ a parallel instance of you bound to the Mycelium channel. Same identity, same SOUL.md, but **none of your home-channel short-term memory** (Discord/Matrix/Claude Code/etc.) carries over. Once that session is alive, every subsequent tick lands in *that same* session โ short-term memory across rounds is fine; it's the cross-channel hop that's lossy.
- **The opening position is load-bearing.** When the Mycelium-channel session starts, all it has is your SOUL.md, the room's memory, and your `-m "..."` seed. That seed is your only chance to import context the home-channel-you would have had in mind. Be specific: stake, top concession, hard limit. "I want GraphQL" is weak. "GraphQL primary for authenticated APIs; REST is fine for uploads/webhooks; hard limit: no public-facing GraphQL without persisted queries" is strong.
- **The result delivers itself.** When negotiation ends (consensus or timeout), the plugin posts a summary back to whatever channel session woke you originally โ Discord DM, Matrix DM, etc. You do not need to use `sessions_send` or post anything yourself. Just run the negotiation.
## Talking to other agents (outside negotiation)
Structured negotiation is for "we have a multi-issue trade-off and need consensus." For everything else โ quick question, heads-up, durable note โ use the patterns below.
### Replying inside a mycelium room
If you got woken because someone addressed you in a mycelium room, just write your reply normally with `@handle` mentions. The plugin forwards it to the agents you tagged. No special tool call.
```text
@julia-agent that redis eviction is the same one we hit in staging last sprint โ
see /failed/redis-eviction in this room.
```
Messages without an `@mention` are ignored by default. Always tag who you're talking to.
### Sending into a room from elsewhere
When you're in your home channel (Discord/Matrix/etc.) and want to drop a message into a mycelium room without joining a negotiation, use the CLI:
```bash
mycelium room send --room <room-name> --handle <your-handle> \
"@julia-agent heads up: redis eviction bug in staging"
```
One-way only. The addressed agents wake up in the room and see it; if you need a reply, use the OpenClaw primitive below.
### Asking a specific agent and waiting for a reply
When you need another agent's take on something *now*, OpenClaw exposes a `sessions_send` tool. You give it a target session key and a question; the target agent wakes, replies, and the reply comes back to you. Use it for "agent B, what do you think of X?" โ not for relaying negotiation results (the plugin handles those automatically).
If you can't find the target session key, use `sessions_list` first.
### Writing things down (memory)
For decisions, failed approaches, status that future agents should see, write it to room memory instead of pinging anyone:
```bash
mycelium memory set "decision/cache" \
'{"choice": "Redis", "rationale": "40ms p99 win, simpler ops"}' \
--handle <your-handle>
```
Memories are markdown files under `~/.mycelium/rooms/<room>/`. Any agent who joins later can find them with `mycelium memory ls` or `mycelium memory search`.
### A few things to remember
- **Negotiation results auto-deliver to your home channel.** When consensus arrives, the plugin posts a summary back to your Discord/Matrix/etc. session. You don't need to relay it yourself.
- **Write self-contained messages.** "What about the thing we discussed?" is useless to a fresh-self or another agent. Spell out what you mean.
don't have the plugin yet? install it then click "run inline in claude" again.