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	["search","query","query_scan","get_evidence","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.

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
• All search, query, and query_scan retrieval phrases are English natural language. Non-English user wording is translated before lookup while exact identifiers stay unchanged.
• Provenance drilldown uses exact evidence refs, not semantic search over archive or inbox material. If a curated timeline cites reviewed draft <hash> and the user asks for origin, more detail, or what was in the draft/session, use get_evidence or local gbrain evidence <hash>. On a trusted local host, add --full-source only when the full archived draft body itself is needed.

Phases

1. Decompose the question into search strategies:
   • Keyword search for specific names, dates, terms
   • Semantic query for conceptual questions
   • Paginated coverage scan for "show/find all about X" requests
   • Structured queries (list by type, backlinks) for relational questions
   • Translate any non-English natural-language wording into English retrieval anchors before executing brain search tools
2. Execute searches:
   • Keyword search gbrain for FTS matches (search)
   • Hybrid search gbrain for semantic+keyword with expansion (query)
   • Coverage scan gbrain for exhaustive paginated matches (query_scan)
   • 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. Resolve provenance when needed. If the page's timeline source hash is the thing the user is asking about, call get_evidence with that exact ref and use the returned ledger row/archive metadata as the source layer. Use gbrain evidence <hash> --full-source only for local full-source hydration.
5. Synthesize answer with citations. Every claim traces back to a specific page slug.
6. Flag gaps. If the brain doesn't have info, say "the brain doesn't have information on X" rather than hallucinating.

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
• Running query against archive/inbox concepts when the correct action is an exact get_evidence drilldown from a curated timeline source hash
• Using --full-source as a normal retrieval mode instead of a trusted local provenance inspection step
• 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.

• gbrain search / gbrain query return ranked chunks with context snippets. These are often enough to answer the question directly.
• 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).
• "Show/find/list all about X" -- use query_scan and follow next_cursor until has_more=false; do not treat a top-K query response as exhaustive.
• "Show/find/list all projects/concepts/gotchas/people about X" -- pass the page type filter to query_scan (type for one type, types for several) and keep following next_cursor until has_more=false.
• query_scan is a discovery surface, not a full-material surface. For exhaustive requests, first collect the complete slug list with cursor pagination, then call get_page for the matching pages before synthesizing material. If the slug list is too large for the current context, load pages in stable priority batches, return the complete slug manifest plus the batch actually read, and explicitly state which matching pages remain unread.
• For small exhaustive result sets (roughly <=20 pages), hydrate every matching page with get_page before answering. For large result sets, never pretend snippets are complete evidence; continue in batches or provide a resumable cursor/manifest.

Query Language

Use English retrieval phrases for every gbrain search surface: search, query, query_scan, temporal search, salience search, recall, and takes_search.

If the user asks in another language, translate the natural-language retrieval phrase to English before the tool call. Preserve exact identifiers as written: commands, code symbols, issue IDs, URLs, slugs, file paths, dates, and quoted immutable strings. For non-English person, company, product, or project names, use the English/transliterated canonical form used by brain pages; keep raw source spelling only for source forensics. Do not use non-English natural-language prose as the primary brain search input.

Durable brain pages are expected to be English, so English retrieval keeps FTS, partial-match, vector search, pagination, and exhaustive scans aligned.

Search Surface Cheat Sheet

Use the implemented filters deliberately:

• search: exact/keyword lookup. Supports limit, offset, detail, type, types, and source_id.
• query: hybrid semantic top-N. Supports limit, offset, type, types, expand, detail, lang, symbol_kind, near_symbol, walk_depth, since, until, source_id, cross_modal, embedding_column, include_meta, recency, and salience.
• query_scan: exhaustive lexical/partial coverage. Supports page_size or limit (aliases, cap 99), cursor, offset, detail, type, types, lang, symbol_kind, since, until, and source_id. Use cursor pagination for large result sets; cursor and offset are mutually exclusive.
• temporal_search: date-windowed memory. Use date_kind=formed for when a memory was formed/discussed, recorded for when markdown was written to the brain, and indexed for when it entered the generated index. Exact days are half-open windows [day, next day).
• recall: hot facts. Use entity, session_id, since, grep, include_expired, supersessions, and include_pending when the question is about extracted facts rather than curated pages.
• takes_search: keyword search over typed takes/claims.
• get_recent_salience: notable recent memory. Use days, limit, slugPrefix, and recency_bias only when the user asks what is salient or recently important.

Diagnostics matter. If query returns weak or empty results for a page you believe exists, rerun with include_meta=true. If meta.vector_enabled=false, the response is keyword-only; inspect meta.vector_disabled_reason, meta.embedding_column, and embedding coverage before saying the brain has no relevant material.

For the default full Postgres deployment, the expected semantic path uses openai:text-embedding-3-large, 3072-dimensional embeddings, and the active embedding_hnsw halfvec(3072) search column. Do not fall back to a PGLite mental model when the configured brain is Postgres-backed. Do not override embedding_column unless the task is explicitly diagnostics, benchmarking, or cross-column comparison.

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

• For semantic-sensitive questions, run query with include_meta=true at least once. If meta.vector_enabled=false, treat results as keyword-only: say semantic/vector retrieval is unavailable, inspect meta.vector_disabled_reason, and run gbrain doctor --json before claiming the brain has no relevant material.
• 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 English 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)
• Exhaustive paginated scan (query_scan)
• Date-windowed lookup (temporal_search)
• 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)
• Hot facts lookup (recall)
• Typed takes lookup (takes_search)
• Recent salience lookup (get_recent_salience)