Manage collections (vault sync)

Collections are how GigaBrain attaches one or more vault directories to a single brain. The reconciler keeps the brain in sync with files on disk; the watcher follows your edits in real time.

This surface ships on macOS and Linux today — Windows parity is on the roadmap.

Attach a vault

gbrain collection add notes ~/Documents/Obsidian --writable

--writable allows mutating MCP tools (brain_put, brain_link, etc.) to write to this collection. Without it, the collection is read-only and writes return CollectionReadOnlyError.

Other useful flags at attach time:

Flag	Effect
--read-only	Forbid mutations through this collection.
--write-gbrain-id	Write a .gbrain-id marker file at the root for collision detection.
--watcher-mode <auto|off>	Override the default file-watcher mode.

See what’s attached

gbrain collection list
gbrain collection info notes

info shows extended diagnostics: state (active / detached / restoring), watcher status, ignore-pattern parse errors, recovery flags.

Reconcile against disk

When serve isn’t running and you’ve edited files outside the brain’s view, force a reconcile:

gbrain collection sync notes
gbrain collection sync notes --remap-root /new/path     # if you moved the vault
gbrain collection sync notes --finalize-pending         # commit pending recovery state

The reconciler does a stat-diff (mtime + size + ctime) over file_state, falling back to SHA-256 only when stat is ambiguous. Most pages skip rehashing entirely.

Ignore patterns

.gbrainignore follows gitignore semantics. Edit via the CLI to keep the parser happy:

gbrain collection ignore add notes "_attachments/**"
gbrain collection ignore add notes "*.tmp"
gbrain collection ignore list notes
gbrain collection ignore remove notes "*.tmp"
gbrain collection ignore clear notes --confirm

Patterns are stored in the collections.ignore_patterns column and surfaced through brain_collections for MCP clients. Parse errors are reported via collection info.

Quarantine lifecycle

When a file disappears or is renamed, the page isn’t hard-deleted — it’s quarantined. Links, assertions, and embeddings are preserved.

gbrain collection quarantine list notes
gbrain collection quarantine export <SLUG> --out /tmp/page.json
gbrain collection quarantine restore <SLUG> notes/path/to/file.md
gbrain collection quarantine discard <SLUG>

Quarantined pages auto-discard after GBRAIN_QUARANTINE_TTL_DAYS (default 30) only if they have no remaining DB-only state. Pages with active links or assertions stay until a human reviews them.

Restore from a backup

gbrain collection restore notes /path/to/backup-vault
gbrain collection restore-reset notes --confirm        # if a previous restore halted

Restore is gated: the collection enters restoring state and rejects writes (CollectionRestoringError) until the manifest is finalized.

Reset reconcile-halted state

If the reconciler halts due to integrity issues, recover with:

gbrain collection reconcile-reset notes --confirm

Use sparingly; investigate the underlying cause first via collection info.

What the watcher does

While serve is running, a notify-based watcher follows attached collection roots:

• Edits debounced for GBRAIN_WATCH_DEBOUNCE_MS (default 1500 ms).
• Renames, moves, and deletes flow through the same reconciler as collection sync.
• The same write-gate applies — restoring or needs_full_sync = 1 collections reject mutations.

Multiple collections, one brain

You can attach more than one vault. Slugs are unique per (collection, slug), so the same people/alice can exist in two collections without collision. Use collection-qualified slugs to disambiguate:

gbrain get work::people/alice
gbrain get personal::people/alice

The MCP server returns Ambiguity if a bare slug matches in more than one collection.

What ships when

Feature	Status
collection add / list / info / sync	Unix
Watcher (live edits)	Unix, in gbrain serve
Quarantine list / export / discard	Unix
Quarantine restore	Unix
restore from backup	Unix
Windows parity	Roadmap

Don’t read the brain at the same time you restore — leases are scoped to a single serve session, so a restore halts other writers via collection_owners.