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
.docxfiles 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
| Tool | Description |
|---|---|
search |
Hybrid vector + keyword search (recommended) |
vector_search |
Semantic similarity search only |
keyword_search |
Exact keyword / phrase match |
get_status |
Index statistics |
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
Metadata
Release files for ai-rag 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ai_rag-0.1.0.tar.gz | 11.3 kB | Without provenance | Details for ai_rag-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_rag-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ai_rag-0.1.0-py3-none-any.whl |
Total release size: 24.7 kB
Release files / ai_rag-0.1.0.tar.gz
| Download URL | ai_rag-0.1.0.tar.gz |
|---|---|
| Size | 11.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2880603ac6191eb278e37f1b95aed9400f2eaea7256d861a93ee12c47cca9faa
|
|
BLAKE2b-256 checksum How to use checksums |
0be2f5c4318496ef14415d64185afca077dd5ae5c7b2811d449241d255089dfc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|
Release files / ai_rag-0.1.0-py3-none-any.whl
| Download URL | ai_rag-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f71fd38670aaf5885be82605b4b1283772a9956559c77ed056270cf7e30c708f
|
|
BLAKE2b-256 checksum How to use checksums |
e1180c89e9c623e7549d58e387c6c81e6d06601ff52bced44c0e4125f06886d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|
Security for ai-rag 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.