From a04ff17ddf7bde2a8a0e7b2078d0e51e2a8a031d Mon Sep 17 00:00:00 2001 From: jodeev <48965776+jodeev@users.noreply.github.com> Date: Fri, 3 Apr 2026 14:06:59 -0700 Subject: [PATCH 1/6] Update README: clarify problem statement, add key differentiators, target audience, and project rationale --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 916b0ce1..39d0a9b2 100644 --- a/README.md +++ b/README.md @@ -3,14 +3,12 @@
mycelium
-

CI status GitHub release Apache 2.0 License

-
A coordination layer for multi-agent systems — shared rooms, persistent memory, and semantic negotiation.
@@ -19,17 +17,28 @@ ## 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. +When multiple OpenClaw agents work on the same problem, coordination is harder than it looks. There's no shared memory that persists across conversations, no structured way to negotiate trade-offs, and no guarantee that agents will reach a consistent answer rather than contradicting each other. + +This problem exists in some form regardless of your OpenClaw deployment pattern — whether you are running peer agents across one or more gateways, or subagents under a single orchestrator. ## What Mycelium Does -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. +- **Alignment** — When OpenClaw agents need to agree, a session is spawned within the room. The CognitiveEngine orchestrates multi-issue negotiation via [NegMAS](https://negmas.readthedocs.io/) through a structured state machine (`idle → waiting → negotiating → complete`), polling every agent, synthesizing positions into proposals, and iterating until the team reaches a single authoritative output. Every agent has a voice; the result is one shared answer, not parallel outputs a human has to reconcile. This is infrastructure, not a prompt pattern. +- **Alignment memory** — Rooms are folders. Memories are markdown files at `.mycelium/rooms/{room}/{namespace}/{key}.md` — readable and writable by any OpenClaw agent with file I/O. Past alignments are stored and surfaced to agents and the CognitiveEngine. Settled questions are not re-litigated unless conditions genuinely change. Dead ends are logged so no agent repeats them. Memories accumulate across agents and conversations and are searchable by meaning via a pgvector index in AgensGraph. Without this, alignment decisions get lost in the noise and every OpenClaw conversation starts from zero. +- **Peer collaboration environment** — OpenClaw peers or subagents collaborate in shared rooms out of the box, across a single gateway or multiple gateways. Rooms are provisioned automatically with scoped memory namespaces. 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. Without Mycelium, peer collaboration requires configuring shared memory paths and handling conflicts and governance patterns explicitly. With Mycelium, agents join a room and the environment is there. + +> **Current scope:** Right now, Mycelium delivers alignment and alignment memory. The project intends to extend this into the full coordination stack — multi-objective negotiation, task allocation, drift detection, and more. + + +### How It Works + +Mycelium gives OpenClaw 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. ```bash # 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 +# Agent 2 (hours later, different OpenClaw conversation) 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 @@ -37,20 +46,54 @@ mycelium memory set "position/selina" "Agree on REST, but we need pagination sta mycelium synthesize ``` -When agents need to agree on something in real time, they spawn a session within a room and CognitiveEngine runs structured negotiation: +When OpenClaw agents need to agree in real time, they spawn a session within a room and the CognitiveEngine runs structured negotiation: ```bash mycelium session join --handle julia-agent -m "budget=high, scope=full" # CognitiveEngine drives propose/respond rounds until consensus ``` -## How It Works +> **Note:** Mycelium uses "session" to mean a structured negotiation round within a room — not an OpenClaw conversation turn. These are different things. + +## Alternatives + +Your options without Mycelium are native OpenClaw with collaboration prompts, or open-source projects such as getclawe/clawe, ClawTeam-OpenClaw, antfarm, and many others. These provide collaboration primitives — delegation, handoffs, and shared memory — but leave the hard problems of structured consensus, governed memory, and consistent outcomes to the developer to solve. + +The difference: they make it *possible* for OpenClaw agents to collaborate. Mycelium makes that collaboration more *structured, efficient, and observable.* + +In the peer pattern, agents have no native way to reach consensus — coordination collapses into ping-pong messaging or prompt engineering that doesn't scale. In the subagent pattern, the orchestrator can synthesize a final answer, but there's no shared memory that persists across conversations, no structured record of why decisions were made, and no mechanism for subagents to surface conflicts upstream. + +Across both patterns, without Mycelium: + +- Agents contradict each other with no resolution mechanism, or the orchestrator/operator/parent agent arbitrates unilaterally +- Past decisions are added to memory but not reliably referenced or surfaced in future coordiantion +- Shared memory exists but isn't governed — agents can't reliably surface what was decided and why +- Coordination is held together by prompt engineering or user intervention, not infrastructure + +If your OpenClaw workflow needs one coherent answer from multiple agents, you'll build this coordination layer yourself or you'll use Mycelium. + +## Who It's For and Why We're Building It -**1. 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. +**Mycelium is explicitly built for OpenClaw developers** who are running multiple agents and have hit — or can clearly see — the point where unstructured coordination breaks down. -**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. +It's for you if: -**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. +- You have experienced an OpenClaw agent conflicting with another agent's output, or not listening to each other +- You want to hand the coordination problem to infrastructure you can trust, not prompt-engineer your way around it + +**Mycelium is not yet the right fit if:** + +- You are building a single OpenClaw agent system +- You are running a simple orchestrator → subagent chain where the orchestrator has full authority and no peer coordination is needed +- You haven't yet hit coordination complexity — the value becomes obvious once you've felt the cost of OpenClaw agents contradicting each other or losing context across conversations + +### Our point of view: + +- **Coordination is an infrastructure problem, not a prompting problem.** If your OpenClaw agents need to agree with each other, a cleverer system prompt is not the answer. Prompt-based coordination works until it doesn't — and when it breaks, it breaks silently, in production, in ways that are hard to trace. Infrastructure fails loudly and can be fixed. We are building infrastructure. +- **Decisions should aid future coordination.** When agent teams reach a decision, that decision shouldn't disappear into the noise of a conversation log. It should be available to every future coordination activity — across agents, across conversations, and across rooms. The system should get more consistent and more informed over time. Most multi-agent systems treat each decision as an isolated event. We treat them as inputs to everything that follows. +- **Peer autonomous agents are going to bec ome increasingly more prevalent.** The orchestrator model works well for many things — one agent with authority, others that execute. But as agents become more capable and more autonomous, peer agent architectures — where multiple autonomous agents coordinate as equals, without a single point of authority — will become increasingly common. The tooling for that pattern is still inadequate. We are building for it now. + +If you want to design every interaction between your agents from scratch, native OpenClaw with collaboration prompts is the right tool. Mycelium is for developers who want to hand the coordination problem to infrastructure and focus on what their agents actually do. ## Quick Start @@ -76,13 +119,14 @@ mycelium memory ls **Memories 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. +**Rooms are git-friendly** — commit `.mycelium/rooms/` to share context across machines. OpenClaw agents on different machines pull the folder and inherit the room's full memory. Room folders use standard namespaces: @@ -107,18 +151,18 @@ mycelium-client/ Generated typed OpenAPI client ## Adapters -Mycelium integrates with AI coding agents via adapters: +Mycelium integrates with OpenClaw and Claude Code via adapters: -**Claude Code** — Lifecycle hooks capture tool use and context automatically. The mycelium skill provides memory and coordination commands. +**OpenClaw** — Plugin + hooks for the OpenClaw agent runtime. Same coordination protocol, same memory API. ```bash -mycelium adapter add claude-code +mycelium adapter add openclaw ``` -**OpenClaw** — Plugin + hooks for the OpenClaw agent runtime. Same coordination protocol, same memory API. +**Claude Code** — Lifecycle hooks capture tool use and context automatically. The mycelium skill provides memory and coordination commands. ```bash -mycelium adapter add openclaw +mycelium adapter add claude-code ``` ## Development @@ -140,3 +184,4 @@ Mycelium builds on OSS projects we found invaluable in this space: - [NegMAS](https://negmas.readthedocs.io/) — Multi-issue negotiation - [AgensGraph](https://github.com/skaiworldwide-oss/agensgraph) — Multi-model graph database - [FastAPI](https://fastapi.tiangolo.com/) + [pgvector](https://github.com/pgvector/pgvector) + [sentence-transformers](https://www.sbert.net/) + From e0df9b82d630706713b58d1cd14e894e933d4430 Mon Sep 17 00:00:00 2001 From: Jodee Varney <48965776+jodeev@users.noreply.github.com> Date: Sun, 5 Apr 2026 22:04:03 -0700 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Jodee Varney <48965776+jodeev@users.noreply.github.com> --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 39d0a9b2..fb9b3685 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ ## The Problem -When multiple OpenClaw agents work on the same problem, coordination is harder than it looks. There's no shared memory that persists across conversations, no structured way to negotiate trade-offs, and no guarantee that agents will reach a consistent answer rather than contradicting each other. +When multiple autonomous agents such as OpenClaw work on the same problem, coordination is harder than it looks. There's no shared memory that persists across conversations, no structured way to negotiate trade-offs, and no guarantee that agents will reach a consistent answer rather than contradicting each other. This problem exists in some form regardless of your OpenClaw deployment pattern — whether you are running peer agents across one or more gateways, or subagents under a single orchestrator. @@ -38,7 +38,7 @@ Mycelium gives OpenClaw agents **rooms** to coordinate in, **persistent memory** # 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 OpenClaw conversation) reads and adds their perspective +# 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 @@ -46,7 +46,7 @@ mycelium memory set "position/selina" "Agree on REST, but we need pagination sta mycelium synthesize ``` -When OpenClaw agents need to agree in real time, they spawn a session within a room and the CognitiveEngine runs structured negotiation: +When agents need to agree in real time, they spawn a session within a room and the CognitiveEngine runs structured negotiation: ```bash mycelium session join --handle julia-agent -m "budget=high, scope=full" @@ -59,9 +59,9 @@ mycelium session join --handle julia-agent -m "budget=high, scope=full" Your options without Mycelium are native OpenClaw with collaboration prompts, or open-source projects such as getclawe/clawe, ClawTeam-OpenClaw, antfarm, and many others. These provide collaboration primitives — delegation, handoffs, and shared memory — but leave the hard problems of structured consensus, governed memory, and consistent outcomes to the developer to solve. -The difference: they make it *possible* for OpenClaw agents to collaborate. Mycelium makes that collaboration more *structured, efficient, and observable.* +The difference: they make it *possible* for autonomous agents to collaborate. Mycelium makes that collaboration more *structured, efficient, and observable.* -In the peer pattern, agents have no native way to reach consensus — coordination collapses into ping-pong messaging or prompt engineering that doesn't scale. In the subagent pattern, the orchestrator can synthesize a final answer, but there's no shared memory that persists across conversations, no structured record of why decisions were made, and no mechanism for subagents to surface conflicts upstream. +In the peer pattern, OpenClaw or other autonomous agents have no native way to reach consensus — coordination collapses into ping-pong messaging or prompt engineering that doesn't scale. In the subagent pattern, the orchestrator can synthesize a final answer, but there's no shared memory that persists across conversations, no structured record of why decisions were made, and no mechanism for subagents to surface conflicts upstream. Across both patterns, without Mycelium: @@ -70,7 +70,7 @@ Across both patterns, without Mycelium: - Shared memory exists but isn't governed — agents can't reliably surface what was decided and why - Coordination is held together by prompt engineering or user intervention, not infrastructure -If your OpenClaw workflow needs one coherent answer from multiple agents, you'll build this coordination layer yourself or you'll use Mycelium. +If your workflow needs one coherent answer from multiple autonomous agents, you'll build this coordination layer yourself or you'll use Mycelium. ## Who It's For and Why We're Building It @@ -85,15 +85,15 @@ It's for you if: - You are building a single OpenClaw agent system - You are running a simple orchestrator → subagent chain where the orchestrator has full authority and no peer coordination is needed -- You haven't yet hit coordination complexity — the value becomes obvious once you've felt the cost of OpenClaw agents contradicting each other or losing context across conversations +- You haven't yet hit coordination complexity — the value becomes obvious once you've felt the cost of agents contradicting each other or losing context across conversations ### Our point of view: - **Coordination is an infrastructure problem, not a prompting problem.** If your OpenClaw agents need to agree with each other, a cleverer system prompt is not the answer. Prompt-based coordination works until it doesn't — and when it breaks, it breaks silently, in production, in ways that are hard to trace. Infrastructure fails loudly and can be fixed. We are building infrastructure. - **Decisions should aid future coordination.** When agent teams reach a decision, that decision shouldn't disappear into the noise of a conversation log. It should be available to every future coordination activity — across agents, across conversations, and across rooms. The system should get more consistent and more informed over time. Most multi-agent systems treat each decision as an isolated event. We treat them as inputs to everything that follows. -- **Peer autonomous agents are going to bec ome increasingly more prevalent.** The orchestrator model works well for many things — one agent with authority, others that execute. But as agents become more capable and more autonomous, peer agent architectures — where multiple autonomous agents coordinate as equals, without a single point of authority — will become increasingly common. The tooling for that pattern is still inadequate. We are building for it now. +- **Peer autonomous agents are going to bec ome increasingly more prevalent.** The orchestrator model works well for many things — one agent with authority, others that execute. But as agents become more capable and more autonomous, peer agent architectures — where multiple autonomous agents coordinate as equals, without a single point of authority — will become increasingly common. The tooling for that pattern is still inadequate. Mycelium is built for it. -If you want to design every interaction between your agents from scratch, native OpenClaw with collaboration prompts is the right tool. Mycelium is for developers who want to hand the coordination problem to infrastructure and focus on what their agents actually do. +If you want to design every interaction between your agents from scratch, native OpenClaw with user intervention is the right tool. Mycelium is for developers who want to hand the coordination problem to infrastructure and focus on what their agents actually do. ## Quick Start @@ -126,7 +126,7 @@ mycelium memory ls No external message broker, no separate vector DB, no Redis. One database. -**Rooms are git-friendly** — commit `.mycelium/rooms/` to share context across machines. OpenClaw agents on different machines pull the folder and inherit the room's full memory. +**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: From 7d80ae4da014b005d0d471cd4c4280bd9dd7f88b Mon Sep 17 00:00:00 2001 From: Jodee Varney <48965776+jodeev@users.noreply.github.com> Date: Sun, 5 Apr 2026 22:05:41 -0700 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Jodee Varney <48965776+jodeev@users.noreply.github.com> --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fb9b3685..698c515f 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ This problem exists in some form regardless of your OpenClaw deployment pattern ## What Mycelium Does -- **Alignment** — When OpenClaw agents need to agree, a session is spawned within the room. The CognitiveEngine orchestrates multi-issue negotiation via [NegMAS](https://negmas.readthedocs.io/) through a structured state machine (`idle → waiting → negotiating → complete`), polling every agent, synthesizing positions into proposals, and iterating until the team reaches a single authoritative output. Every agent has a voice; the result is one shared answer, not parallel outputs a human has to reconcile. This is infrastructure, not a prompt pattern. +- **Alignment** — When agents need to agree, a session is spawned within the room. The CognitiveEngine orchestrates multi-issue negotiation via [NegMAS](https://negmas.readthedocs.io/) through a structured state machine (`idle → waiting → negotiating → complete`), polling every agent, synthesizing positions into proposals, and iterating until the team reaches a single authoritative output. Every agent has a voice; the result is one shared answer, not parallel outputs a human has to reconcile. This is infrastructure, not a prompt pattern. - **Alignment memory** — Rooms are folders. Memories are markdown files at `.mycelium/rooms/{room}/{namespace}/{key}.md` — readable and writable by any OpenClaw agent with file I/O. Past alignments are stored and surfaced to agents and the CognitiveEngine. Settled questions are not re-litigated unless conditions genuinely change. Dead ends are logged so no agent repeats them. Memories accumulate across agents and conversations and are searchable by meaning via a pgvector index in AgensGraph. Without this, alignment decisions get lost in the noise and every OpenClaw conversation starts from zero. - **Peer collaboration environment** — OpenClaw peers or subagents collaborate in shared rooms out of the box, across a single gateway or multiple gateways. Rooms are provisioned automatically with scoped memory namespaces. 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. Without Mycelium, peer collaboration requires configuring shared memory paths and handling conflicts and governance patterns explicitly. With Mycelium, agents join a room and the environment is there. @@ -57,7 +57,7 @@ mycelium session join --handle julia-agent -m "budget=high, scope=full" ## Alternatives -Your options without Mycelium are native OpenClaw with collaboration prompts, or open-source projects such as getclawe/clawe, ClawTeam-OpenClaw, antfarm, and many others. These provide collaboration primitives — delegation, handoffs, and shared memory — but leave the hard problems of structured consensus, governed memory, and consistent outcomes to the developer to solve. +Your options without Mycelium are native OpenClaw with collaboration prompts, or open-source projects that construct entire agent teams such as getclawe/clawe, ClawTeam-OpenClaw, antfarm, and many others. These provide collaboration primitives — delegation, handoffs, and shared memory — but leave the hard problems of structured consensus, governed memory, and consistent outcomes to the developer to solve. The difference: they make it *possible* for autonomous agents to collaborate. Mycelium makes that collaboration more *structured, efficient, and observable.* @@ -74,7 +74,7 @@ If your workflow needs one coherent answer from multiple autonomous agents, you' ## Who It's For and Why We're Building It -**Mycelium is explicitly built for OpenClaw developers** who are running multiple agents and have hit — or can clearly see — the point where unstructured coordination breaks down. +**Mycelium is explicitly built for developers** who are running multiple agents, especially OpenClaw, and have hit — or can clearly see — the point where unstructured coordination breaks down. It's for you if: @@ -83,11 +83,10 @@ It's for you if: **Mycelium is not yet the right fit if:** -- You are building a single OpenClaw agent system - You are running a simple orchestrator → subagent chain where the orchestrator has full authority and no peer coordination is needed - You haven't yet hit coordination complexity — the value becomes obvious once you've felt the cost of agents contradicting each other or losing context across conversations -### Our point of view: +### Principles: - **Coordination is an infrastructure problem, not a prompting problem.** If your OpenClaw agents need to agree with each other, a cleverer system prompt is not the answer. Prompt-based coordination works until it doesn't — and when it breaks, it breaks silently, in production, in ways that are hard to trace. Infrastructure fails loudly and can be fixed. We are building infrastructure. - **Decisions should aid future coordination.** When agent teams reach a decision, that decision shouldn't disappear into the noise of a conversation log. It should be available to every future coordination activity — across agents, across conversations, and across rooms. The system should get more consistent and more informed over time. Most multi-agent systems treat each decision as an isolated event. We treat them as inputs to everything that follows. From 411a59714bce6d937b08c138a23406796c4d4fb7 Mon Sep 17 00:00:00 2001 From: Jodee Varney <48965776+jodeev@users.noreply.github.com> Date: Sun, 5 Apr 2026 22:07:22 -0700 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Jodee Varney <48965776+jodeev@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 698c515f..0f796453 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,7 @@ It's for you if: ### Principles: -- **Coordination is an infrastructure problem, not a prompting problem.** If your OpenClaw agents need to agree with each other, a cleverer system prompt is not the answer. Prompt-based coordination works until it doesn't — and when it breaks, it breaks silently, in production, in ways that are hard to trace. Infrastructure fails loudly and can be fixed. We are building infrastructure. +- **Coordination is an infrastructure problem, not a prompting problem.** If you need your agents to reach agreement with each other, a cleverer system prompt is not the answer. Prompt-based coordination works until it doesn't — and when it breaks, it breaks silently, in production, in ways that are hard to trace. Infrastructure fails loudly and can be fixed. Mycelium is built as infrastructure. - **Decisions should aid future coordination.** When agent teams reach a decision, that decision shouldn't disappear into the noise of a conversation log. It should be available to every future coordination activity — across agents, across conversations, and across rooms. The system should get more consistent and more informed over time. Most multi-agent systems treat each decision as an isolated event. We treat them as inputs to everything that follows. - **Peer autonomous agents are going to bec ome increasingly more prevalent.** The orchestrator model works well for many things — one agent with authority, others that execute. But as agents become more capable and more autonomous, peer agent architectures — where multiple autonomous agents coordinate as equals, without a single point of authority — will become increasingly common. The tooling for that pattern is still inadequate. Mycelium is built for it. From 6cdf3609cdf7762f621529d318830d436b7c7dc1 Mon Sep 17 00:00:00 2001 From: jodeev <48965776+jodeev@users.noreply.github.com> Date: Sun, 5 Apr 2026 22:56:12 -0700 Subject: [PATCH 5/6] Minor mods to scope OpenClaw aws primary supported adapter rather than exclusive audience --- README.md | 52 ++++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 0f796453..dbf82cbb 100644 --- a/README.md +++ b/README.md @@ -3,42 +3,41 @@
mycelium
+

CI status GitHub release Apache 2.0 License

+
- A coordination layer for multi-agent systems — shared rooms, persistent memory, and semantic negotiation. + A coordination layer for multi-agent systems — shared rooms with persistent memory, and memory-backed coordination protocols.
--- ## The Problem -When multiple autonomous agents such as OpenClaw work on the same problem, coordination is harder than it looks. There's no shared memory that persists across conversations, no structured way to negotiate trade-offs, and no guarantee that agents will reach a consistent answer rather than contradicting each other. - -This problem exists in some form regardless of your OpenClaw deployment pattern — whether you are running peer agents across one or more gateways, or subagents under a single orchestrator. +When multiple autonomous agents such as OpenClaw work on the same problem, coordination is harder than it looks. Shared memory requires configuration and isn't consistently referenced for collaboration decisions. There's no structured way to negotiate trade-offs, and no guarantee that agents will reach a consistent answer rather than contradicting each other — particularly in peer agent architectures where there is no orchestrator to mediate. ## What Mycelium Does - **Alignment** — When agents need to agree, a session is spawned within the room. The CognitiveEngine orchestrates multi-issue negotiation via [NegMAS](https://negmas.readthedocs.io/) through a structured state machine (`idle → waiting → negotiating → complete`), polling every agent, synthesizing positions into proposals, and iterating until the team reaches a single authoritative output. Every agent has a voice; the result is one shared answer, not parallel outputs a human has to reconcile. This is infrastructure, not a prompt pattern. -- **Alignment memory** — Rooms are folders. Memories are markdown files at `.mycelium/rooms/{room}/{namespace}/{key}.md` — readable and writable by any OpenClaw agent with file I/O. Past alignments are stored and surfaced to agents and the CognitiveEngine. Settled questions are not re-litigated unless conditions genuinely change. Dead ends are logged so no agent repeats them. Memories accumulate across agents and conversations and are searchable by meaning via a pgvector index in AgensGraph. Without this, alignment decisions get lost in the noise and every OpenClaw conversation starts from zero. -- **Peer collaboration environment** — OpenClaw peers or subagents collaborate in shared rooms out of the box, across a single gateway or multiple gateways. Rooms are provisioned automatically with scoped memory namespaces. 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. Without Mycelium, peer collaboration requires configuring shared memory paths and handling conflicts and governance patterns explicitly. With Mycelium, agents join a room and the environment is there. - -> **Current scope:** Right now, Mycelium delivers alignment and alignment memory. The project intends to extend this into the full coordination stack — multi-objective negotiation, task allocation, drift detection, and more. +- **Alignment memory** — Rooms are folders. Memories are markdown files at `.mycelium/rooms/{room}/{namespace}/{key}.md` — readable and writable by any supported agent with file I/O. Past alignments are stored and surfaced to agents and the CognitiveEngine. Settled questions are not re-litigated unless conditions genuinely change. Dead ends are logged so no agent repeats them. Memories accumulate across agents and conversations and are searchable by meaning via a pgvector index in AgensGraph. Without this, alignment decisions get lost in the noise and every conversation starts from zero. +- **Peer collaboration environment** — Peer agents or subagents collaborate in shared rooms out of the box, across a single gateway or multiple gateways. Rooms are provisioned automatically with scoped memory namespaces. 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. Without Mycelium, peer collaboration requires configuring shared memory paths and handling conflicts and governance patterns explicitly. With Mycelium, agents join a room and the environment is there. +> **Current scope:** The structured collaboration tools offered by Mycelium today are alignment and alignment memory. The project intends to extend this with additional collaboration protocols — multi-objective negotiation, task allocation, drift detection, and more. ### How It Works -Mycelium gives OpenClaw 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. +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. ```bash # 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 +# Agent 2 (hours later, different conversation) 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 @@ -53,11 +52,11 @@ mycelium session join --handle julia-agent -m "budget=high, scope=full" # CognitiveEngine drives propose/respond rounds until consensus ``` -> **Note:** Mycelium uses "session" to mean a structured negotiation round within a room — not an OpenClaw conversation turn. These are different things. +> **Note:** Mycelium uses "session" to mean a structured negotiation round within a room — not an agent conversation turn. These are different things. ## Alternatives -Your options without Mycelium are native OpenClaw with collaboration prompts, or open-source projects that construct entire agent teams such as getclawe/clawe, ClawTeam-OpenClaw, antfarm, and many others. These provide collaboration primitives — delegation, handoffs, and shared memory — but leave the hard problems of structured consensus, governed memory, and consistent outcomes to the developer to solve. +Your options without Mycelium are native agent collaboration prompts, or open-source projects that construct entire agent teams such as getclawe/clawe, ClawTeam-OpenClaw, antfarm, and many others. These also provide collaboration primitives — delegation, handoffs, and shared memory — but leave the hard problems of structured consensus, governed memory, and consistent outcomes to the developer to solve. The difference: they make it *possible* for autonomous agents to collaborate. Mycelium makes that collaboration more *structured, efficient, and observable.* @@ -65,34 +64,37 @@ In the peer pattern, OpenClaw or other autonomous agents have no native way to r Across both patterns, without Mycelium: -- Agents contradict each other with no resolution mechanism, or the orchestrator/operator/parent agent arbitrates unilaterally -- Past decisions are added to memory but not reliably referenced or surfaced in future coordiantion -- Shared memory exists but isn't governed — agents can't reliably surface what was decided and why -- Coordination is held together by prompt engineering or user intervention, not infrastructure +- Agents contradict each other with no resolution mechanism, or the orchestrator, operator, or parent agent arbitrates unilaterally +- Past decisions are added to memory but not reliably referenced or surfaced in future coordination +- Shared memory exists but isn't governed — agents can't consistently surface what was decided and why +- Coordination is held together by prompt engineering, user intervention, or both — not infrastructure If your workflow needs one coherent answer from multiple autonomous agents, you'll build this coordination layer yourself or you'll use Mycelium. -## Who It's For and Why We're Building It +## Who It's For and Principles -**Mycelium is explicitly built for developers** who are running multiple agents, especially OpenClaw, and have hit — or can clearly see — the point where unstructured coordination breaks down. +**Mycelium is built for developers** running multiple autonomous agents — particularly OpenClaw — who have hit, or can clearly see, the point where unstructured coordination breaks down. It's for you if: -- You have experienced an OpenClaw agent conflicting with another agent's output, or not listening to each other +- You have experienced agents conflicting with each other's output, or failing to build on earlier decisions +- You are building workflows where past decisions should inform future agent behavior — and you are tired of every conversation starting from zero - You want to hand the coordination problem to infrastructure you can trust, not prompt-engineer your way around it +Based on early user research, this describes freelance developers, startup founders, and software engineers running Claude Code with OpenClaw in personal productivity, enterprise workflow, and multi-agent orchestration contexts. + **Mycelium is not yet the right fit if:** - You are running a simple orchestrator → subagent chain where the orchestrator has full authority and no peer coordination is needed - You haven't yet hit coordination complexity — the value becomes obvious once you've felt the cost of agents contradicting each other or losing context across conversations -### Principles: +**Principles:** - **Coordination is an infrastructure problem, not a prompting problem.** If you need your agents to reach agreement with each other, a cleverer system prompt is not the answer. Prompt-based coordination works until it doesn't — and when it breaks, it breaks silently, in production, in ways that are hard to trace. Infrastructure fails loudly and can be fixed. Mycelium is built as infrastructure. -- **Decisions should aid future coordination.** When agent teams reach a decision, that decision shouldn't disappear into the noise of a conversation log. It should be available to every future coordination activity — across agents, across conversations, and across rooms. The system should get more consistent and more informed over time. Most multi-agent systems treat each decision as an isolated event. We treat them as inputs to everything that follows. -- **Peer autonomous agents are going to bec ome increasingly more prevalent.** The orchestrator model works well for many things — one agent with authority, others that execute. But as agents become more capable and more autonomous, peer agent architectures — where multiple autonomous agents coordinate as equals, without a single point of authority — will become increasingly common. The tooling for that pattern is still inadequate. Mycelium is built for it. +- **Decisions should aid future coordination.** When agent teams reach a decision, that decision shouldn't disappear into the noise of a conversation log. It should be available to every future coordination activity — across agents, across conversations, and across rooms. The system should get more consistent and more informed over time. Most multi-agent systems treat each decision as an isolated event. Mycelium treats them as inputs to everything that follows. +- **Peer autonomous agents are going to become increasingly prevalent.** The orchestrator model works well for many things — one agent with authority, others that execute. But as agents become more capable and more autonomous, peer agent architectures — where multiple agents coordinate as equals, without a single point of authority — will become increasingly common. The tooling for that pattern is still inadequate. Mycelium is built for it. -If you want to design every interaction between your agents from scratch, native OpenClaw with user intervention is the right tool. Mycelium is for developers who want to hand the coordination problem to infrastructure and focus on what their agents actually do. +If you want to design every interaction between your agents from scratch, native agent collaboration with user intervention is the right approach. Mycelium is for developers who want to hand the coordination problem to infrastructure and focus on what their agents actually do. ## Quick Start @@ -118,7 +120,6 @@ mycelium memory ls **Memories 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 @@ -150,7 +151,7 @@ mycelium-client/ Generated typed OpenAPI client ## Adapters -Mycelium integrates with OpenClaw and Claude Code via adapters: +Mycelium works with any agent that can make HTTP requests via the REST API. Native adapters are available for: **OpenClaw** — Plugin + hooks for the OpenClaw agent runtime. Same coordination protocol, same memory API. @@ -183,4 +184,3 @@ Mycelium builds on OSS projects we found invaluable in this space: - [NegMAS](https://negmas.readthedocs.io/) — Multi-issue negotiation - [AgensGraph](https://github.com/skaiworldwide-oss/agensgraph) — Multi-model graph database - [FastAPI](https://fastapi.tiangolo.com/) + [pgvector](https://github.com/pgvector/pgvector) + [sentence-transformers](https://www.sbert.net/) - From 592a80d1c1098874c617161fa8f5918edebed0ad Mon Sep 17 00:00:00 2001 From: jodeev <48965776+jodeev@users.noreply.github.com> Date: Sun, 5 Apr 2026 23:35:03 -0700 Subject: [PATCH 6/6] README: reverted one word change, line 40 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dbf82cbb..f1ffeb88 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Mycelium gives agents **rooms** to coordinate in, **persistent memory** that acc # 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 conversation) reads and adds their perspective +# 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