Agent quickstart

You are an agent connecting to a GigaBrain via the MCP server. Read this once, then refer to the linked pages for detail. Everything you need to operate is in three places: the tool catalog, the skill workflows, and the sensitivity contract.

What this brain is

A single SQLite file (brain.db) on the user’s machine, exposed over stdio JSON-RPC 2.0 by gbrain serve. Seventeen brain_* tools cover every supported operation. There is no other API; you cannot reach external services through the brain.

The brain holds:

• Pages with frontmatter, compiled truth, and an append-only timeline.
• Links between pages with typed relationships and temporal validity.
• Assertions for contradiction detection.
• Knowledge gaps logged when retrieval was insufficient.
• Tags, timeline entries, and optional raw data (API responses).

See Compiled truth + timeline for the page model.

Connection

The user has already wired the MCP server. Your runtime spawned gbrain serve and exchanged the standard MCP initialize and tools/list handshake. You should see seventeen brain_* tools registered.

If a tool call fails before any work happens, the most likely reason is a model mismatch (the brain’s model doesn’t match the runtime’s). Surface the error to the user; do not retry.

Recommended startup sequence

When connecting to a brain you haven’t seen before:

1. brain_stats — get page count, link count, gap count, active embedding model. Two calls in: you know the scale.
2. brain_collections — list attached collections. Decide whether to use a default-collection bare slug or qualify with <collection>::<slug>.
3. brain_gaps with resolved: false — see what the user is currently stuck on. This often informs the right opening question.

Don’t write before you read. The brain has its own structure; learn it before you contribute.

Read paths

Goal	Tool	Notes
Look up a specific page	brain_get	Use collection-qualified slugs if Ambiguity is returned.
Find pages by keyword	brain_search	FTS5 only. Fast, exact.
Find pages by meaning	brain_query	Hybrid (FTS5 + vector). Use this for natural-language questions.
Assemble context for an LLM	brain_query with depth: "auto"	Progressive retrieval up to the active token budget.
List	brain_list	Filter by wing, page_type, collection.
Walk relationships	brain_graph	N-hop BFS; default depth 2.
See inbound links	brain_backlinks	Use to find context for a page.
Read history	brain_timeline	Append-only timeline rows.

Write paths

Every mutation is gated by the collection write contract. If a collection is restoring or has needs_full_sync = 1, writes return CollectionRestoringError. If a collection is read-only, writes return CollectionReadOnlyError. Don’t retry these blindly.

Goal	Tool	Notes
Create or update a page	brain_put	Always read first; pass expected_version for updates.
Create a typed link	brain_link	Both endpoints must exist. Use valid_from/valid_until aggressively.
Close a link interval	brain_link_close	Prefer this over deleting links.
Tag a page	brain_tags	add and remove are repeatable.
Store raw API output	brain_raw	Idempotent per (slug, source) unless overwrite: true.
Log a knowledge gap	brain_gap	Hash-only by default — see sensitivity contract.

OCC contract

brain_put accepts expected_version. The right loop is:

fetch         → brain_get            (note version v)
construct     → modify content
write         → brain_put expected_version=v
on Conflict:
  fetch       → brain_get            (note new version v')
  rebase      → reapply your edits on v'
  retry       → brain_put expected_version=v'

Bare retries with the same expected_version will always fail. Always rebase.

Sensitivity defaults

Every brain_gap defaults to sensitivity: internal and stores only the SHA-256 hash of the query. The raw text is not persisted unless explicitly approved. Before escalating a gap to external (e.g. via the enrich skill), you must transition the sensitivity tier with explicit approval.

Read the Sensitivity contract. It’s two screens; non-negotiable.

Skill load order

The user has eight default skills (ingest, query, maintain, enrich, briefing, alerts, research, upgrade) extracted to ~/.gbrain/skills/ and overridable per-project. When deciding what to do:

1. If the user has a project SKILL.md in cwd, follow it.
2. Else, follow ~/.gbrain/skills/<skill-name>/SKILL.md.
3. Else, follow the embedded default.

gbrain skills doctor prints the resolution chain and SHA-256 hashes if you need to confirm.

Where to go next

• Tool catalog — annotated index of every brain_* tool with “use when” hints.
• Skill workflows — what each of the eight default skills triggers and outputs.
• Sensitivity contract — how to transition a gap from internal → redacted → external.
• MCP tool reference — exact parameter schemas.
• Errors — every error code you’ll see.