Project and Workspace Model

MindMux is organized around a local project root. In the codebase this is often implemented as a workspace, but the product-facing concept is the project: a durable home for knowledge, sessions, tasks, and inbound material.

Two storage layers

At a high level, a project contains two separate layers:

brain/ for durable, reviewable project knowledge
local runtime state for sessions, tasks, and project-scoped settings

This separation is deliberate.

`brain/`: durable knowledge

The brain/ directory is meant to survive across sessions, machines, and runtimes. It is designed to be:

human-readable
git-friendly
easy to back up
easy to inspect outside the app

The brain contains:

root docs such as background.md, architecture.md, and roadmap.md
pages/ for structured knowledge pages, each with a lifecycle status
metadata such as mindmux.json

Operational state

Local runtime state stores app state that should usually stay out of source control. This includes:

session logs and metadata
task state
project-specific settings

This keeps runtime bookkeeping separate from durable project knowledge.

Why the split matters

MindMux is opinionated about what should become part of the long-term project record.

Items that belong in brain/:

stable product context
architecture decisions
design rationale
durable references

Items that belong in local runtime state:

active session transcripts
in-progress task runtime events
temporary operational metadata

Project naming

MindMux stores a small metadata file in brain/mindmux.json so a project can have a user-facing display name that survives app restarts and travel with the brain itself.

Brain location flexibility

The default model is "brain inside the project". The app also contains support for brain-root override behavior, but the guiding principle remains the same: one stable project brain should anchor the whole working context.

Practical advice

For most teams, the best starting point is:

Keep brain/ inside the repository or adjacent project root.
Let runtime state stay local and unversioned.
Treat the brain as shared project memory, not as a scratchpad.

That layout matches how MindMux is designed internally and keeps the product model easy to reason about.