/query

name: query
version: 1.0.0
description: |
  Answer questions using the brain's knowledge with 3-layer search, synthesis,
  and citation propagation. Use when the user asks a question, wants a lookup,
  or needs information from the brain.
triggers:
  - "what do we know about"
  - "tell me about"
  - "who is"
  - "what happened"
  - "search for"
  - "look up"
  - "background on"
  - "notes on"
  - "who knows who"
  - "relationship between"
  - "connections"
  - "graph query"
tools:
  - recall
  - search
  - query
  - get_page
  - list_pages
  - get_backlinks
  - traverse_graph
  - get_timeline
mutating: false

Query Skill

Answer questions using the brain's knowledge with 3-layer search and synthesis.

> **Memory verbs (MEMORY_VERBS v1, gbrain ≥ 0.43).** When connected to a brain > over MCP, prefer the seven frozen memory verbs for memory work — they carry > provenance, evidence, and a server-enforced token budget: > - **`recall(query | entity, budget_tokens)`** — the budget-packed memory read. > Use it instead of bare `search` for "what do we know that we SAVED about X". > - **`entity(name)`** — a zero-LLM person/company/project card (aliases, > last-touched, open threads, top edges). Use it instead of `get_page` + > `get_backlinks` when you just need the card. > - **`synthesize(question)`** — the explicitly-expensive cross-page answer; the > heavy version of `query`. Reach for it only when the answer must combine > evidence across pages. > Fall back to `search`/`query`/`get_page` when the verbs aren't on the surface > (pre-0.43 servers; `--surface full` includes the verbs alongside every other > op). See `docs/protocol/MEMORY_VERBS_v1.md`.

Contract

This skill guarantees:

• Every answer is grounded in brain content (no hallucination)
• Every claim has a citation tracing back to a specific page slug
• Gaps are flagged explicitly ("the brain doesn't have information on X")
• Source precedence is respected (user statements > compiled truth > timeline > external)
• Conflicting sources are noted with both citations

Phases

1. **Decompose the question** into search strategies:

• Keyword search for specific names, dates, terms
• Semantic query for conceptual questions
• Structured queries (list by type, backlinks) for relational questions

2. **Execute searches:**

• Cheap-hybrid search gbrain for exact tokens / known names (search)
• Full-hybrid search gbrain for concept questions (query; `--expand` adds multi-query expansion)
• List pages in gbrain by type or check backlinks for structural queries
• Narrow with filters instead of grepping the brain checkout: `--types '["meeting"]'`,

`--match keyword`, `gbrain query "<q>" --since 2026-09-01 --until 2026-09-30`, `--source <id>`. Every call and flag: "Which gbrain call for which lookup" in `skills/conventions/brain-first.md`. 3. **Read top results.** Read the top 3-5 pages from gbrain to get full context. 4. **Synthesize answer** with citations. Every claim traces back to a specific page slug. 5. **Flag gaps.** If the brain doesn't have info, say "the brain doesn't have information on X" rather than hallucinating. Read the result's notices first (see "When it fails"): a degraded or truncated result is not a gap.

When it fails

Follow the [agent operator protocol](../conventions/agent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill:

• Check each retrieval result for notices before answering: on MCP, extra text blocks whose first line looks like [gbrain notice empty_retrieval kind=degraded], mirrored in `_meta.gbrain_notices`; on the CLI, the `[AGENT]` block, `search_degraded`, or a `note: search degraded` line.
• `empty_retrieval` with `kind=degraded` (or `search_degraded: keyword_only_no_embedding_provider`): an empty result is NOT proof the user has no notes. Tell the user "your brain is searching keywords only right now, so I may be missing notes on X", try exact names and synonyms with `gbrain search`, and point to the notice's fix (usually enabling embeddings).
• `empty_retrieval` with "retrieval healthy": nothing was degraded, but this one query matched nothing. Before saying "the brain doesn't have information on X", try the display name, a synonym or a hybrid search (`--match hybrid`, the default).
• `listing_truncated` or `budget_truncated`: the list was cut off. Say "showing the first N", and page or narrow the query before claiming something is absent.
• `page_not_found` from `get_page`: the slug is wrong or in another source; search by title (and check `--source`) before reporting the page missing.

Anti-Patterns

• Answering from general knowledge when the brain has relevant content
• Hallucinating facts not in the brain
• Silently picking one source when sources conflict
• Loading full pages when search chunks are sufficient
• Ignoring source precedence (user statements are highest authority)

Output Format

Answers should include:

• Direct response to the question
• Citations: "According to [Source: people/jane-doe, compiled truth]..."
• Gap flags: "The brain doesn't have information on X"
• Conflict notes when sources disagree

Quality Rules

• Never hallucinate. Only answer from brain content.
• Cite sources: "According to concepts/do-things-that-dont-scale..."
• Flag stale results: if a search result shows [STALE], note that the info may be outdated
• For "who" questions, use backlinks and typed links to find connections
• For "what happened" questions, use timeline entries
• For "what do we know" questions, read compiled_truth directly

Token-Budget Awareness

Search returns **chunks**, not full pages. Read the excerpts first before deciding whether to load a full page.

For a question about saved **page evidence** with a tight budget, explicitly choose `recall` with `budget_policy: "query_first"`. It gives the existing ranked page results first use of the budget, then packs recent/fil