marker-inc-korea/autorag/autorag-setup

AutoRAG setup

Use this skill when AutoRAG is unconfigured, the autorag CLI is missing, model resolution fails, indexes are missing or stale, or the user wants to change the document collection or datasources.

For model-free external-agent search, use autorag-lite-setup to configure and register autorag-mcp; do not configure a search model or install a search skill for Lite. This skill's model setup and CLI search apply to the full librarian, not the Lite MCP server.

Safety

• Inspect only non-secret provider/model metadata and credential availability.
• Never print, copy, migrate, compare, or persist credential values. Store only

environment-variable names such as apiKeyEnv.

• Do not scan the whole filesystem or home directory without explicit approval.
• Setup, indexing, and refresh never move, rename, edit, or delete source

documents. The librarian itself may organize files when the user asks it to.

• Do not index system trees, app bundles, caches, credential stores,

node_modules, .git, dist, build, target, .cache, .autorag, or .jikji.

Install the CLI if needed

The CLI is @autorag/librarian (autorag). Runtime is Node.js ≥ 24 or Bun.

command -v autorag >/dev/null || bun install -g @autorag/librarian
autorag --help

If Bun is unavailable, npm install -g @autorag/librarian is acceptable.

Inspect existing configuration

Check --config, AUTORAG_CONFIG, $AUTORAG_HOME/config.json, or ~/.autorag/config.json. Relevant fields are:

• searchPaths, workspacePath, and memoryPath
• model.provider, model.id, model.api, model.baseUrl, model.apiKeyEnv
• bm25, minSync, and jikji
• limits (retrieval, baseline-prefetch, and model-facing candidate caps)
• datasources and ui

Preserve explicit user choices and a working config unless the user asks to replace them or health checks fail.

Configure one search model

AutoRAG is the specialized librarian agent. One configured model plans the search, calls retrieval and filesystem tools, reads sources, judges evidence, and curates the answer in one loop. There are no orchestrator/explorer roles.

Prefer a model with reliable tool calling and structured output, enough context for source excerpts, high output TPS, and low first-token latency. Use a larger reasoning model only when difficult synthesis or domain judgment matters more than latency.

Start from a provider/model the current runtime can actually call. A Pi-usable ChatGPT, Claude, Gemini, or other authenticated subscription is valid; an installed CLI or subscription that Pi cannot invoke is not. For custom OpenAI-compatible endpoints, record the real wire API, base URL, and credential environment-variable name.

Allowed api values:

• openai-completions
• openai-responses
• anthropic-messages
• openai-codex-responses
• azure-openai-responses

If no callable setup can be established, ask the user for the provider, model id, API protocol, base URL when custom, and credential environment-variable name. Do not invent provider identities or model ids.

Propose and approve document roots

Explicit user paths win. Otherwise inspect only these likely document-dense candidates for existence and approximate supported-file counts, then ask for approval before indexing:

Supported parsed formats are md, markdown, txt, text, pdf, docx, pptx, xlsx, xls, hwp, hwpx, and eml. OCR for jpg, jpeg, png, bmp, and tiff is optional (parserOptions.ocr.enabled). Do not present legacy .doc as a supported parsed format.

Keep the first-run set small, usually one to three roots. Present a concrete proposal and require yes, a narrowed keep-list, a custom list, or skip before running refresh.

Initialize

autorag init \
  --search-paths "/path/to/documents,/path/to/notes" \
  --workspace "/path/to/workspace" \
  --model-provider PROVIDER \
  --model-id MODEL

Model resolution runs through the pi runtime. A configured provider/id is resolved against the pi runtime catalog — the built-in providers plus any ~/.pi/agent/models.json, custom, or extension providers — and credentials come from stored pi auth (~/.pi/agent/auth.json, API key or OAuth established with pi /login), then provider environment variables. When no model is configured, AutoRAG uses pi's defaultProvider/defaultModel when that provider has configured credentials; otherwise it falls back to the authenticated local codex runtime. So model flags may be omitted when either pi or the local runtime already supplies the intended model. Inspect what pi can resolve with autorag models list (--available shows only providers with configured credentials); it never prints credential values.

For a custom endpoint, add api, baseUrl, and apiKeyEnv to the single model object in the trusted config:

{
  "searchPaths": ["/path/to/documents"],
  "model": {
    "provider": "openrouter",
    "id": "anthropic/claude-sonnet-5.5",
    "api": "openai-completions",
    "baseUrl": "https://openrouter.ai/api/v1",
    "apiKeyEnv": "OPENROUTER_API_KEY"
  }
}

When provider/id names a pi runtime catalog model, the catalog entry stays the base: baseUrl, api, and any declared reasoning, input, contextWindow, or maxTokens override only those fields, and the catalog's reasoning, thinking, and compat settings are kept. Only an id outside the catalog (private proxy, Ollama, LiteLLM) gets a generic text model with a 128k context window unless those fields are declared.

Use --force only when intentionally replacing an existing config, and target it with an explicit path (--config or AUTORAG_CONFIG); --force refuses to replace the implicit ~/.autorag/config.json. Legacy cwd autorag.config.json is a migration source only and is never deleted by init.

Retrieval defaults

MinSync and Jikji are enabled by default. Leave them enabled unless the user explicitly asks otherwise. Indexing never happens while answering: a question only reads indexes that autorag refresh (or autorag watch) built, so run a refresh after setup and whenever documents change. A never-refreshed workspace still answers, but without MinSync/Jikji evidence.

Refresh (never a query) auto-installs the binaries: MinSync installs a verified GitHub release into <workspace>/.autorag/bin (minSync.autoInstall defaults to true), and Jikji installs jikji-cli through cargo (jikji.autoInstall defaults to true; requires the Rust toolchain). Set "autoInstall": false only when managing the binary yourself. Refresh is incremental: MinSync syncs only changed parsed mirrors, and jikji prepare reuses unchanged documents. Jikji roots prepare one at a time (they share one central SQLite file that rejects concurrent writers). A search root nested inside, or duplicating, another root is skipped for Jikji because the outer root's index already covers it.

Jikji keeps its prepared corpus (search index, parsed text, wiki, routes) in one central store, not inside your documents: <OS data dir>/jikji/index.sqlite plus <OS data dir>/jikji/roots/<id>/ (macOS ~/Library/Application Support, Linux $XDG_DATA_HOME or ~/.local/share, Windows %LOCALAPPDATA%; override with the JIKJI_DATA_DIR environment variable). The only file refresh adds inside an approved document root is the .jikji_agent_map.md guide. Tell the user that before the first refresh, and never delete or edit Jikji's central store by hand; removing it only forces a full Jikji re-prepare on the next refresh. Older Jikji versions wrote a <root>/.jikji directory instead; such a leftover is now unused and safe for the user to delete.

Exact duplicate exclusion is enabled by default. AutoRAG invokes the external dupey CLI before parsed-mirror indexing, keeps the newest filesystem copy for each exact canonical-text hash, and excludes older copies from the mirror. Install dupey during setup when it is missing (command -v dupey || cargo install dupey --locked) and tell the user the feature is available; when installation is impossible, refresh continues without this optimization and the user is told duplicate exclusion is off. Set "excludeExactDuplicates": false to index every copy.

AutoRAG owns no embedding model. MinSync provisions the embedder (Qwen/Qwen3-Embedding-0.6B, 1024 dimensions) in its own cache (~/.cache/minsync/models); there is no local model download and no bundled runtime. One shared embedder serves everything that embeds inside AutoRAG: MinSync indexing/query, memory similar-question search, the chat-crawler sidecars, the GitHub Gist vector index, and the endpoint external CLIs are pointed at. The default needs no embedder flags and no API key. It resolves in order:

1. A configured remote endpoint (minSync.embedder), used for everything; no

daemon is started and no local model is loaded.

1. A running minsync serve daemon (loopback only; MinSync 0.4.12+).

AutoRAG never starts it: run minsync serve --idle-timeout 0 yourself, as a launchd/systemd service (see docs/minsync-setup.md), or press Ctrl+Shift+E in autorag tui. autorag setup only reports whether it is alive.

1. MinSync's in-process engine, through the optional Node-API addon

@nomadamas/minsync-native (same engine and weights, so bit-for-bit identical vectors; not bundled). Without a daemon and without the addon, embedding fails with an error naming the missing package.

Override the embedder only when intentionally using a remote provider:

autorag init \
  --embedder-id "voyageai/voyage-4-lite" \
  --embedder-base-url "https://openrouter.ai/api/v1" \
  --embedder-api-key-env "OPENROUTER_API_KEY" \
  --embedder-dimension 1024 \
  --embedder-batch-size 64

A remote minSync.embedder names an id (openai:<model>, tei:<model>, or any id together with a baseUrl) plus optional apiKeyEnv (the name of the environment variable holding the bearer token), dimension, batchSize, and timeoutMs. OpenAI-protocol endpoints POST {baseUrl}/v1/embeddings; a tei: endpoint POSTs {baseUrl}/embed; openai: with no baseUrl means https://api.openai.com. Only store the environment-variable name, never its value. dimension and batchSize must be positive integers, and dimension must match the endpoint (the local default is 1024).

Jev routing and question decomposition (on by default)

Leave both enabled. They are the recommended setup: they make simple questions fast and multi-part questions thorough.