WHITE_PAPER.md · gabriel/muse

Git is brilliant at version-controlling text. Everything that isn't text — music, genomes, 3D scenes, simulation states — Git stores blindly and manages badly. Muse fixes this.

14

15

---

16

17

## What Git Actually Does

18

19

Git treats every file as a sequence of bytes. It finds the difference between two versions by scanning for changed lines. It detects a conflict when two branches both changed lines in the same region.

20

21

This is a deeply elegant model for source code. Source code is text. Lines have meaning. Changes to line 47 rarely affect line 3. The model fits.

22

23

But what happens when you commit a MIDI file?

24

25

```

26

$ git diff before.mid after.mid

27

Binary files before.mid and after.mid differ

28

```

29

30

That's it. That's all you get. Git sees bytes — it doesn't see notes, velocities, tempo, sustain pedal, key signature. It doesn't know which bytes matter or why. And when two people edit the same MIDI file on different branches, Git calls it a conflict even if one person only touched the sustain pedal and the other only changed a note's velocity. Those changes have nothing to do with each other. Git can't tell.

31

32

This isn't a limitation of Git specifically. It's a limitation of the model: **bytes don't remember what they mean.**

---

## The World Git Was Built For Is Shrinking

37

38

For thirty years, version control was a programmer's tool. The things being versioned were mostly code. That world is ending fast.

39

40

AI agents write music. They generate genomic annotations. They construct 3D environments. They run scientific parameter sweeps that produce petabytes of structured simulation state. They compose, iterate, branch, and merge at a rate no human team ever could.

41

42

When ten AI agents are concurrently editing a MIDI composition — each working on a different aspect, each on its own branch — they need to merge. With byte-level VCS, that merge is a disaster. With Muse, it just works.

43

44

The pace of AI-assisted creative and scientific work is going to expose the byte-level model as the bottleneck it has always been. Muse is the answer to that bottleneck.

---

## What Muse Does Differently

49

50

Muse doesn't see bytes. It sees **things**.

51

52

When Muse looks at a MIDI file, it sees 21 distinct dimensions of musical state: the notes, the sustain pedal, the tempo map, the pitch bend, the volume automation, the reverb sends, the key signatures, the marker cues, and more. Each dimension is declared independently. Each has its own diff algorithm. Each can be merged independently.

53

54

When two branches both modify the same MIDI file, Muse doesn't ask "which bytes overlapped?" It asks: "did they touch the same dimension?" If Alice changed the sustain pedal and Bob changed a note velocity, those are two independent dimensions. Muse merges them automatically. No conflict. No human required.

55

56

Of the 21 MIDI dimensions Muse tracks, 18 are fully independent. Two collaborators can edit any two of those 18 simultaneously and always merge cleanly. Only the three structural dimensions — tempo, time signature, and track identity — require coordination, because changes to those shift the meaning of everything else.

57

58

Git would have called every one of those 18×18 combinations a conflict. Muse calls them clean merges.

---

## A Concrete Example

63

64

Imagine two musicians collaborating on a MIDI file.

65

66

**Alice** records a sustain pedal pass — she's cleaning up the piano performance, adding lifts and holds through the chord progression.

67

68

**Bob** adjusts note velocities in the same section — he's working on dynamics, making the melody swell in bars 5–8.

69

70

They're working on the same file. They're working in the same bars. In Git:

71

72

```

73

CONFLICT (content): Merge conflict in lead.mid

74

```

75

76

Git can't tell that Alice's sustain edits and Bob's velocity edits are completely independent. All it knows is that both branches produced different bytes in the same file.

In Muse:

```

✅ Auto-merged: cc_sustain (Alice) + notes (Bob) — independent dimensions

82

```

83

84

Muse parsed both files, classified every event by dimension, checked independence, and merged. No conflict because there was no real conflict. The byte-level appearance of conflict was an artifact of flat storage, not a real semantic collision.

85

86

This is the whole idea. **The conflict wasn't real. The byte model made it look real.**

---

## The Plugin Model: Teaching Muse New Domains

91

92

Muse's core engine is domain-agnostic. It doesn't know anything about MIDI, genomes, or scene graphs. What it knows is: there are plugins, and plugins understand domains.

93

94

Every domain plugin implements six things:

95

96

1. **Snapshot** — capture the current state of the artifact

97

2. **Diff** — describe what changed, in domain terms (not byte offsets)

98

3. **Merge** — combine two change streams, dimension by dimension

99

4. **Drift** — detect uncommitted changes in the working copy

100

5. **Apply** — apply a delta to a live state

101

6. **Schema** — declare the structure: which dimensions exist, which are independent

102

103

That's the entire contract. If you can implement those six methods for your domain, Muse can version-control it — with semantic diffs, clean merges, entity lineage tracking, and selective cherry-pick.

104

105

The core engine never changes. New domains are new plugins. Music was first. Source code, Bitcoin's UTXO state, and a scaffold for new domains are next. Genomics, 3D spatial design, and climate simulation are the logical next steps.

---

## What "Semantic Diff" Actually Feels Like

110

111

Git's diff for a note velocity change:

112

113

```

114

Binary files before.mid and after.mid differ

115

```

116

117

Muse's diff for the same change:

118

119

```

120

~ C4 vel=80 → vel=100 @beat=1.00 bar 2

121

(expression edit — velocity increased by 20)

122

```

123

124

Git's diff for a new note:

125

126

```

127

Binary files before.mid and after.mid differ

```

Muse's diff:

```

+ E4 vel=90 @beat=3.50 dur=0.25 bar 7

134

(new eighth note inserted in melody)

135

```

136

137

These aren't cosmetic differences. They're the difference between information you can act on and noise. A semantic diff tells you what changed in the language of the domain. A byte diff tells you that something changed — somewhere — in a blob.

138

139

This matters even more for blame and history. Git blame on a MIDI file: meaningless. Muse's equivalent:

140

141

```

142

$ muse note-blame lead.mid C4@beat=1.00

143

note C4 @beat=1.00: commit a3f8... "adjusted expression in bar 2"

144

by Alice · 2026-03-10

145

```

146

147

"Who last changed the velocity of this specific note, and why?" That question is structurally unanswerable with byte-level VCS. Muse answers it because it has been tracking note identity — not byte offsets — across the entire commit history.

---

## Entity Identity

Here's a subtle but important point: byte-level diff doesn't just lose semantic meaning — it loses the ability to track whether two versions of something are the *same thing*.

154

155

Consider a note C4 at beat 1.00. Someone changes its velocity from 80 to 100. To Git, this is: "some bytes changed somewhere in the file." It can't say "the same note, mutated." It can only say "these bytes were removed, these bytes were added."

156

157

Muse tracks a stable identity for each entity — a note, a gene, an AST node — across its entire mutation history. When a note's velocity changes, Muse records:

158

159

```

160

MUTATE note:C4@beat=1.00

161

velocity: 80 → 100

162

(same note, different expression)

163

```

164

165

This unlocks a capability byte-level systems can never have: **field-level merge**. Two concurrent edits to the same note — one changes velocity, one changes timing — are independent field mutations. They don't conflict. Muse auto-merges them. Git can't even see that they're about the same note.

---

## Why This Matters for AI Agents Specifically

170

171

Human collaboration is slow. Two musicians editing the same file in the same week is unusual. Two AI agents editing the same file in the same second is routine.

172

173

At human timescales, coarse conflict detection is tolerable. You can open the file, look at the conflict markers, make a judgment call. At AI timescales — ten agents running in parallel, each committing dozens of changes per minute — coarse conflict detection is a wall. Every false conflict is a stall. Every stall requires human intervention. The entire point of using AI agents is lost.

174

175

Muse is built for this reality. The dimension-level independence model means that AI agents working on different aspects of the same artifact — melody vs. dynamics vs. automation — never conflict, because they're declared independent. The CRDT layer goes further: for domains that support it, concurrent writes by any number of agents converge mathematically to the same result, with no conflicts possible at all.

176

177

This isn't a future aspiration. It's in the codebase now.

---

## Muse Today

Muse is a working CLI tool — `muse init`, `muse commit`, `muse diff`, `muse merge`, `muse log` — built on a content-addressed object store, a commit DAG, and a plugin architecture. The MIDI plugin is the reference implementation. The code plugin adds AST-level diffing for 15 programming languages and automatic semver impact detection. A scaffold plugin makes it straightforward to add new domains.

184

185

The test suite has 3000+ passing tests across the core engine and plugin layer. The architecture is strict: the core never imports from plugins, plugins are fully isolated, and every public interface is typed end-to-end.

186

187

This is not a prototype or a thought experiment. It's a real system with real constraints, real tradeoffs, and a real path to the domains that need it most.

---

## The Domains Waiting

192

193

The same problem that breaks MIDI in Git breaks everything else that isn't text:

194

195

**Genomics** — A team annotating a reference genome needs to track edits across chromosomes, gene boundaries, and structural variants. Each chromosome is an independent dimension. Concurrent edits to different chromosomes should never conflict. `muse blame genome.gff3 chr3:14523` should tell you exactly which researcher established that annotation. None of this is possible with byte-level VCS.

196

197

**3D Design** — A game studio versioning scene graphs, animation rigs, material libraries, and physics parameters. Mesh positions, light targets, and camera frustums all depend on the coordinate system and scale — a structural global parameter, like tempo in MIDI. Editing a mesh is independent of editing a material. These should merge cleanly.

198

199

**Scientific Simulation** — Climate models, molecular dynamics, orbital simulations. Floating-point arrays where "changed" means "changed by more than epsilon." Multiple researchers running parameter sweeps on different variables simultaneously. The sweep results need to be versioned, diffed, and merged — not stored as opaque binary blobs.

200

201

The plugin protocol is the same for all of them. The core engine doesn't change. The problem is the same problem — bytes that don't remember what they mean — and the solution is the same solution: give the VCS a domain model.

---

## What Muse Is Not

Muse is not trying to replace Git for source code. Git is excellent at source code. Muse's code plugin adds semantic diffing on top of a Git-like foundation, but the point isn't "Git, but better for Python." The point is: **the 98% of structured data that isn't source code has never had a real version control system.** Muse is that system.

208

209

Muse is also not a database, not a file sync service, not a cloud storage layer. It's a version control system — the same abstraction as Git, operating at a different semantic level.

210

211

And Muse is not finished. It's a working foundation with proven architecture and a clear path forward. The hard part — getting the plugin model right, getting the typed operation algebra right, getting the merge hierarchy right — is done. The easy part (relatively speaking) is implementing more domain plugins.

---

## The Core Idea, Distilled

216

217

Version control has always been about tracking **what changed**. Git answers that question for bytes. Muse answers it for **things** — notes, genes, mesh vertices, AST nodes, simulation parameters.

218

219

The things have structure. The structure has independence. The independence enables conflict-free collaboration at a scale and speed that byte-level systems can never reach.

220

221

That's the whole idea. The implementation is in `/muse/`. The plugin protocol is six methods. The first domain is music.

222

223

The rest is an open invitation.

---

*Muse is open source. Implementation: `muse/`. Plugin protocol: `muse/domain.py`. MIDI plugin: `muse/plugins/midi/plugin.py`. Tests: `tests/`. Version 0.1.4 · 419 commits · 3,273 passing tests · March 2026.*