qi - query engine cli for ai agents and humans

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

• ⚡ Ultra-fast indexing
• ⚡ Lower tokens + latency
• 🧠 Better reasoning (agents focus on thinking, not retrieval)
• 🔒 Fully local + offline
• 🧩 Works with Ollama, LM Studio, Claude, OpenAI, MLX, etc.

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 https://github.com/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

# Collection names are generated from paths
# ~/notes -> notes

# Re-index it later by generated collection 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 collections
qi list

# Delete a 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 — 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.