Skip to content

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 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"
}
]
}
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.

GET /aidy/v0/search?q=gpu&limit=10&types=vm,doc

aidy 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 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".

@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 is document title › heading path. Each hit carries the chunk text as content.
  • Retrieval is lexical (BM25 on SQLite and D1, ts_rank on Postgres), with CJK bigrams so Chinese text matches without spaces. With an embed function, 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.
  • ingest skips unchanged documents, so you can re-run it on every deploy.

See the Knowledge guide for ingestion, embeddings and limits.