Build with Muse
Muse is a content-addressed version control engine for structured state.
Where Git versions lines of text, Muse versions what the content means: for
source code that is its functions, classes and imports, so history, diffs and
merges can be followed symbol by symbol. Every object has a
sha256: ID, and hub API requests are authenticated with MSign
Ed25519 request signatures — no passwords, no JWTs.
The domain protocol is six methods — snapshot, diff,
merge, drift, apply and schema.
Implement them and the engine supplies the rest: the commit DAG, branching,
checkout, history and merge-base finding. Source code is the primary domain
today; a MIDI plugin is maintained but off by default, and state spaces such as
genomic data or financial models are each one new plugin away.
Agents are first-class. Commits record agent_id and
model_id when an agent supplies them. Once you have an identity on the
repository's hub (Getting Started),
signing is one switch — muse commit --sign, or
commit.sign = true in config — and without one, a signing commit
stops instead of writing an unsigned commit. A signed commit carries an Ed25519
signature, and its ID binds the signer's public key. Recurring conflicts can be
taught: when the same conflict comes back, muse merge replays the
resolution you recorded, and muse harmony engine adds declarative
policies and similarity matching, then records an escalation for whatever is
left for a human or an agent to resolve.
How Muse fits together
Start at the core and work outward. Every concept links to the section that explains it; hover over or focus one to trace what it connects to.
- Shipped
- Opt-in
- Not wired yet
- Not built yet
-
Muse Core
How is state stored and versioned?
-
Content-addressed objects
Shipped
01 Foundations
Every object is stored and addressed by its
sha256:ID. -
Snapshots
Shipped
01 Foundations
A flat manifest mapping every path to an object ID: the whole state at once.
- lists Content-addressed objects
-
Commit DAG
Shipped
01 Foundations
A commit ID hashes its parents, snapshot, message, timestamp, author and signer key.
- records a Snapshots
-
Branches and refs
Shipped
01 Foundations
Named pointers into the commit DAG.
- point into the Commit DAG
-
Content-addressed objects
Shipped
01 Foundations
-
Domain engines
What does a change mean?
-
Domain protocol
Shipped
03 Domain Protocol
Six methods teach the engine a new kind of state:
snapshot,diff,merge,drift,apply,schema.- produces Snapshots
-
Code domain
Shipped
04 Code Intelligence
Versions functions, classes and imports, so history, diffs and merges follow symbols.
- implements the Domain protocol
-
MIDI domain
Opt-in
03 Domain Protocol
Maintained, but registered only when
MUSE_ENABLE_MIDI=1is set.- implements the Domain protocol
-
Your domain
Not built yet
03 Domain Protocol
Genomic data, financial models: none ships today. Each would be one new plugin.
- would implement the Domain protocol
Registered by default: chess, code, identity, mist, scaffold, social, timeline, todo.
-
Domain protocol
Shipped
03 Domain Protocol
-
Merging
How do parallel changes combine?
-
Merge engine
Shipped
05 Merge Engine
Three-way merge from the merge base; the domain plugin decides what conflicts.
- finds the base in the Commit DAG
- delegates to the Domain protocol
-
Harmony
Shipped
06 Harmony
muse mergereplays the resolution you recorded when the same conflict comes back.muse harmony engineadds policies and similarity matching, and records an escalation for the rest.- resolves conflicts for the Merge engine
-
CRDT join
Not wired yet
15 CRDT Primitives
A plugin that implements
CRDTPluginis meant to merge byjoin, which never conflicts. Known gap in muse 0.2.1rc20:muse mergenever calls it (musehub#204).- is meant to replace conflicts in the Merge engine
-
Merge engine
Shipped
05 Merge Engine
-
Provenance
Who made a change, and can anyone check?
-
HD Ed25519 identity
Shipped
02 Cryptographic Identity
Signing keys are HD-derived from one recovery seed; an agent can instead be handed a sub-seed.
-
Signed commits
Opt-in
02 Cryptographic Identity
muse commit --signorcommit.sign = true; the commit ID binds the signer's public key.- signs the Commit DAG
- uses keys from HD Ed25519 identity
-
MSign requests
Shipped
11 MuseHub API Reference
Hub API requests carry Ed25519 request signatures, not passwords or JWTs.
- uses keys from HD Ed25519 identity
-
HD Ed25519 identity
Shipped
02 Cryptographic Identity
-
Collaboration
How do people and agents share work?
-
Wire protocol
Shipped
10 Wire Protocol
Push and fetch move MPack bundles of commits, snapshots and blobs.
- transfers the Commit DAG
-
MuseHub
Shipped
11 MuseHub API Reference
Hosts repositories, issues and proposals behind a signed REST API.
- receives pushes over the Wire protocol
- authenticates with MSign requests
-
Agent coordination
Shipped
07 Agent Coordination
Advisory symbol reservations let parallel agents spot conflicts early.
- reserves symbols in the Code domain
-
MCP tooling
Shipped
08 MCP Tooling
Agents drive MuseHub through Model Context Protocol tools.
- exposes MuseHub
-
Wire protocol
Shipped
10 Wire Protocol
Getting Started
Install muse, authenticate with Ed25519, create your first repo, and run the core workflow.
01Foundations
Content-addressed object model, commit DAG, snapshots, branches, push/pull.
02Cryptographic Identity
HD Ed25519 keys, MSign auth, human→agent→org trust chains, quorum authorization, MPay.
03Domain Protocol
MuseDomainPlugin — six methods, any state space. Typed delta algebra, address-keyed Map merge.
04Code Intelligence
Symbol graph, blast radius, gravity, hotspots, entanglement, dead-code detection.
05Merge Engine
Three-level granularity, strategy × history matrix, --explain observability, local and proposal merge, Harmony integration.
06Harmony
Four-tier conflict resolution: policy, exact replay, semantic match, escalation.
07Agent Coordination
Work queues, claim/complete lifecycle, sharding, reservations, forecasting.
08MCP Tooling
Model Context Protocol server — tools, resources, elicitation, SSE streaming.
09Shelves
Working-tree checkpoints — intent types, resumability, domain state, handoff patterns.
10Wire Protocol
MsgPack over HTTP — presigned mpack push, fetch delta, refs.
11MuseHub API Reference
REST API, MSign authentication, rate limits, webhooks, pagination.
12Identity Profiles
Three-archetype profile system — Spectral Sigil, attestations, MPay ledger, agent genealogy.
13Mist Domain
Content-addressed, forkable, embeddable artifact shares. URL schema, artifact types, CLI, REST API, security model.
14Vision
Why Muse exists. Semantic vs binary diffs, independent-dimension auto-merge, domain agnosticism, and the AI-agent imperative.
15CRDT Primitives
Six lattice-based primitives — VectorClock, LWWRegister, ORSet, RGA, AWMap, GCounter — with full API reference and integration patterns.
16Security Reference
Client-side security guards: object-ID validation, path containment, ANSI injection, HTTP transport, snapshots, identity store, and more, with where each is applied.
Suggested reading paths
New to Muse? Pick a goal and follow the path. Every section can be read stand-alone, but the paths below give the fastest on-ramp to each use case.
| Goal | Sections, in reading order |
|---|---|
| Evaluate Musewhy it exists and the core object model | |
| Work with code semanticallysymbol graph, blast radius, symbol-level merges | |
| Build a domain pluginextend Muse to a new state space | |
| Understand mergingmerge strategies, conflict memory, CRDT dimensions | |
| Run agentscoordination, MCP tooling, shelves | |
| Integrate via REST APIMSign auth, repos, issues, webhooks | |
| Understand the wire protocolpush/fetch frame format, presign, msgpack | |
| Host and share artifactsmist URLs, artifact types, CLI, REST API | |
| Set up an identity profileSpectral Sigil, attestations, agent genealogy | |
| Review the security modeltrust chains, request signing, layered guards |