# 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` 斷詞提供關鍵字搜尋（支援中文）
- 透過 embeddings 提供語意搜尋
- 完全在使用者機器上執行 —— 無外部服務

## 整合模型

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` | 搜尋資料庫 —— 關鍵字比對與語意向量相似度並行執行，結果依來源檔案分組 |

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

## RAG + 即時網路的配對

規則由 `reasoning_guide(topics=[rag_web])` 承載（v1.0.26 之前為單一 `topic`）。工具列表中出現 RAG 工具，代表操作者在那裡整理過一批資料，而其內容無法由名稱推知 —— 因此模型會判斷該問題是否可能落在其中（內部規範、慣例、內部文件、操作者自身的領域素材），可能就搜。非閒聊的資訊查詢一律執行即時網路那半（`search_web`）；即時數字只從網路那半取得。兩邊都可能有答案時，於同一次回應中並行發出，不採「先網路、再看要不要 RAG」。未註冊任何 RAG 工具時只跑網路那半 —— 缺少資料集不會讓訓練知識升格為替代品。

## 檔案與路徑

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