Agent Protocol Specification

Inspired by MemOS (multi-agent isolation + sharing) and multi-agent-memory (cross-agent persistence). Adapted for MUSE's pure Markdown zero-dependency architecture. Added in v2.12.0 (Batch 2 — competitive tech absorption).

Why

MUSE role files (

.muse/*.md

Problems this solves:

1. Agent handoff: When switching between Agents (e.g., Claude → Gemini), context should be portable
2. Multi-agent coordination: Multiple Agents working on the same project should respect role boundaries
3. Tool interoperability: MCP servers, IDE plugins, and CLI tools should be able to read/write role files

Protocol: MUSE Role File Spec v1.0

File Discovery

.muse/
├── strategy.md    # Strategy role
├── build.md       # Build/Dev role
├── growth.md      # Growth/Marketing role
├── qa.md          # QA/Verification role
├── gm.md          # General Manager role
├── ops.md         # Operations role
├── research.md    # Research role
├── fundraise.md   # Fundraise role
└── archive/       # Archived content (not loaded)

Discovery rule: Any

.md

.muse/

archive/

L0 Header (Machine-Readable Status Line)

Every role file MUST have an L0 comment as its first line:

<!-- L0: {version} | {top_priority} | {status_flags} -->

Parsed fields:

version

v2.11.0

top_priority

P0=竞品技术吸收Batch2

status_flags

QA PASS, 3 pending directives

L0 is the Agent's "at a glance" API — any tool can grep all L0 lines to get project status in ~400 tokens.

Section Protocol

Role files use Markdown headers as semantic sections. Tools should parse these:

## 📐 职责边界

## ⏳ 待办

## 🎯 TODO

## 📡 已接收战略指令

## 📡 QA→BUILD 通知

## 🛠️ 技术栈

## 📋 CHANGELOG 维护规则

Directive Protocol (📡)

Directives are the message-passing API between roles:

📡 **S{NNN}→{TARGET}**: {STATUS} **{TITLE}**
> {BODY}

S{NNN}

S041

{TARGET}

ROLE

PROJECT/ROLE

MUSE/BUILD

GROWTH

{STATUS}

🟡

{TITLE}

竞品深度调研回传

{BODY}

Pickup protocol:

1. Target role's

   /resume

   scans for 🟡 directives
2. On pickup: write to role file's

   📡 已接收战略指令

   section
3. Change source 🟡 → ✅ with timestamp

Memory Protocol

memory/
├── YYYY-MM-DD.md   # Daily log (short-term, raw)
├── archive/        # Old logs
MEMORIES.md          # Long-term knowledge (distilled + auto-captured)

memory/YYYY-MM-DD.md

/bye

/resume

MEMORIES.md

/distill

/bye

/resume

CLAUDE.md

USER.md

/settings

/resume

Isolation Rules

┌─────────────────────────────────────────────┐
│ Agent Session (e.g., /resume build)         │
│                                             │
│  ✅ CAN READ:                               │
│  - Own role file (.muse/build.md)           │
│  - L0 lines of ALL role files               │
│  - memory/*.md                              │
│  - MEMORIES.md, CLAUDE.md, USER.md          │
│  - Source code & docs (on demand)           │
│                                             │
│  ✅ CAN WRITE:                               │
│  - Own role file                            │
│  - memory/YYYY-MM-DD.md                     │
│  - MEMORIES.md (auto-capture only)          │
│  - Source code (if build/dev role)           │
│                                             │
│  ❌ MUST NOT:                                │
│  - Write to other role files directly       │
│  - Create files outside .muse/ convention   │
│  - Discuss other roles' topics in depth     │
│                                             │
│  📡 CROSS-ROLE COMMS:                        │
│  - Only via directive protocol (📡 S{NNN})  │
│  - Sender writes directive to OWN file      │
│  - Receiver picks up during /resume         │
└─────────────────────────────────────────────┘

Multi-Project Protocol

For users managing multiple projects:

~/ProjectA/.muse/build.md     ← ProjectA's build role
~/ProjectB/.muse/build.md     ← ProjectB's build role
~/ProjectA/.muse/strategy.md  ← May hold cross-project directives

Cross-project directives use

PROJECT/ROLE

📡 S041→MUSE/BUILD: 🟡 ...    ← Targets MUSE project's BUILD role
📡 S040→DYA/GROWTH: ✅ ...     ← Targets DYA project's GROWTH role

Path resolution:

CLAUDE.md

> strategy.md 绝对路径: `/Users/jj/Desktop/DYA/.muse/strategy.md`

Integration Points

For MCP Servers

An MCP server implementing MUSE protocol is included — see

scripts/mcp-server.sh

muse_get_status

muse_list_roles

muse_get_role

muse_send_directive

muse_write_memory

muse_search_memory

Configuration: Add to your MCP client config:

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

For CLI Tools

# Get project status (all L0 lines)
grep "<!-- L0:" .muse/*.md

# Check for pending directives
grep "🟡" /path/to/strategy.md

# Count role file lines (bloat check)
wc -l .muse/*.md

For IDE Plugins

• Status bar: Show L0 summary of current role
• Sidebar: List pending directives (🟡)
• On save: Auto-update L0 line if role file changed

Version History

scripts/mcp-server.sh