Finding Anything in HQ

Illustrative · search by meaning across everything HQ knows

Everything HQ learns, meeting notes, project plans, company knowledge, even indexed code, is searchable from one place: /search. This article covers how to search well, how to narrow a search to one company, and where things live if you'd rather browse.

/search: one command for everything#

A session with HQ only remembers what's in front of it, but your HQ remembers everything it has stored. /search is how you pull that memory back:

/search pricing calculator

Under the hood, HQ uses a search engine (called qmd) that combines keyword search (finds exact words, fast) with semantic search (finds meaning. "customer cancellations" will surface documents about churn even if they never say "cancellations"). Results come back scored and ranked, with file paths and snippets, so you can jump straight to the source.

By default /search uses keyword matching. Two options change that:

• --mode vsearch, semantic search, for conceptual questions where you don't know the exact words.
• --mode query, hybrid, keyword + semantic + smart re-ranking. Highest quality, slightly slower. Use it when the first search misses.

You can also ask for more results with -n 20, or show the full text of the top hit with --full.

Scoping to a company#

Your knowledge is organized into collections, one per company (an isolated workspace for one business or team), plus a few shared ones for HQ's own commands, workers, projects, and any indexed codebases. Scope a search with -c:

/search "brand guidelines" -c acme

Most of the time you don't need to: if you're already working inside a company's folders or on its project, HQ auto-detects the company and scopes for you, you'll see (auto: acme) in the results header. Leave -c off entirely to search everything you have access to. Company isolation still applies: searches never cross into companies you're not a member of.

Five searches an operator actually runs#

/search "onboarding checklist" -c acme

Find the doc a teammate mentioned, without asking where it lives.

/search "what did we decide about annual billing" --mode vsearch

Semantic mode shines for decisions, you remember the topic, not the wording. Meeting notes and extracted signals are indexed too (see Meeting notes & signals).

/search pricing-calculator prd

Pull up a project's plan and status, every PRD (project plan) is indexed.

/search "how do we handle refunds" --mode query -c acme

The high-stakes lookup before answering a customer: hybrid mode digs through knowledge, policies, and meeting history together.

/search "stripe webhook" -c acme-app

If a codebase is indexed as a collection, you can search the code itself, useful even if you never write code, to check whether something exists.

Would rather browse? The three homes#

Everything in HQ lives in one of three top-level places (the full tour is in The HQ mental model):

1. personal/, your private overlay: your profile, personal projects, personal rules. Only you.
2. companies/, one folder per company you belong to. Inside each: knowledge/ (the company's knowledge base, its accumulated documents and facts), projects/ (plans and progress), policies/ (standing rules), and meeting notes. This is where most searchable content lives.
3. repos/, actual code, split into repos/public/ and repos/private/.

If you know roughly where something is, browsing companies/acme/knowledge/ in Finder or your editor is perfectly fine. Search is just faster when you don't.

One more place: files shared through HQ Cloud live in your company's vault (shared cloud file storage). Browse it without downloading anything via /hq-files, see HQ Cloud explained.

Common questions#

If you get stuck#

If every search errors or comes back empty, the search index may be missing on this machine, say "search isn't working" and HQ will diagnose it (or see The "I'm stuck" guide). Persistent trouble: /hq-bug.