🎭 MUSE

Memory-Unified Skills & Execution

[](https://github.com/myths-labs/muse/blob/main/LICENSE) [](https://github.com/myths-labs/muse/blob/main/CHANGELOG.md) [](https://github.com/myths-labs/muse) [](#) [](#)

[](https://x.com/MythsLabs) [](https://linkedin.com/company/MythsLabs) [](https://github.com/myths-labs) [](https://x.com/sunshiningday)

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 operating system for AI pair programming. Through constitutions, memory layers, skills, and execution workflows, it enables lossless context management across AI coding conversations.

Inspired by the LCM (Lossless Context Management) paper + lossless-claw plugin. 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. Long conversations forget early content. New conversations start from scratch. The same mistakes are made twice.

Solution: MUSE doesn't change the AI — it wraps it with a document protocol that lets it manage its own memory, restore its own context, and save critical info before compression.

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

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, 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)
├── 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
└── [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

🏛 Architecture

graph TB
    subgraph "🏛 Constitution Layer"
        A["CLAUDE.md"] --> B["Iron Rules + Safety"]
        A --> C["Context Protection"]
    end

    subgraph "🧠 Memory Layer"
        D["memory/*.md<br/>short-term"] -->|"/distill"| E["MEMORIES.md<br/>long-term"]
    end

    subgraph "⚡ Skills Layer"
        G["Trigger Skills<br/>on-demand"]
        H["Lifecycle Skills<br/>strategic-compact"]
    end

    subgraph "🔄 Workflow Layer"
        I["/resume"] --> J["Work"]
        J -->|"/ctx"| K{"Healthy?"}
        K -->|"🟢"| J
        K -->|"🔴"| L["/bye"]
        L --> D
    end

LCM Concept Mapping

📖 Commands

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.

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

Tier Classification

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

Assets Convention

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

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)

🤔 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?
Six tools with native install support: Claude Code, OpenClaw, Cursor, Windsurf, Gemini CLI, and Codex CLI. Run ./scripts/install.sh --tool <name> to install in the correct format for each tool. Any other tool that reads Markdown project rules will also work with manual setup.

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.

💬 Follow Us

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

🙏 Credits

• 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

MIT © Myths Labs

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

MUSE v2.15.0