rungent v0.5.1
EN中文

rungentConcepts

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
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:

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

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

{
  "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:

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_.

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:
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:

## Rotate certificates {#rotate}

Grounding and citations#

An answer citing its source
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 puts the palette beside the dock, MCP and the CLI.

For agents: search.mdEdit this page