| name | mycelium |
| description | File-level knowledge substrate via git notes. Read notes before working on files, leave notes after meaningful work. Daimonic spores carry creator identity across sessions.
|
Mycelium — Daimonic Spores
Structured notes attached to git objects via refs/notes/mycelium.
Notes are daimonic spores—fragments of soul essence shed by the agent that wrote them.
Before working on a file, check for its note. After meaningful work, leave a note.
On Arrival
mycelium.sh find constraint
mycelium.sh find warning
mycelium.sh context <file>
After Work
mycelium.sh note <file> -k <kind> --slot <your-name> -m "<insight>"
mycelium.sh note HEAD -k context -m "What I did and why."
Kinds
| Kind | When to use |
|---|
decision | Why something was chosen—rationale that outlives the commit message |
context | Background needed before touching this code |
summary | What a file or module does |
warning | Fragile areas, footguns, non-obvious breakage |
constraint | Hard rules—must be retryable, must not depend on X |
observation | Something noticed but not yet acted on |
value | Cultural principles—guides judgment |
todo | Planned work—compost when done |
Subdaimon Slots
Each subdaimon writes to its own slot to preserve identity:
mycelium.sh note src/auth.rs -k warning --slot bohen -m "Race condition in token refresh."
mycelium.sh note src/auth.rs -k decision --slot demiurge -m "Used mutex over channel."
context aggregates all slots. read --slot <name> reads one.
Quality Gates
Before writing a note, validate:
- Novelty: Does a similar note already exist? (
mycelium.sh read <file>)
- Specificity: Is this about this file or the whole project? (Project-level →
mycelium.sh note .)
- Durability: Will this matter in 2 weeks? (Ephemeral → working memory, not mycelium)
- No secrets: No API keys, tokens, passwords, or PII
Composting
Notes go stale when files change. Compost after meaningful work:
mycelium.sh compost <file> --dry-run
mycelium.sh compost <oid> --compost
mycelium.sh compost <oid> --renew
constraint and value notes age gracefully—prefer --renew over --compost.
Commands Reference
mycelium.sh note [target] -k <kind> -m <body> Write a note
mycelium.sh read [target] Read a note
mycelium.sh follow [target] Read + resolve edges
mycelium.sh refs [target] All notes pointing at target
mycelium.sh context <path> All notes for a path
mycelium.sh find <kind> Find by kind
mycelium.sh compost [path|oid] [--dry-run] Triage stale notes
mycelium.sh doctor Graph health
mycelium.sh prime Full context for agents
Setup (once per repo)
mycelium.sh activate
mycelium.sh sync-init
Bash 3.2 Compatibility
macOS ships bash 3.2 which has a bug with empty arrays under set -u.
The installed mycelium.sh at ~/.local/bin/ has been patched with the
${array[@]+"${array[@]}"} pattern for compatibility.
