--- title: "Brains and Sources" type: concept tags: [brains, foundational, operator] created: 2026-07-02 updated: 2026-07-02 sources: ["raw/github_doc-docs-architecture-brains-and-sources-md.md", "raw/github_doc-docs-architecture-system-of-record-md.md", "raw/github_doc-docs-guides-originals-folder-md.md", "raw/github_doc-docs-guides-multi-source-brains-md.md", "raw/github_doc-docs-guides-source-attribution-md.md"] confidence: high gbrain_version: 0.42.56.0 --- ## Definition GBrain organizes knowledge along two orthogonal axes. A **brain** is a database (PGLite file, self-hosted Postgres, or Supabase) — you can have many, and each has its own tables, OAuth surface, and lifecycle. A **source** is a named content repo *inside* one brain — a wiki, a `gstack` checkout, an essay collection — and one brain can hold several. `--brain ` picks which database; `--source ` picks which repo within it. Underneath both axes sits the **system-of-record** contract: the git repo of markdown files is canonical, and the Postgres/PGLite database is a derived, disposable cache that gets rebuilt from the repo, never backed up directly. ## How It Works **Resolution precedence** is identical in shape for both axes — highest-priority match wins: ``` WHICH BRAIN (DB)? WHICH SOURCE (repo in DB)? 1. --brain 1. --source 2. GBRAIN_BRAIN_ID env 2. GBRAIN_SOURCE env 3. .gbrain-mount dotfile 3. .gbrain-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' ``` Sources are managed with `gbrain sources add --path

[--federated|--no-federated]`, `gbrain sources list`, `remove`, `rename`, `default`, `attach` (writes `.gbrain-source` into the CWD, kubectl-context style), `detach`, `federate`/`unfederate`. Every `pages` row carries a `source_id`, and slugs are unique **per source**, not globally — the same slug can exist under two different sources as two different pages. The **federation** flag (`config.federated`, default `false` for new sources) controls whether a source joins unqualified `gbrain search "X"` results; the seeded `default` source is `federated=true` so pre-v0.17 brains behave unchanged. Multi-source citations use `[source-id:slug]` form, e.g. `[wiki:topics/ai]`. Brains are enumerated by a **host** (the default, in `~/.gbrain/config.json`) plus **mounts** registered via `gbrain mounts add --path --db-url `. Topologies range from a single-person/single-source setup, to one person with several federated sources inside one brain, to a personal brain plus one mounted team brain, up to a CEO-class user mounting several team brains — each internally organized as its own multi-source brain. Cross-brain queries are **not deterministic**: the agent sees the brain list (`gbrain mounts list`) and decides when to fan out, which keeps access control clean by design. **Durability ("harden")**: `gbrain sources add wiki --url --pat-file ` clones a brain repo and automatically installs pull-first rebase safety, an atomic commit+push helper (`scripts/brain-commit-push.sh`), a 30-minute DB-free background pull cron, and a repo-scoped credential — verified before declaring success. Re-run `gbrain sources harden ` any time to audit an existing source. **The system of record** classifies every table into three buckets: FS-canonical (takes, facts, links, timeline, tags — markdown is the source of truth, a reconciler like `extract links` or `extract_facts` rebuilds the DB row from the fence/section), derived-but-not-user-authored (`pages`, `content_chunks`, `page_versions` — rebuilt by the chunker/embedder on import), and DB-only-by-design (OAuth tokens, job queues, audit logs — infrastructure state that never belongs in git). Disaster recovery is one command: `gbrain rebuild --confirm-destructive` wipes derived tables and `gbrain sync && gbrain extract all` regenerates them from markdown. **Provenance and originals.** Every fact written to the brain — compiled truth or timeline — carries an inline `[Source: who, channel/context, date time tz]` citation; tweet citations must include the full URL, not just a handle. When sources conflict, both are noted rather than silently resolved, following a priority order (user direct statements > primary sources > enrichment APIs > web search > social media). A separate `originals/` directory captures the user's own thinking verbatim — not paraphrased — using the user's exact phrasing for the slug (`meatsuit-maintenance-tax`, not a sanitized description), cross-linked aggressively to the people, meetings, and media that shaped it. A user's *synthesis* of someone else's idea also counts as original and belongs in `originals/`, not `concepts/`. ## Key Parameters - `--brain ` / `GBRAIN_BRAIN_ID` / `.gbrain-mount` — which database. - `--source ` / `GBRAIN_SOURCE` / `.gbrain-source` — which repo within that database. - `federated: true|false` per source — whether it joins default cross-source search. - FS-canonical vs derived-but-not-authored vs DB-only-by-design — which category a new table falls into determines its rebuild story. ## When To Use Use `--source` when the data owner stays the same but the topic/repo changes (a second personal repo, an isolated essays draft folder). Use `--brain` when the data owner changes (a team-published brain, someone else's server). Isolate a topic from personal search with `federated=false`; keep cross-repo recall automatic with `federated=true`. ## Risks & Pitfalls - Treating a source boundary as a brain boundary (or vice versa) misroutes queries silently — the resolver never guesses on writes, but reads can quietly search the wrong scope. - A team's facts belong in the team's brain, not the personal brain — writing cross-brain without asking violates the ownership model. - Skipping citations on compiled-truth claims (not just timeline entries) is the most common attribution failure; compiled truth is not exempt just because it's synthesized. - Assuming the database is backed up: it isn't, by design — losing the markdown repo (not the DB) is the actual failure mode to guard against. ## Related Concepts - [[concepts/overview]] — compiled truth + timeline, the page-level pattern this architecture supports - [[concepts/schema-packs]] — what shape each source/brain takes - [[concepts/ingestion-pipeline]] — how content lands inside a source - [[concepts/verification-and-quality]] — citation and audit discipline ## Sources docs/architecture/brains-and-sources.md; docs/architecture/system-of-record.md; docs/guides/originals-folder.md; docs/guides/multi-source-brains.md; docs/guides/source-attribution.md.