Context Vault

QMD - Query Markup Documents (온디바이스 검색 엔진)

4 min read

QMD - Query Markup Documents

마크다운 노트, 회의록, 문서를 위한 온디바이스 검색 엔진. BM25 + 벡터 검색 + LLM 리랭킹을 로컬에서 실행.

핵심 컨셉

  • 온디바이스 — 모든 것이 로컬에서 실행 (node-llama-cpp + GGUF 모델)
  • 하이브리드 검색 — BM25 전체 텍스트 + 벡터 시맨틱 + LLM 리랭킹
  • 에이전트 친화적 — JSON/파일 출력 포맷, MCP 서버 지원

빠른 시작

# 설치
npm install -g @tobilu/qmd
 
# 컬렉션 추가
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
 
# 컨텍스트 추가 (검색 품질 향상)
qmd context add qmd://notes "Personal notes and ideas"
 
# 임베딩 생성
qmd embed
 
# 검색
qmd search "project timeline"           # 키워드 검색
qmd vsearch "how to deploy"             # 시맨틱 검색
qmd query "quarterly planning process"  # 하이브리드 + 리랭킹 (최고 품질)

검색 모드

명령어설명
searchBM25 전체 텍스트 검색 (빠름)
vsearch벡터 시맨틱 검색
query하이브리드: FTS + Vector + 쿼리 확장 + 리랭킹

MCP 서버

에이전트 통합용 MCP 서버 제공:

노출 도구:

  • query — 검색 (lex/vec/hyde 서브쿼리)
  • get — 문서 조회
  • multi_get — 배치 조회
  • status — 인덱스 상태

Claude Code 설정:

claude plugin marketplace add tobi/qmd
claude plugin install qmd@qmd

또는 ~/.claude/settings.json:

{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

HTTP Transport

장기 실행 서버:

qmd mcp --http              # localhost:8181
qmd mcp --http --daemon     # 백그라운드
qmd mcp stop                # 정지

아키텍처

User Query
    │
    ▼
Query Expansion (LLM) → Original + 2 Variants
    │
    ▼
┌───────────────────────────────────────┐
│  각 쿼리마다:                          │
│  BM25 (FTS5)  +  Vector Search        │
└───────────────────────────────────────┘
    │
    ▼
RRF Fusion (k=60)
- 원본 쿼리 ×2 가중치
- Top-rank bonus: #1 +0.05, #2-3 +0.02
    │
    ▼
Top 30 → LLM Re-ranking (qwen3-reranker)
    │
    ▼
Position-Aware Blend:
- Rank 1-3:  75% RRF / 25% reranker
- Rank 4-10: 60% RRF / 40% reranker
- Rank 11+:  40% RRF / 60% reranker

스마트 청킹

~900 토큰 청크, 15% 오버랩:

브레이크 포인트점수
# Heading100
## Heading90
### Heading80
``` (코드 블록)80
--- / ***60
빈 줄20

코드 펜스 보호: 코드 블록 내부는 분할하지 않음.

GGUF 모델

자동 다운로드 (~/.cache/qmd/models/):

모델용도크기
embeddinggemma-300M-Q8_0벡터 임베딩~300MB
qwen3-reranker-0.6b-q8_0리랭킹~640MB
qmd-query-expansion-1.7B-q4_k_m쿼리 확장~1.1GB

다국어 지원

CJK(중/일/한) 지원을 위해 Qwen3-Embedding 사용:

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
qmd embed -f

SDK 사용

import { createStore } from '@tobilu/qmd'
 
const store = await createStore({
  dbPath: './index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
    },
  },
})
 
const results = await store.search({ query: "authentication flow" })
console.log(results.map(r => `${r.title} (${Math.round(r.score * 100)}%)`))
 
await store.close()

에이전트용 출력 포맷

# JSON 출력
qmd search "authentication" --json -n 10
 
# 파일 목록 (임계값 이상)
qmd query "error handling" --all --files --min-score 0.4
 
# 전체 문서 내용
qmd get "docs/api-reference.md" --full

데이터 저장

  • 위치: ~/.cache/qmd/index.sqlite
  • 스키마: collections, path_contexts, documents, documents_fts, content_vectors, vectors_vec, llm_cache

요구사항

  • Node.js >= 22 또는 Bun >= 1.0.0
  • macOS: Homebrew SQLite (brew install sqlite)

Sources

그래프 뷰