# KuraDB

> KuraDB is a Go RAG database and MCP RAG server with hybrid keyword and vector search over local documents, built by 邱敬幃 Pardn Chiu (pardnchiu).

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd, Taiwan · Infrastructure Engineering. Source: https://github.com/pardnchiu/KuraDB

Full text in one file: [English](https://kuradb.pardn.io/llms-full.txt) · [中文](https://kuradb.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://kuradb.pardn.io/index.md): KuraDB is a Go RAG database and MCP RAG server with hybrid keyword and vector search over local documents, built by 邱敬幃 Pardn Chiu (pardnchiu).
- [Getting Started](https://kuradb.pardn.io/getting-started.md): Prerequisites for KuraDB and how to install the kura binary with go install or build it from source.
- [First Search](https://kuradb.pardn.io/getting-started-first-search.md): Register a folder as a KuraDB database, start the daemon, index a file, and run your first keyword and semantic search.
- [Service State](https://kuradb.pardn.io/getting-started-service-state.md): Check KuraDB daemon health and loaded databases over HTTP, then change its port or stop it.

## Architecture

- [Architecture](https://kuradb.pardn.io/architecture.md): KuraDB system overview: the runtime components, how they are composed, and the HTTP and stdio MCP transports.
- [Lifecycle](https://kuradb.pardn.io/architecture-lifecycle.md): KuraDB startup order, background goroutines, locking, and graceful shutdown of the daemon.
- [Storage Topology](https://kuradb.pardn.io/architecture-storage.md): Where KuraDB keeps state: per-database SQLite files, the registry, query cache, and in-memory vector cache.
- [Trust Boundaries](https://kuradb.pardn.io/architecture-trust-boundaries.md): KuraDB invariants: read-only API, a single SQLite writer, dismissed-row filtering, and embedding dimension checks.

## Concepts

- [Core Concepts](https://kuradb.pardn.io/core-concepts.md): KuraDB's read-only service boundary, shared core behind every transport, database registry, and platform assumptions.
- [Data Consistency](https://kuradb.pardn.io/core-concepts-data-consistency.md): Why SQLite is KuraDB's source of truth, how chunks move from pending to embedded to dismissed, and embedding dimension rules.
- [Retrieval Model](https://kuradb.pardn.io/core-concepts-retrieval.md): KuraDB's dual keyword and semantic retrieval, source-level vector filtering, and the query embedding cache.

## Indexing

- [Indexing Pipeline](https://kuradb.pardn.io/indexing-pipeline.md): How KuraDB watches registered folders with directory snapshots and how often each indexing stage runs.
- [Parsing](https://kuradb.pardn.io/indexing-pipeline-parsing.md): Which file types KuraDB parses, how content is detected and chunked, and which inputs are skipped.
- [Upsert and Removal](https://kuradb.pardn.io/indexing-pipeline-storage.md): How KuraDB writes parsed chunks to SQLite in one transaction and marks rows of deleted files as dismissed.
- [Embedding](https://kuradb.pardn.io/indexing-pipeline-embedding.md): How KuraDB batches pending chunks to OpenAI embeddings, applies results without races, and updates the vector cache.

## Search

- [Search and Retrieval](https://kuradb.pardn.io/search-and-retrieval.md): How KuraDB picks a search strategy per request and runs keyword retrieval with gse segmentation over SQLite.
- [Semantic Search](https://kuradb.pardn.io/search-and-retrieval-semantic.md): KuraDB semantic search: query embedding, two-stage source-then-chunk cosine ranking, score threshold, and hydration.
- [Result Grouping](https://kuradb.pardn.io/search-and-retrieval-results.md): How KuraDB groups hits by source file, keeps ranking fields private, and behaves while indexing is in progress.

## Configuration

- [Configuration](https://kuradb.pardn.io/configuration.md): KuraDB's OpenAI credential, configuration directory layout, and fixed service constants.
- [Port and Remote MCP](https://kuradb.pardn.io/configuration-network.md): Set the KuraDB HTTP port, enable or disable the remote MCP endpoint, and how clients discover the running daemon.
- [Platform Constraints](https://kuradb.pardn.io/configuration-platform.md): When a registered KuraDB database is available, and the operating systems and filesystems KuraDB supports.

## CLI

- [CLI Reference](https://kuradb.pardn.io/cli-reference.md): Every kura subcommand at a glance, plus the Makefile targets for building and running KuraDB.
- [Database Commands](https://kuradb.pardn.io/cli-reference-databases.md): kura add, list, edit, and remove: manage the folders KuraDB indexes as named databases.
- [Daemon Commands](https://kuradb.pardn.io/cli-reference-daemon.md): Start the KuraDB daemon, pin its HTTP port, and stop it with the kura CLI.
- [MCP Commands](https://kuradb.pardn.io/cli-reference-mcp.md): Turn KuraDB's HTTP MCP endpoint on or off and serve MCP over stdio with kura mcp.

## HTTP API

- [API Reference](https://kuradb.pardn.io/api-reference.md): KuraDB HTTP API base URL, endpoint summary, the health check, and the database list endpoint.
- [Search Endpoint](https://kuradb.pardn.io/api-reference-search.md): KuraDB search endpoint: query parameters, combined keyword and semantic response, and legacy compatibility routes.
- [Errors and Contract](https://kuradb.pardn.io/api-reference-errors.md): KuraDB HTTP error responses, the read-only API boundary, and which response fields are part of the contract.

## MCP

- [MCP Server](https://kuradb.pardn.io/mcp-server.md): KuraDB as a Model Context Protocol server: stdio and HTTP transports sharing one implementation, and its server instructions.
- [Connect a Client](https://kuradb.pardn.io/mcp-server-connect.md): Connect an MCP client to KuraDB over stdio with kura mcp, or over streamable HTTP when remote access is enabled.
- [Tools](https://kuradb.pardn.io/mcp-server-tools.md): KuraDB MCP tools list_rag and search_rag: parameters, results, errors, and naming kept in sync with Agenvoy.

## 中文文件

- [首頁](https://kuradb.pardn.io/zh/index.md): KuraDB 是以 Go 撰寫的本地 RAG 資料庫與 MCP RAG 伺服器，提供混合關鍵字與向量搜尋，由邱敬幃（pardnchiu）開發。
- [開始使用](https://kuradb.pardn.io/zh/getting-started.md): KuraDB 的前置需求，以及用 go install 安裝或從原始碼建置 kura 執行檔。
- [第一次搜尋](https://kuradb.pardn.io/zh/getting-started-first-search.md): 把資料夾註冊為 KuraDB 資料庫、啟動 daemon、索引檔案並執行第一次搜尋。
- [服務狀態](https://kuradb.pardn.io/zh/getting-started-service-state.md): 透過 HTTP 確認 KuraDB daemon 健康狀態與已載入資料庫，再調整 port 或停止服務。
- [架構](https://kuradb.pardn.io/zh/architecture.md): KuraDB 系統概覽：執行期元件、組裝方式，以及 HTTP 與 stdio MCP transport。
- [生命週期](https://kuradb.pardn.io/zh/architecture-lifecycle.md): KuraDB daemon 的啟動順序、背景 goroutine、鎖與優雅關閉。
- [儲存拓撲](https://kuradb.pardn.io/zh/architecture-storage.md): KuraDB 狀態存放位置：各資料庫 SQLite、註冊表、query 快取與記憶體向量快取。
- [信任邊界](https://kuradb.pardn.io/zh/architecture-trust-boundaries.md): KuraDB 不變條件：唯讀 API、單一 SQLite 寫入者、dismiss 過濾與 embedding 維度檢查。
- [核心概念](https://kuradb.pardn.io/zh/core-concepts.md): KuraDB 的唯讀服務邊界、各 transport 共用核心、資料庫註冊與平台假設。
- [資料一致性](https://kuradb.pardn.io/zh/core-concepts-data-consistency.md): 為何 SQLite 是 KuraDB 的真理來源、chunk 的狀態流轉與 embedding 維度規則。
- [檢索模型](https://kuradb.pardn.io/zh/core-concepts-retrieval.md): KuraDB 的關鍵字與語意雙路檢索、來源層級向量過濾與 query embedding 快取。
- [索引管線](https://kuradb.pardn.io/zh/indexing-pipeline.md): KuraDB 如何以目錄快照監控已註冊資料夾，以及各索引階段的執行頻率。
- [解析](https://kuradb.pardn.io/zh/indexing-pipeline-parsing.md): KuraDB 解析哪些檔案類型、如何偵測與切塊內容，以及會略過哪些輸入。
- [寫入與移除](https://kuradb.pardn.io/zh/indexing-pipeline-storage.md): KuraDB 如何以單一交易寫入 chunk，並將已刪除檔案的資料列標記為 dismiss。
- [Embedding](https://kuradb.pardn.io/zh/indexing-pipeline-embedding.md): KuraDB 如何批次送出 OpenAI embedding、無競態套用結果並更新向量快取。
- [搜尋與檢索](https://kuradb.pardn.io/zh/search-and-retrieval.md): KuraDB 如何為每次請求選擇搜尋策略，並以 gse 斷詞在 SQLite 上執行關鍵字檢索。
- [語意搜尋](https://kuradb.pardn.io/zh/search-and-retrieval-semantic.md): KuraDB 語意搜尋：query embedding、先來源後 chunk 的兩階段 cosine 排序、分數門檻與回填。
- [結果分組](https://kuradb.pardn.io/zh/search-and-retrieval-results.md): KuraDB 如何依來源檔分組結果、隱藏排序欄位，以及索引進行中的行為。
- [設定](https://kuradb.pardn.io/zh/configuration.md): KuraDB 的 OpenAI 憑證、設定目錄結構與固定服務常數。
- [Port 與遠端 MCP](https://kuradb.pardn.io/zh/configuration-network.md): 設定 KuraDB HTTP port、開關遠端 MCP endpoint，以及 client 如何找到 daemon。
- [平台限制](https://kuradb.pardn.io/zh/configuration-platform.md): 已註冊的 KuraDB 資料庫何時可用，以及支援的作業系統與檔案系統。
- [CLI 參考](https://kuradb.pardn.io/zh/cli-reference.md): 所有 kura 子指令總覽，以及建置與執行 KuraDB 的 Makefile target。
- [資料庫指令](https://kuradb.pardn.io/zh/cli-reference-databases.md): kura add、list、edit、remove：管理 KuraDB 索引的具名資料庫。
- [Daemon 指令](https://kuradb.pardn.io/zh/cli-reference-daemon.md): 以 kura CLI 啟動 KuraDB daemon、固定 HTTP port 與停止服務。
- [MCP 指令](https://kuradb.pardn.io/zh/cli-reference-mcp.md): 開關 KuraDB 的 HTTP MCP endpoint，並以 kura mcp 透過 stdio 提供 MCP。
- [API 參考](https://kuradb.pardn.io/zh/api-reference.md): KuraDB HTTP API 的 base URL、endpoint 總覽、健康檢查與資料庫清單 endpoint。
- [搜尋 Endpoint](https://kuradb.pardn.io/zh/api-reference-search.md): KuraDB 搜尋 endpoint：query 參數、合併的關鍵字與語意 response，以及相容 route。
- [錯誤與契約](https://kuradb.pardn.io/zh/api-reference-errors.md): KuraDB HTTP 錯誤 response、唯讀 API 邊界，以及哪些 response 欄位屬於契約。
- [MCP Server](https://kuradb.pardn.io/zh/mcp-server.md): KuraDB 作為 MCP 伺服器：stdio 與 HTTP 兩種 transport 共用同一實作，以及其 server instructions。
- [連接 Client](https://kuradb.pardn.io/zh/mcp-server-connect.md): 以 kura mcp（stdio），或啟用遠端後以 streamable HTTP，將 MCP client 接上 KuraDB。
- [工具](https://kuradb.pardn.io/zh/mcp-server-tools.md): KuraDB MCP 工具 list_rag 與 search_rag：參數、結果、錯誤，以及與 Agenvoy 同步的命名。

## Optional

- [Release Notes](https://kuradb.pardn.io/released/index.md): KuraDB changelog by version