qmd-gemini

Fast markdown search with Gemini embeddings. Fork of qmd optimized for Clawdbot agents.

Key difference: Uses Google Gemini API for embeddings instead of local models. No 1.3GB downloads. Just fast, cloud-based vector search.

Features

• BM25 search (qmd search) — Fast keyword matching
• Vector search (qmd vsearch) — Semantic similarity via Gemini embeddings
• No local models — All embeddings via Gemini API
• SQLite storage — Portable, single-file index

Quick Start

# Clone
git clone https://github.com/mikeOnBreeze/qmd-gemini.git
cd qmd-gemini

# Install dependencies
bun install

# Set your Gemini API key
export GEMINI_API_KEY="your-api-key-here"

# Add a collection (your notes/memory folder)
./qmd collection add ~/path/to/your/notes --name my-notes --mask "**/*.md"

# Generate embeddings
./qmd embed

# Search!
./qmd search "exact keywords"      # BM25
./qmd vsearch "semantic query"     # Vector similarity

Clawdbot Setup

1. Clone the repo

cd ~/openai-demo  # or your preferred location
git clone https://github.com/mikeOnBreeze/qmd-gemini.git
cd qmd-gemini
bun install

2. Get a Gemini API Key

Get one free at Google AI Studio.

Save it somewhere secure:

echo "your-api-key" > ~/KeyApis/GEMINI_API_KEY

3. Add your collections

Point qmd at your memory files:

export GEMINI_API_KEY=$(cat ~/KeyApis/GEMINI_API_KEY)

# Example: Clawdbot memory folder
./qmd collection add ~/openai-demo/clawdbot/memory --name clawdbot-memory --mask "**/*.md"

# Example: Root workspace files
./qmd collection add ~/openai-demo/clawdbot --name clawdbot-root --mask "*.md"

# Add context descriptions (helps with search)
./qmd context add qmd://clawdbot-memory "Daily notes, transcripts, todos, and session logs"
./qmd context add qmd://clawdbot-root "Core agent files: MEMORY.md, USER.md, TOOLS.md"

4. Generate embeddings

./qmd embed

This sends document chunks to Gemini API and stores vectors locally (~5 seconds for 50 docs).

5. Copy the skill to your Clawdbot

cp -r skills/qmd ~/openai-demo/clawdbot/skills/

6. Add to AGENTS.md

Add this to your AGENTS.md memory lookup section:

### 🔍 Memory Lookup Protocol

Before saying "I don't know" or "I don't have context on that":

1. **Current context** — Is it in this conversation? (free, check first)
2. **qmd search** — BM25 keyword search (exact names, dates, terms)
3. **qmd vsearch** — Vector similarity search (semantic/fuzzy queries)
4. **memory_search** — Fallback if qmd misses

**See `skills/qmd/SKILL.md` for setup and usage.** Uses qmd-gemini fork with Gemini API.

7. Set up nightly cron

Add a cron job to re-index and embed new files nightly:

# Via Clawdbot CLI
clawdbot cron add --name "qmd-nightly-embed" \
  --schedule "0 2 * * *" \
  --tz "America/Los_Angeles" \
  --text "🔄 QMD NIGHTLY EMBED

Re-index and embed any new memory files:

\`\`\`bash
cd ~/openai-demo/qmd-gemini
export GEMINI_API_KEY=\$(cat ~/KeyApis/GEMINI_API_KEY)
./qmd update
./qmd embed
./qmd status
\`\`\`

Reply HEARTBEAT_OK when done."

Or add manually via the Clawdbot dashboard.

Commands

# Search
./qmd search "keywords"              # BM25 keyword search
./qmd vsearch "semantic query"       # Vector similarity
./qmd search "query" -n 10           # More results
./qmd search "query" -c my-notes     # Filter by collection

# Documents
./qmd get "path/to/file.md"          # Get full document
./qmd get "#docid"                   # Get by document ID
./qmd get "file.md:50" -l 100        # Get from line 50, max 100 lines

# Maintenance
./qmd status                         # Check index status
./qmd update                         # Re-index collections
./qmd embed                          # Generate/update embeddings
./qmd collection list                # List collections

How It Works

1. Indexing: qmd collection add indexes markdown files into SQLite
2. Embedding: qmd embed chunks documents (~800 tokens), sends to Gemini API, stores vectors
3. BM25 Search: qmd search does fast keyword matching (no API call)
4. Vector Search: qmd vsearch embeds your query via Gemini, finds similar chunks

Vector search requires GEMINI_API_KEY at search time (to embed the query).

Requirements

• Bun runtime
• Gemini API key (free tier works fine)

License

MIT