ai-rag

A local knowledge base CLI tool with hybrid vector + keyword search and MCP server support.

Automatically indexes .docx files from a watch directory, stores embeddings in ChromaDB, and exposes retrieval as both a CLI and an MCP server for LLM clients like Claude Desktop and Cursor.

Features

• 📄 Auto-indexing — watches a directory and indexes .docx files automatically
• 🔍 Hybrid search — combines semantic vector search with exact keyword matching (RRF fusion)
• 🤖 MCP server — expose your knowledge base as tools callable by Claude / Cursor / any MCP client
• ⚙️ Configurable — chunk size, overlap, embedding model, watch directory via YAML config

Installation

pip install ai-rag

Requirements: Python 3.9+, macOS / Linux
First run will download the embedding model (~120 MB).

Quick Start

# 1. Index documents in ~/Downloads
ai-rag sync

# 2. Search
ai-rag search "your query"

# 3. Check status
ai-rag status

Search Modes

# Hybrid (default, recommended)
ai-rag search "direct broadcast architecture" --mode hybrid

# Semantic vector search
ai-rag search "broadcast architecture" --mode vector

# Exact keyword match
ai-rag search "SPU" --mode keyword

# Control number of results
ai-rag search "query" -n 10

File Watcher

# Foreground — auto-re-index when files change
ai-rag watch

# Background daemon
ai-rag watch --daemon
ai-rag stop

MCP Server (for Claude Desktop / Cursor)

Start the MCP server (stdio transport):

ai-rag-mcp

Claude Desktop config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ai-rag": {
      "command": "ai-rag-mcp"
    }
  }
}

Cursor config (~/.cursor/mcp.json)

{
  "mcpServers": {
    "ai-rag": {
      "command": "ai-rag-mcp"
    }
  }
}

After restarting the client, you can ask: "Search my knowledge base for broadcast backend architecture" and the LLM will call the retrieval tools automatically.

Available MCP Tools

Configuration

Default config file: ~/.config/ai-rag/config.yaml

watch_dir: ~/Downloads        # directory to watch and index
file_patterns:
  - "*.docx"
chunk_size: 500               # characters per chunk
chunk_overlap: 100            # overlap between chunks
model_name: paraphrase-multilingual-MiniLM-L12-v2

Architecture

docx files
    │
    ▼
DocxParser → TextChunker (500 chars, 100 overlap)
    │
    ▼
sentence-transformers (paraphrase-multilingual-MiniLM-L12-v2)
    │
    ▼
ChromaDB (local persistent vector store)
    │
    ├── vector_search  (cosine similarity)
    ├── keyword_search (substring match via where_document)
    └── hybrid_search  (RRF fusion, vector×0.7 + keyword×0.3)

License

MIT