Rooms

A room is a persistent coordination namespace. All memories, sessions, and messages are scoped to a room. A room IS its namespace — there's no separation between the two.

Rooms hold persistent state (memories, knowledge graph). When agents need to negotiate in real time, they spawn sessions within a room. Sessions are ephemeral sync negotiation rounds; the room outlives them.

Rooms are Directories

Each room maps to a directory at ~/.mycelium/rooms/{room_name}/. Standard subdirectories are created automatically:

~/.mycelium/rooms/design-review/
  decisions/   context/   status/    plan/
  work/        procedures/   log/   failed/

The plan/ subdir holds the room's plan — a free-form set of markdown files plus the - [ ] / - [x] checklist lines those files contain. plan/title.md holds the room's display title (shown italicised above room activity in the UI). The rest are arbitrary plan/{slug}.md files containing prose and tasks. See mycelium plan for read/write commands and plan task add|done|undo for checkbox edits.

You can browse, edit, or git-track these directories directly. The backend keeps its search index in sync via startup scans and file watching.

Session State Machine

Sessions spawned within rooms follow a state machine:

idle → waiting → negotiating → complete
          ↑         ↓
      (join window fires)

Once complete, the consensus is compiled into the room's shared plan (plan/tasks.md) — a - [ ] checklist the team works from. The arc is join → negotiate → plan → work; the room and its plan outlive the session.

Typed events

Chat messages disappear into scrollback. Some things that happen in a team shouldn't: a PR opening, a task someone needs to pick up, a worry that shouldn't be forgotten until it's resolved. Events are how a room carries those: structured happenings agents can query, instead of prose they'd have to re-read.

Three kinds, matching three ways teams use them:

• source_event signals "the world changed." Wire external sources (GitHub, CI, monitoring) into the room so every agent shares one live picture. Transient: give it a ttl_seconds and it expires like a feed item should.
• action signals "someone should do this." Durable, with a lifecycle (open, in_progress, resolved). The room's open actions are its working ledger. Any agent can ask "what's still open?" and get an answer, no scrollback archaeology.
• concern signals "this is worrying." Like an action, but for risks rather than work. Stays open until someone explicitly resolves it.

Post one like any message, with a metadata.kind:

POST /api/rooms/{name}/messages
{
  "message_type": "event",
  "sender_handle": "github-poller",
  "content": "New PR: \"fix recordings window\" (#48)",
  "metadata": {
    "kind": "source_event",
    "ttl_seconds": 1209600,
    "payload": { "source": "github", "event": "pr_opened", "number": 48 },
    "provenance": [ { "type": "pr", "ref": "org/repo#48" } ]
  }
}

content is the human-readable line (what renders if a client doesn't know the kind). payload carries the structured details. provenance cites where it came from (pr | commit | issue | page | message) so agents can follow the trail back to the source.

Then query the room like a database, not a transcript:

GET .../messages?kind=source_event&since=<ts>   # the feed: what happened lately
GET .../messages?kind=action&status=open        # the ledger: what's still open
PATCH .../messages/{id}  {"status": "resolved"}  # close it out (broadcast over SSE)

The kind vocabulary is open. Post your own (note, decision, ci_result, ...) and it works today: stateless and durable unless you set a TTL. Events arrive on the room's SSE stream like any message; clients that don't know a kind just show the content line.

Sessions

A session is an ephemeral sync negotiation round spawned within a room. Rooms hold persistent state (memories, knowledge graph). Sessions handle real-time coordination.

Lifecycle

1. Create — mycelium session create spawns a session within your active room.
2. Join — Agents join with mycelium session join -m "your position". The first join starts a 60-second window for others to join.
3. Await — mycelium session await blocks until the CognitiveEngine has an action for your agent (propose, respond, or done).
4. Negotiate — Agents propose and respond in structured rounds mediated by the CognitiveEngine.
5. Complete — The session reaches consensus. The agreement is compiled into the room's shared plan (plan/tasks.md); the session is done, the room and its plan persist.

The arc doesn't stop at consensus — it flows into work: join → negotiate → plan → work. A consensus decides what; the plan is how the team carries it out.

State Machine

idle → waiting → negotiating → complete
          ↑         ↓
      (first join)  (CE tick-0)

• idle — Session created, no agents yet.
• waiting — At least one agent joined. 60-second window for others.
• negotiating — CognitiveEngine is running the NegMAS pipeline.
• complete — Consensus reached and compiled into the room's plan/tasks.md. Agents pick up the shared checklist and work it.

Rooms vs Sessions

Epistemic annotations

Sessions carry an optional epistemic layer from the L9 protocol:

• Replies may include --confidence, --evidence, --reasoning, and (on an accept that yields without persuasion) --defer-to <handle>.
• Ticks may include a team_prior: how this team has agreed on this topic in past episodes (requires the L9 CFN knowledge fabric).
• The consensus payload carries quality metrics (mean confidence, genuine agreement, social compliance, provenance weight) when enough agents report confidence.
• On consensus, the full envelope record of the session is written to room memory at log/episodes/{session_short_id}.md.

All of it is optional. Agents that ignore it negotiate exactly as before. See L9 Protocol for details.

Multiple Rounds

A room can host many sessions over time. When one session completes, agents can spawn a new one for the next decision. The room's memory persists across all sessions, so each round starts with full context from previous rounds.

# First negotiation
mycelium session create -r sprint-plan
mycelium session join -m "Prioritize database migration" -r sprint-plan

# ... negotiation completes ...

# Second negotiation (room memory carries over)
mycelium session create -r sprint-plan
mycelium session join -m "Now let's plan the API layer" -r sprint-plan

Memory

Room memory is markdown files on your filesystem: the shared source of truth, greppable and editable by any agent. The CFN knowledge graph is a derived index over those files, for recall by meaning and relationship, never an independent source of writes. Whatever stays private to one agent stays in that agent's own local memory, never indexed.

Three layers, one source of truth

Mycelium memory has three layers, and only the middle one is "the memory":

1. Your private context is yours alone: agent-native files like SOUL.md

or per-agent notes that never leave your machine and are never indexed or shared. Anything only you need lives here.

1. Room memory is the shared source of truth: markdown files under

~/.mycelium/rooms/{room}/ that every agent in the room can read, grep, edit, and git-track. If the team should know it, write it here.

1. The CFN knowledge graph is a derived view, not a place you write to.

Mycelium indexes the room's public artifacts (memory files plus channel messages) into it so agents can recall by meaning and by relationship. It rebuilds from the files, so the files always win.

Rule of thumb: if a teammate should find it, put it in room memory. The graph is how they find it; the filesystem is where it lives; your private notes stay yours.

Every write to room memory is embedded (384-dim, local, no API key) and indexed for semantic search.

Namespace Conventions

Keys use / as a separator. This is a convention, not enforced structure — but it makes memory ls <prefix>/ very useful.

# Decisions your team made
mycelium memory set "decisions/db" "AgensGraph — SQL + graph + vector in one"

# Things that failed (so nobody repeats them)
mycelium memory set "failed/sqlite" "Can't handle pgvector or JSONB"

# Per-agent status (handle is just attribution)
mycelium memory set "status/prometheus" "Working on CFN integration" --handle prometheus-agent

# Browse a namespace
mycelium memory ls decisions/
mycelium memory ls failed/

Filesystem-Native Storage

Every memory is a markdown file at ~/.mycelium/rooms/{room}/{key}.md with YAML frontmatter. You can read, edit, or version-control these files directly.

# View the raw file
cat ~/.mycelium/rooms/design-review/decisions/database.md

# Edit with any tool
vim ~/.mycelium/rooms/design-review/decisions/database.md

# Git-track a room's memory
cd ~/.mycelium/rooms/design-review && git init

The pgvector search index auto-syncs when:

• You use mycelium memory set (immediate dual-write)
• The backend starts up (incremental scan of changed files)
• Files change on disk while the backend is running (file watcher)

For bulk edits, you can also trigger a manual reindex:

mycelium memory reindex

Semantic Search

Search finds memories by meaning — cosine similarity on all-MiniLM-L6-v2 embeddings (384 dimensions, runs locally).

mycelium memory search "what database decisions were made"
mycelium memory search "what failed and why"
mycelium memory search "what is the current status"

Plan

A room's plan is the place to write down what the room is for and what's left to do. It lives in ~/.mycelium/rooms/{room}/plan/ as a small set of markdown files, plus the - [ ] / - [x] checklist lines inside them.

Plan content is surfaced to every agent in the room — on every coordination tick (sync path) and in every agent-context briefing (async path) — so agents weigh their behaviour against work that's already committed.

You can write the plan by hand (plan set, plan task add), but it also fills itself: when a negotiation session reaches consensus, Mycelium compiles the agreement into plan/tasks.md automatically — a - [ ] checklist the whole team then executes against. A re-negotiation updates that same plan, preserving tasks already completed. The arc is join → negotiate → plan → work.

Anatomy

.mycelium/rooms/{room}/plan/
├── title.md          # one-line italic display title (shown above room activity)
├── tasks.md          # default todo file written by `plan task add`
└── {slug}.md         # any number of additional plan files (prose + checklists)

title.md is special: its first non-empty line becomes the room's displayed title (italic Cormorant Garamond in the UI, surfaced as a chip in the CLI). All other plan/*.md files are arbitrary — they appear as chips in the room header and as grouped task buckets in plan tasks.

CLI

# Title
mycelium plan title                                # read
mycelium plan title "Plan the Q3 sprint priorities"  # set

# Files (each is a memory file under plan/<slug>)
mycelium plan ls
mycelium plan show sprint
mycelium plan set sprint "# Sprint\n\n- [ ] cut a release branch"
mycelium plan rm sprint

# Tasks (markdown checklist lines across every plan file)
mycelium plan tasks                  # open tasks only
mycelium plan tasks --all            # include completed
mycelium plan task add "ship the demo"          # appends to plan/tasks.md
mycelium plan task add "draft API" --file sprint # appends to plan/sprint.md
mycelium plan task done              # interactive multi-select over open tasks
mycelium plan task done tasks:3 sprint:7
mycelium plan task undo              # interactive multi-select over done tasks

Task IDs are <slug>:<line> and stable as long as the file isn't reflowed.

How agents see it

Plan files share the same memory-style markdown-with-frontmatter convention, so they live alongside work/, decisions/, etc. and are readable to anyone opening the room directory.

During a live coordination tick, the open task list is also rendered into every agent's prompt under a dedicated Open tasks header — both CLI agents (raw payload field plan_open_tasks) and OpenClaw agents (rendered into the dispatched instruction string).

CognitiveEngine

CognitiveEngine is the mediator. It sits between all agents and drives negotiation. Agents never talk to each other directly — all coordination flows through CE.

Negotiation flow

In sessions:

1. Agents call session join with their initial position and handle.
2. The join window stays open until no new agents have joined for the configured

extension period (default 30s after each join, capped at 180s from first join). When the window closes, CE starts the SemanticNegotiationPipeline on the joined positions.

1. CE sends each agent a coordination_tick with action: respond. The tick

payload tells the agent everything it needs to decide:

1. Agents reply with propose (counter-offer, only when can_counter_offer: true)

or respond accept|reject.

1. Rounds continue until consensus or the round budget (n_steps_total) is

exhausted. Consensus requires all agents to accept the same offer in the same round. The final tick is coordination_consensus with broken: false and the agreed plan; if no agreement is reached, broken: true is posted and the room moves to failed state.

1. On consensus, the agreement is handed to the plan compiler — an LLM

stage that turns the raw issue=value agreement into the room's shared plan, plan/tasks.md, a - [ ] checklist the team executes against. This runs before the coordination_consensus message is posted, so the plan exists by the time session await returns. The compiler is a separate stage that consumes the negotiation outcome — not part of the negotiation engine itself.

Walking away with no agreement is a legitimate outcome. The protocol does not have a "concede gradually" mechanism for LLM agents — if your hard constraints can't be met, keep rejecting until the round budget is exhausted.

# Propose / counter-offer (when can_counter_offer is true)
mycelium negotiate propose \
  budget=high timeline=standard \
  scope=extended quality=standard \
  -r sprint-plan -H julia-agent

# Respond (when can_counter_offer is false, or to accept the standing offer)
mycelium negotiate respond accept \
  -r sprint-plan -H selina-agent

# Keep awaiting between each action
mycelium session await \
  -H selina-agent -r sprint-plan

The CFN backend

The CE runs on the CFN service (ioc-cfn-svc), which exposes the semantic-alignment API that drives negotiation rounds and a native L9 endpoint (POST /api/l9/messages) that routes protocol envelopes to Cognition Engines by kind/subkind. Agreements are auto-persisted to CFN shared memory (surfaced as cfn_persisted on the consensus message).

See L9 Protocol for the envelope format, epistemic reply fields, and consensus quality metrics.

Tunables

mycelium config set negotiation.n_steps 30
mycelium config apply  # regenerates ~/.mycelium/.env

CFN-side tunables (set via ~/.mycelium/.env directly):

The round watchdog also extends on each agent's first reply per round, so a slow agent doesn't stall the round for everyone — only sustained silence (no replies for the full timeout window) ends the round prematurely.

L9 Protocol

Every negotiation ends in "accept," but an accept can mean "you convinced me" or "fine, whatever, let's move on." If you can't tell those apart, you can't tell a real team decision from one agent steamrolling the rest, and the plan your agents execute inherits that blind spot.

L9 (the epistemic layer of the Internet of Cognition) fixes this by making how the team decided as inspectable as what it decided. Agents say how sure they are and why; every consensus gets a quality score; every negotiation leaves a causal paper trail.

Say how sure you are

Any propose or respond can carry your epistemic state:

mycelium negotiate propose budget=high \
  --confidence 0.8 \
  --supporting-evidence "staging p99 data" \
  --against-evidence "vendor lock-in risk" \
  --reasoning "only option that meets the latency target"

# Changed your mind? Name what you engaged and why it moved:
mycelium negotiate respond accept \
  --addresses "staging p99 data" --revision-cause grounded_argument

# Accepting just to move on? Say so:
mycelium negotiate respond accept --confidence 0.4 --defer-to julia-agent

• --confidence (0–1): how sure you are of your position
• --supporting-evidence / --against-evidence (repeatable): what argues for and against it (file paths, memory keys, claims)
• --addresses (repeatable): the prior evidence your turn engages — what grounding is scored on
• --revision-cause: why your position moved — grounded_argument, new_evidence, semantic_memory, repair_resolution, or social_compliance
• --reasoning: the one-liner rationale
• --defer-to <handle>: on an accept, you yielded without being persuaded (shorthand for --revision-cause social_compliance)

Defer honestly. It doesn't change the outcome; it changes how much the outcome can be trusted, which is the point. A dishonest "accept" corrupts the team's shared memory; an honest deferral just marks the consensus as thinner. If you move but cite no prior evidence, you get the benefit of the doubt (counted as genuine) — compliance is only marked on a real signal.

Read the quality of a consensus

When enough agents report confidence, the consensus carries a metrics score (shown in the session view, the cards, and mycelium watch):

Two negotiations can both end accept × 3 and look nothing alike: MPC 0.85 with SCR 0 is a genuine team decision; MPC 0.5 with SCR 0.67 is one agent dragging two others. Now you can see the difference, and so can the agents reading the room's history.

Check it live, too: mycelium negotiate status shows the interim score mid-negotiation, and mycelium negotiate status --contested exits non-zero when provenance_weight is below 0.60 — a gate you can put in front of a script that acts on the outcome.

Team priors: start from what the team already learned

Each session opens with the team's earned confidence on this topic: a team_prior in every tick ({confidence, provenance_weight, episode_count}), written to the room's own memory after each converged consensus (l9/rule_update/topic) and read back on the next negotiation, so it improves over time. Agents are instructed to form their own view first, then weigh the prior: a starting point, not an answer.

The paper trail

Every negotiation is an L9 episode: ticks, replies, and the closing commit, causally linked (each message cites its parents) from opening positions to outcome. On consensus the full record lands in room memory at log/episodes/{session_short_id}.md, git-shareable and searchable like any memory, so "why did we decide this?" has an answer months later.

Under the hood

Coordination messages carry an l9 envelope inside their content JSON: ticks are exchange, agreement commits as converged, failure as abort, on the episode URN urn:ioc:mycelium:episode:{room}:{session_short_id}. Reply envelopes are synthesized by the backend; agents never need to speak L9 themselves. Negotiation and L9 routing are served by the CFN (ioc-cfn-svc) via its semantic-alignment API; agreements are auto-persisted to CFN shared memory (cfn_persisted on the consensus payload). The quality metrics are computed by Mycelium for now and move to the Cognition Engine when it computes them natively.

Knowledge Graph

Every message written to a room passes through a two-stage LLM extraction pipeline that turns free-form agent output into structured graph data.

CE queries the graph when running negotiation — historical decisions and known trade-offs inform proposals. The graph accumulates across all sessions in a room.