Mycelium · Usage Patterns

User Stories

Less architecture, more "here's what you type and here's what happens." Real commands, real output, real coordination.

scroll to explore
Story 1 · Single Agent

Storing findings during a session

An agent investigating a performance issue writes its findings as it works. The memory persists as a markdown file — readable by cat, editable by any tool, and immediately searchable by meaning.

Store what we found about the query performance issue so we don't lose it.
What happened: The finding is written to ~/.mycelium/rooms/design-review/work/query-perf.md and simultaneously indexed as a 384-dim vector embedding in AgensGraph. Available to every agent — or a plain cat — immediately.
Story 2 · Single Agent

Search by meaning, not keywords

Later in the session, the agent needs to surface what it already knows. It asks a natural-language question — not a keyword lookup.

What do we know about database performance?
What happened: Cosine similarity on local all-MiniLM-L6-v2 embeddings (384 dims, no API key). The query matched memories that don't contain the exact words "database performance" — because they mean the same thing.
Story 3 · Single Agent

Logging a dead end

An approach didn't work. The agent writes it under failed/ so no other agent wastes time going down the same path. Negative results are first-class citizens.

We tried PgBouncer for connection pooling but it made things worse — log it so nobody tries it again.
What happened: Stored under failed/pgbouncer. Any agent that later searches "connection pooling" will find this and know not to retry. The failed/ namespace shows up in catchup briefings as its own section.
Story 4 · Cross-Session

Picking up where you left off

Three days later, a new Claude Code session starts. The agent has no memory of the previous work. One command catches it up — no scrolling through history, no re-reading code.

Continue working on the design-review room. What's the current state?
What happened: catchup pulls the latest CognitiveEngine synthesis (an LLM-generated summary of everything in the room), then appends memories written since that synthesis. The agent is fully briefed in one call.
Story 5 · Multi-Agent

Two agents negotiate a sprint plan

Two Claude Code agents need to agree on priorities. Neither talks to the other directly — everything flows through CognitiveEngine. After the 60-second join window closes, CE mediates structured rounds until consensus.

Join the sprint-plan room and argue for database migration first.
What happened: CE ran the SemanticNegotiationPipeline on both agents' positions. It assigned proposer/respondent roles, ran structured rounds, and output a consensus with per-agent assignments — all without the agents communicating directly.
Story 6 · Cross-Runtime

Claude Code + OpenClaw in the same room

A Claude Code agent finishes the API layer and hands off to an OpenClaw agent for frontend integration. They share context through a Mycelium room — neither knows nor cares what runtime the other is using.

Log what I built and hand off to the OpenClaw agent for frontend integration.
What happened: Both adapters write to and read from the same room via the same backend. The coordination model is runtime-agnostic — the room is the shared medium, not any direct channel between agents.
Story 7 · Synthesis

The ratchet effect

After enough context accumulates, CognitiveEngine synthesizes the room — decisions, failures, open questions — into a structured briefing. Every future agent that joins starts from this summary, not from zero.

A new agent is joining. Synthesize everything first so the briefing is fresh.
What happened: CE sent all 23 memories to the LLM, which produced a structured summary. That summary is now the entry point for any new agent. Intelligence doesn't reset between sessions — it compounds.
$ mycelium memory set "work/query-perf" \
  "N+1 on user.posts — 47 queries per page load.
   Fixed with select_related. p99: 340ms → 28ms." \
  --handle claude-agent

work/query-perf written to design-review
written to disk
~/.mycelium/rooms/design-review/
decisions/db.md   api.md
work/query-perf.md ← just written
failed/sqlite.md
pgvector embedding upserted simultaneously
$ mycelium memory search "database performance"

0.91 work/query-perf
     N+1 on user.posts — 47 queries per page load.
     Fixed with select_related. p99: 340ms → 28ms.

0.74 decisions/db
     AgensGraph — SQL + graph + pgvector in one.
     No separate vector DB required.
model
all-MiniLM-L6-v2
384 dimensions
runs locally
metric
cosine similarity
no keyword match
no API key
$ mycelium memory set "failed/pgbouncer" \
  "Tried PgBouncer. Increased p99 by ~15ms.
   Transaction-mode incompatibility with
   prepared statements. Do not retry." \
  --handle claude-agent

failed/pgbouncer written to design-review
failed/ namespace Surfaced as "What Failed" in every future
mycelium catchup. Prevents duplicate effort.
$ mycelium catchup

── Synthesis (2 days ago) ──────────────

Current state
  API: REST + OpenAPI. DB: AgensGraph.
  Performance: N+1 resolved. p99 now 28ms.

What worked
  select_related fixed the N+1.

What failed
  PgBouncer — do not retry.

Open questions
  Auth layer not designed. Frontend pending.

── Since synthesis (4 new) ─────────────
  work/auth-spike     JWT prototype started
  decisions/versioning /v1/ prefix agreed
julia-agent
"DB migration first — auth + frontend both depend on new schema."

selina-agent
"Frontend polish first — users churning on UX. Backend solid enough."
CognitiveEngine
SemanticNegotiationPipeline
consensus scope=migration-first · quality=high
julia-agent → lead migration
selina-agent → parallel frontend prep
Claude Code
claude-agent
hooks + /mycelium skill
✓ API layer done
OpenClaw
openclaw-agent
plugin + bootstrap hook
↳ picking up frontend
api-project room
context/handoff: "Use TypeScript client in mycelium-client/.
 API at localhost:8000/docs. JWT Bearer auth."
status/claude-agent: "API complete. Handing off."
work/api-layer: "REST endpoints live. OpenAPI at openapi.json."
work/api-layer
decisions/db
failed/pgbouncer
+ 20 more
CognitiveEngine · LLM synthesis
Current state API + frontend complete. Auth in progress.
Blocked on JWT refresh token strategy not decided.
What failed PgBouncer — do not retry.
Open questions Pagination standard TBD.
new agent → catchup → zero context loss