How to Install, Manage, and Query On-Device Documents with QMD Search

# 1. Create global directory and configure npm prefix
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# 2. Install QMD globally as user
npm install -g @tobilu/qmd

# 3. Add to user PATH in ~/.bashrc if not already present
grep -q '~/.npm-global/bin' ~/.bashrc || echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"

# 4. Download local GGUF models (embedding and re-ranking)
qmd pull --progress

# Register project documentation and AI agent skill directories
qmd collection add /home/user/workspace/my-project/docs --name myproj-docs
qmd collection add /home/user/workspace/my-project/.agents --name myproj-agents

# Add human context summaries to guide semantic search routing
qmd context add qmd://myproj-docs "Technical documentation, API specs, and architecture design notes"
qmd context add qmd://myproj-agents "AI agent constitution, brain memory files, and executable skills"

# Generate initial vector embeddings
qmd embed

# 1. Scan collections for new, modified, or deleted Markdown files (~1-2 seconds)
qmd update

# 2. Embed vector representations strictly for new or modified text chunks
qmd embed

# 3. (Optional) Purge stale records of deleted files and reclaim database space
qmd cleanup

#!/usr/bin/env bash
# ==============================================================================
# QMD Hourly Incremental Sync Script (WSL2 / Linux)
# Protocol: Deep State of Mind (DSOM) v0.2
# ==============================================================================

set -euo pipefail

export PATH="$HOME/.npm-global/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
LOG_FILE="$HOME/.local/var/log/qmd-sync.log"

mkdir -p "$HOME/.local/var/log"
echo "[$(date '+%Y-%m-%d %H:%M:%S')] === Starting QMD incremental update ===" >> "$LOG_FILE"

if command -v qmd >/dev/null 2>&1; then
    qmd update >> "$LOG_FILE" 2>&1 || echo "[$(date '+%Y-%m-%d %H:%M:%S')] Warning: qmd update exited with code $?" >> "$LOG_FILE"
    qmd embed >> "$LOG_FILE" 2>&1 || echo "[$(date '+%Y-%m-%d %H:%M:%S')] Warning: qmd embed exited with code $?" >> "$LOG_FILE"
else
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] ERROR: qmd binary not found in PATH" >> "$LOG_FILE"
    exit 1
fi

echo "[$(date '+%Y-%m-%d %H:%M:%S')] === QMD incremental update completed ===" >> "$LOG_FILE"

chmod +x ~/.local/bin/qmd-sync-hourly.sh
(crontab -l 2>/dev/null | grep -v "qmd-sync-hourly.sh" ; echo "0 * * * * /home/$USER/.local/bin/qmd-sync-hourly.sh") | crontab -

# Executed via FastMCP server in tools/mcp/server.py
qmd_search(query="gitea podman setup", collection="myproj-docs", mode="query", limit=5)

# Resolve executable location or use default user-global path
QMD_PATH="$(command -v qmd || echo "$HOME/.npm-global/bin/qmd")"

{
  "mcpServers": {
    "qmd": {
      "command": "/home/user/.npm-global/bin/qmd",
      "args": ["mcp"]
    }
  }
}

chmod 600 ~/.gemini/config/mcp_config.json

# Scoped Hybrid Query (Recommended Default)
qmd query "architecture design" -c myproj-docs -n 2

# Scoped BM25 Lexical Keyword Search
qmd search "architecture" -c myproj-docs --json -n 2

# Scoped Semantic Vector Search
qmd vsearch "cognitive state preservation" -c myproj-docs -n 2

# Check index health and status
qmd status