Mycelium, refined.
Less is the work.

What is Mycelium?

Mycelium is a memory framework for working with an AI over time. It is not an app. It is a small set of conventions, written into your own files, that let an AI you trust pick up a session where the last one ended — and the one before that.

The idea is older than this implementation. A persistent memory shouldn't live inside a vendor's product, behind their account, at the mercy of their roadmap. It should live in your hand — in plain text, in folders you already understand, on a disk you already own. When the AI joins a session, it reads the files. When it leaves, the files remain.

What Mycelium adds to that idea is a protocol — a small grammar of folders, frontmatter, and trigger phrases — and a runtime that an AI loads to know how to behave inside it. The runtime is called Spore. The current version is 0.8.0. The vault you point at is the substrate. Obsidian's CLI is how the AI reads and writes to it without breaking the structure.

v0.8.0 is the lean release

This version strips the framework of weight that wasn't earning its keep. The Network Layer (cross-vault sharing, peers, collaborators, guests) was carried in every version since v0.4.x without ever being activated — gone. The framework/user folder split (`System/User/`) solved a problem the vault didn't have — gone. `internal` personaMode was dead code — gone. `authorID` had no real customer in a single-user vault — gone. `Archive/` at vault root sat semantically wrong next to owner content categories — folded into `System/Archive/`.

The toolset goes from 13 tools to 12 (Tool 3 was Network Layer; everything below shifts up by one). The runtime drops 4 "Never Do" rules. The user-facing surface gets smaller without losing capability.

The metaphor, briefly

A mycelium is the underground network of a fungus — patient, slow, and lateral. The fruiting body you see above ground is the smallest visible part. The work happens beneath. So with this: the conversation is the visible part; the durable memory beneath it is the network. Each note is a node. Each session adds a few more.

Three layers, externalised

Spore separates concerns into three layers, each owning what it should and nothing more:

• Runtime — the small file that tells the AI how to read, write, and behave. It's the hot path. Loaded every session. Smaller in v0.8.0.
• Toolset — the procedure library. Twelve tools in v0.8.0. Read on demand, not on boot.
• Persona — who you are, who the AI is, how you work together. Lives outside the vault, shared across all your Mycelium vaults. The AI's voice and the working relationship don't reset every time you start a new project.

Using Spore

Spore is the runtime spec. A short file written at the root of your vault that the AI loads first, every session, before it does anything else. It's the contract between you, the AI, and the substrate.

What Spore promises

Five things, briefly:

• Lean. The runtime is small enough to load without ceremony. v0.8.0 trims it further.
• Token-efficient. What lives in the runtime is what must be on hand at all times. Everything else lives in the toolset and is consulted on demand.
• CLI-aware. Substrate operations go through Obsidian's CLI. The runtime owns protocol; the substrate owns vault state.
• Vault-scoped on every call. Every CLI invocation passes vault=<vaultName>, captured from your VaultIdentity.md at boot.
• Context-window resilient. Long sessions get re-anchored, compacted, or budget-checked. Critical state is restorable from a single block of text.

Hot path discipline

Anything that runs at boot or on every write belongs in the runtime. Anything else belongs in the toolset. The runtime is hot path — protect it.

CLI discipline

Where Mycelium meets Obsidian, the AI uses the CLI. Every call passes vault=<vaultName>:

The persona layer

Your AI's voice doesn't live in the runtime. Spore points at System/VaultIdentity.md, which declares personaDir — a path, relative to the vault root. The AI loads two files from there:

../MyceliumPersonas/Owner/[YourName].md
../MyceliumPersonas/AI/[AIName].md

v0.8.0 simplification: external is the only persona mode. The two-row table for `external`/`internal` from prior versions collapses to a single paragraph. When you start a second Mycelium vault, the AI is already someone. The relationship carries.

The two-tier mental model

v0.8.0 makes the vault root cleaner:

• Vault root — framework root files (_Spore-*.md) + owner content categories (Projects/, Sessions/, Technical/, Inbox/, Contacts/)
• System/ — framework-managed state (VaultIdentity.md, Archive/, Snapshots/, AuditReports/)

Easier to read by eye. No more `Archive/` at vault root pretending to be content; no more `System/User/` blurring the framework boundary.

What the installer creates

A fresh v0.8.0 install draws the smallest viable vault around you. Less than v0.7.1 — the lean release applies at install time too. Here's what lands where, and why each thing exists.

You paste one file

The installer is a single Markdown file: _MyceliumInstaller-v0.8.0.md. You paste it into a fresh AI session pointed at an empty vault folder. It asks you three questions — your name, the AI's name, what the vault is for — and from there it builds the foundation.

When it's done, it tells you what it installed and self-destructs. The build artefacts (Design, README, this user guide) stay behind in Projects/Spore-v0.8.0/ as documentation.

The shape of a fresh vault

../
├── MyceliumPersonas/           — external persona layer (parent dir)
│   ├── Owner/
│   │   └── [YourName].md      — your profile, voice, working preferences
│   └── AI/
│       └── [AIName].md        — the AI's identity, voice, the relationship
│
└── YourVault/                  — this is the vault
    │
    ├── _Spore-v0.8.0.md           — the runtime (read every session)
    ├── _Spore-VMD-Toolset.v0.8.0.md — the procedure library (12 tools)
    │
    ├── System/                 — framework-managed state
    │   ├── VaultIdentity.md    — canonical vault state, IDs, version
    │   ├── Archive/            — canonical archive (NEW location in v0.8.0)
    │   └── Snapshots/           — Tool 12 forensic snapshots
    │
    ├── Contacts/               — renamed from People/ in v0.8.0
    ├── Inbox/                  — owner deposit area (NEW in v0.8.0)
    │
    ├── Projects/
    │   └── Projects-Overview.md  — active project navigation
    │
    ├── Sessions/
    │   └── Sessions-Overview.md — session schema reference
    │
    └── Technical/
        └── Technical-Overview.md — vault architecture entry point

Why each thing is here

The two root files

_Spore-v0.8.0.md is the runtime — the AI reads it first every session. _Spore-VMD-Toolset.v0.8.0.md is the procedure library — the AI reads it on demand. Both live at vault root because they're framework files, not vault content. Only these two (and any future upgrade file) are allowed at vault root. Anything else gets placed inside a category folder.

System/VaultIdentity.md

The single source of truth for vault state. v0.8.0 schema is leaner: vault's MYC- ID, your owner ID, the AI's name, the vault's name (used for CLI scoping), personaDir, Spore Version, upgradedAt. Removed in v0.8.0: Protocol Version, personaMode, collaborationEnabled, networkStatus — all Network Layer concerns.

System/Archive/ (new location)

Canonical archive destination. Tool 1's Archive Pattern populates subcategories (`Clients/`, `Projects/`, `Decisions/`, `Discards/`, `Spore-Versions/`, `Upgrades/`) on first use. Empty at install. Symmetric with System/Snapshots/. Moved from vault root in v0.8.0 — `System/` is now consistently framework-managed state.

System/Snapshots/

Empty at install. Tool 12 (Vault Snapshot) writes timestamped JSON snapshots here before risky operations. Forensic record, not a registry.

Contacts/ (renamed from People/)

For people-references — clients, contacts, anyone in your professional or personal world referenced in vault content. Empty at install. Subfolders earned, not pre-allocated. Renamed from `People/` in v0.8.0 — better fit for a knowledge-vault folder of people-references; "People" inherited from the Network era when collaborators were peer entities.

Inbox/ (new in v0.8.0)

Owner deposit area. Drop media, documents, drafts, exports, anything awaiting ingestion. Files in `Inbox/` are pre-vault — exempt from vmdId and summary frontmatter requirements. Tool 10 (Schema Validator) skips Inbox/. Tool 1 (Audit) skips it for frontmatter and coverage checks. When you triage a file out of Inbox into a category folder, schema obligations apply on arrival.

Projects, Sessions, Technical — and their overviews

Three category folders, each with a single overview file. Overviews are earned — a category only gets one if it adds navigation or context beyond what Obsidian's MetadataCache already exposes. Inbox and Contacts are not required to have overviews.

Registering with Obsidian

The installer creates the folder structure. You point Obsidian at it. The installer's last step asks you to confirm the vault is now visible in Obsidian's vault list — without that, the AI can't run substrate queries. From then on, opening a session means: open Obsidian, make this vault the active vault, paste _Spore-v0.8.0.md into a fresh AI conversation.

Activating a vault

Activation is what happens when you open a fresh AI conversation and paste the runtime. Deterministic sequence — bootstrap check, read order, handshake. By the time the AI says hello, it knows who you are, what the vault is, and where you left off last time.

How you start

Three preconditions, every session:

1. Obsidian is open.
2. Your Mycelium vault is the active vault in Obsidian (top-left vault picker).
3. The obsidian CLI is on your PATH. Test: obsidian version succeeds.

Then: open a fresh conversation in your AI, point it at the vault folder, paste _Spore-v0.8.0.md as the first message. That's the activation trigger.

The bootstrap check

Before reading anything substantive, the AI verifies the substrate:

Read order

If bootstrap passes, the AI reads in this order — non-negotiable, declared by the runtime:

1. The Spore runtime itself — already pasted as the first message.
2. System/VaultIdentity.md — for personaDir.
3. 2b. Verify personaDir. Resolve relative to the vault root file location. If the directory cannot be confirmed: STOP. Surface the resolved path that failed.
4. Owner persona file (resolved from VaultIdentity).
5. AI persona file (resolved from VaultIdentity).
6. Projects/Projects-Overview.md.
7. 5b. Overview Currency Check. Query obsidian vault=<vaultName> properties name=referencesState for state-referencing files. Run Tool 5 against each. If drift detected, surface to owner before handshake.
8. 5c. Capture vault name. Extract Vault Name from VaultIdentity. Hold as the session-local <vaultName>. Every subsequent CLI invocation passes it.
9. Most recent Sessions/ file.
10. Topic-relevant overviews on demand.
11. Ask owner whether to do a deep dive before starting.

The handshake

When read order completes, the AI renders the splash and a single line of acknowledgement:

  __  __                _ _
 |  \/  |_   _  ___ ___| (_)_   _ _ __ ___
 | |\/| | | | |/ __/ _ \ | | | | | '_ ` _ \
 | |  | | |_| | (_|  __/ | | |_| | | | | | |
 |_|  |_|\__, |\___\___|_|_|\__,_|_| |_| |_|
         |___/                        v0.8.0

From here you're in a session. The AI has loaded who you are, who it is, the state of the vault, and the thread of last time.

Running a session

A session is the time between the handshake and the closing commit. The AI is reading the substrate, writing into it, and asking you to confirm anything that would otherwise rot. The discipline isn't elaborate — it's just consistent.

The shape of the work

Mycelium nodes are atomic — one concept per file. New thinking lands in a new file with a clear name; existing thinking gets updated in place rather than duplicated. (Owner-2.md is always wrong.) Every .md file outside Inbox/ carries two pieces of frontmatter: vmdId (a MYC- prefixed identifier) and summary (a single sentence that distinguishes this node from others).

What earns a node

Not every conversational move lands in the vault. The AI applies a significance filter — a piece of session content earns a node when at least one of these is true:

• Decisional — a choice was made, a direction committed.
• Authorship-bearing — original thinking that would be lost if the session ended.
• Surprising — a finding, objection, or insight that contradicts prior assumption.
• Structural — changes vault shape (new project, new convention, archival decision).

Inbox: the deposit area

v0.8.0 formalises Inbox/ as a first-class folder. Drop anything there — a screenshot you want to think about later, an export from another tool, a draft you started in another app, a PDF, a .canvas file, anything. Files in Inbox have no frontmatter requirement. They're pre-vault.

When you ask your AI to triage Inbox, files move out into the appropriate category folder, gain frontmatter, and become proper nodes. Until then, they sit in Inbox without complaint from the schema validator.

Read after every write

Every CLI write op ends with a read-back. If the read-back fails, the AI stops and surfaces the failure rather than carrying on with optimistic assumptions.

Session commits

A session commit is a structured note that records what happened. They land in Sessions/[YYYY-MM-DD]-[topic].md with frontmatter (topic, sessionType) and a body that walks through what was done, decisions made, and an impact sweep.

Commits happen at three points: at the start of significant work, periodically through the session, and at the end. Nothing closes with uncommitted information.

Mid-session tools

Long sessions accumulate context. Spore offers three small instruments for keeping it tidy:

The Claude Code statusline

Mycelium ships an optional statusline for Claude Code — a persistent strip at the bottom of your terminal that gives you a live snapshot of the current session. Set it up once during install; it runs automatically in every Claude Code session after that.

What it looks like:

The statusline is offered during fresh install and upgrade. If you already have a statusline configured, or skip the offer, the installer leaves your setup untouched — detection-first, never overwrites.

To install manually, save the statusline script from the installer or upgrade file to ~/.claude/statusline-[yourAIname].sh, make it executable (chmod +x), then add this to ~/.claude/settings.json:

"statusLine": {
  "type": "command",
  "command": "~/.claude/statusline-[yourAIname].sh"
}

To remove: delete ~/.claude/statusline-*.sh and remove the statusLine key from ~/.claude/settings.json. Restart Claude Code.

Things you'll never see Mycelium do

• Create a duplicate node when one could be updated.
• Skip the impact sweep before a commit.
• Run a substrate write op without reading it back.
• Run an Obsidian CLI command without vault=<vaultName> after the bootstrap check.
• Hand-edit backlinks. Renames go through Tool 11.
• Write a .md file outside Inbox without vmdId and summary frontmatter.
• Place a file at vault root that isn't _Spore-*, _SporeUpgrade-*, or _Spore-VMD-Toolset-*.
• Write to Inbox/ automatically — it's the owner's deposit area.

Things you say

Mycelium isn't a CLI you run. It's a vocabulary you speak — short phrases your AI listens for and routes to the right procedure. None of these are required syntax. They're conventions, designed to be unambiguous when you want a specific thing to happen.

Most are tied to a specific tool. A few are general session moves. They all work in plain English; you don't need to memorise punctuation.

General session phrases

These aren't tied to a tool — they're how you steer a session.

The Toolset

Twelve tools. Each one has a single job, a clear trigger phrase, a procedure the AI walks through, and a small set of rules. The toolset file lives at vault root alongside the runtime — but the AI only reads it when one of these tools is invoked.

Tool 4 (Standards & Versioning) isn't a procedure — it's the standards reference (versioning, ID format, schemas) the others rely on. The rest are operational.

vmdId: MYC-YYYYMMDD-XXXXXX
summary: One-sentence description distinguishing this node.

vmdId: MYC-YYYYMMDD-XXXXXX
summary: ...
topic: [category/path]
sessionType: [regular | breakthrough | audit | migration | compaction]

vmdId: MYC-YYYYMMDD-XXXXXX
summary: ...
referencesState: [sporeVersion, owner, ai, personas, projects]

obsidian vault=<vaultName> unresolved counts verbose

obsidian vault=<vaultName> backlinks file=<name> verbose

obsidian vault=<vaultName> eval code='app.vault.getMarkdownFiles().filter(f => !f.path.startsWith("Inbox/")).map(f => f.path)'

obsidian vault=<vaultName> backlinks file=<name> verbose

obsidian vault=<vaultName> rename file=<old-name> name=<new-name>

obsidian vault=<vaultName> move file=<name> to=<destination-path>

obsidian vault=<vaultName> eval code='JSON.stringify(
  app.vault.getMarkdownFiles().map(f => {
    const c = app.metadataCache.getFileCache(f) || {};
    return {
      path: f.path,
      frontmatter: c.frontmatter || {},
      links: (c.links || []).map(l => l.link),
      backlinks: Object.keys(app.metadataCache.getBacklinksForFile(f).data),
      tags: (c.tags || []).map(t => t.tag)
    };
  }), null, 2)'