A convention for local-first, portable AI memory.
Mycelium gives your AI assistant persistent memory across conversations — stored as plain markdown on your disk, owned by you, readable by any tool. No cloud sync. No vendor lock-in. No re-explaining yourself every session.
Every conversation with an AI starts from zero. You spend the first few minutes re-explaining who you are, what you're building, what you decided last week, what not to suggest again. Or you skip the re-briefing and get generic output.
The fix isn't a better model. It's giving the model a memory it doesn't own.
Mycelium is that memory. A structured vault of markdown files that your AI reads at the start of every session. It arrives knowing you — your projects, your decisions, your preferences, your history. When you switch tools or the next model drops, your memory comes with you. It's just files.
Mycelium is a convention, not a binary. The framework is four markdown files that together define how an AI assistant should boot into, read, write, and maintain a vault.
| File | Role |
|---|---|
_Spore-v0.5.1b.md |
Runtime — the core rules. Read order, write discipline, session lifecycle, handshake protocol. This is what your AI reads first every session. |
_Spore-VMD-Toolset.v0.5.1b.md |
Toolset — operational procedures. Vault audits, health checks, network layer, migration tools, versioning standards. Loaded on demand, not at boot. |
_MyceliumInstaller-v0.5.1b.md |
Installer — first-time setup. Creates the vault structure, persona files, identity system, and drops in the runtime. Runs once, then self-destructs. |
_SporeUpgrade-v0.5.1b.md |
Upgrade — brings an existing vault from any prior Spore version to the current one. Handles ID migration, persona migration, structural updates. Runs once per version bump, then self-destructs. |
The runtime and toolset live in your vault permanently. The installer and upgrade file do their job and disappear.
The repo also includes persona templates in templates/ — starting-point files for defining who you are and who your AI is. See Persona files are memory too for why these matter.
A Mycelium vault is a folder of structured markdown. At its core is Spore — a lean runtime specification that tells any AI assistant how to operate inside the vault.
- Boot — your AI reads the Spore runtime file
- Bootstrap check — it reads
System/VaultIdentity.mdto confirm the vault is healthy and the version matches - Persona load — it reads your owner profile and the AI persona file, so it knows who you are and who it is
- Context load — it reads the projects overview and the most recent session file
- Handshake — it confirms it's loaded and ready: "VMD loaded. Running Spore-v0.5.1b. Last session: [date] — [summary]. Ready to continue."
- Session — you work. The AI writes atomic notes, tracks decisions, commits session logs
- Close — impact sweep, session commit, index update. No session ends with uncommitted information
- Write one concept per file (atomic notes)
- Never duplicate — update existing nodes
- Tag every file with a unique VMD ID
- Read back after every write to confirm success
- Track what it changed and verify before committing
- Maintain a living index of every node in the vault
- Store sensitive data
- Overwrite files without reading them first
- Skip session commits
- Create files at the vault root
- Act without your confirmation on irreversible changes
After installation, your vault looks like this:
your-vault/
├── _Spore-v0.5.1b.md # Runtime (loaded every session)
├── _Spore-VMD-Toolset.v0.5.1b.md # Toolset (loaded on demand)
├── System/
│ ├── VaultIdentity.md # Vault ID, owner, config
│ ├── VMD-Index.json # Live node registry
│ └── User/ # Your operational files
├── Projects/
│ └── Projects-Overview.md # Active project navigation
├── Sessions/
│ └── Sessions-Overview.md # Session schema reference
├── Technical/
│ └── Technical-Overview.md # Vault architecture entry point
├── People/ # Collaborator nodes
└── Archive/ # Retired content (never deleted)
Persona files (your profile and the AI's identity) live outside the vault in a shared MyceliumPersonas/ directory, so they're consistent across all your vaults.
MyceliumPersonas/
├── Owner/
│ └── YourName.md # Who you are
└── AI/
└── AIName.md # Who the AI is in this relationship
The vault stores what you work on. The persona files store who's doing the work — and how you work together.
The owner file tells the AI who you are: how you think, how you build, what you care about, where your expertise sits. The AI file defines who the AI is in this relationship: its voice, its boundaries, its role, how it shows up. Together they form the relational memory that shapes every session. The way your AI responds to you, the way it calibrates tone, the way it knows when to push back and when to follow your lead — that all lives here.
The installer creates basic stubs to get you started, but the real value comes from building these out over time. The richer and more honest your persona files are, the better every conversation gets. And they're not static — as the working relationship evolves, the files should too. Your AI will propose updates when it notices something worth capturing. You should edit them yourself when something shifts.
Template files are included in templates/ to give you a starting point:
Owner-Template.md— sections for identity, thinking style, working preferences, technical knowledge, goals, and moreAI-Template.md— sections for personality, tone calibration, boundaries, vault role, and relationship context
The templates include a built-in enrichment mechanism. The AI template carries a standing mandate that instructs the AI to proactively propose updates to both persona files whenever something in a session would deepen the working relationship — a shift in how you collaborate, a new insight about how you think, a decision that changes the dynamic. The owner template includes a "What the Vault Knows" section that the AI maintains over time as its understanding of you evolves. Both files update together because they represent two sides of the same relationship.
This means your persona files don't depend on you remembering to edit them. The AI watches for significant moments and surfaces proposed changes. You approve or reject them. Over time, both files grow richer — and every session gets better because of it.
Copy them into your MyceliumPersonas/Owner/ and MyceliumPersonas/AI/ directories, rename them, and start filling them in. They don't need to be complete on day one — they compound, just like the vault.
- An AI assistant that can read and write local files — Claude Code CLI is the primary supported client
- A folder to use as your vault (an Obsidian vault works well, but any folder will do)
Mycelium has been token-optimised — the runtime is lean, the index loads on demand, and the boot sequence reads only what it needs. That said, a full session involves reading persona files, project context, session history, and writing structured notes back to disk. For the best experience, we recommend a Claude Max account, where extended conversations and heavy file interaction aren't constrained by rate limits. Mycelium works on lower tiers, but it really shines when you give it room to breathe.
- Create a folder for your vault (or use an existing Obsidian vault)
- Copy
_MyceliumInstaller-v0.5.1b.mdinto the folder - Open Claude Code pointed at that folder:
claude --project /path/to/your-vault
- Tell Claude to read the installer:
Read _MyceliumInstaller-v0.5.1b.md and run it. - The installer will ask you three questions — your name, the AI's name, and what the vault is for — then build everything. When it's done, it deletes itself.
- Build out your persona files — the installer creates stubs, but you'll want to flesh them out. Copy the templates from
templates/into yourMyceliumPersonas/Owner/andMyceliumPersonas/AI/directories and fill them in. This is where the real value starts.
Once installed, every new conversation starts the same way:
Read _Spore-v0.5.1b.md and run it as the vault runtime.
The AI boots into the vault, loads your context, and delivers the handshake. You're caught up from the first message.
If you'd rather skip the terminal, Mycelium Desktop handles vault registration, health checks, one-click Claude sessions, install and upgrade flows from a native macOS app.
Every vault and every person gets a unique, immutable ID.
| Prefix | Purpose |
|---|---|
MYC-YYYYMMDD-XXXXXX |
Vault identity |
OWN-YYYYMMDD-XXXXXX |
Owner identity (shared across all your vaults) |
GST-YYYYMMDD-XXXXXX |
Guest identity (scoped, revocable) |
Every markdown file in the vault carries a vmdId in its YAML frontmatter. The VMD-Index tracks every node — path, summary, type, timestamps. IDs survive vault renames, folder moves, and restructuring.
When a new Spore version drops:
- Copy
_SporeUpgrade-v0.5.1b.mdinto your vault - Tell Claude to read and run it
- The upgrade detects your current version, proposes a plan, waits for your approval, executes, runs a health check, and self-destructs
Or click the upgrade button in Mycelium Desktop.
The toolset (_Spore-VMD-Toolset.v0.5.1b.md) ships with five operational procedures your AI can run on demand:
| Tool | What it does |
|---|---|
| Audit | Full diagnostic — coverage, integrity, broken links, orphans, persona health, overview staleness |
| Migration | Version upgrades (delegates to the upgrade file) |
| Network Layer | Cross-vault communication — peers, collaborators, guests, propagation rules |
| Health Check | Lightweight index integrity, frontmatter sampling, root cleanliness |
| Standards | Versioning convention, ID format, node schemas, category rules |
Run any of them by asking your AI: "Run a vault audit" or "Run a health check."
- Local-first — your data never leaves your disk unless you put it there
- Plain markdown — human-readable, git-versionable, tool-agnostic
- Convention over configuration — the framework is a set of rules, not a runtime dependency
- Portable — switch AI providers, switch tools, your memory stays
- Sovereign — you own everything. No accounts, no cloud, no extraction
- Composable — vaults can connect via the Network Layer, but isolation is the default
Spore v0.5.1b — lean runtime with external persona layer, on-demand index loading, persona directory verification, and impact sweep protocol.
See the runtime and toolset files for the full specification.
Mycelium is actively developed. Here's what's on the roadmap:
Your vault holds context about you — that's the point. But not everything your AI needs to understand should be readable in plain text. Sensitive personal information — financial details, health notes, legal references, identity documents — shouldn't need to be exposed to the model to be useful.
We're building a redaction layer that automatically blinds sensitive fields before the AI reads them, while preserving enough structure for the AI to know the information exists and what category it falls into. You keep full access. The AI gets context without exposure.
Privacy shouldn't depend on trusting the model. It should be enforced by the format.
This is early. If something breaks, doesn't make sense, or could be better — halicon@gmail.com or open an issue here.
Apache License 2.0. See LICENSE.
- Designed and built by halicon at neuromance
- AI — Anthropic / Claude
Mycelium is built to compound over time. The longer you use it, the more it knows. The more it knows, the less you repeat yourself.