AutoRAG Lite search

Use this skill when AutoRAG Lite is already configured and indexed, and the user wants model-free retrieval, or wants to persist an externally curated report, inspect its evidence, or record feedback. Use autorag-lite-setup when config, indexing, or refresh is missing or broken. Use the autorag skill when a model-backed curated answer is requested.

AutoRAG Lite never mutates sources. Retrieval reads local source documents and authorized datasource content; writes go only to workspace .autorag/ indexes, the memory file, and Jikji .jikji/ caches.

Preflight

Retrieval needs a completed refresh. If autorag lite retrieve returns exit code 2 with an index-not-ready diagnostic, no refresh has completed yet — run autorag lite refresh (or autorag refresh) first, then retry. Confirm freshness with:

autorag lite status --json

status is model-free and path-opaque, and its stale field is read from disk, so it answers "is indexing complete?" even from a fresh process.

A stale corpus is not a failure: retrieve answers from the index it has and reports the staleness it is answering past ("stale": true plus stale-index diagnostics). Pass --refresh to rebuild incrementally before answering, or --strict to keep the old fail-closed behavior and exit 2 instead of answering.

Retrieve

autorag lite retrieve "key findings in the Q3 report" --top-k 5 --json

The JSON envelope is:

{
  "ok": true,
  "query": "key findings in the Q3 report",
  "stale": false,
  "results": [
    {
      "number": 1,
      "source": "<opaque source identifier>",
      "method": "minsync",
      "score": 0.83,
      "metadata": {},
      "content": "..."
    }
  ],
  "unsearched": [],
  "diagnostics": []
}

• --top-k N must be a positive integer. Invalid values exit with code 2 and an {"ok": false, "error": "..."} rejection envelope.

• Before any refresh, the envelope is {"ok": false, "query": ..., "diagnostics": [{"code": "index-not-ready", "severity": "error", ...}]} with exit code 2.

• stale: true means the last refresh does not cover the current sources; the results are still returned. Each entry in diagnostics with code stale-index names the opaque source and a reason (for example mtime-and-size-changed) plus action: "refresh". Sources the refresh deliberately skipped (exact duplicates, oversized or unparseable files, and AutoRAG/Jikji product artifacts) are not stale.

• --refresh runs an incremental refresh before answering and reports the corpus current; --strict exits 2 with the index-not-ready envelope when the index is stale, for callers that must not answer from a stale index.

• Each result carries a provenance pair: the source identity and the method that produced it. Source identities are source-native: real file paths for local files, datasource identities for datasource results. Never rewrite, guess, or flatten them.

• unsearched lists the retrieval surfaces that did not run for this query. ok: true with a non-empty unsearched means the answer is partial: for example local MinSync files are skipped while an index sync holds the workspace lock, leaving only datasource hits. Check unsearched.length > 0 before concluding that the returned sources are the whole corpus. Each entry is:

  {
    "surface": "minsync",
    "methods": ["hybrid", "minsync"],
    "reason": "MinSyncQueryError: another sync is in progress (/Users/me/corpus/.autorag/minsync)"
  }

  surface is minsync for local files or the datasource id. reason is the underlying failure verbatim — the CLI's failure kind, exit status, stderr and real paths — so the operator can act on it directly. Report it to the user as given; do not summarize it away.

• diagnostics carry the same transparency: source is the component or method label, reason repeats the underlying error, and codes include retrieval-method-failed and minsync-unavailable. A degraded component produces a diagnostic, not a failed run; check diagnostics before trusting an empty result set.

• --debug adds per-result metadata and the diagnostics list to human output. Skipped-surface warnings print without it, and their reasons carry real filesystem paths.

• Exit codes: 0 on success (results may be empty, and a stale index is a warning rather than a failure), 2 for usage, config, not-ready, or --strict staleness errors, 1 for runtime errors.

Retrieval methods run in parallel and merge: parsed mirrors and MinSync lexical/vector/hybrid methods, plus configured datasource methods. Jikji is a local discovery/indexing preparer, not a retrieval method in the lite registry. --method selection applies to refresh, not retrieve; retrieval always queries every active retrieval method.

Scope and tag narrowing (default-deny)

Datasource access is default-deny from trusted config (datasourceAccess.allowedTags, allowedScopes). Retrieval flags can only narrow that access, never widen it:

• --scope SCOPE narrows datasource retrieval to a requested sub-path; it cannot grant access to anything the config does not already allow.
• --tags tag1,tag2 further narrows already-authorized datasource results by intersecting with configured allowed tags; it never grants new access.

Persisting a curated report

An external agent curates the raw retrieval results, then persists the structured report so evidence and feedback commands work against it:

autorag lite report "key findings in the Q3 report" --input report.json --json
cat report.json | autorag lite report "key findings in the Q3 report" --json

The input is the emit_autorag_results JSON schema: answer, numbered results (with number, title, summary, confidence in [0, 1], optional source), and a mapping whose entries map each result number to its method and source, plus optional evidenceRefs and warnings. Result and mapping numbers must be one-to-one positive integers. Evidence confidence values must be in [0, 1]. Invalid input exits with code 2 and {"ok": false, "error": "..."}.

source values in a report are opaque identifiers carried from retrieval output. Report persistence performs no filesystem reads against them; it stores the identifiers as given. Preserve the exact source-native identities from the retrieve envelope.

On success the JSON envelope is:

{
  "ok": true,
  "sessionId": "<uuid>",
  "query": "key findings in the Q3 report",
  "answer": "...",
  "resultCount": 3
}

Use the returned sessionId for evidence inspection and feedback.

Evidence and feedback

autorag evidence <sessionId> --result 1 --json
autorag feedback <sessionId> --useful 1,3 --not-useful 2 --json

• evidence shows the persisted source, retrieval method, stable evidence ID, excerpt or content, and any chunkIndex, lineNumber, and retrievalResultId behind a numbered result. Omit --result to inspect the whole session.
• feedback records numbered usefulness so retrieval memory can learn. Numbers refer to the report's result numbers. Supply at least one feedback list.
• Preserve real source mapping and numbered identifiers end to end: retrieve output feeds the report, the report's session feeds evidence and feedback.

Rules

• Refresh before retrieval; refresh again when roots change.
• Use only configured and approved search paths and datasources.
• Never move, rename, edit, or delete source documents.
• Never expose provider credentials or authentication payloads.
• Treat report source values as opaque: persist them verbatim, never read the filesystem through them.
• Surface diagnostics and unsearched reasons to the user as written; they carry the real error text needed to fix the failure.
• Prefer --json whenever another agent consumes the output.