🎭 MUSE

May 8, 2026 · View on GitHub

🎭 MUSE

The AI Coding Governance System — Roles, Memory, Skills, in Plain Markdown

The nine Muses of Greek mythology were daughters of Mnemosyne — the Titaness of Memory. They transformed their mother's gift of total recall into mastery of the arts and sciences.

MUSE inherits this lineage. It ensures no insight is lost across AI conversations, transforming raw session data into structured knowledge that drives execution.

MUSE is a pure-Markdown governance system for AI pair programming. It goes beyond format specs (like AGENTS.md or .cursorrules) by providing a full system — role isolation, persistent memory, 65 skills, cross-role directives, and visual dashboards — all with zero code dependencies.

┌─────────────────────────────────────────────────────┐
│ L3  Memory Infrastructure   mem0 · MemOS · memsearch│  ← MUSE doesn't compete here
├─────────────────────────────────────────────────────┤
│ L2  Governance System       🎭 MUSE                 │  ← Only player at this layer
│     Roles · Memory · Skills · Directives · Dashboard│
├─────────────────────────────────────────────────────┤
│ L1  Workflow Kits           Spec Kit · sudocode      │  ← MUSE covers this + more
├─────────────────────────────────────────────────────┤
│ L0  Format Specs            AGENTS.md · .cursorrules │  ← MUSE is compatible
└─────────────────────────────────────────────────────┘

AGENTS.md defines the format. MUSE builds the system on top of it.

Inspired by LCM (Lossless Context Management) + lossless-claw. MUSE implements LCM's core design principles using pure Markdown SOPs — zero code dependencies.

📖 中文文档 / Chinese Docs

✨ Why MUSE?

Problem: AI coding assistants have context window limits. Format specs like .cursorrules or AGENTS.md give your AI instructions — but they can't manage memory, roles, or cross-session knowledge. Long conversations forget early content. New conversations start from scratch.

Solution: MUSE wraps your AI with a governance protocol — role isolation, persistent dual-layer memory, 65 reusable skills, cross-role directive queue, and visual dashboards. All in plain Markdown.

Without MUSE	With MUSE
AI forgets early context in long conversations	Pre/Post Compaction protocols preserve critical info
New conversations need manual context setup	`/resume` auto-assembles context in 5 steps
One persona for all tasks	Role isolation: build / QA / growth each see only their context
No cross-session memory	Dual-layer: `memory/` (short-term) + `MEMORIES.md` (long-term)
Same mistakes repeated	`/distill` distills lessons → `/search` finds them later
No visibility into project health	Web Dashboard + VS Code Extension

🎯 Benchmark (run ./scripts/benchmark.sh on your own project):

/resume loads 16.9× more context than a bare .cursorrules cold start

15/15 governance features vs 0/15 for format-spec-only setups

344 lines of accumulated project knowledge vs 0 retained across sessions

MUSE Demo — /resume → boot → work → /ctx → /bye

Without MUSE vs With MUSE

Optional

Works with: Claude Code · OpenClaw · OpenCode · Cursor · Windsurf · Gemini CLI · Codex CLI · Copilot · Aider · Antigravity — or any AI tool that supports system prompts.

Tool	Install Command	Format
Claude Code / OpenClaw	`./scripts/install.sh --tool claude`	`.agent/skills/` + `CLAUDE.md`
OpenCode	`./scripts/install.sh --tool opencode`	`.agents/skills/` + `CLAUDE.md`
Cursor	`./scripts/install.sh --tool cursor`	`.cursor/rules/*.mdc`
Windsurf	`./scripts/install.sh --tool windsurf`	`.windsurf/rules/*.md`
Gemini CLI	`./scripts/install.sh --tool gemini`	`.gemini/skills/` + `GEMINI.md`
Codex CLI	`./scripts/install.sh --tool codex`	`AGENTS.md` (single file)
Copilot	`./scripts/install.sh --tool copilot`	`.github/copilot-instructions.md`
Aider	`./scripts/install.sh --tool aider`	`CONVENTIONS.md`
Antigravity	`./scripts/install.sh --tool antigravity`	`.gemini/antigravity/skills/`

Recommended companion: nah — context-aware permission guard for Claude Code. Deterministic classifier that auto-allows safe operations, asks for ambiguous ones, and blocks dangerous patterns (e.g. curl | bash). Eliminates permission fatigue without sacrificing safety. pip install nah && nah install

🚀 Quick Start (5 minutes)

Option A: Interactive Setup (Recommended)

# Clone MUSE
git clone https://github.com/myths-labs/muse.git

# Run interactive setup — configures language, model, and preferences
cd muse && ./setup.sh

The setup wizard will ask for your language, AI model, and docs preferences, then configure everything automatically.

Option B: Multi-Tool Install (Cursor / Windsurf / Gemini CLI / Codex CLI)

# Clone MUSE
git clone https://github.com/myths-labs/muse.git

# Install for your tool (auto-converts to the right format)
cd muse && ./scripts/install.sh --tool cursor --target /path/to/your-project

# Or auto-detect installed tools
./scripts/install.sh --target /path/to/your-project

Supported: claude, openclaw, opencode, cursor, windsurf, gemini, codex, or all.

Option C: Manual Setup

# Clone MUSE
git clone https://github.com/myths-labs/muse.git

# Copy templates to your project
cp muse/templates/CLAUDE.md your-project/CLAUDE.md
cp muse/templates/USER.md your-project/USER.md
cp muse/templates/MEMORIES.md your-project/MEMORIES.md
mkdir -p your-project/memory your-project/.muse

# Copy skills & workflows
cp -r muse/skills your-project/.agent/skills
cp -r muse/workflows your-project/.agent/workflows

# Add MUSE entries to your .gitignore
cat muse/templates/.gitignore-template >> your-project/.gitignore

Your project should look like:

your-project/
├── CLAUDE.md              # 📜 Constitution (AI iron rules)
├── ETHOS.md               # 💡 Builder philosophy (5 principles)
├── USER.md                # 👤 Your preferences
├── MEMORIES.md            # 🧠 Long-term lessons
├── .muse/                 # 🎭 Role states
│   └── build.md           # ⚙️ Dev execution
├── memory/                # Short-term memory
│   └── YYYY-MM-DD.md
├── .agent/
│   ├── skills/            # Skills library
│   └── workflows/         # resume/bye/sync/distill/ctx/sprint/retro
└── [your code]

2. Customize `CLAUDE.md`

This is MUSE's core — the AI's "constitution". Edit to match your project:

# Iron Rules
1. All communication in [your language]
2. Check Skills before ANY task
3. Large files: view ≤300 lines at a time
4. Context ≥ 80%: immediately exit
5. Verify before claiming done
6. End conversations with /bye

3. Start using

You: /resume           ← AI reads constitution → reads memory → starts work
     ... work ...
You: /ctx              ← Check if context is enough
     ... continue ...
You: /bye              ← One-click wrap-up, auto-save

Sprint workflow (v2.29+):

You: /sprint           ← Think → Plan → Build → Review → Test → Ship → Reflect
You: /retro             ← Weekly stats from git log + memory (commits, shipped, lessons)

🏛 Architecture

graph TB
    subgraph "🏛 Constitution Layer"
        A["CLAUDE.md"] --> B["Iron Rules + Safety"]
        A --> C["ETHOS.md<br/>Builder Philosophy"]
    end
    
    subgraph "🎭 Role Layer"
        R[".muse/*.md<br/>build · qa · growth"] --> S["Role Isolation"]
        R --> T["📡 Directive Queue<br/>cross-role messaging"]
    end
    
    subgraph "🧠 Memory Layer"
        D["memory/*.md<br/>short-term"] -->|"/distill"| E["MEMORIES.md<br/>long-term"]
        D --> D1["Drift Detection<br/>stale >7d auto-flag"]
        E --> E1["4 Categories<br/>preference · feedback<br/>project · reference"]
    end
    
    subgraph "🤖 Coordinator"
        CO["coordinator-mode"] --> CO1["Understand → Dispatch"]
        CO --> CO2["Sub-agent Synthesis"]
    end
    
    subgraph "⚡ Skills Layer (65)"
        G["Trigger Skills<br/>on-demand"]
        H["Lifecycle Skills<br/>strategic-compact"]
    end
    
    subgraph "🔄 Workflow Layer"
        I["/resume"] --> J["Work"]
        J -->|"/sprint"| SP["Think→Plan→Build<br/>→Review→Test→Ship"]
        J -->|"/ctx"| K{"Healthy?"}
        K -->|"🟢"| J
        K -->|"🔴"| L["/bye"]
        L --> D
        L --> L1["Digital Twin<br/>profile update"]
    end

LCM Concept Mapping

LCM Concept	MUSE Implementation	Description
SQLite persistence	`memory/` + `MEMORIES.md`	Markdown as database
Leaf nodes	`memory/YYYY-MM-DD.md`	Daily conversation snapshots
Condensed nodes	`MEMORIES.md`	Cross-day distilled lessons
Condensation	`/distill`	Leaf → long-term memory
Assembler	`/resume`	Context assembly
lcm_grep	`./scripts/search.sh` (TF-IDF)	Ranked semantic search
compact:before	Pre-Compaction Protocol	Save before compress
contextThreshold	`/ctx` 80% red line	Auto health check

📖 Commands

Command	Description	Input
`/start`	First-time setup — configures project, roles, language	None (interactive)
`/resume [scope]`	Boot — restore context & start work	`build`, `growth`, etc.
`/sprint`	Feature sprint — Think → Plan → Build → Review → Test → Ship → Reflect	None (guided)
`/retro`	Weekly retrospective — stats from git log + memory	None needed
`/settings`	Change language, AI model, or preferences	Subcommand (optional)
`/ctx`	Context health check (🟢🟡🔴)	None needed
`/bye`	One-click wrap-up — save, sync, archive	None needed
`/distill`	Condense `memory/` → `MEMORIES.md`	None needed
`/search`	TF-IDF search across memory, roles, skills	Query string
`/sync [direction]`	Cross-file sync in multi-role setup	Direction (optional)
`/sync receive`	Pull updates from other roles mid-conversation	None needed
`/resume [project] qa`	Start QA verification (independent from build)	Project name (optional)
`/resume crash`	Recover from context blowout	None needed

Defensive Auto-Save (L0 Defense)

MUSE doesn't wait for context to run out. Every 10 interaction rounds, it silently updates memory/CRASH_CONTEXT.md. If a sudden blowout occurs, at most 10 rounds of progress are lost.

Layer	Trigger	Reliability
L0	Every 10 rounds (silent)	⭐⭐⭐
L1	🔴 context detection	⭐⭐
L2	`/resume crash` scans `convo/`	⭐

Auto-Distill Detection

Every /bye automatically checks memory/ accumulation. Reminds you to /distill when:

≥ 7 days of un-distilled logs
≥ 5 new log files since last distill
≥ 15 total files and never distilled

🧩 Skill System

Loading Behavior

Type	When Loaded	Examples
Always-on	Every turn automatically	`CLAUDE.md` iron rules, Safety
Trigger	When task matches	`git-commit`, `systematic-debugging`
Lifecycle	On specific events	`strategic-compact` (compression), `verification` (completion)

Tier Classification

Tier	Description	Ships with MUSE?	Examples
🏛 Core	Required for MUSE to function	✅ Built-in	`context-health-check`, `strategic-compact`, `verification-before-completion`, `using-superpowers`
🔧 Toolkit	General dev tools, recommended	✅ Included	`git-commit`, `systematic-debugging`, `security-review`, `tdd-workflow`, `frontend-design`, `ui-ux-pro-max`, +19 more
🎯 Domain	User-created, domain-specific	❌ Private	Your own custom skills

Skill Lifecycle

memory/ lessons repeat → /distill finds pattern → write to MEMORIES.md
→ appears ≥3 times → upgrade to CLAUDE.md constitution
→ methodology is generic enough → create new Skill
→ useful across projects → contribute to MUSE Toolkit

📁 Directory Convention

Standard Project Structure

project/
├── CLAUDE.md              # 📜 Constitution
├── README.md              # Public README
├── LICENSE                # License
├── USER.md                # Preferences (private)
├── MEMORIES.md            # Long-term lessons (private)
├── assets/                # 🎨 Project assets (public)
│   ├── logo.png           # Project logo
│   ├── banner.png         # README/social banner
│   ├── screenshots/       # App screenshots
│   ├── diagrams/          # Architecture diagrams
│   └── social/            # Social media assets (OG images, previews)
├── .muse/                 # 🎭 Role states (private)
│   ├── build.md / qa.md / growth.md / ...
├── memory/                # Short-term memory (private)
│   └── YYYY-MM-DD.md
├── convo/                 # Conversation archives (private)
│   └── YYMMDD/
├── docs/                  # Documentation
│   ├── [public docs]      # → git push ✅
│   └── internal/          # Strategy/fundraising (private)
├── src/ | packages/       # Source code
└── .agent/                # Skills + Workflows (private)

Naming Conventions

Category	Pattern	Example
Memory logs	`YYYY-MM-DD.md`	`2026-03-12.md`
Conversations	`YYMMDD-NN-desc.md`	`260312-02-muse_setup.md`
Crash archives	`+_CRASH` suffix	`260312-05-debug_CRASH.md`
.muse roles	`[role].md` lowercase	`build.md`, `qa.md`

Assets Convention

Subdirectory	Purpose	Naming Pattern
`assets/` (root)	Logo, banner, favicon	`logo.png`, `banner.png`, `favicon.ico`
`assets/screenshots/`	App/feature screenshots	`feature-name.png` or `YYMMDD-feature.png`
`assets/diagrams/`	Architecture, flow charts	`component-name-diagram.png`
`assets/social/`	OG images, social cards	`og-default.png`, `x-card.png`

Tip: Keep assets/ in git (public). Large video files (>10MB) should use Git LFS or external hosting.

🔧 Customization

Minimal Setup (Personal Project)

Just 3 things:

CLAUDE.md — Constitution (required)
memory/ — Short-term memory (required)
MEMORIES.md — Long-term memory (recommended)

Standard Setup (Indie Developer)

Add the role system:

.muse/build.md — Dev state
.muse/qa.md — Quality verification
USER.md — Personal preferences

Full Setup (Team / Multi-Project)

Add GM + all roles + sync:

.muse/strategy.md — Strategy (global, one per workspace)
.muse/gm.md — Project GM (project-level CEO)
.muse/build.md + qa.md + growth.md + ops.md + research.md + fundraise.md
/sync workflow — Cross-role sync

🔌 MCP Server (Claude Plugin)

MUSE includes a built-in MCP (Model Context Protocol) server — a zero-dependency Bash implementation that lets Claude Code, Cursor, and other tools access your project's role files, memory, and directives through a standard protocol.

Quick Setup

# From your MUSE-enabled project
./scripts/mcp-server.sh --help

Available Tools

Tool	Description
`muse_get_status`	Read all L0 lines → project overview (~400 tokens)
`muse_list_roles`	List all role files with summaries
`muse_get_role`	Deep-read a specific role file
`muse_send_directive`	Send 📡 cross-role directive
`muse_write_memory`	Append to today's memory log
`muse_search_memory`	Search across memory files

Configuration

Add to your tool's MCP config (e.g., ~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "muse": {
      "command": "/path/to/muse/scripts/mcp-server.sh",
      "args": ["--project-root", "/path/to/your/project"]
    }
  }
}

Requires: jq (brew install jq on macOS, apt install jq on Linux)

🌐 Optional Third-Party MCP Integrations

MUSE links well-vetted third-party MCP servers as optional add-ons. Each runs independently, has its own token / config, and is fully opt-in.

MCP	Purpose	Cost	Setup
🎨 Lazyweb	UI design reference search · real-app screenshots + semantic descriptions (pricing pages, onboarding, dashboards, etc.)	Free (per-user token)	`/setup-lazyweb` — 3 steps, ~2 min

How it works: Open the vendor's install page, copy the generated install instructions block (token embedded), paste it to your AI agent (Claude Code / Cursor / Codex / OpenClaw / Windsurf / etc.), and say "install this". The agent picks the right install path for its client. Restart the client to load tools.

Why we link these: design taste calibration is non-trivial without real references. Lazyweb gives MUSE-driven projects access to a curated UI library — useful when an agent needs to advise on pricing pages, onboarding flows, dashboard layouts, or compare a mockup to industry patterns.

Want to suggest another MCP for the list? Open a PR · we vet for free-tier availability, no-billing safety, and per-user token isolation.

🤔 FAQ

Q: Does MUSE require installation? No. MUSE is pure Markdown files. Copy them to your project and you're ready. Zero dependencies.

Q: Which AI tools does it support? Ten tools with native install support: Claude Code, OpenClaw, OpenCode, Cursor, Windsurf, Gemini CLI, Codex CLI, Copilot, Aider, and Antigravity. Run ./scripts/install.sh --tool <name> to install in the correct format for each tool. Additionally, ./scripts/convert-skills.sh --tool <name> exports all 65 skills to any supported format. Import from agency-agents (35K+ ⭐) with --import agency-agents.

Q: How is this different from lossless-claw? lossless-claw is a code plugin (SQLite + DAG + sub-agents) that requires the OpenClaw runtime. MUSE is pure Markdown SOPs, works with any AI tool, zero dependencies. Same principles, different implementation.

Q: What if memory/ files pile up? Archive files older than 30 days to memory/archive/. Use /distill to extract key lessons into MEMORIES.md first, then safely archive the originals.

Q: Is there a visual dashboard? Yes! Two options:

Online: Visit muse.mythslabs.ai/dashboard and load your project folder — 100% client-side, data stays in your browser.
Local: Run ./scripts/dashboard.sh to generate a self-contained HTML dashboard at .muse/dashboard.html.

Q: How do I discover and share skills? Use ./scripts/skill-discovery.sh with commands like recommend "frontend", categories, stats, export <name>, or registry. See CHANGELOG for details.

Q: Is there a VS Code extension? Yes — vscode-extension/ provides an activity bar with Roles, Skills, and Memory tree views, plus in-editor dashboard and skill search. Run cd vscode-extension && npm install && npm run compile, then press F5.

💬 Follow Us

🌐 GitHub: Myths Labs
🐦 X (Twitter): @MythsLabs
💼 LinkedIn: Myths Labs
👤 Creator: @SunshiningDay — indie dev, solo-building MUSE

🙏 Credits

gstack by Garry Tan — Sprint pipeline, builder ethos, and reframing methodology (YC CEO's open-source software factory)
LCM Paper by Ehrlich & Blackman — Theoretical foundation for lossless context management
lossless-claw by Martian Engineering — OpenClaw implementation of LCM
nah by Manuel Schipper — Context-aware permission guard (complements MUSE's Safety Protocol)
Greek Mythology — Mnemosyne and her nine Muses, eternal symbols of memory and creation

📜 License

Built with 🎭 by Myths Labs — Solo-developed by JC

MUSE v3.4.0