Kunkun Docs

AI Search indexes local files, notes, and web pages into searchable knowledge bases — then lets you search and ask questions in natural language. It uses a local embedding model to vectorize your content and supports hybrid (vector + keyword) search.

How it works

A knowledge base (RAG instance) holds a collection of items — each item is a typed source:

Type	Description
Directory	Scans a folder recursively — files are auto-discovered and indexed
File	A single file (text or code)
Note	Text you write directly in Kunkun
URL	A single web page fetched on demand

Each knowledge base has its own configuration: embedding model, chunk size, search mode, and threshold. The indexed documents, vectors, and full-text search data live in a dedicated SQLite database per instance.

Creating a knowledge base

Open Settings → AI Search

Press Cmd+, (macOS) or Ctrl+, (Windows/Linux), then select AI Search from the sidebar.

If you don't see AI Search, make sure you have at least one AI model configured under Settings → AI Providers. The embedding model you select here must also be available.

Create a new knowledge base

Click Create Knowledge Base, give it a name, and select an embedding model. The chunk size and overlap control how documents are split before embedding — the defaults work well for most content.

Add sources

Once created, you can add items:

Click Add Directory and pick a folder. Kunkun scans it recursively and adds all supported files as child items. You can override the indexing policy per directory (e.g., include/exclude patterns).

Click Add File and pick a single file. This is useful for indexing specific documents without scanning an entire folder.

Click Add Note, give it a title, and paste or write the content. Notes are stored in the primary database and indexed like any other source.

Click Add URL and enter a web page address. Kunkun fetches the page, normalizes it to text, and indexes it. The first slice supports single-page URLs. Recursive crawling and sitemap ingestion are planned follow-ups.

Index

After adding sources, Kunkun queues indexing jobs automatically. You can also click Reindex on any item to refresh it. Directory items reconcile their children — new files are discovered, changed files are reindexed, and removed files are marked missing.

The indexing status shows for each item:

idle — waiting to be indexed
preparing / processing / reading / embedding — active indexing phases
completed — indexed and searchable
stale — settings changed, needs reindex
failed / missing — source unavailable or error

Searching and asking

Once a knowledge base has indexed items, open the Ask tab in the Settings UI.

Search

# In the Settings → AI Search → Ask tab
# Type a query and select "Search" mode
# Results show snippets with relevance scores

Search mode supports:

FTS — full-text keyword search
Vector — semantic similarity search
Hybrid (default) — combines both with a configurable alpha weight

Ask

Question-answering mode uses a language model to generate answers grounded in your indexed content:

Query: "What does the README say about permissions?"
→ Answer synthesized from the relevant chunks, with citations back to source documents

Managing knowledge bases

From the Settings UI you can:

Rename or delete a knowledge base (optionally deleting the artifact data too)
Update settings — changing chunk size, search mode, or embedding model marks material as stale and triggers reindexing
View stats — document count, queue status, and per-item health

Accessing AI Search programmatically

Kunkun exposes AI Search through multiple channels:

Channel	Description	Link
Local REST API	HTTP server on port 9559 with Bearer token auth	Local API Server
MCP	Model Context Protocol server at `/mcp/rag`	AI Search MCP
TypeScript Client	`@kunkunsh/client` package for Node/browser/Deno	Developer docs → Kunkun Client

The REST API and MCP server share the same API key authentication. Create tokens in Settings → API Keys and scope them to specific actions (search, ask, or admin).

AI Search

On this page