The picture exists only in the whole.
Mosaix is a file-level format for vaults of atomic, self-describing notes. Machines retrieve one note at a time. People read many notes as one document.
Nothing is silently lost.
Every knowledge base has this: the last edit wins, and nobody recorded that there was a disagreement. Mosaix records it at the file level, and keeps every version where it was.
The same knowledge, once as prose in a document and once as Mosaix tiles. The body of each tile is the sentence you already wrote. The keys are generated by enrichment and reviewed by a person.
Nothing in the body changes. The keys sit above it, in plain YAML. Hover a key to find it in the note.
idULID — stable across renames. Warning if absent (W003).summaryOne declarative sentence, 120–240 characters.keywordsSix to eight terms: synonyms, spoken phrasings, questions.entitiesNamed things, typed.relationsTyped links between entities. The graph lives in the note.revHash of the body when metadata was computed. Mismatch means stale.A note of type document lists the tiles it is made of, in reading order. Hover a paragraph to see its tile. Nothing is copied.
64 tiles · 5 in fragments, reading order · one still to confirm
1The European industrial coatings market is consolidating: three acquisitions in 2025 moved 18% of distribution under two groups.← Coatings consolidation 2025 · ✅ sourced
2Westguard sells in 130+ countries and undercuts distributors with an own-brand line; it is the reference competitor for price.← Westguard — player card · ✅ sourced
3Whether Westguard opened a Romanian plant in 2024 is disputed between two sources; the argument does not depend on it.← Open question #33 · ⚠ to confirm
4CoatExpo Munich in October is the single most relevant fair; exhibitor lists confirm both direct competitors will attend.← Coatings trade fairs, Europe 2026 · ✅ sourced
5Recommendation: enter through marine coatings, where Eastern European manufacturing has a documented cost advantage of 22–30%.← Strategic scenarios · ✅ sourced
A vault that obeys them can call itself Mosaix 1.1 conformant. Conformance is a property of the files, not of any tool.
A contradiction between notes goes in the open-questions ledger with both versions, dates and consequence. Nobody picks a winner silently.
A note that is no longer valid is marked and left in place, because other notes link to it. Deletion is for mistakes only.
R8 — Propose, don't apply. Automated writes go to a branch or a review queue. A person merges. The revision hash shows whether the proposal was made against the current body. This is a SHOULD, not a MUST — the checker does not verify it.
One note answers one question.
Every note carries the core keys.
No orphans, no broken links.
Every tag lives in the meta note.
Read together? Composed, never copied.
Same model, same task, same pass rate. Change the input structure, change everything.
A planner hands each agent one tile and its direct dependencies. No agent reads the whole vault; there is no shared memory to keep in sync. So each agent can run on the smallest model that passes its tile, local or cloud, general or vertical, all in parallel.
In production vaults, a single agent task typically consumes around 600 tokens — one note plus its direct dependencies, measured across three real vaults. This is an observed average, not a prescribed limit. Actual token consumption depends on note size, dependency depth, and model tokenizer. The format imposes no token budget.
Because the cluster is the unit of work, the model is a per-agent choice: a 2B model for the tiles it passes, a vertical model where the domain needs it, a cloud model only where nothing smaller will do. Swap one, and the others don't notice. This is the direct evolution of the system: work verticalised across different models, each on its own cluster of knowledge.
Obsidian is the reference host. The format needs none.
One Python file, standard library. It reports every error and warning against §10, note by note, and exits 0 when the vault is conformant. On the right: the example vault, then a real marketing vault before and after two fixes.
Download audit_reference.pySix skills for Claude, a reference MCP server, and two utilities. All open, all stdlib-only Python, all in the repo.
npx degit mosaix-format/spec/skill ~/.claude/skills/mosaix-formatInstall any skill the same way. ~/.claude/skills/ for personal use, .claude/skills/ for a project repo. Skills are non-normative: they encode the specification as agent instructions. Nothing in the checker depends on them.
--dry-run first.
python -m mosaix_mcp ~/vaults/my-vault # start the MCP server
python mosaix_init.py my-vault --with-examples # scaffold a new vault
python mosaix_migrate.py ~/notes --dry-run # preview migrationSkills teach what to write and how to validate it. The tools above connect any agent to a vault. How to produce knowledge at scale — enrichment, ingest, retrieval — is out of scope (§8), and that's where implementations compete.
The fourth tile of the mark is outlined and empty: it stands for what is decided but not built. These are the open tiles of the format itself. Each is recorded in the example vault's ledger with a status, like any other open question.
The question key records the single question a note answers (R1 atomicity). Documentation-only in v1.2: the checker does not validate it. The other proposals (origin, as_of, relation vocabulary, entity registry) remain under discussion for a future version.
shipped in 1.2.0A stable id (ULID, 26 chars, Crockford Base32) so links survive renames. Missing id is a warning (W003) in 1.x; becomes an error in v2.0. Every 1.0 vault stays conformant.
shipped in 1.1.0spec.yaml encodes every CORE key, rule, alias, and conformance check in one parseable file. A test corpus of 39 cases — valid, invalid, warnings and edge-cases — with expected results and a runner verifies the checker against the spec. Both ship with 1.1.0.
shippedmosaix_mcp/: a stdlib-only Python package, JSON-RPC 2.0 over stdio, six tools — read, write, search, compose, check, list. Writes validate against §10 before persisting. No dependencies, no vector DB, no network: the "SQLite" of Mosaix.
shippedmosaix_init.py creates a new vault with the standard structure, meta note, ledger and CI workflow. mosaix_migrate.py brings an existing directory of Markdown files toward conformance with best-effort inference — title, summary, keywords, tags, links, rev — without touching the body.
shippedGOVERNANCE.md defines SemVer policy, the RFC process, backward compatibility guarantees and deprecation rules. OBSIDIAN-PLUGIN-SPEC.md specifies six features for obsidian-mosaix: inline lint, scaffolding, graph enhancements, status bar, sidebar and settings.
shippedA GitHub Action now wraps the checker: eight lines of YAML give you conformance checks on every push and PR comments. Next: pip install mosaix-check and a --fix mode for the mechanical part.
action shipped · pip install and --fix not builtThe numbers in 07 come from our own runs. The next step is the method and the fixtures in the open, so anyone can rerun one agent, one cluster, on the model they have.
method being written upLogseq and Foam read the substrate; a verified profile for each, like §9, says exactly what resolves and what does not.
to confirmThe specification vault as a zip you can open in any editor, and a badge for vaults that pass the checker. Plus a second vault: a fictional bakery, ordinary knowledge, 26 notes. All shipped with 1.0.0; the badge is self-declared, the checker report is the evidence.
shippedA DOI per tagged release so the spec can be cited in a stable way. English is normative, Italian is here; other languages arrive as pull requests.
on request