# KuraDB RAG

KuraDB 是獨立的 RAG（Retrieval-Augmented Generation）daemon。它是一個獨立的執行檔（`kura`），Agenvoy 既不啟動也不管理它的生命週期 —— Agenvoy 以接觸任何其他外部能力的同一種方式接觸它：**當成 MCP 伺服器**。註冊只是往 `mcp.json` 寫入一筆設定；此後 KuraDB 的工具就會像其他 MCP 工具一樣以 `mcp__` 前綴出現在註冊表中，未註冊或未連線時則完全不存在。

## 這是什麼

KuraDB（[pardnchiu/KuraDB](https://github.com/pardnchiu/KuraDB)）是自研的本地文件索引：

- 將使用者檔案（notes、inbox、code...）索引為多個具名資料庫
- 透過 `gse` 斷詞提供關鍵字搜尋（支援中文）
- 完全在使用者機器上執行 —— 無外部服務

## 整合模型

Agenvoy 端**已不再有** KuraDB 專屬套件。整合方式於 v0.32.1 改為單純的 MCP 註冊，`internal/runtime/kuradb/` 與 `/kuradb` TUI 精靈則於 v0.35.0 移除 —— 安裝、更新、重連不再由 Agenvoy 負責。剩下的只有一般 MCP client 路徑：

| 步驟 | 位置 |
|---|---|
| 安裝執行檔 | 自行在真實終端機執行 `curl -fsSL https://agenvoy.com/scripts/kuradb.sh \| bash`（需要 TTY 以處理 `sudo` 與套件管理器提示）|
| 註冊伺服器 | `/mcp` → add，或直接在 `~/.config/agenvoy/mcp.json` 寫入一筆 |
| 變更後重連 | `/mcp` → `kura` → reconnect，或 `POST /v1/mcp/reconnect`（全部 server） |

```json
{
  "kura": { "command": "kura", "args": ["mcp"] }
}
```

Agenvoy 端沒有 HTTP client、沒有 endpoint 檔、沒有健康檢查 goroutine，也沒有金鑰同步。Agenvoy 自己的更新腳本（`public/scripts/update.sh`）也不再處理 `kura` —— 請用同一支安裝腳本更新。

### 工具

KuraDB 自己的 MCP 伺服器決定要暴露什麼，這些工具並非由 Agenvoy 定義：

| 工具 | 說明 |
|---|---|
| `mcp__kura__list_rag` | 列出可用的 KuraDB 資料庫（例如 `notes`、`inbox`、`code`） |
| `mcp__kura__search_rag` | 以關鍵字搜尋資料庫（`mode` 只接受 `keyword`；`limit` 為 1-100，預設 10），結果依來源檔案分組 |

由於它們經由 MCP client 傳入，伺服器未註冊或連線失敗時會完全從註冊表消失 —— LLM 不會看到一個叫不動的殘樁。

## 網路搜尋 guide 與 RAG 工具

規則由 `reasoning_guide(topics=[web_search])` 承載即時網路那半：非閒聊的資訊查詢（人物、組織、事實、時事、價格）一律走 `search_web`，值得引用的結果用 `fetch_page` 讀取，即時數字只來自工具輸出，每項說法都要標出來源頁面與工具輸出中出現過的 URL。該 topic 在 v1.2.1 之前名為 `rag_web`，v1.2.1 移除了規則中的 RAG 配對那半：guide 不再要求模型在網路搜尋的同時查詢 RAG 資料集。工具列表中的 KuraDB 工具成為一般工具，當問題可能落在操作者整理的資料集（內部規範、慨例、內部文件）時模型可自行呼叫，但 guide 不再強制。

## 檔案與路徑

| 路徑 | 用途 |
|---|---|
| `PATH` 上的 `kura` | KuraDB 執行檔，由 `kuradb.sh` 安裝 |
| `~/.config/agenvoy/mcp.json` | 寫入 `kura` server 設定之處 |
| `~/.config/kuradb/` | KuraDB 自己的設定 / 資料目錄，完全由 KuraDB 管理 |