# Search and knowledge

One search runs across your own search endpoints and your docs. People use it in ⌘K, the agent searches with it before it answers, and every answer cites the hits it used.

![The ⌘K palette searching for gpu](/images/palette.png "Servers from the console's search endpoint and a page of its docs, merged into one list. The last row hands the words to the assistant; a source that did not answer in time is named at the bottom.")

The palette, the agent's `search` tool, MCP and the CLI (`acme search "gpu"`) run the same
search. Each of your `role: search` operations is a source, and your docs, indexed by rungent, are
one more, named `knowledge`.

## Add a search source

A search source is a `GET` with a required `q` query parameter and an optional `limit`:

```json
"/api/vms/search": { "get": { "x-rungent": { "name": "search_vms", "role": "search" } } }
```

`GET /api/vms/search?q=gpu&limit=10` answers its best hits first:

```json
{
  "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`, `doc`), for grouping and filtering. |
| `id` | Required. Unique within the type. |
| `title` | Required. |
| `url` | Required. A path in your product, or an absolute URL. |
| `excerpt` | Plain text, at most 300 characters; matches may be wrapped in `«…»`. |
| `updatedAt` | An RFC 3339 time. |
| `content` | The passage itself, at most 4000 characters, for the model only. People never see it. |

rungent calls each source as the user, so your permission checks already filter the hits. `limit`
defaults to 10 and is at most 50.

## One search over every source

rungent asks every source at once, each with its own timeout (2 seconds by default, at most 10, set
with `timeoutSeconds`), and merges the lists by reciprocal rank fusion: a hit's place depends on
the rank each source gave it, so the sources' scores never need to be comparable. A source that
times out or fails is listed in `failed`, and the others still answer.

## Add your docs

With `rungent serve`, two variables index a folder of Markdown at start:

```bash
RUNGENT_KNOWLEDGE_DIR=/srv/docs
RUNGENT_KNOWLEDGE_BASE_URL=https://docs.acme.example.com
```

Every `.md` and `.mdx` file under the folder becomes a page. Its address is the base URL plus its
path without the extension (`deploy/certificates.md` becomes `…/deploy/certificates`, and an
`index` file stands for its folder); its title is the frontmatter `title`, else the first heading.
Unchanged pages are skipped, so a restart is cheap. The base URL may be a path on your product
(`/help`).

## Index docs from code

Embedded, or to choose who sees which docs, use `rungent/knowledge`. It runs on Postgres,
SQLite or D1 and may share rungent's database: its tables start with `rungent_knowledge_`.

```ts
import { readFile } from 'node:fs/promises';
import { createKnowledge } from 'rungent/knowledge';
import { postgresDriver } from 'rungent/sql/postgres';

const knowledge = createKnowledge({ driver: postgresDriver(process.env.DATABASE_URL!) });
await knowledge.migrate();

await knowledge.ingest('docs', [
  {
    id: 'deploy/certificates',
    title: 'Rotate certificates',
    url: '/help/deploy/certificates',
    markdown: await readFile('docs/deploy/certificates.md', 'utf8'),
  },
]);

const rungent = createRungent({
  // ...
  sources: [knowledge.source({ collections: (identity) => ['docs', `manuals/${identity.tenant}`] })],
});
```

- **`ingest(collection, documents)`** adds or replaces documents and answers
  `{ updated, unchanged }`. Run it after each docs build; unchanged documents are skipped, and
  sections whose text did not change keep their embeddings. `remove(collection, ids)` deletes
  documents your source no longer has.
- **`collections`** receives the user's identity and picks what that user may search, so a
  tenant's private manuals stay with that tenant. The source is named `knowledge`; pass `name` to
  change it.
- **`embed`** and **`dimensions`** add search by meaning ("cert expiry" finds "Rotate
  certificates") with any embedding provider:

```ts
const knowledge = createKnowledge({
  driver,
  embed: async (texts) =>
    (await openai.embeddings.create({ model: 'text-embedding-3-small', input: texts })).data.map((d) => d.embedding),
  dimensions: 1536,
});
```

Without an embedder, search works on words alone, Chinese included. Vector search reads at most
the newest 20,000 sections of the searched collections per query.

## Write docs that cite well

rungent splits each page at its h1 to h3 headings, and cuts a section longer than about 800 tokens at
paragraphs. A hit's title is `page title › heading`, and its link is the page address plus the
heading's anchor. Write so that each section answers one question under a heading that names it.
Give a heading an explicit id when its anchor must not change with its wording:

```md
## Rotate certificates {#rotate}
```

## Grounding and citations

![An answer citing its source](/images/answer.png "The numbered mark after cn-beijing-a links the hit the sentence came from.")

With knowledge, each new user message starts with a search for its text (the first 200
characters, 5 hits) before the model's first step. It is an ordinary `search` call in the
conversation, so the user sees it with the other lookups. The model is told to answer questions
about your product only from tool results and search hits, to search again with other words
when the hits do not answer, and to say so when nothing does. Without knowledge, the agent
searches your `role: search` operations when it needs to find something.

The `search` tool numbers hits from 1 across the run and gives the model their `content`. When an
answer cites `[1]`, the run emits a `rungent.citation` event mapping each number to its hit
(without `content`), and the dock renders it as a link to the hit's `url`.

## Where to go next

[Surfaces](surfaces.md) puts the palette beside the dock, MCP and the CLI.
