qi

qi - query engine cli for ai agents and humans

qi is an ultra-fast knowledge search CLI for your files on your local machine. No dependencies, no runtime, just a single executable that indexes code, docs, notes, papers, logs, and other text into SQLite, then gives you BM25 search, optional vector search, and grounded LLM Q&A with citations. Use it offline with Ollama, LM Studio, llama.cpp, or MLX, or connect OpenAI for cloud models.

Save tokens by delegating some of your AI Agent's work to qi.

Features

• Blazing-fast full-text search — BM25 via SQLite FTS5, no external search engine required
• Flexible vector search — embeddings stored and queried on your machine; works with Ollama, LM Studio, llama.cpp, or OpenAI's SOTA models.
• Hybrid search with RRF fusion — combines BM25 and vector rankings for results that are both precise and semantically aware
• LLM-powered Q&A with citations — ask questions in plain English and get grounded answers pointing back to your actual documents
• Smart chunking — breakpoint scoring prioritizes headings, code fences, and paragraph boundaries so chunks stay meaningful, not arbitrary
• Zero-dependency storage — a single SQLite file holds your entire index; content-addressable blobs (SHA-256) eliminate duplicates automatically
• Works offline, always — vector search and Q&A are optional enhancements; BM25 search works out of the box with no providers configured

Install

brew tap itsmostafa/qi
brew install qi

Or via go install:

go install github.com/itsmostafa/qi@latest

Claude Code Plugin

qi is available as a Claude Code plugin. Add the marketplace and install with:

# Add the marketplace
/plugin marketplace add itsmostafa/qi

# Install the plugin
/plugin install qi

Quickstart

# Initialize config and database
qi init

# Index current directory
qi index

# Or index a specific path
qi index ~/notes

# Save a directory as a named collection
qi index ~/notes --name notes

# Re-index it later by name
qi index notes

# Search
qi search "my query"

# Search a specific collection
qi search "my query" -c notes

# Hybrid search (BM25 + vector, requires embedding provider)
qi query "my query" --mode hybrid

# Hybrid search a specific collection
qi query "my query" --mode hybrid -c notes

# Ask a question (requires generation provider)
qi ask "how does X work?"

# Ask a question to a specific collection
qi ask "how does X work?" -c notes

# List all named collections
qi list

# Delete a named collection and all its indexed data
qi delete notes

# Health check
qi doctor

Commands

Search Modes

qi query supports three modes via --mode:

• lexical: BM25 full-text search only
• hybrid (default): BM25 + vector search fused with Reciprocal Rank Fusion (RRF)
• deep: hybrid + optional reranking

Use --explain to see scoring breakdown:

qi query "chunking algorithm" --mode hybrid --explain

Documentation

Full documentation is in the docs/ directory:

• docs/architecture.md — system architecture, data flows, and design decisions
• docs/configuration.md — all config options with explanations
• docs/config.example.yaml — fully annotated example config
• docs/named-collections.md — named collections guide

Configuration

The config lives at ~/.config/qi/config.yaml. See docs/configuration.md for all options or docs/config.example.yaml for a fully annotated example.

database_path: ~/.local/share/qi/qi.db

collections:
  - name: notes
    path: ~/notes
    extensions: [.md, .txt]

providers:
  # Local (Ollama / llama.cpp)
  embedding:
    name: ollama
    base_url: http://localhost:11434
    model: nomic-embed-text
    dimension: 768

  generation:
    name: ollama
    base_url: http://localhost:11434
    model: llama3.2

  # Or: OpenAI cloud (set OPENAI_API_KEY in your environment)
  # embedding:
  #   name: openai
  #   model: text-embedding-3-small
  #   dimension: 1536
  #   batch_size: 32
  # generation:
  #   name: openai
  #   model: gpt-5.4-nano

Document IDs

Each document gets a short ID from the first 6 hex characters of its SHA-256 content hash:

qi get abc123

License

This project is licensed under the MIT License - see the LICENSE file for details.