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 # project principles & rules
mycelium.sh find warning # known fragile things
mycelium.sh context <file> # everything known about it
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 # see what's stale
mycelium.sh compost <oid> --compost # absorb and archive
mycelium.sh compost <oid> --renew # still true, re-attach
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 # notes visible in git log
mycelium.sh sync-init # notes travel with fetch/push
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.