RAGrep — Local Semantic Recall

Key Features

Recall-First CLI: ragrep "query" is the default workflow and auto-indexes changed files when needed.
Single-File Storage: Indexes, chunks, embeddings, and metadata live in one local SQLite file: .ragrep.db.
Local Embeddings: Uses mxbai-embed-large in process with no remote API keys or external vector database.
Incremental Updates: New, modified, and removed files are detected automatically instead of rebuilding the whole index every run.
Device-Aware Runtime: Supports cpu, cuda, and mps via --device, with --check-gpu to inspect runtime support.

Quick Start

RAGrep requires Python 3.9+. Install it directly from PyPI, then run a query against the current directory.

pip install ragrep

# First recall auto-indexes the project and downloads the embedding model on demand
ragrep "authentication middleware"

Override model storage with RAGREP_MODEL_DIR or --model-dir. GPU usage is optional and depends on your local PyTorch build.

CLI Essentials

# Recall relevant chunks (default command; auto-indexes when files changed)
ragrep "authentication middleware"

# Explicit recall with a higher limit
ragrep recall "authentication middleware" --limit 5

# Build or refresh the index manually
ragrep index .

# Inspect index statistics
ragrep stats
ragrep --stats

# Check GPU/device support
ragrep --check-gpu

Useful flags include --path, --db-path, --model-dir, --device, --json, --no-auto-index, and --force for a full rebuild.

Project Highlights

Current Release: Version 0.2.1 targets Python 3.9 through 3.13.
Storage Model: The local database tracks indexed files, chunk text, embedding vectors, and index metadata in one place.
Backwards Compatibility: Legacy aliases such as RAGSystem and dump(...) still exist, but recall is the primary interface.
Automation Ready: JSON output, deterministic CLI formatting, and GitHub Actions workflows make it suitable for scripts and agent-driven tooling.

Stay in the Loop

Track releases, file issues, and follow the implementation details: