qmd: Instructions file for Codex

QMD — Developer & Agent Guide

This document describes the project architecture, build instructions, and known issues for contributors and AI coding agents working on this repository.

---

Project Overview

qmd is a local knowledge-base search engine written in Rust. It provides:

• BM25 full-text search via SQLite FTS5
• Vector semantic search via sqlite-vec (statically linked)
• Hybrid search with RRF (Reciprocal Rank Fusion) score merging
• LLM query expansion (local GGUF model or remote OpenAI-compatible API)
• MCP server for AI agent integration (JSON-RPC 2.0)

Single binary (~10 MB), no runtime .so dependencies beyond glibc 2.17+.

---

Repository Structure

qmd-standalone/
├── Cargo.toml              # Workspace root
├── qmd/                    # Core library
│   └── src/
│       ├── lib.rs          # Public API
│       ├── store.rs        # DB layer — FTS5, vec0, structured_search
│       ├── search.rs       # Query validation, RRF, snippet extraction
│       ├── embed.rs        # Embedding engine (llama.cpp GGUF)
│       ├── generate.rs     # Generation engine for query expansion
│       ├── rerank.rs       # Cross-encoder reranker
│       ├── collections.rs  # Collection management
│       ├── chunker.rs      # Smart chunking (900-token target, 15% overlap)
│       ├── ingest.rs       # File ingestion pipeline
│       └── ...
├── qmd-cli/                # CLI binary + MCP server
│   └── src/
│       ├── main.rs         # Commands: search, vsearch, query, embed, mcp, …
│       └── mcp.rs          # MCP JSON-RPC server implementation
├── tests/
│   └── integration_test.sh # Shell-based integration tests
└── scripts/
    └── build.sh            # Build helper

---

Build

Requirements

Component	Version	Notes
Rust	1.83+	rustup update stable
glibc	2.17+	Runtime only (CentOS 7+, Ubuntu 13.04+)

Standard Build

export AWS_LC_SYS_NO_PREFIX=1
export CFLAGS="-fno-builtin-memcmp"
cargo build --release
# binary: target/release/qmd