Brain Schema

This page summarizes the main file model of a MindMux brain.

Example layout

brain/
├── background.md
├── architecture.md
├── flow.md
├── mindmap.md
├── stack.md
├── roadmap.md
├── index.md
├── schema.md
├── mindmux.json
└── pages/

Root docs

Every brain has six fixed root docs:

background.md
architecture.md
flow.md
mindmap.md
stack.md
roadmap.md

These are project-level documents and are updated in place.

Pages

Pages live in brain/pages/ and are unbounded in count.

Each page contains:

frontmatter metadata
a compiled_truth section
a timeline section

A typical page shape looks like this:

---
id: runtime-profile-model
category: decision
status: active
tags: [runtime, profile]
title: Runtime and Profile Model
created: "2026-05-01"
updated: "2026-06-01T10:00:00Z"
---

## compiled_truth

Current best understanding.

## timeline

- time: 2026-06-01T10:00:00Z
  kind: decision
  summary: Adopted the current runtime/profile boundary.

Page metadata

Important page metadata fields include:

id
title
category
status
tags
created
updated

Timeline semantics

The timeline is append-only in spirit. It records how understanding evolved through:

decisions
observations
source material
reversals

The intent is:

compiled_truth can be rewritten
timeline should preserve the historical reasoning path

Page lifecycle status

Every page has a lifecycle status: draft, active, or archived.

draft — still taking shape and not yet treated as project truth.
active — current, readable project knowledge.
archived — superseded or no longer relevant, but kept for history.

If a page file omits status, it is treated as active for backwards compatibility. Ordinary reads default to active pages only; tools can opt in to draft or archived pages when the user explicitly asks for them.

Cross-reference style

The knowledge model uses wiki-style page references for cross-linking between pages.

Metadata file

The brain can also include project-level metadata such as a user-facing project name in mindmux.json. This lets the project identity travel with the brain itself rather than living only in local app preferences.