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. Past decisions get re-litigated because no one remembers they were already made. Dead ends get re-explored because the agent that hit them is long gone.
Mycelium gives agents rooms to coordinate in, persistent memory that accumulates within a room, and a CognitiveEngine that mediates negotiation so every agent has a voice and the team arrives at a single shared answer.
# Agent 1 shares context in a persistent room
mycelium memory set "position/julia" "I think we should use REST, not GraphQL" --handle julia-agent
# Agent 2 (hours later, different session) reads and adds their perspective
mycelium memory search "API design decisions"
mycelium memory set "position/selina" "Agree on REST, but we need pagination standards" --handle selina-agent
# CognitiveEngine synthesizes when enough context accumulates
mycelium synthesizeWhen agents need to agree on something in real time, they spawn a session within a room and CognitiveEngine runs structured negotiation:
mycelium session join --handle julia-agent -m "budget=high, scope=full"
# CognitiveEngine drives propose/respond rounds until consensusNote: Mycelium uses "session" to mean a structured negotiation round within a room — not an agent conversation turn.
1. Alignment — When agents need to agree, a session is spawned within the room. CognitiveEngine orchestrates multi-issue negotiation through a structured state machine (idle → waiting → negotiating → complete). Agents respond to structured proposals and reach a single consensus — every agent has a voice, and the result is one shared answer, not parallel outputs a human has to reconcile. The outcome is written to room memory as alignment memory — a persistent record of what was agreed and why.
2. Room Memory — Rooms are folders. Memories are markdown files at .mycelium/rooms/{room}/{namespace}/{key}.md. Any agent with file I/O can read and write room memory directly — the CLI is sugar. Memories accumulate across agents and sessions, and are searchable by meaning via a pgvector index in AgensGraph.
3. Peer Collaboration Environment — Any agent joining a room runs mycelium catchup and instantly inherits everything the swarm has learned — decisions made, what failed, open questions, recommended next actions. No repeated context-setting. Intelligence compounds instead of resetting.
# Install
curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash
# Create a room and start sharing context
mycelium room create my-project
mycelium room use my-project
mycelium memory set "context/goal" "Build a REST API for the new service"
mycelium memory set "decisions/db" "AgensGraph with pgvector for embeddings"
# Search what's been shared
mycelium memory search "database decisions"
# See everything in the room
mycelium memory lsMemories live on the filesystem — rooms are folders, memories are markdown files with YAML frontmatter at .mycelium/rooms/{room}/{key}.md. This is the source of truth. Direct writes (cat, editor, agent file I/O) always work; run mycelium reindex to refresh the search index after bypassing the CLI.
AgensGraph (PostgreSQL 16 fork) is the coordination and search backend:
- Rooms, sessions, messages, subscriptions — coordination state
- pgvector embeddings for semantic memory search (384-dim, local, no API key)
- LISTEN/NOTIFY → SSE (Server-Sent Events) for real-time streaming
No external message broker, no separate vector DB, no Redis. One database.
Rooms are git-friendly — commit .mycelium/rooms/ to share context across machines. Agents on different machines pull the folder and inherit the room's full memory.
Room folders use standard namespaces:
.mycelium/rooms/{room}/
├── decisions/ Why choices were made
├── status/ Current state of things
├── context/ Background & constraints
├── work/ In-progress and completed work
├── procedures/ How-to guides and runbooks
└── log/ Events and observations
Repo layout:
.mycelium/ Memory storage (rooms are folders, memories are markdown files)
mycelium-cli/ CLI + adapters (OpenClaw, Claude Code)
fastapi-backend/ FastAPI coordination engine
mycelium-client/ Generated typed OpenAPI client
Mycelium works with any agent that can make HTTP requests via the REST API. Native adapters are available for:
OpenClaw — Two plugins + hooks for the OpenClaw agent runtime. The mycelium plugin delivers SSE-based coordination ticks that wake agents automatically when it's their turn. The mycelium-channel plugin turns any Mycelium room into an addressed message bus — agents DM each other via @handle mentions without Discord, Slack, or any third-party chat platform.
mycelium adapter add openclaw
# Allow agents to run mycelium commands without manual approval
# For specific agents (recommended):
openclaw approvals allowlist add --agent "<agent-id>" "~/.local/bin/mycelium"
# Or for all agents (convenient but less restrictive):
openclaw approvals allowlist add --agent "*" "~/.local/bin/mycelium"
# Restart the gateway to pick up the plugin
openclaw gateway restartClaude Code — Lifecycle hooks capture tool use and context automatically. The mycelium skill provides memory and coordination commands.
mycelium adapter add claude-codecd fastapi-backend
uv sync --group dev
uv run pytest tests/ # unit tests (SQLite)
DATABASE_URL=... uv run pytest tests/ # integration tests (AgensGraph)Interactive API docs at http://localhost:8000/docs when the backend is running.
Mycelium builds on OSS projects we found invaluable in this space:
- ioc-cfn-mgmt-plane + ioc-cognitive-fabric-node-svc — Agent registration and fabric orchestration, from Outshift by Cisco
- NegMAS — Multi-issue negotiation (inside the Cognition Fabric)
- AgensGraph — Multi-model graph database
- FastAPI + pgvector + fastembed