ai-workspace-services/qmd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3b22f88c9f
qmd/CLAUDE.md
Tobi Lutke bab46dacb2
Refactor: extract store, LLM, and formatter modules with comprehensive tests 
- Extract store.ts: database operations, search, document retrieval
  - createStore() factory pattern for clean DB lifecycle management
  - Unified DocumentResult type with optional body loading
  - Snippet extraction with diff-style headers (@@ -line,count @@)

- Extract llm.ts: LLM abstraction layer with Ollama implementation
  - Clean interface for embed, generate, rerank operations
  - High-level rerankerLogprobsCheck with logprob-based scoring
  - Query expansion support

- Extract formatter.ts: output formatting utilities
  - Support for CLI, JSON, CSV, MD, XML formats
  - MCP-specific CSV formatting

- Extract mcp.ts: MCP server using createStore() pattern
  - Single DB connection for server lifetime (fixes closed DB errors)
  - URL-decode resource paths for proper space/special char handling

- Add comprehensive test suites (215 tests total)
  - store.test.ts: 96 tests covering all store operations
  - llm.test.ts: 60 tests for LLM abstraction
  - mcp.test.ts: 59 tests for MCP endpoints and resources
  - All tests use mocked Ollama (errors on unmocked calls)

- Add bun run inspector script for MCP debugging

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-09 16:33:32 -05:00

2.0 KiB
Raw Blame History

QMD - Quick Markdown Search

Use Bun instead of Node.js (bun not node, bun install not npm install).

Commands

qmd add .              # Index markdown files in current directory
qmd status             # Show index status and collections
qmd update-all         # Re-index all collections
qmd embed              # Generate vector embeddings (requires Ollama)
qmd search <query>     # BM25 full-text search
qmd vsearch <query>    # Vector similarity search
qmd query <query>      # Hybrid search with reranking (best quality)
qmd get <file>         # Get document content (fuzzy matches if not found)
qmd multi-get <pattern> # Get multiple docs by glob or comma-separated list

Options

# Search & retrieval
-c, --collection <name>  # Restrict search to a collection (matches pwd suffix)
-n <num>                 # Number of results
--all                    # Return all matches
--min-score <num>        # Minimum score threshold
--full                   # Show full document content

# Multi-get specific
-l <num>                 # Maximum lines per file
--max-bytes <num>        # Skip files larger than this (default 10KB)

# Output formats (search and multi-get)
--json, --csv, --md, --xml, --files

Development

bun qmd.ts <command>   # Run from source
bun link               # Install globally as 'qmd'

Architecture

  • SQLite FTS5 for full-text search (BM25)
  • sqlite-vec for vector similarity search
  • Ollama for embeddings (embeddinggemma) and reranking (qwen3-reranker)
  • Reciprocal Rank Fusion (RRF) for combining results

Important: Do NOT run automatically

  • Never run qmd add, qmd add-context, qmd embed, or qmd update-all automatically
  • Never modify the SQLite database directly
  • Write out example commands for the user to run manually
  • Index is stored at ~/.cache/qmd/index.sqlite

Do NOT compile

  • Never run bun build --compile - it overwrites the shell wrapper and breaks sqlite-vec
  • The qmd file is a shell script that runs bun qmd.ts - do not replace it