AutoRAG Agent工作流

Installation

Published as @autorag/librarian (dist bundled with Bun, runtime Node ≥ 24 or Bun):

```bash bun add @autorag/librarian # library bun install -g @autorag/librarian # autorag CLI

Quick Start

import { AutoRAGAgent } from "@autorag/librarian";

const agent = new AutoRAGAgent({
  searchPaths: ["/path/to/documents"],
});

const response = await agent.searchDocuments("summarize the compliance requirements");
console.log(response.answer);
for (const result of response.results) {
  console.log(`[${result.number}] ${result.title} — ${result.summary}`);
}

// Mark which results were useful — AutoRAG remembers for next time
agent.recordFeedbackByNumbers(response.sessionId, [1, 3], [2]);

searchDocuments() runs the Pi agent loop — it searches, reads, consults memory, curates, and finalizes through the emit_autorag_results structured tool — then returns a typed SearchDocumentsResponse. The caller consumes the structured payload directly; no assistant text parsing.

Configuration and state

The default home state is kept outside the workspace:

~/.autorag/
├── config.json
├── memory.json
└── logs/
    └── runs.jsonl

config.json selects sources, the workspace, memory path, retrieval settings, and the agent model. Provider and model IDs must refer to a model available in the user's authenticated runtime:

{
  "searchPaths": ["/path/to/documents"],
  "workspacePath": "/path/to/workspace",
  "memoryPath": "/Users/you/.autorag/memory.json",
  "model": { "provider": "provider-name", "id": "reasoning-model" }
}

autorag init leaves model unset when no model flags are supplied. At search time AutoRAG resolves an authenticated local provider when possible; otherwise configure the model explicitly.

For fast interactive search, prefer a model with reliable tool calling, high output TPS, and low first-token latency. A query can require several short model turns while AutoRAG alternates between retrieval tools and direct source reading, so model throughput has a visible effect on end-to-end response time. It does not accelerate BM25, MinSync, Jikji, filesystem access, or indexing itself. Larger reasoning models remain useful for difficult synthesis, conflicting evidence, and specialized domain judgment, but they are not a requirement for ordinary retrieval.

Config path precedence is --config > AUTORAG_CONFIG > ~/.autorag/config.json. When the home config is absent and <cwd>/autorag.config.json exists, AutoRAG copies the legacy file to ~/.autorag/config.json without deleting or modifying the legacy file. The legacy cwd file is a migration source, not the default location.

memory.json stores retrieval memory and logs/runs.jsonl records run events. Model authentication remains with the user's configured provider or authenticated local runtime. Corpus indexes remain workspace-local: refresh keeps parsed mirrors and BM25/MinSync indexes under <workspace>/.autorag.

autorag refresh and autorag index reset|rebuild accept --method <csv> (e.g. --method bm25,minsync,parsed) to scope which indexing methods run or which index directories are removed. When omitted, all methods run. autorag init accepts --embedder-* flags to configure the MinSync embedder endpoint in the config file.

autorag health checks model/provider auth before a search — it resolves the model, verifies credential presence, and optionally probes one completion call. Use it to diagnose model, provider, auth, or timeout failures. autorag status remains the model-free index-health command (corpus freshness and BM25/MinSync readiness). When autorag search fails for a model/provider reason, the error output includes a hint pointing to autorag health.

autorag ui opens a loopback-only page (127.0.0.1) to connect local folders and datasource skills without editing JSON. It writes the same trusted datasources / datasourceAccess fields as a hand-edited config, stores env-var names rather than secrets, and refuses non-loopback binds. Use --no-open to print the URL without launching a browser.

For a deliberately deployed UI, opt in explicitly in config.json. Keep the session token in the environment, set the public URL used by the browser, and allow only the frontend origins that should make credentialed API requests:

{
  "ui": {
    "host": "0.0.0.0",
    "port": 8787,
    "allowRemote": true,
    "publicOrigin": "https://autorag.example.com",
    "corsOrigins": ["https://autorag.example.com"],
    "tokenEnv": "AUTORAG_UI_TOKEN"
  }
}

Start it with AUTORAG_UI_TOKEN set to a random value of at least 16 characters. Local use remains the safe default: omit ui (or leave allowRemote false) and AutoRAG binds to loopback, including a working localhost URL on systems that resolve it to IPv6.

Configure your document roots and model once:

node dist/cli/index.js init --search-paths /path/to/documents

Multiple retrieval methods, one interface

Different documents need different search strategies:

AutoRAG supports pluggable retrieval methods. Local lexical BM25, semantic vector, and hybrid retrieval all go through MinSync over one shared CDC chunk lifecycle, wired through the RetrievalMethodRegistry. The librarian invokes retrieval tools, reads the underlying documents directly through bash, and curates one unified result set after ResultMerger score normalization and deduplication. External datasources keep their own archive/index lifecycle.

BM25, vector, and hybrid are enabled by default whenever MinSync is enabled. Disable local indexing with "minSync": false, or disable only lexical search with "bm25": false. MinSync auto-installs a verified release into <workspace>/.autorag/bin on first use (autoInstall: true); set "autoInstall": false only when managing the binary yourself. Configure minSync.embedder via autorag init --embedder-* flags for remote embedding endpoints, and set minSync.maxChunkSize (or --minsync-max-chunk-size) when a local embedder has a smaller context window. AutoRAG never forces TEI or any external embedding service.

See docs/minsync-setup.md for automatic installation, managed binary paths, and the local EmbeddingGemma QA flow.