/brain-ops

name: brain-ops
version: 1.2.0
upstream: brain-ops@fc834ee
description: |
  Brain knowledge base operations. The core read/write cycle: brain-first lookup,
  read-enrich-write loop, source attribution, ambient enrichment, back-linking.
  Read this before any brain interaction.
triggers:
  - any brain read/write/lookup/citation
tools:
  - search
  - query
  - get_page
  - put_page
  - add_link
  - add_timeline_entry
  - get_backlinks
  - sync_brain
mutating: true
writes_pages: true
writes_to:
  - people/
  - companies/
  - deals/
  - concepts/
  - meetings/

Brain Operations — The Ambient Context Layer

Recall relevant context before responding. Save explicit requests with provenance; automatic capture is off until the user opts in. Reading this skill does not enable capture, delegation, or paid enrichment. A chat-only instruction suppresses writes for that turn, including when standing capture is enabled.

> **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.

> **Memory verbs (MEMORY_VERBS v1, gbrain ≥ 0.43).** Over MCP, prefer the five > core memory verbs for the read/write cycle: **`remember(fact, provenance, > ttl?)`** to save a single durable fact (mandatory provenance; dedupes + > supersedes), **`recall(query | entity, budget_tokens)`** to read it back > budget-packed, **`entity(name)`** for a zero-LLM card, **`synthesize(question)`** > for the expensive cross-page answer, **`forget(id)`** to withdraw active memory > (history, source material, and backups may remain). `context_pack` and `delta` > complete the seven-verb surface. Use > `remember` instead of `extract_facts` when you already have ONE formed fact; > `put_page` / `add_link` / `add_timeline_entry` stay the page/graph write path. > Fall back to the classic ops when the verbs aren't on the surface. Contract: > `docs/protocol/MEMORY_VERBS_v1.md`. > > **Keyless brains:** when `extract_facts` returns `skipped: > extraction_unavailable`, YOU are the extractor — pull the facts from the turn > yourself and write each one via `remember` with `kind` set (event | preference > | commitment | belief | fact — those five are the frozen protocol enum; the > `idea` kind the extractor and DB carry is NOT one of them) and the > visibility the envelope's `agent_action` names > (default private — pin it; `remember` defaults to world), or author a > `## Facts` fence on the entity page. A `skipped: extraction_failed` envelope > (server-side extractor errored on this turn; `reason` names why) invites the > same manual `remember` fallback for that turn — automatic extraction stays > on for future writes.

Contract

This skill guarantees:

• Brain is checked BEFORE any external API call (brain-first lookup)
• Explicit save requests and opted-in inbound signals trigger the READ → WRITE

loop; enrichment requires its separately configured authority

• 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:

1. `gbrain entity "<name>"` (v0.43+) — ONE known person/company/project → full card (description, aliases, open threads, recent events, edges, backlink/fact counts). Zero LLM calls, sub-100ms. This one call replaces steps 2–6 for known-entity lookups; near-misses return suggestions. 2. `gbrain search "name"` — exact-token lookup for existing pages (cheap hybrid, no expansion) 3. `gbrain query "natural question about name"` — concept/landscape questions go here FIRST (expansion recovers synonym phrasings; a nonzero `search` count is not proof of completeness) 4. `gbrain get <slug>` — if you know the slug, read the full page 5. Check backlinks: who references this entity? 6. Check timeline: recent events involving this entity

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

**⚠️ NEVER scope/count a corpus with shallow `ls` — query gbrain or `find`.** Federated sources often carry MULTIPLE coexisting directory conventions — a flat legacy layer AND a date-nested `meetings/YYYY/MM/` layer. A non-recursive `ls dir/*.md` sees only one and undercounts massively. Real example: a shallow `ls` of one source's `meetings/` counted 132 files, almost all the user's, and concluded that WAS the corpus — missing thousands of transcripts nested under `meetings/YYYY/MM/`. To count/scope a brain corpus:

• **Best:** `gbrain sources list` (shows per-source indexed page counts) + `gbrain query`. gbrain indexes ALL federated sources correctly; trust its index, not the filesystem.
• **If you must hit the FS:** `find <dir> -name '*.md' | wc -l`, never `ls *.md`. Then map the layout: `find <dir> -name '*.md' | sed -E 's#(.*/)[^/]+$#\1#' | sort | uniq -c`.
• The bug is never "gbrain can't see the source" — it's almost always a shallow FS glob. Verify against `gbrain sources list` before believing a low count.

Phase 1.5: Analytical Queries (gbrain think)

For questions that need synthesis, temporal grounding, or analytical answers — not just "find the page" but "answer the question":

1. Use `gbrain think "<question>"` — multi-hop synthesis across pages + takes + the graph. Temporal questions route through trajectory analysis; everything else gets an LLM-synthesized, cited answer with conflict + gap analysis. Returns a grounded answer, not just a list of matching pages. 2. Best for: "when did acme-example last raise