README.md
markdown
| 1 | # Muse |
| 2 | |
| 3 | > **A domain-agnostic version control system for multidimensional state.** |
| 4 | |
| 5 | Git works on text because text is one-dimensional — a sequence of lines. Diffs are additions and deletions to that sequence. |
| 6 | |
| 7 | Muse works on *any* state space where a "change" is a delta across multiple axes simultaneously. Music is the first domain. It is not the definition. |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## The Core Abstraction |
| 12 | |
| 13 | Strip Muse down to its invariants and what remains is: |
| 14 | |
| 15 | ``` |
| 16 | State = a serializable, content-addressed snapshot of any multidimensional space |
| 17 | Commit = a named delta from a parent state, recorded in a DAG |
| 18 | Branch = a divergent line of intent forked from a shared ancestor |
| 19 | Merge = three-way reconciliation of two divergent state lines against a common base |
| 20 | Drift = the gap between committed state and live state |
| 21 | Checkout = deterministic reconstruction of any historical state from the DAG |
| 22 | Lineage = the causal chain from root to any commit |
| 23 | ``` |
| 24 | |
| 25 | None of those definitions contain the word "music." |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## Plugin Architecture |
| 30 | |
| 31 | A domain plugin implements five interfaces. Muse provides the rest — the DAG engine, content-addressed object store, branching, lineage walking, topological log graph, and merge base finder. |
| 32 | |
| 33 | ```python |
| 34 | class MuseDomainPlugin(Protocol): |
| 35 | def snapshot(self, live_state: LiveState) -> StateSnapshot: |
| 36 | """Capture current live state as a serializable, hashable snapshot.""" |
| 37 | |
| 38 | def diff(self, base: StateSnapshot, target: StateSnapshot) -> StateDelta: |
| 39 | """Compute the minimal delta between two snapshots.""" |
| 40 | |
| 41 | def merge( |
| 42 | self, |
| 43 | base: StateSnapshot, |
| 44 | left: StateSnapshot, |
| 45 | right: StateSnapshot, |
| 46 | ) -> MergeResult: |
| 47 | """Three-way merge. Return merged snapshot + conflict report.""" |
| 48 | |
| 49 | def drift( |
| 50 | self, |
| 51 | committed: StateSnapshot, |
| 52 | live: LiveState, |
| 53 | ) -> DriftReport: |
| 54 | """Compare committed state against current live state.""" |
| 55 | |
| 56 | def apply(self, delta: StateDelta, live_state: LiveState) -> LiveState: |
| 57 | """Apply a delta to produce a new live state (checkout execution).""" |
| 58 | ``` |
| 59 | |
| 60 | The music plugin — the reference implementation — implements these five interfaces for MIDI state: notes, velocities, controller events, pitch bends, and aftertouch. Every other domain is a new plugin. |
| 61 | |
| 62 | --- |
| 63 | |
| 64 | ## Music — The Reference Implementation |
| 65 | |
| 66 | Music is the domain that proved the abstraction. State is a snapshot of MIDI files on disk. Diff is file-level set difference plus content comparison. Merge is three-way reconciliation of file sets against a common ancestor. Drift compares the committed snapshot against the live working tree. Checkout incrementally applies the delta between snapshots using the plugin. |
| 67 | |
| 68 | ```bash |
| 69 | # Initialize a Muse repository (default domain: music) |
| 70 | muse init |
| 71 | |
| 72 | # Commit the current working tree |
| 73 | muse commit -m "Add verse melody" |
| 74 | |
| 75 | # Create and switch to a new branch |
| 76 | muse checkout -b feature/chorus |
| 77 | |
| 78 | # View commit history as an ASCII graph |
| 79 | muse log --graph |
| 80 | |
| 81 | # Show uncommitted changes vs HEAD |
| 82 | muse status |
| 83 | |
| 84 | # Three-way merge a branch |
| 85 | muse merge feature/chorus |
| 86 | |
| 87 | # Cherry-pick a specific commit |
| 88 | muse cherry-pick <commit-id> |
| 89 | |
| 90 | # Revert a commit (creates a new commit undoing the change) |
| 91 | muse revert <commit-id> |
| 92 | |
| 93 | # Show a commit's metadata and file changes |
| 94 | muse show [<ref>] [--json] [--stat] |
| 95 | ``` |
| 96 | |
| 97 | Run `muse --help` for the full command list. |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | ## Domain Instantiations |
| 102 | |
| 103 | ### Music *(reference implementation)* |
| 104 | MIDI state across notes, velocities, controller events, pitch bends, and aftertouch. Three-way merge reconciles divergent takes. Drift detection compares the committed snapshot against the live DAW. **Already ships with full DAG, branching, three-way merge, and E2E tests.** |
| 105 | |
| 106 | ### Scientific Simulation *(planned)* |
| 107 | A climate model is a multidimensional state space: temperature, pressure, humidity, ocean current, ice coverage at every grid point. Commit a named checkpoint. Branch to explore a parameter variation. Merge two teams' adjustments against a common baseline run. Drift detection flags when a running simulation has diverged from its last committed checkpoint. |
| 108 | |
| 109 | ### Genomics *(planned)* |
| 110 | A genome under CRISPR editing is a high-dimensional sequence state. Each editing session is a commit. Alternate intervention strategies are branches. When two research teams converge on the same baseline organism and apply different edits, merge reconciles those edit sets against the common ancestor genome. The Muse DAG becomes the provenance record of every edit. |
| 111 | |
| 112 | ### 3D Spatial Design *(planned)* |
| 113 | Architecture, urban planning, game world construction. Branch to explore "what if we moved the load-bearing wall." Merge the structural engineer's changes and the lighting consultant's changes against the architect's baseline. Drift detection surfaces the delta between the committed design and the as-built state. |
| 114 | |
| 115 | ### Spacetime *(theoretical)* |
| 116 | A spacetime plugin models state as a configuration of matter-energy distribution across a coordinate grid. A commit is a named configuration at a set of coordinates. A branch is a counterfactual — what would the state space look like if this mass had been positioned differently at T₀. |
| 117 | |
| 118 | This is exactly what large-scale physics simulation does, without the version control semantics. Adding Muse semantics — content-addressed states, causal lineage, merge — makes simulation runs composable in a way they currently are not. Two simulations that share a common initialization can be merged or compared with the same rigor that two branches of a codebase can. |
| 119 | |
| 120 | Whether this scales to actual spacetime is a question for physics. Whether it applies to spacetime *simulation* is just engineering. |
| 121 | |
| 122 | --- |
| 123 | |
| 124 | ## Agent Collaboration |
| 125 | |
| 126 | Muse's most transformative application is **shared persistent memory for teams of collaborating agents**. |
| 127 | |
| 128 | Without a shared state store, collaborating agents are stateless with respect to each other. Each agent knows what it has done; none knows what the others have committed, branched, or abandoned. There is no canonical record of what has happened. |
| 129 | |
| 130 | Muse solves this at the protocol level. Every agent in a tree sees the same DAG. An agent can: |
| 131 | |
| 132 | - Read the full commit history to understand what has been tried |
| 133 | - Branch from any commit to explore an alternative without polluting the main line |
| 134 | - Commit its work with a message that becomes part of the permanent record |
| 135 | - Merge its branch back, with three-way reconciliation handling conflicts |
| 136 | - Check out any historical state to understand what the system looked like at any prior point |
| 137 | |
| 138 | This is the missing primitive for agent collaboration — not a message queue, not a shared database, but a **versioned, branchable, mergeable, content-addressed state store** that every agent in the tree can read and write coherently. |
| 139 | |
| 140 | A tree of musical agents with distinct cognitive identities, collaborating over a shared Muse repository: |
| 141 | |
| 142 | ``` |
| 143 | Composer (root coordinator) |
| 144 | ├── Bach agent — commits fugue subject on branch counterpoint/main |
| 145 | ├── Jimi Hendrix agent — commits lead response on branch lead/main |
| 146 | └── Miles Davis agent — commits harmonic reframing on branch modal/main |
| 147 | ``` |
| 148 | |
| 149 | The Composer runs a three-way merge. Conflicts are real musical conflicts — two agents wrote to the same beat, the same frequency range, the same structural moment. The Composer's cognitive architecture resolves them. |
| 150 | |
| 151 | This is not AI generating music from a prompt. This is structured improvisation between agents with distinct cognitive identities, mediated by a version control system. |
| 152 | |
| 153 | --- |
| 154 | |
| 155 | ## Repository Structure |
| 156 | |
| 157 | ``` |
| 158 | muse/ |
| 159 | domain.py — MuseDomainPlugin Protocol + shared type definitions |
| 160 | core/ — domain-agnostic VCS engine |
| 161 | store.py — file-based commit/snapshot/tag store (no external DB) |
| 162 | repo.py — repository detection (directory walk or MUSE_REPO_ROOT) |
| 163 | snapshot.py — content-addressed snapshot and commit ID derivation |
| 164 | object_store.py — SHA-256 blob storage under .muse/objects/ |
| 165 | merge_engine.py — three-way merge state machine |
| 166 | errors.py — exit codes and error primitives |
| 167 | plugins/ |
| 168 | registry.py — maps domain names → MuseDomainPlugin instances |
| 169 | music/ — music domain plugin (reference implementation) |
| 170 | plugin.py — implements all five MuseDomainPlugin methods for MIDI state |
| 171 | cli/ |
| 172 | app.py — Typer application root |
| 173 | commands/ — one file per subcommand |
| 174 | |
| 175 | tests/ |
| 176 | test_cli_*.py — CLI integration tests (one per command group) |
| 177 | test_core_*.py — core engine unit tests |
| 178 | test_music_plugin.py |
| 179 | test_plugin_registry.py |
| 180 | |
| 181 | docs/ |
| 182 | architecture/ — architecture reference and E2E walkthrough |
| 183 | protocol/ — MuseDomainPlugin protocol spec and domain concepts |
| 184 | reference/ — type contracts, .museattributes format |
| 185 | ``` |
| 186 | |
| 187 | --- |
| 188 | |
| 189 | ## Installation |
| 190 | |
| 191 | ```bash |
| 192 | # From source (recommended during v0.1.x development) |
| 193 | git clone https://github.com/cgcardona/muse |
| 194 | cd muse |
| 195 | pip install -e ".[dev]" |
| 196 | ``` |
| 197 | |
| 198 | Core dependencies: |
| 199 | |
| 200 | - Python 3.11+ |
| 201 | - Typer (CLI) |
| 202 | - mido (MIDI parsing, music plugin only) |
| 203 | - toml |
| 204 | |
| 205 | No database required. Muse stores all state in the `.muse/` directory — objects, snapshots, commits, refs — exactly like Git stores state in `.git/`. |
| 206 | |
| 207 | --- |
| 208 | |
| 209 | ## Documentation |
| 210 | |
| 211 | - [Architecture](docs/architecture/muse-vcs.md) — full technical design and module map |
| 212 | - [E2E Walkthrough](docs/architecture/muse-e2e-demo.md) — step-by-step lifecycle from `init` to merge conflict |
| 213 | - [Plugin Protocol](docs/protocol/muse-protocol.md) — language-agnostic `MuseDomainPlugin` specification |
| 214 | - [Domain Concepts](docs/protocol/muse-domain-concepts.md) — universal terms, cross-domain patterns, and music-specific vocabulary |
| 215 | - [Variation Spec](docs/protocol/muse-variation-spec.md) — music-domain variation UX and wire contract |
| 216 | - [Type Contracts](docs/reference/type-contracts.md) — named type definitions with Mermaid diagrams |
| 217 | - [`.museattributes` Reference](docs/reference/muse-attributes.md) — per-repo merge strategy overrides |
| 218 | |
| 219 | --- |
| 220 | |
| 221 | ## Origin |
| 222 | |
| 223 | Muse v1 proved the core VCS abstraction against a real, production music domain. Muse v2 generalizes that foundation into a domain-agnostic engine. |
| 224 | |
| 225 | *Built from the couch. March 2026.* |