​

Brains and Sources — the mental model

• A brain is a database. You can have many.
• A source is a named repo of content inside a brain. One brain can hold many.
• --brain <id> picks WHICH DATABASE.
• --source <id> picks WHICH REPO WITHIN that database.
• They’re independent. You can target any combination.

​

The two axes

​

Brains (the DB axis)

• Its own pages table, chunks table, embeddings, etc.
• Its own OAuth surface if served over HTTP MCP (v0.19+, PR 2).
• Its own separate lifecycle, backup, access control.

• host — your default brain, configured in ~/.modusbrain/config.json.
• mounts — additional brains registered in ~/.modusbrain/mounts.json via modusbrain mounts add <id> (v0.19+).

​

Sources (the repo axis, v0.18.0+)

​

When does each axis move?

​

Topology: a single-person developer

┌─────────────────────────────────────────┐
│  host brain (~/.modusbrain)                 │
│  ├── source: default (federated=true)   │
│  │   └── all pages                      │
└─────────────────────────────────────────┘

​

Topology: a personal brain with multiple repos

┌──────────────────────────────────────────────┐
│  host brain (~/.modusbrain)                      │
│  ├── source: wiki      (federated=true)      │
│  │   └── personal notes, people, companies   │
│  ├── source: gstack    (federated=true)      │
│  │   └── gstack plans, learnings             │
│  ├── source: openclaw  (federated=true)      │
│  │   └── openclaw docs, memos                │
│  └── source: essays    (federated=false)     │
│      └── draft essays, isolated on purpose   │
└──────────────────────────────────────────────┘

• You own all the content.
• You want cross-repo search to just work.
• You don’t need to share any of it with someone who isn’t you.

​

Topology: personal brain + one team brain

┌──────────────────────────────────────────────┐
│  host brain (~/.modusbrain)  — YOUR personal DB  │
│  ├── source: wiki                            │
│  ├── source: gstack                          │
│  └── ...                                     │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  mount: media-team                           │
│  path:   ~/team-brains/media                 │
│  engine: postgres (team's Supabase)          │
│  └── sources: wiki, raw, enriched            │
└──────────────────────────────────────────────┘

• You’re on a team and someone publishes a brain the team subscribes to.
• You need data isolation between work and personal.
• Different teams/orgs own different brains.

​

Topology: a CEO-class user with multiple team memberships

┌──────────────────────────────────────────────┐
│  host brain — YOUR personal DB               │
│  ├── source: wiki                            │
│  ├── source: essays                          │
│  ├── source: gstack                          │
│  └── source: openclaw                        │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  mount: media-team (your media team's brain) │
│  └── sources: wiki, pipeline, enriched       │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  mount: policy-team (your policy team's)     │
│  └── sources: wiki, research, letters        │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│  mount: portfolio (another team's)           │
│  └── sources: companies, deals, diligence    │
└──────────────────────────────────────────────┘

• You cross-cut multiple teams.
• Each team owns its own brain with its own access policy.
• You need latent-space federation (agent decides when to query across brains), not SQL federation.

​

Resolution precedence (one page to remember)

WHICH BRAIN (DB)?                    WHICH SOURCE (repo in DB)?
 1. --brain <id>                      1. --source <id>
 2. MODUSBRAIN_BRAIN_ID env               2. MODUSBRAIN_SOURCE env
 3. .modusbrain-mount dotfile             3. .modusbrain-source dotfile
 4. longest-prefix mount path match   4. longest-prefix source path match
 5. (reserved: brains.default v2)     5. sources.default config
 6. fallback: 'host'                  6. fallback: 'default'

​

For agents reading this

• Default assumption when the user asks a question: start in the current brain (resolved via the precedence above). Don’t jump brains without a reason.
• If the user asks a question that crosses topic areas a team might own (e.g. “what did Team X decide last week?”), the right move is to query the team’s brain explicitly rather than searching host with “team x”.
• Cross-brain federation is YOUR JOB, not the DB’s. You have the brain list (modusbrain mounts list). You decide when to fan out. You synthesize findings. You cite brain:source:slug.
• When writing a page, respect the brain boundary. A fact about a team’s work belongs in the team’s brain, not in the user’s personal brain. Ask before writing cross-brain.
• See skills/conventions/brain-routing.md for the full decision table.

​

For users reading this

• Default path: set up your personal brain (modusbrain init), add a source per repo you care about (modusbrain sources add gstack --path ~/gstack). You’ll almost never need --brain.
• When a team publishes a brain: modusbrain mounts add <team-id> --path <clone> --db-url <url> and the .modusbrain-mount dotfile in that checkout routes queries there automatically.
• When you are the CEO-class user with multiple team memberships: mount each team brain. Trust the resolver — inside a team’s directory the dotfile picks the brain, inside a subdirectory the dotfile picks the source. The flags are for when you want to query across the boundary deliberately.

​

Further reading

• v0.18.0 CHANGELOG — introduced sources primitive.
• v0.19.0 CHANGELOG (TBD after PR 0+1+2 ship) — introduces mounts.
• docs/mounts/publishing-a-team-brain.md (PR 2) — how to be the brain publisher, not just the subscriber.