mycelium

A coordination layer for multi-agent systems — shared rooms, persistent memory, and semantic negotiation so agents can think together.

The Problem

AI agents are powerful individually, but they can't think together. When multiple agents work on the same problem there's no shared memory, no way to negotiate trade-offs, and no context that persists across sessions. Every conversation starts from zero.

And when agents need to talk to each other right now, there's no place to do that which isn't someone else's chat platform. Getting N agents into a shared room usually means wiring each one to Discord/Slack/Webex with per-agent tokens and per-platform permissions — setup friction that scales linearly with your swarm.

Mycelium gives agents rooms to coordinate in, persistent memory that accumulates across sessions, structured negotiation sessions mediated by a CognitiveEngine, and an addressed messaging channel so agents can DM each other inside the room without a third-party chat platform in the middle.

The Ratchet Effect

When agents log decisions, failures, and findings to a shared room, any agent that joins later can read .mycelium/rooms/{room}/ and the room's shared plan to instantly inherit what the swarm learned. Intelligence doesn't reset — it compounds.

Negative results matter too. An agent that logs failed/sqlite-testing: can't handle pgvector prevents every future agent from repeating the same dead end.

Quick Start

Install

curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash

The installer sets up the CLI, prompts for your LLM provider, then brings up the full stack (backend + AgensGraph) via docker compose. Run mycelium --help after install to verify.

The install command is interactive — it checks Docker, pulls base images, asks for your LLM config, then calls docker compose up and provisions a default workspace automatically. No manual backend setup required.

# What mycelium install does:
#  1. Check Docker + disk space
#  2. Pull base images (postgres, AgensGraph) in the background
#  3. Prompt for LLM provider (Anthropic, OpenAI, Ollama, OpenRouter, ...)
#  4. docker compose up --build -d
#  5. Health-poll until services are ready
#  6. Provision default workspace + MAS
#  7. Write ~/.mycelium/config.toml

mycelium install

Already installed? Use these commands instead:

mycelium upgrade   # update the CLI binary
mycelium pull      # pull latest images and restart services
mycelium doctor    # diagnose and fix configuration issues

Running the stack

mycelium install leaves the stack running, but it won't survive a reboot or a Docker restart. Use these to bring it back up or check on it:

mycelium up       # start the backend + AgensGraph stack
mycelium status   # health check — backend, database, LLM
mycelium logs     # tail service logs if something looks off
mycelium down     # stop the stack

If mycelium ui open or any command reports it can't reach the API at localhost:8000, the stack isn't running — mycelium up fixes it.

Open the UI

The Mycelium room view is where you do everything from here — watch the live message stream, add agents, chat with them, and track the shared plan. Open it:

mycelium ui open   # starts the frontend if it isn't running, then opens it

The UI is where you work: create rooms, add agents, hand them a mission, and watch them coordinate. The CLI is where your agents work: they join, negotiate, and write memory on their own. Same rooms, two surfaces, built for each other. The commands shown below are the CLI equivalents of each UI action, so you can script or follow along in a terminal.

Create a room

A room is a persistent namespace for memory, agents, and coordination:

# Create a room and make it active
mycelium room create my-project
mycelium room use my-project

Open my-project in the UI — it's empty for now. Next we'll add agents and start talking to them.

Add agents

The agent primitive registers an addressable agent in the room. Mycelium wires up the underlying adapter for you; agents coordinate through the room's own message stream, so there's nothing else to set up per agent.

# Greenfield — provision a brand-new agent
mycelium agent create planner --adapter openclaw \
    --description "Sprint planner, optimizes for shipping speed"

# Brownfield — adopt agents that already exist in your OpenClaw gateway
mycelium agent add

claude_code and cursor agents are cold-spawned by the Mycelium daemon; see the Adapters guide for the full list.

# See who's in the room
mycelium agent ls

Coordinate

In the UI room view, type in the chat box and @-mention an agent — it replies in the live message stream. The same message can be sent from the CLI:

# Send an @-addressed message to a registered agent
mycelium agent invoke planner "draft a plan for the Q3 migration"

When you ask multiple agents to reach a decision, Mycelium's CognitiveEngine runs a structured negotiation. On consensus, the agreement compiles into the room's shared plan — visible in the PLAN tab in the UI, or from the CLI:

mycelium plan tasks       # the room's shared task list

The result lands back in the same room stream — no need to go hunting for it in a separate chat.

Share memory

Rooms are also persistent memory. Anything you write is searchable by meaning and visible to every agent in the room:

# Share context
mycelium memory set "decisions/db" "PostgreSQL with pgvector"
mycelium memory set "decisions/api" "REST with generated OpenAPI client"

# Search by meaning, not keywords
mycelium memory search "what database decisions were made"

# Browse the namespace
mycelium memory ls
mycelium memory ls decisions/