--- name: autorag description: Search, summarize, compare, and answer questions from an already configured AutoRAG librarian over local documents and configured datasources. Use when the user asks AutoRAG to search PDFs, wikis, notes, or a knowledge base. Use autorag-setup for install, model, roots, indexing, or datasource changes. license: MIT --- # AutoRAG Librarian Skill Use this skill when AutoRAG is already configured and the user asks to search, summarize, compare, or answer questions from local PDFs, wikis, notes, research papers, knowledge bases, or configured datasources. AutoRAG is the specialized librarian agent. One configured model plans the search, calls MinSync, Jikji, datasource, and filesystem tools, reads sources, judges evidence, and curates the final answer. There is no subagent or separate model role. AutoRAG reads source documents and writes indexes only under the configured workspace `.autorag/` directory and Jikji's per-source `.jikji/` caches. Never move, rename, edit, or delete source files. ## Preflight Confirm a config exists at `--config`, `AUTORAG_CONFIG`, `$AUTORAG_HOME/config.json`, or `~/.autorag/config.json`. Inspect only non-secret `searchPaths` and `model` metadata, then run: ```bash autorag duplicates --json autorag status --json autorag health --json ``` ### Duplicate-file review Use `autorag duplicates` when the user asks to find duplicate files, choose likely latest copies, or reduce corpus/index space. The command and the `scan_duplicate_documents` Agent tool are read-only and never delete or move source files. Exact means dupey's canonical extracted-text hash matches; near/contains families require human review. Exact duplicate exclusion during refresh is enabled by default and can be disabled with `"excludeExactDuplicates": false` in `config.json`. ### Excluding local files from the index `"excludePaths"` in `config.json` lists files or folders (absolute, or relative to `workspacePath`) that refresh keeps out of the parsed mirror and MinSync. A folder entry excludes everything under it. Removing an entry and running `autorag refresh --method minsync` indexes the file again. Excluded sources are recorded as `user-excluded` skips, so they are not reported as stale. Jikji indexes the source folders directly and is not refreshed here, so AutoRAG also drops excluded paths from the `jikji_find` answer pack and the baseline prefetch at retrieval time; the on-disk `.jikji_agent_map.md` stays complete, and direct file reads remain available. `status` is model-free and path-opaque. `health` resolves the single model, checks credential presence, and normally probes one live completion. If the model, authentication, configuration, or indexes are unhealthy, use `autorag-setup` rather than guessing private provider details. MinSync and Jikji should normally be healthy. Answering a question never builds or installs them: `autorag refresh` auto-installs both by default and builds their indexes incrementally. If they are missing or stale, run a full `autorag refresh` or return to setup rather than silently degrading to lexical-only search. ## Search Prefer `--json --debug` when another agent will consume the result. `--json` alone omits `sessionId`. `--debug` adds session/diagnostics fields and does not print filesystem paths. ```bash autorag search "what were the key findings in the Q3 report" --top-k 5 --json --debug ``` `--json --debug` includes `answer`, numbered `results` (`number`, `title`, `summary`, optional `source`), and `sessionId`. `--json` without `--debug` is only `answer` plus `results`. Every bracketed `[n]` citation in `answer` resolves to a `results[].number` of the same response; an unmatched citation is removed and reported as a `citation-without-result` diagnostic. To inspect the exact persisted evidence behind numbered results, use: ```bash autorag evidence --result 1 --json ``` The response includes the original source, retrieval method, stable evidence ID, raw excerpt/content, and any available `chunkIndex`, `lineNumber`, `retrievalResultId`, and metadata. Omit `--result` to inspect every result in the session. Prefer this command whenever the caller wants detailed chunk text rather than only the curated summary. - `--scope` narrows datasource retrieval to a requested sub-path (ordinary per-query filtering). - `--json` is required for programmatic consumption. - `--debug` is required for `sessionId` and diagnostics in search output. - `autorag evidence` is the detailed source/chunk inspection path. Do not bypass the librarian with ad hoc raw search when the user requested AutoRAG. The search loop can use Jikji, MinSync lexical/vector/hybrid retrieval, datasource retrieval, and direct source reading as appropriate. If search fails because of model, provider, auth, or timeout problems, diagnose with `autorag health --json`. Every search is two-phase: a fast answer, then verification. With Jev on (the default, OpenRouter), Jev first routes the question: - General knowledge or small talk is answered directly. - A request to view or change AutoRAG's own settings (model, providers, datasources) is handled by the agent itself: it loads the setup skill, edits the active config, verifies it, and reports what changed. The running agent keeps its startup model; changes apply to the next `autorag` launch. - Private-data questions use local search; public current facts use web search. - A multi-part question is split into up to five parallel search queries. - On local search, Jev also picks which registered datasources (Slack, Discord, KakaoTalk, email, ...) to search before the fast answer, from each datasource's description and where similar past questions were answered; their chunks are reranked together with local file evidence. After the fast answer, Jev ends the run if the answer is complete and evidence-backed. So `results` may come straight from the fast answer, with no verification phase. `--debug` diagnostics show the decision: `query-routed` (branch and queries), `datasources-selected` (datasources searched or skipped, with probabilities), `follow-up-skipped` (fast answer final), or `query-route-fallback` (Jev unavailable, single local search). ## Maintenance ```bash autorag setup --format json autorag status --json autorag health --json autorag refresh --json autorag refresh --method minsync,jikji --json autorag watch --once --json autorag watch autorag refresh --force --json autorag index rebuild --yes --json autorag index reset --method parsed --yes --json autorag memory inspect --json autorag tui autorag serve --force autorag p2p policy list --json ``` Prefer a full refresh so parsed mirrors, MinSync, Jikji, configured datasources, and (on Windows) the bundled Everything file-name index stay aligned. `--method` accepts `parsed,minsync,datasources,jikji,everything,all`. BM25 is a MinSync retrieval mode, not a `--method` name. Use `--method` only for deliberate narrowing. Scheduled maintenance should use non-daemon `autorag watch --once`, typically every 1 hour, with the same config used by search and no overlapping runs. `autorag tui` is the shipped beta terminal UI. `autorag serve` / `autorag p2p` are opt-in SimpleX peer sharing (disabled until `p2p.enabled` is true, unless `--force`). Reset and rebuild commands remove only selected workspace `.autorag` indexes. Never target source documents. `memory inspect` is read-only and path-opaque. ## Rules - Use only configured and approved search paths. - Never expose provider credentials or authentication payloads. - Never invent provider identities or model ids. - A Pi-usable subscription is valid; a subscription Pi cannot invoke is not. - Preserve real source mapping. - Prefer `--json --debug` when another agent consumes search output. - Do not invent CLI commands. `autorag --help` is the command list of record, including the shipped `setup`, `gateway`, `models`, `serve`, `p2p`, `tui`, and `lite` commands. `autorag --help` prints that command's own flags, and `autorag --version` prints the installed version. See `docs/embedding-runtime.md` for the local embedding runtime and gateway setup.