Open-source retrieval CLI tool for AI agents

Give your agent a fast way to search a local knowledge base.

Build a knowledge base from local documents. Retrieve with keywords, meaning, or both, and return structured evidence your agent can read and call directly.


                curl -sSL
                https://github.com/KuaishouGameMind/arag-cli/releases/latest/download/install.sh |
                bash

See a real run Read the docs

REAL CLI RUN · BM25-ONLY

Watch the retrieval loop complete.

These outputs come from the released macOS arm64 binary against the repository's own Rust and Python fixtures. No embedding API was configured.

~/knowledge/game-guides LOCAL

$ arag-cli build-index --input-dir ./docs --no-embedding

⚠ Skipping embeddings (BM25-only mode)

✅ Index build complete
├─ Chunks:        2
├─ Sentences:     6
├─ Mode:          BM25-only (no embeddings)
├─ Native read:   2 files
├─ Skipped files: 0
└─ Time:          4.2s

$ arag-cli keyword-search rust safety performance -k 3 --no-cache

{
  "tool": "keyword_search",
  "results": [{
    "chunk_id": "1",
    "matched_keywords": ["rust", "safety", "performance"],
    "score": 2.6269903156735817,
    "snippet": "[Rust Programming Language] | Rust is a systems
      programming language focused on safety and performance"
  }],
  "meta": {
    "search_time_ms": 2,
    "retrieved_tokens": 40,
    "cache_hit": false
  }
}

$ arag-cli read-chunk 1

{
  "tool": "read_chunk",
  "results": [{
    "chunk_id": "1",
    "metadata": { "source": "rust.md" },
    "text": "[Rust Programming Language]\nRust is a systems
      programming language focused on safety and performance.\nIt provides
      memory safety without garbage collection.",
    "tokens": 39
  }],
  "meta": { "read_time_ms": 0, "cache_hit": false }
}

$ arag-cli inspect-index

{
  "tool": "inspect_index",
  "index": {
    "exists": true,
    "format": "rust_native",
    "total_sentences": 6,
    "total_chunks": 2,
    "embedding_dim": 0,
    "sample_chunk_ids": ["0", "1"],
    "has_embeddings": false
  }
}

no API key local index structured JSON

END-TO-END PROCESS ~10ms local process time for search

INTERNAL SEARCH 2ms reported by Arag CLI

CONTEXT RETURNED 40 retrieved tokens

Local smoke test on 2 fixture chunks; this verifies the workflow, not production-scale throughput.

01 / QUICKSTART

Build and search your first knowledge base in three commands.

Start with exact keyword retrieval and no external services. Add embeddings only when your workflow needs semantic or hybrid search.

01

Install the binary

Use the latest release for your platform.
curl .../install.sh | bash
02

Build a local knowledge base

Markdown, text and CSV are read natively.
arag-cli build-index --input-dir ./docs --no-embedding
03

Let the agent search the knowledge base

Get ranked chunks, snippets and metadata as JSON.
arag-cli keyword-search "query" -k 5

02 / WORKFLOW

A retrieval layer, not another chat interface.

INDEX

Bring the files you already have.

Read Markdown, text and CSV directly. Convert PDF, Office, HTML, images and audio through MarkItDown.

STRUCTURE

Keep meaningful units intact.

Heading chains travel with each chunk. Tables and code blocks stay atomic instead of breaking mid-structure.

RETRIEVE

Choose the right retrieval cost.

Use local BM25 for exact signals, embeddings for meaning, or RRF hybrid fusion for both.

ACT

Return an explicit next step.

Stable chunk IDs, source metadata and JSON output let an agent inspect evidence before it answers.

03 / RETRIEVAL

One tool. Three ways to find context.

Start local and deterministic. Upgrade the retrieval path without changing the interface your agent calls.

01 BM25

Fast exact-term retrieval

Multi-keyword scoring and snippets with no model, network or API key.

keyword-search LOCAL

02 VECTOR

Semantic retrieval by meaning

Connect an OpenAI-compatible embedding endpoint when exact words are not enough.

semantic-search OPTIONAL API

03 RRF

Hybrid recall with fused ranking

Combine lexical and semantic rankings, then apply adaptive personalized scoring.

search FUSED

160ms PROJECT-REPORTED KEYWORD SEARCH

5.1MB PROJECT-REPORTED BINARY SIZE

110MB PROJECT-REPORTED MEMORY

Published project baseline versus the original Python implementation. See the repository for benchmark details.

04 / HTTP API

One retrieval service. Every agent can share it.

Run Arag CLI once in your cloud or private network. Local agents and server agents call the same indexed knowledge through a typed FastAPI service instead of maintaining separate copies on every machine.

REQUEST PATH · HTTP / JSON

Local Agent A macOS

Local Agent B Windows

Server Agent Linux

POST / GET

ARAG API :8080

Shared retrieval gateway

FastAPI async subprocess arag-cli

code data text request_id

persistent volume

Shared index ~/.arag one source of truth

01 / DATA

One mounted data directory

Agents query the same index, cache, history, notes and pins through the service.

02 / CONTRACT

Validated request and response

Pydantic models validate input. Every endpoint returns code, data, text, message and request_id.

03 / LOGS

Request-level records

JSONL logs record request IDs, endpoint latency and results. Timeouts and CLI errors map to 408 and 503.

DEPLOY THE SERVICE

Start on :8080

docker build -f api/Dockerfile -t arag-api .
docker run --rm -p 8080:8080 \
  -v /srv/arag:/root/.arag \
  -e ARAG_INDEX_DIR=/root/.arag/index \
  arag-api

Run from the repository root and mount a prebuilt Arag data directory.

REST SURFACE API docs

RETRIEVE


                  POST
                  /arag/keyword-search


                  POST
                  /arag/semantic-search


                  POST
                  /arag/search


                  POST
                  /arag/read-chunk

MEMORY


                  POST
                  /arag/note · /arag/pin · /arag/cache


                  GET
                  /arag/history · /arag/profile · /arag/pin-candidates

OPERATE


                  GET
                  /health · /arag/health


                  POST
                  /arag/lint

Deployment boundary: the current service does not add authentication. Run it inside a trusted network or place it behind your own TLS and identity-aware API gateway before exposing it externally.

05 / AGENT INTERFACE

Stable interfaces with explicit parameters.

Arag CLI defines parameter schemas, structured results and diagnostic states for its retrieval commands. Agents can call them through CLI, Agent Skill or REST API.

Machine-readable parameter schemas
Structured results and explicit error codes
CLI, Agent Skill and REST API references

Agent Skill REST API

schema --tool keyword_search function

{
  "tools": [{
    "function": {
      "name": "keyword_search",
      "description": "Search for document
        chunks using keyword-based exact
        text matching (case-insensitive).",
      "parameters": {
        "required": ["keywords"],
        "type": "object"
      }
    },
    "type": "function"
  }]
}

06 / OPERATE

Everything around retrieval is already in the box.

Keep indexes current, isolate projects, inspect usage and diagnose failures without stitching together another toolchain.

JOB COMMANDS WHAT YOUR AGENT GETS

Index lifecycle build-index · update · daemon · inspect-index Incremental refresh and observable index state

Knowledge bases kb create · kb use · kb list · kb delete Isolated context for each project or domain

Retrieval memory cache · history · note · pin · profile Reuse, annotations, hot chunks and blind spots

Diagnostics health · lint · config · schema Runtime status, configuration and interface schemas

Your documents are ready. Give your agent a way in.

Install Arag CLI and search locally first.

Get the latest release GitHub