Brain Operations — The Ambient Context Layer

The brain is not an archive. It is a live context membrane that every interaction flows through in both directions.

Convention: See
skills/conventions/brain-first.md
for the 5-step lookup protocol. Convention: See
skills/conventions/quality.md
for citation and back-link rules.

Contract

This skill guarantees:

Brain is checked BEFORE any external API call (brain-first lookup)
Every inbound signal triggers the READ → ENRICH → WRITE loop
Every outbound response checks brain for relevant context
Source attribution on every fact written (inline
```
[Source: ...]
```
citations)
User's direct statements are highest-authority data
Back-links maintained on every brain write (Iron Law)

Iron Law: Back-Linking (MANDATORY)

Every mention of a person or company with a brain page MUST create a back-link FROM that entity's page TO the page mentioning them. An unlinked mention is a broken brain. See

skills/conventions/quality.md

for format.

Phases

Phase 1: Brain-First Lookup (MANDATORY)

Before using ANY external API to research a person, company, or topic:

```
gbrain search "name"
```
— keyword search for existing pages

gbrain query "natural question about name"

— hybrid search for context

```
gbrain get <slug>
```
— if you know the slug, read the full page
Check backlinks: who references this entity?
Check timeline: recent events involving this entity

The brain almost always has something. External APIs fill gaps, not start from scratch.

Phase 2: On Every Inbound Signal (READ → ENRICH → WRITE)

Every message, meeting, email, or conversation that references a person or company:

Detect entities — people, companies, deals mentioned
Load brain pages — read existing pages for context before responding
Identify new information — what does this signal tell us that the page doesn't know?
Write it back — update the brain page with new info + timeline entry + source citation
Create if missing — if notable and no page exists, create via enrich skill

User's direct statements are the highest-value data source. Write them to brain pages immediately with attribution

[Source: User, YYYY-MM-DD]

Phase 2.5: Structured Graph Updates (automatic)

Every

put_page

call automatically extracts entity references and writes them to the graph (

links

table) with inferred relationship types. Stale links (refs no longer in the page text) are removed in the same call. This is "auto-link" reconciliation.

No manual
```
add_link
```
calls needed for ordinary page writes.
Inferred link types:
```
attended
```
(meeting -> person),
```
works_at
```
,
```
invested_in
```
,
```
founded
```
,
```
advises
```
,
```
source
```
(frontmatter),
```
mentions
```
(default).
The
```
put_page
```
MCP response includes
```
auto_links: { created, removed, errors }
```
so the agent can verify outcomes.
To disable:
```
gbrain config set auto_link false
```
. Default is on.
Timeline entries with specific dates still need explicit
```
gbrain timeline-add
```
(or batch via
```
gbrain extract timeline --source db
```
).

Phase 3: On Every Outbound Response (READ → PULL → RESPOND)

Before answering any question about a person, company, or topic:

Check the brain — read relevant pages
Pull context — use compiled truth + recent timeline
Respond with context — the brain makes every answer better

Don't answer from general knowledge when a brain page exists.

Phase 4: Ambient Enrichment

This is not a special mode. This is the default. Everything the user says is an ingest event.

Person mentioned → check brain, create/enrich if needed (spawn background)
Company mentioned → same
Link shared → ingest it (delegate to idea-ingest)
Data shared → delegate to appropriate skill

Rules:

Never interrupt the conversation to do enrichment
Spawn sub-agents for anything that would slow down the response
Never announce "I'm enriching the brain" — just do it silently

Output Format

No separate output. Brain-ops is an always-on behavior layer, not a report generator. The output is updated brain pages and enriched responses.

Cross-source citation format (v0.18.0+)

When a brain has multiple sources (wiki, gstack, yc-media, etc.), every citation MUST include the source id:

[source-id:slug]

. Example:

You told me about the retry budget approach — see [wiki:topics/resilience] and [gstack:plans/retry-policy] for where this came from.

Rules:

The key is
```
sources.id
```
(immutable), never
```
sources.name
```
(mutable display).
Single-source brains still write
```
[default:slug]
```
OR may omit the prefix for backward compat.
Every page payload returned by
```
search
```
,
```
query
```
,
```
get_page
```
,
```
list_pages
```
carries
```
source_id
```
— always use it when citing, never guess.

If a search result has

source_id: "gstack"

and

slug: "plans/foo"

, the citation is

[gstack:plans/foo]

. That's the whole rule.

Anti-Patterns

Answering questions about people/companies without checking the brain first
Using external APIs before checking the brain
Writing facts without inline
```
[Source: ...]
```
citations
Blocking the response to do enrichment
Overwriting user's direct statements with lower-authority sources
Creating brain pages for non-notable entities

Tools Used

```
search
```
— keyword search
```
query
```
— hybrid vector+keyword search
```
get_page
```
— read a brain page
```
put_page
```
— create/update brain pages
```
add_link
```
— cross-reference entities
```
add_timeline_entry
```
— record events
```
get_backlinks
```
— check who references an entity
```
sync_brain
```
— sync changes to the index

brain-ops

NPX Install

Tags

SKILL.md Content