inegmdev/qrag

1. What this repo is

- qrag is a local-first indexing and retrieval system for teams: one person builds semantic databases once, then everyone else downloads and queries them from AI agents.

- The core boundary is between database preparation and database consumption.

2. Primary runtime and packaging

- The main implementation is a Python package under src/qrag.

- User entry points are exposed through the CLI (src/qrag/cli.py), with supporting config, storage, parsing, embedding, and integration modules.

- Packaging is handled with standard Python tooling (pyproject.toml, setup.py, uv.lock), and there is also an npm/ package present for JavaScript-side distribution/integration.

3. Build/indexing pipeline

- The build flow takes local input directories (qrag build -i ... -o version) and turns them into versioned indexes.

- Source code goes through doc_parser.py, chunker.py, and likely tree-sitter-based symbol extraction before being written into a code-oriented database.

- Documentation files are parsed into section/chunk units and stored separately so code and docs can be searched independently.

4. Embeddings and semantic search

- embedder.py is the semantic layer: it generates embeddings locally rather than calling an external service.

- The README indicates the bundled model is all-MiniLM-L6-v2, with optional GPU acceleration for larger installs.

- Search is therefore a hybrid of symbolic structure plus vector similarity.

5. Storage model

- Each published version is stored locally under ~/.qrag/<version>/.

- The two main artifacts are code.db and docs.db, both SQLite databases.

- The active version set is separate from storage; users can keep multiple versions installed and search across all of them simultaneously.

6. Query path

- The CLI supports search, search code, search docs, and search symbol.

- database.py is the retrieval boundary: it likely merges results from active databases, deduplicates them, and returns ranked matches.

- Symbol lookup is exact/structural, while code/docs search is semantic.

7. Distribution and team sharing

- github_distribution.py handles the “hub” workflow: listing versions, downloading them, pushing them, and deleting local copies.

- The repository is configured through QRAG_GITHUB_URL, and GitHub auth is required via gh or GITHUB_TOKEN.

- This makes the architecture explicitly publisher/consumer rather than centralized SaaS: the team hosts databases in a GitHub repo and clients fetch them.

8. AI agent integration

- mcp_server.py exposes qrag as tools to external AI clients.

- The README mentions Claude and Gemini CLI support via qrag ai setup, which installs or configures an MCP-style tool bridge.

- The integration boundary is local: the agent calls qrag-installed tools on the user machine, not a remote API.

9. User-facing interfaces

- The main user interface is the CLI, but there is also a tui.py module for terminal-based interaction.

- status and info provide operational visibility into which versions are active and whether the databases exist locally.

- This is a developer-tooling style application, not a web service.

10. Repository organization for workflows

- docs/ contains the product and architecture docs, including architecture, backlog, handoff, quickstart, and progress tracking.

- issues/ contains issue-sized work items that map onto roadmap features like incremental updates, live folder watching, GPU embeddings, and distribution.

- tests/ covers the main subsystems: chunking, database behavior, integration, and TUI.

11. Build and release pipeline

- GitHub Actions in .github/workflows/ci.yml and publish.yml handle validation and release publication.

- The repo is designed to be installed either for end users or for builders, with separate dependency profiles for CPU vs GPU-heavy builds.

- scripts/download_model.py and tools/afk.py are supporting utilities rather than core architecture.

12. Important architectural takeaway

- The system is centered on local immutable-ish versioned indexes plus a GitHub-backed distribution channel.

- All runtime behavior flows from that: build locally, store per version, activate one or more versions, search across them, and expose the result to AI agents through a local MCP integration.