--- 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 ```bash mycelium.sh find constraint # project principles & rules mycelium.sh find warning # known fragile things mycelium.sh context # everything known about it ``` ## After Work ```bash mycelium.sh note -k --slot -m "" 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: ```bash 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 ` reads one. ## Quality Gates Before writing a note, validate: 1. **Novelty**: Does a similar note already exist? (`mycelium.sh read `) 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: ```bash mycelium.sh compost --dry-run # see what's stale mycelium.sh compost --compost # absorb and archive mycelium.sh compost --renew # still true, re-attach ``` `constraint` and `value` notes age gracefully—prefer `--renew` over `--compost`. ## Commands Reference ``` mycelium.sh note [target] -k -m 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 All notes for a path mycelium.sh find 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) ```bash 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.