Search and knowledge
Search is one contract shared by the ⌘K palette, the agent’s search tool, MCP and the CLI.
Every role: search operation in your catalog is a source, and aidy’s knowledge index is one
more source, named knowledge.
A search source
Section titled “A search source”A search operation is a GET with effect read, a required q query parameter and an optional
limit:
"/api/vms/search": { "get": { "x-aidy": { "name": "search_vms", "role": "search" } }}GET /api/vms/search?q=gpu&limit=10{ "hits": [ { "type": "vm", "id": "vm-42", "title": "gpu-train-01", "excerpt": "Running · 8 × H100 · cn-beijing-a", "url": "/console/instance/vm-42", "updatedAt": "2026-11-19T08:00:00Z" } ]}SearchHit
Section titled “SearchHit”| Field | Meaning |
|---|---|
type |
Required. A short kind (vm, item, doc), used for grouping and filtering. |
id |
Required. Unique within the type. |
title |
Required. |
excerpt |
Optional plain text, at most 300 characters. Matches may be wrapped in «…». |
url |
Required. A path in the product, or an absolute URL for external content. |
updatedAt |
Optional RFC 3339 time. |
content |
Optional plain text, at most 4000 characters: the passage itself, for the model. |
content lets the model answer from the passage rather than a 300-character excerpt. aidy gives
it to the model through the search tool and MCP, and strips it from GET /aidy/v0/search and
from citations, which people see.
aidy calls each source as the user, so results are already filtered by the user’s permissions.
Return the best hits first. limit defaults to 10 and is at most 50. The Python kit has
SearchHit and SearchResponse models; TypeScript has SearchHit in @aidy-dev/spec/search.
Federation
Section titled “Federation”GET /aidy/v0/search?q=gpu&limit=10&types=vm,docaidy queries every source in parallel, each with its own timeout, and answers:
{ "hits": [{ "source": "search_vms", "type": "vm", "id": "vm-42", "title": "gpu-train-01", "url": "/console/instance/vm-42" }], "failed": [{ "source": "search_chat", "code": "timeout" }]}Hits are merged by reciprocal rank fusion with k = 60. Each hit scores the sum, over the
sources that returned it, of 1 / (60 + rank). Only the rank a source gave a hit matters, so
no source’s scores need to be comparable with another’s. Each hit names its source.
A failed source is listed in failed with the code timeout, http_<status> or
invalid_response. It never fails the whole search: a slow chat index leaves the server and
docs results intact.
Each source’s timeout is 2 seconds by default and at most 10: set timeoutSeconds in a
search operation’s x-aidy (a larger value is a catalog error), or timeoutMs on a configured
SearchSource (default 2000, at most 10 000).
"x-aidy": { "name": "search_chat", "role": "search", "timeoutSeconds": 5 }The agent’s search tool
Section titled “The agent’s search tool”The model sees a built-in search tool next to your operations. It returns the same hits as
the federated endpoint, with their content, numbered n from 1 across the run. When the
answer cites hits as [1], [2], the run emits a CUSTOM event:
{ "type": "CUSTOM", "name": "aidy.citation", "value": { "messageId": "msg_…", "citations": [ { "n": 1, "hit": { "source": "knowledge", "type": "doc", "id": "docs/stop/0", "title": "Stopping servers", "url": "/docs/stop" } } ] }}Each cited hit comes under the number n the answer wrote, so [11] or [2][4] link the right
hit and a client can render footnotes. MCP clients get the same
search tool, and the CLI exposes it as aidy search "gpu box".
Knowledge
Section titled “Knowledge”@aidy-dev/knowledge indexes Markdown documents into collections on any SqlDriver
(Postgres, SQLite, Cloudflare D1) and is a search source named knowledge. Answers grounded in
it cite their sources through the same aidy.citation event.
import { createKnowledge } from '@aidy-dev/knowledge';import { sqliteDriver } from '@aidy-dev/sql/sqlite';
const knowledge = createKnowledge({ driver: sqliteDriver('knowledge.sqlite') });await knowledge.migrate();
await knowledge.ingest('docs', [ { id: 'stop', title: 'Stopping servers', url: '/docs/stop', markdown: '# Stopping servers\n\n## Forced stop\n\nA forced stop skips the guest shutdown.', },]);
createAidy({ // ... sources: [knowledge.source({ collections: (identity) => ['docs', `manuals/${identity.tenant}`] })],});- Documents are split at h1 to h3 headings, and long sections at paragraphs, then sentences.
A chunk’s URL is the document URL plus the heading anchor (an explicit
{#id}on the heading, or else its GitHub-style slug), and its title isdocument title › heading path. Each hit carries the chunk text ascontent. - Retrieval is lexical (BM25 on SQLite and D1,
ts_rankon Postgres), with CJK bigrams so Chinese text matches without spaces. With anembedfunction, vector similarity is fused with the lexical ranking, again by RRF with k = 60. collections(identity)picks what each user may search, for example shared docs plus their tenant’s manuals.ingestskips unchanged documents, so you can re-run it on every deploy.
See the Knowledge guide for ingestion, embeddings and limits.
Related
Section titled “Related”- Identity
- AG-UI profile:
aidy.citation - React guide:
SearchPalette