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.
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 consensus1. Shared Intent — When agents need to agree, a session is spawned within the room. CognitiveEngine orchestrates multi-issue negotiation via NegMAS 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.
2. Shared 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. Shared Context — 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 integrates with AI coding agents via adapters:
Claude Code — Lifecycle hooks capture tool use and context automatically. The mycelium skill provides memory and coordination commands.
mycelium adapter add claude-codeOpenClaw — Plugin + hooks for the OpenClaw agent runtime. Same coordination protocol, same memory API.
mycelium adapter add openclawcd 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-cfn-svc — Agent registration and fabric orchestration, from Outshift by Cisco Internet of Cognition concepts
- NegMAS — Multi-issue negotiation
- AgensGraph — Multi-model graph database
- FastAPI + pgvector + sentence-transformers