README.md
markdown
| 1 | # Muse VCS |
| 2 | |
| 3 | **Muse** is a Git-style version control system for musical compositions. It gives AI agents and human composers a complete version-control workflow — commit, branch, merge, checkout, rebase, cherry-pick, bisect, and more — built specifically around the semantics of music: notes, phrases, tracks, regions, and time. |
| 4 | |
| 5 | Muse was extracted from [Maestro](https://github.com/tellurstori/maestro), the AI music composition backend powering the [Stori DAW](https://tellurstori.com) for macOS. |
| 6 | |
| 7 | --- |
| 8 | |
| 9 | ## What is Muse? |
| 10 | |
| 11 | Where Git tracks line-level diffs in text files, Muse tracks **note-level diffs** in MIDI compositions. A Muse commit records which notes were added, modified, or removed — and by which instrument, in which region, at which beat. The commit graph forms a DAG identical to Git's, enabling the same branching and merging model, but applied to music. |
| 12 | |
| 13 | Key capabilities: |
| 14 | |
| 15 | - **Commit / branch / checkout / merge** — full VCS lifecycle for musical state |
| 16 | - **Three-way merge** — auto-resolves non-conflicting note changes across tracks |
| 17 | - **Drift detection** (`muse status`) — detects uncommitted working-tree changes against HEAD |
| 18 | - **Rebase / cherry-pick / revert / reset** — full history rewriting and surgery |
| 19 | - **Bisect** — binary search over commit history for regression hunting |
| 20 | - **Stash** — shelve uncommitted changes temporarily |
| 21 | - **Rerere** — reuse recorded conflict resolutions across repeated merges |
| 22 | - **Musical analysis** — groove-check, emotion-diff, motif tracking, divergence scoring, contour analysis, and more |
| 23 | - **CLI** (`muse`) — 70+ subcommands covering every VCS primitive |
| 24 | - **HTTP API** — FastAPI router at `/api/v1/muse/*` for DAW integration |
| 25 | - **Content-addressed object store** — SHA-256 blobs under `.muse/objects/`, mirroring Git's loose-object layout |
| 26 | |
| 27 | --- |
| 28 | |
| 29 | ## Repository Structure |
| 30 | |
| 31 | ``` |
| 32 | maestro/ |
| 33 | services/muse_*.py — 33 service modules (merge, rebase, drift, checkout, etc.) |
| 34 | muse_cli/ — CLI package: app.py + 73 command files |
| 35 | api/routes/muse.py — FastAPI HTTP router |
| 36 | db/muse_models.py — SQLAlchemy ORM models |
| 37 | |
| 38 | tourdeforce/ |
| 39 | clients/muse.py — HTTP client for the Muse API |
| 40 | |
| 41 | tests/ |
| 42 | test_muse_*.py — 30 unit/integration test files |
| 43 | muse_cli/ — 54 CLI-level test files |
| 44 | e2e/ — E2E harness, golden-path, and integration tests |
| 45 | test_commit_drift_safety.py |
| 46 | |
| 47 | docs/ |
| 48 | architecture/muse-vcs.md — canonical architecture reference |
| 49 | architecture/muse-e2e-demo.md — E2E demo walkthrough |
| 50 | protocol/muse-protocol.md — language-agnostic protocol spec |
| 51 | protocol/muse-variation-spec.md — variation UX and wire contract |
| 52 | reference/muse-attributes.md — .museattributes format reference |
| 53 | ``` |
| 54 | |
| 55 | The internal package paths (`maestro/services/muse_*.py`, `maestro/muse_cli/`, etc.) are preserved from the original Maestro monorepo so that all internal cross-imports remain intact. |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## CLI Quick Reference |
| 60 | |
| 61 | ```bash |
| 62 | # Initialize a Muse repository in the current directory |
| 63 | muse init |
| 64 | |
| 65 | # Stage and commit the current working tree |
| 66 | muse commit -m "Add verse melody" |
| 67 | |
| 68 | # Create and switch to a new branch |
| 69 | muse checkout -b feature/chorus |
| 70 | |
| 71 | # View commit history as an ASCII graph |
| 72 | muse log --graph |
| 73 | |
| 74 | # Show uncommitted changes vs HEAD |
| 75 | muse status |
| 76 | |
| 77 | # Three-way merge a branch |
| 78 | muse merge feature/chorus |
| 79 | |
| 80 | # Cherry-pick a specific commit |
| 81 | muse cherry-pick <commit-id> |
| 82 | |
| 83 | # Binary-search for a regression |
| 84 | muse bisect start --bad HEAD --good <commit-id> |
| 85 | |
| 86 | # Analyse rhythmic groove drift across history |
| 87 | muse groove-check |
| 88 | |
| 89 | # Compare emotion vectors between two commits |
| 90 | muse emotion-diff <commit-a> <commit-b> |
| 91 | ``` |
| 92 | |
| 93 | Run `muse --help` for the full list of subcommands, or `muse <subcommand> --help` for per-command usage. |
| 94 | |
| 95 | --- |
| 96 | |
| 97 | ## HTTP API |
| 98 | |
| 99 | The FastAPI router exposes five endpoints at `/api/v1/muse`: |
| 100 | |
| 101 | | Method | Path | Description | |
| 102 | |--------|------|-------------| |
| 103 | | `POST` | `/muse/variations` | Persist a variation (commit a musical change) | |
| 104 | | `POST` | `/muse/head` | Set the HEAD pointer | |
| 105 | | `GET` | `/muse/log` | Retrieve the commit DAG as a `MuseLogGraph` | |
| 106 | | `POST` | `/muse/checkout` | Check out a prior variation (time travel) | |
| 107 | | `POST` | `/muse/merge` | Three-way merge two variations | |
| 108 | |
| 109 | --- |
| 110 | |
| 111 | ## Dependencies |
| 112 | |
| 113 | Muse was extracted from the Maestro monorepo. Some imports reference `maestro.*` packages (domain models, database utilities, DAW state). To run Muse standalone, you will need to either: |
| 114 | |
| 115 | 1. Install the Maestro core package as a dependency, or |
| 116 | 2. Refactor the `maestro.*` imports to a standalone `muse.*` package namespace (planned for a future release). |
| 117 | |
| 118 | Core runtime dependencies (inherited from Maestro): |
| 119 | |
| 120 | - Python 3.11+ |
| 121 | - FastAPI + uvicorn |
| 122 | - SQLAlchemy (async) + asyncpg |
| 123 | - Pydantic v2 |
| 124 | - Typer (CLI) |
| 125 | - httpx |
| 126 | |
| 127 | --- |
| 128 | |
| 129 | ## Documentation |
| 130 | |
| 131 | - [Architecture](docs/architecture/muse-vcs.md) — full technical design |
| 132 | - [E2E Demo](docs/architecture/muse-e2e-demo.md) — step-by-step lifecycle walkthrough |
| 133 | - [Protocol Spec](docs/protocol/muse-protocol.md) — language-agnostic protocol definition |
| 134 | - [Variation Spec](docs/protocol/muse-variation-spec.md) — variation UX and wire contract |
| 135 | - [`.museattributes` Reference](docs/reference/muse-attributes.md) — per-repo merge strategies |
| 136 | |
| 137 | --- |
| 138 | |
| 139 | ## Origin |
| 140 | |
| 141 | Muse is part of the [Tellurstori](https://tellurstori.com) music technology stack. It was built as an embedded subsystem of [Maestro](https://github.com/tellurstori/maestro) and extracted into this standalone repository to enable independent development and reuse. |