> ## Documentation Index
> Fetch the complete documentation index at: https://musicready.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MRS: Music Representation

> A format for encoding musical scores optimized for AI-assisted composition workflows.

# MRS: Music Representation

**MRS enables AI-assisted composition and orchestration of full scores—symphonies, vocal arrangements, film cues—through iterative collaboration with a human arranger/orchestrator.**

Think of it as *Dorico-level score semantics* designed for collaboration with AI: the system can propose precise edits, but the human remains the musical authority. You might enter material through notation, a MIDI keyboard, or a rough sketch; MRS lets an agent work on a bounded region of the score with the right surrounding context, and lets you review and audition changes before they become canonical.

## Why MRS?

AI cannot currently compose or edit full orchestral scores reliably. Three fundamental challenges block progress:

1. **Scale**: A full orchestral score (\~1.5M tokens) exceeds any context window
2. **Context**: Musical decisions require understanding surrounding material
3. **Reliability**: Asking AI to emit complete score fragments creates high failure rates

MRS solves these through architectural separation:

* **MRS-S** for storage and reading: Complete, archival-quality score encoding with stable UUIDs
* **MRS-Ops** for mutation: Typed operations (create/update/delete) instead of “rewrite this section”
* **Task-adaptive context**: Context views shaped for the task (melody reference, harmony, phrase structure, orchestration map)
* **Orchestrator authority**: One system applies changes after validation, minting IDs and computing derived fields

> Note: “Syntax” is not the point. The core idea is a **semantic model + safe mutation protocol**. MRS-S is one representation of the model; implementations may also keep a database/graph-backed canonical state and *export* MRS-S for interchange and auditability.

**Is this approach feasible?** [Yes—read the detailed analysis →](/problem-and-approach)

## Core Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    SEMANTIC MODEL                            │
│         (One meaning, multiple representations)              │
└─────────────────────────────────────────────────────────────┘
                    │                    │
           ┌───────┴───────┐    ┌───────┴───────┐
           │    MRS-S      │    │   MRS-Ops     │
           │  (storage,    │    │  (mutation,   │
           │   reading)    │    │   writing)    │
           └───────────────┘    └───────────────┘
```

**MRS-S**: Agents read complete, human-auditable score fragments
**MRS-Ops**: Agents write typed operations that the orchestrator validates and applies

## Key Features

### Separation of Storage and Mutation

Different formats optimized for different purposes. Agents read MRS-S for complete context; agents write typed operations for reliable mutations. This eliminates accidental deletions, calculation errors, and hallucinated references.

### Player-Instrument-Staff Model

Professional orchestration semantics with instrument doubling and switching. Flute 2 can double piccolo. Clarinet can switch from Bb to A. Percussion players can cover multiple instruments.

### Orchestrator Authority

The orchestrator is the sole authority for UUID minting, derived field computation, and state management. Agents use temporary IDs; the orchestrator assigns final UUIDs. This eliminates coordination failures.

### Task-Adaptive Context

Agents receive context views tailored to their specific task—not fixed "near/far" rings. A countermelody task gets the melody it responds to. An orchestration task gets the texture map.

### Progressive Validation

Operations are validated in stages before application: syntax, references, permissions, musical rules. Errors are caught before state mutation with specific feedback.

### Lane Bundles

Common workflows grant multiple related lanes. "Orchestrate" grants notes + expression + technique. Reduces negotiation overhead for arrangers.

## Quick Links

**Getting Started**

* [The Problem & Why MRS is Feasible](/problem-and-approach) — Detailed feasibility analysis
* [Introduction](/introduction) — Motivation, goals, and terminology
* [Design Principles](/design-principles) — Core design philosophy
* [Quickstart](/quickstart) — Get started with MRS

**Architecture**

* [Architecture Overview](/architecture-overview) — How components work together
* [Orchestrator Contract](/orchestrator-contract) — Validation, transactions, conflict detection
* [Working Set Envelope](/working-set-envelope) — Scoped extraction with context

**Specification**

* [MRS Specification RFC](/MRS-Specification-RFC) — Full normative specification

## The Hardest Version of the Problem

MRS is designed for the demanding case: **building a large, evolving score from scratch** with professional notation detail, while keeping iteration fast.

That means supporting:

* **Professional orchestration reality**: player/instrument semantics (doubling, switching, condensing)
* **Structural evolution**: insert measures/sections/movements without breaking references
* **Draft states**: placeholders and sketches that are intentionally incomplete
* **Safe iteration**: edits expressed as operations, validated before they touch canonical state
* **Human checkpoints**: the orchestrator can lock approved decisions (form, harmony plan, orchestration) and prevent regression

If this architecture works for a symphony, it will work for smaller projects too.