query · diff

v1.0.0 to v1.0.0

66 added, 1 removed. Audit A to A.

---

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 with multi-query expansion for concept questions (query)

- List pages in gbrain by type or check backlinks for structural queries

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.

+ 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](../../docs/protocol/AGENT_OPERATOR_v1.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 "no retrieval degradation — this is a clean miss": then say "the brain doesn't have information on X".

+ - `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/filtered facts into what remains.

+ This is an opt-in packing choice, not a new relevance model: an irrelevant page can

+ displace a useful fact. Keep entity-first, session/event-filtered and fact-focused

+ questions on their existing facts-first route. Do not change `context_pack` or

+ existing third-party calls.

+ ```bash

+ gbrain recall --query 'zebra telescope' --budget-tokens 75 --budget-policy query_first --json

+ ```

+ Equivalent MCP request:

+ ```json

+ {"name":"recall","arguments":{"query":"zebra telescope","budget_tokens":75,"budget_policy":"query_first"}}

+ ```

+ **Say to your agent:** “Recall the saved notes about the zebra telescope using a

+ 75-token estimated budget and query-first packing. Cite the returned evidence;

+ if the first page cannot fit, tell me rather than treating that as missing memory.”

+ Use the resolved brain and source as usual; the option does not widen permissions.

+ `budget_packing` reports the effective policy and per-arm candidate/kept/dropped/used

+ counts. Costs estimate `ceil(fact.length/4)` or

+ `ceil(title.length/4) + ceil(chunk.length/4)`, not exact tokenizer or JSON-envelope

+ size. Packing never skips an oversized prefix item or truncates it; multiple

+ required pages may still not fit. With no nonblank query or no positive finite

+ budget, the operation keeps legacy behavior. An eligible positive budget below one

+ token returns empty arms. See the protocol for fractional-budget compatibility.

+ This guidance and advertised tool schemas do not prove native-harness adoption.

+ Confirm an observed query-first call in a fresh harness conversation before

+ claiming activation; otherwise report adoption as unverified.

- `gbrain search` / `gbrain query` return ranked chunks with context snippets.

These are often enough to answer the question directly.

+ - Hits on conversation pages (sessions, transcripts, meetings, chat logs)

+ already come back as the whole session by default (`return_unit: "auto"`,

+ 24,000-token default budget). For other multi-page or "when did X change"

+ questions, where the answer depends on the surrounding text rather than one

+ chunk, ask for whole evidence in the same call: `return_unit: "page"` (whole

+ page, budgeted by `token_budget`, default 6,000) or `"window"` (neighbor

+ chunks). `return_unit: "chunk"` opts out.

+ Each result then carries the evidence in `chunk_text` plus a `delivered`

+ block; see [evidence delivery](../../docs/evidence-delivery.md).

+ `gbrain query "when did the launch move?" --return-unit page --token-budget 6000`

- Only use `gbrain get <slug>` to load the full page when a chunk confirms the

page is relevant and you need more context (e.g., compiled truth, timeline).

- **"Tell me about X"** -- get the full page (the user wants the complete picture).

- **"Did anyone mention Y?"** -- search results are enough (the user wants a yes/no with evidence).

### Source precedence

When multiple sources provide conflicting information, follow this precedence:

1. **User's direct statements** (highest authority -- what the user told you directly)

2. **Compiled truth** (the brain's synthesized, cited understanding)

3. **Timeline entries** (raw evidence, reverse-chronological)

4. **External sources** (web search, API enrichment -- lowest authority)

When sources conflict, note the contradiction with both citations. Don't silently

pick one.

## Citation in Answers

When referencing brain pages in your answer, propagate inline citations:

- Cite the page: "According to [Source: people/jane-doe, compiled truth]..."

- When brain pages have inline `[Source: ...]` citations, propagate them so

the user can trace facts to their origin

- When you synthesize across multiple pages, cite all sources

## Graph Traversal (v0.10.1+)

For relationship questions ("who knows who at X?", "connections between A and B",

"who works at Acme?", "who attended the standup?"), use the graph layer instead

of full-text search:

- `gbrain graph-query <slug> --type <link_type> --depth N --direction in|out|both`

- Available link types: `attended`, `works_at`, `invested_in`, `founded`, `advises`, `mentions`, `source`

- `--direction in` answers "who points to X?" (e.g., who works at company X)

- `--direction out` answers "what does X point to?" (default)

- `--depth N` controls multi-hop traversal (default 5)

Examples:

- "Who works at Acme?" → `gbrain graph-query companies/acme --type works_at --direction in`

- "Who attended Demo Day W26?" → `gbrain graph-query meetings/demo-day-w26 --type attended --direction out`

- "What companies has Emily advised?" → `gbrain graph-query people/emily --type advises --direction out`

- "Who has Alice met (via meetings)?" → `gbrain graph-query people/alice --type attended --depth 2`

Combine with `gbrain query` for queries that need BOTH semantic similarity AND

graph structure. Search results are ranked with a small backlink boost so well-

connected entities surface higher.

## Search Quality Awareness

If search results seem off (wrong results, missing known pages, irrelevant hits):

- Run `gbrain doctor --json` to check index health

- Check embedding coverage -- partial embeddings degrade hybrid search

- Compare keyword search (`gbrain search`) vs hybrid search (`gbrain query`)

for the same query to isolate whether the issue is embedding-related

- Report search quality issues in the maintain workflow (see maintain skill)

## Tools Used

- Keyword search gbrain (search)

- Hybrid search gbrain (query)

- Read a page from gbrain (get_page)

- List pages in gbrain with filters (list_pages)

- Check backlinks in gbrain (get_backlinks)

- Traverse the link graph in gbrain (traverse_graph)

- View timeline entries in gbrain (get_timeline)

+ ## Tools outside your MCP surface

+ This plugin serves the starter tool surface. When a step above names one of these tools and your tool list

+ does not have it, run its gbrain CLI equivalent instead:

+ - `get_timeline` → `gbrain timeline`

+ Or widen this machine's plugin surface with GBRAIN_SURFACE=full (new sessions pick it up).