mycelium

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   # 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:

1. Novelty: Does a similar note already exist? (mycelium.sh read <file>)
2. Specificity: Is this about this file or the whole project? (Project-level → mycelium.sh note .)
3. Durability: Will this matter in 2 weeks? (Ephemeral → working memory, not mycelium)
4. 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.