Query Router (Stage 1: Memory-or-Not Gate)

Live run: see the QueryRouter initialize a 1,720-chunk corpus across 50 topics and 333 sources on the agentos.sh demo gallery. Source: examples/query-router.mjs.

QueryRouter is the one-call grounded Q&A pipeline. Point it at your markdown directories, ask a question, get back a fully-attributed answer:

import { QueryRouter } from '@framers/agentos';

const router = new QueryRouter({
  knowledgeCorpus: ['./docs'],
  verifyCitations: true,
});
await router.init();

const result = await router.route('how do I configure a guardrail?');
//   result.answer          → grounded answer text
//   result.sources         → citations with title, URI, snippet
//   result.classification  → { tier, strategy, confidence, reasoning }
//   result.tiersUsed       → which tiers actually fired
//   result.fallbacksUsed   → e.g. ['keyword-fallback']
//   result.grounding       → per-claim verdicts when verifyCitations is on

When To Use It

Reach for QueryRouter when you're building any of these on top of a documentation corpus or knowledge base:

• An in-product help / "ask the docs" feature
• A support copilot that answers from internal runbooks
• An agent tool that needs to ground responses in a specific corpus before answering
• A test harness that needs reproducible classify-retrieve-answer triples for evals

It replaces the boilerplate of chunker + vector store + tier classifier + retriever + LLM call + citation collector with a single object whose route() returns a result you can hand straight to a UI. The result is intentionally provenance-oriented — the answer always comes with the sources it was drawn from, the tier path it took, and any fallback strategies that activated.

How It Works

Each call to route() runs three stages in sequence:

1. Classify the query into one of four tiers (T0 trivial → T3 deep research) using an LLM prompt that sees the corpus topics, recent conversation history, and any registered tool names.
2. Retrieve the context for that tier: nothing for T0; a 5-chunk vector search for T1; for T2 a 15-chunk search, graph expansion when graphEnabled is on, and a rerank down to 5; for T3 the query split into sub-queries, a 10-chunk search for each, graph expansion, a rerank down to 10, and deep research when deepResearchEnabled is on. The built-in router generates no hypothetical answer (HyDE) for T2 or T3: both run its plain vector search unless a UnifiedRetriever built with a hydeRetriever is attached with setUnifiedRetriever().
3. Generate a grounded answer from the retrieved context, attaching SourceCitation[] entries that point back at the chunks the answer was drawn from.

If no embedding provider is configured, the router degrades cleanly to keyword search instead of failing. The platform-knowledge entries that ship with @framers/agentos (68 in the published package: FAQ, API reference and troubleshooting) are merged into your corpus automatically, with no extra configuration.

What It Does

• Tier classification uses an LLM prompt with corpus topics, recent conversation history, and optional tool names.
• The router embeds local markdown docs into an in-memory vector store when an embedding provider is available.
• If embeddings are unavailable or vector search fails, the router falls back to keyword search automatically.
• cacheResults backs an in-memory route() result cache and is enabled by default.
• verifyCitations: true runs post-generation citation verification when retrieved chunks and embeddings are available; the verdicts land on result.grounding.
• Result metadata includes tiersUsed and fallbacksUsed.
• Lifecycle events cover classification, retrieval, research, generation, and route completion.

Execution Paths

• Default path: route() classifies the query, then dispatches retrieval through the legacy QueryDispatcher.
• Opt-in path: if a host calls setUnifiedRetriever(...), route() switches to plan-aware retrieval through UnifiedRetriever.

UnifiedRetriever runs only after a host calls setUnifiedRetriever(); it is not the default retrieval path.

Built-in Retrieval Branches

The graph, rerank and research branches have built-in implementations that use only the local corpus:

• graphExpand() adds chunks from the same document and with overlapping headings; it is not a GraphRAG engine.
• rerank() is a lexical reranker, not a cross-encoder.
• deepResearch() synthesizes from the local corpus; it searches no web sources.

Hosts replace any of the three with their own implementation through the hooks below.

Host-Injected Runtime Hooks

You can replace the built-in heuristic branches without forking QueryRouter by passing host-provided callbacks in the constructor:

• graphExpand(seedChunks) for GraphRAG or relationship expansion
• rerank(query, chunks, topN) for provider-backed reranking
• deepResearch(query, sources) for real multi-source research

When these hooks are supplied, router.getCorpusStats() reports the corresponding runtime mode as active instead of the built-in heuristic mode.

Example

Runnable source: examples/query-router.mjs

import { QueryRouter } from '@framers/agentos';

const router = new QueryRouter({
  knowledgeCorpus: ['./docs', './packages/agentos/docs'],
  availableTools: ['web_search', 'deep_research'],
});

await router.init();

console.log(router.getCorpusStats());

const result = await router.route('How does memory retrieval work?');

console.log(result.answer);
console.log(result.classification.tier);
console.log(result.tiersUsed);
console.log(result.fallbacksUsed);
console.log(result.sources);

await router.close();

Host-Injected Runtime Example

Runnable source: examples/query-router-host-hooks.mjs

const router = new QueryRouter({
  knowledgeCorpus: ['./docs', './packages/agentos/docs'],
  graphEnabled: true,
  deepResearchEnabled: true,
  graphExpand: async (seedChunks) => [...seedChunks, extraGraphChunk],
  rerank: async (_query, chunks, topN) => chunks.slice(0, topN),
  deepResearch: async (query, sources) => ({
    synthesis: `Host-provided research for ${query}`,
    sources: externalResearchChunks,
  }),
});

await router.init();
console.log(router.getCorpusStats()); // graph/deepResearch/rerank runtime modes become active

Bundled Platform Knowledge

The QueryRouter loads a bundled platform-knowledge corpus at startup and merges it into the corpus alongside your project docs, with no configuration required.

What's Included

Category	Count in the published package	Examples
FAQ	38	"How do I add voice?", "What models are supported?", "Does AgentOS support streaming?"
API	15	generateText(), streamText(), agent(), agency(), embedText(), generateImage()
Troubleshooting	15	Missing API keys, model not found, embedding init failures
Tools	0	One entry per capability-catalog entry of the extensions registry
Skills	0	One entry per curated skill

npm run build:knowledge adds the tool and skill entries only when agentos-extensions-registry and agentos-skills sit beside the package; the published package is built without them, so it carries the 68 FAQ, API and troubleshooting entries.

How It Works

Platform knowledge is loaded from knowledge/platform-corpus.json inside the @framers/agentos package. During init(), these entries are converted to CorpusChunk objects and appended to the user corpus. Both the vector index and the keyword fallback index cover platform entries, so they work regardless of whether an embedding API key is available.

The platform knowledge layer sits beneath your project documentation:

User project docs     (your ./docs, ./guides, etc.)
  + Platform knowledge  (FAQ, API, troubleshooting; tools and skills only when
                         the corpus was built beside their registries)
  + GitHub repos        (optional — indexed asynchronously after init)
  = Complete corpus

An agent can answer questions such as "How do I add voice?" or "What messaging channels are supported?" without any project documentation: the published corpus holds FAQ entries for both.

Agentic Credential Discovery

A key application of platform knowledge is agentic credential setup. The corpus includes dedicated FAQ entries for:

• Gmail setup (faq:setup-gmail): Step-by-step instructions for creating a Google Cloud project, enabling the Gmail API, downloading the client_secret_*.json file, and running the OAuth flow.
• General credential setup (faq:setup-credentials-general): The universal pattern for helping users configure any extension — discover what's needed via discover_capabilities, find files via shell_execute, parse them via file_read, and persist credentials.
• Extension credentials reference (faq:extension-credentials): Complete listing of what environment variables each extension requires (GITHUB_TOKEN, DISCORD_BOT_TOKEN, ELEVENLABS_API_KEY, etc.).
• File discovery (faq:find-credential-files): How to locate downloaded credential files on the user's system (checking ~/Downloads, ~/Desktop, ~/.aws, ~/.ssh).
• Connect reference (faq:wunderland-connect): Reference for the wunderland connect <service> OAuth flow, its supported services and the --credentials flag.

When a user asks "help me set up Gmail" or "I downloaded a credentials file", retrieval surfaces these entries, and an agent with tools such as shell_execute and file_read can follow them to guide the user through credential setup.

Configuration

Platform knowledge is enabled by default. To disable it:

const router = new QueryRouter({
  knowledgeCorpus: ['./docs'],
  includePlatformKnowledge: false,
});

Regenerating Platform Knowledge

If you are contributing to AgentOS and need to update the bundled knowledge:

npm run build:knowledge

This regenerates knowledge/platform-corpus.json from the current tool manifests, skill registry, FAQ sources, and API documentation.

Config Notes

• knowledgeCorpus is required.
• init() throws when the corpus is empty: no readable .md / .mdx sections under knowledgeCorpus and no platform knowledge (includePlatformKnowledge: false, or the bundled file missing).
• availableTools is optional and is only used to help the classifier reason about what the runtime can do.
• apiKey / baseUrl configure classifier and generator LLM calls. When omitted, a classifier or generator whose provider is not OpenAI takes that provider's own key variable (MINIMAX_API_KEY for minimax), or none when it is unset, and no URL from the router, so generateText resolves its credentials and endpoint and another vendor's key never reaches it. An OpenAI one prefers OPENAI_API_KEY and falls back to OPENROUTER_API_KEY with the OpenRouter compatibility base URL. With MINIMAX_API_KEY as the only provider key, the classifier and generator default to minimax and MiniMax-M3.1-Flash. An empty or whitespace-only baseUrl counts as omitted, so an OpenAI route on the OpenRouter key keeps the OpenRouter URL.
• embeddingApiKey / embeddingBaseUrl override only the embedding path when vector retrieval should use a different provider or credential. When omitted, embeddings fall back to apiKey and baseUrl when they use the classifier's or the generator's provider, never for another vendor's; without that, an embedding provider other than OpenAI that has a key variable of its own takes that key (GEMINI_API_KEY for gemini), or none, and an OpenAI one takes the first provider key set, OPENAI_API_KEY first and OPENROUTER_API_KEY last. An embedding provider other than OpenAI gets no URL from the router; the OpenRouter compatibility URL goes only to an OpenAI one on the OpenRouter key. An empty or whitespace-only embeddingBaseUrl or inherited baseUrl counts as omitted. MiniMax publishes no embedding model, so a MiniMax key alone leaves embeddingProvider on openai, and the MiniMax provider refuses an embedding request before sending it.
• githubRepos optionally enables non-blocking GitHub corpus indexing after init(). Newly indexed repo chunks are merged back into the live corpus, keyword fallback, classifier topics, and the vector index when embeddings are active.
• deepResearchEnabled controls whether the tier-3 research branch is attempted (by default, on when SERPER_API_KEY is set); the default core implementation is a local-corpus heuristic, and hosts can inject a web-backed implementation.
• onClassification and onRetrieval are hooks for consumers that want lightweight runtime integration without reading the full event stream.
• cacheResults controls an in-memory cache of completed route() results. QueryRouter clears that cache when indexed corpus chunks change and when retrieval-planning dependencies such as UnifiedRetriever or the capability-discovery engine are swapped.
• verifyCitations enables post-generation CitationVerifier runs against the retrieved chunks for a route. When verification runs successfully, the result is attached to QueryResult.grounding; if embeddings are unavailable or no chunks were retrieved, verification is skipped gracefully.
• router.getCorpusStats() returns a QueryRouterCorpusStats snapshot with configured path count, loaded chunk/topic/source counts, live bundled platform-knowledge category counts, whether retrieval is running in vector+keyword-fallback or keyword-only mode, the embedding health field embeddingStatus, and the runtime-truth fields graphRuntimeMode, rerankRuntimeMode, and deepResearchRuntimeMode.
• embeddingStatus: 'active' means the vector index initialized successfully, 'disabled-no-key' means init stayed keyword-only because no embedding credential was available, and 'failed-init' means embedding bootstrap was attempted but failed and the router fell back to keyword-only mode.
• graphRuntimeMode: 'heuristic' means the built-in same-document / heading-overlap expansion is active; 'active' means a host-injected graphExpand hook; 'disabled' means graphEnabled is off.
• rerankRuntimeMode: 'heuristic' means the built-in lexical reranker is active; 'active' means a host-injected rerank hook.
• deepResearchRuntimeMode: 'heuristic' means the built-in local-corpus synthesis pass is active; 'active' means a host-injected deepResearch hook; 'disabled' means deepResearchEnabled is off.

Result Metadata

QueryResult includes:

• classification: the final classification result
• sources: citations built from retrieved chunks
• grounding: optional VerifiedResponse from post-generation citation verification
• recommendations: optional skill/tool/extension suggestions inferred during plan-aware classification
• tiersUsed: the tiers actually exercised after fallbacks
• fallbacksUsed: retrieval/classification fallback strategy names such as keyword-fallback or research-skip
• durationMs: total end-to-end wall-clock time for classification, retrieval, and generation

Events

The router records typed events for:

• classify:start
• classify:complete
• classify:error
• retrieve:*
• research:*
• generate:*
• route:complete

Hosts use them for observability and audit trails.