/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:
  - recall
  - 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 lookup chain and copyable retrieval filters. > **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`. > > **Tight-budget page questions:** explicitly use > `recall({query: "zebra telescope", budget_tokens: 75, budget_policy: "query_first"})` > so ranked page evidence packs before recent facts. CLI: > `gbrain recall --query 'zebra telescope' --budget-tokens 75 --budget-policy query_first --json`. > Keep entity-first, event/session-filtered and fact-focused questions on their > existing facts-first route; do not change `context_pack`. Costs are character-based > estimates, and an oversized first item is dropped without skipping or truncation. > Read `budget_packing` before interpreting an empty result as missing memory. > See `skills/query/SKILL.md` for the MCP request and caller example. Guidance is > not native-harness activation: adoption remains unverified until a fresh > conversation is observed making the opted-in call. > > **Choose a readback path that can see the intended visibility.** Trusted local > CLI callers can recall and withdraw private facts. Every other MCP caller, including > stdio, and a thin CLI connected to MCP have world-only fact recall > and withdrawal; a credential bound to the brain owner (`gbrain access owner`) > also recalls private facts. A > request to remember does not authorize making real private information > world-visible. Use a trusted local write/readback path for private memory > when available. If only remote access is available, a successful private > write receipt confirms storage, but private recall remains unverified; explain > that limit and the trusted local path needed for private readback or withdrawal. > Do not widen visibility > or request broader OAuth scopes merely to make verification pass. For an MCP > connection test, use only a harmless synthetic `visibility: "world"` fixture > with the user's test authorization, retain its ID, and withdraw it afterward. > > **`<REDACTED:pattern>` in a result** (for example `<REDACTED:url_credentials>` > or `<REDACTED:high_entropy_assignment>`) means the brain holds a > credential-shaped value there and withheld it from this response; the stored > page is unchanged. Tell the user which kind of value was withheld and that it > is readable on the brain host. Do not retry other operations to recover it, > and do not echo a guess. A credential the user asked you to `remember` is > withheld from remote recall by design: every MCP caller, including stdio, and > a thin CLI connected to MCP is remote, so only `gbrain recall` run on the > brain host shows it as written. Docs: > `docs/guides/write-refusals.md#secret-scan-refusals-and-redaction`. > > **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 to your own > member page when your credential is bound to a member), 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 crea