qmd(Query Markup Documents)는 마크다운 노트, 회의 기록, 기술 문서, 지식 베이스를 로컬에서 검색하는 온디바이스 CLI 도구다. BM25 전문 검색, 벡터 시맨틱 검색, LLM 리랭킹 세 가지를 결합하며 모두 node-llama-cpp와 GGUF 모델로 로컬 실행된다. 에이전트 워크플로에 맞는 JSON·파일 경로 출력 포맷과 MCP 서버를 내장하고 있어, AI 에이전트가 개인 지식 베이스를 도구로 사용하는 시나리오에 적합하다.

왜 qmd인가

기존 전문 검색(BM25)은 정확한 키워드에는 강하지만 의미 검색에 약하고, 순수 벡터 검색은 시맨틱 유사도는 잡지만 정확한 용어 매칭을 놓친다. qmd는 두 방식을 RRF(Reciprocal Rank Fusion)로 결합하고, Qwen3 리랭커로 최종 정렬해 쿼리 품질을 극대화한다.

클라우드 서비스와 달리 모든 데이터가 로컬에 머문다. 사내 문서, 개인 노트, 비공개 코드베이스를 외부로 보내지 않고 검색할 수 있다.

하이브리드 검색 파이프라인

User Query
    │
    ├── LLM Query Expansion (1.7B fine-tuned model)
    │       └── 원본 쿼리(×2 가중) + 확장 쿼리 2개 생성
    │
    ├── 각 쿼리에 대해 병렬 실행
    │   ├── BM25 (FTS5)       ── 전문 검색
    │   └── Vector Search     ── 시맨틱 검색
    │
    ├── RRF Fusion
    │   └── 상위 30개 후보 선별
    │
    ├── LLM Re-ranking (Qwen3-Reranker 0.6B)
    │
    └── Position-Aware Blending
        ├── 1~3위: RRF 75% + 리랭커 25%
        ├── 4~10위: RRF 60% + 리랭커 40%
        └── 11위+: RRF 40% + 리랭커 60%

주요 기능

세 가지 검색 모드

컬렉션 관리

디렉터리 단위로 컬렉션을 만들고 컨텍스트 설명을 붙인다. LLM이 문서를 선택할 때 컨텍스트를 활용해 더 나은 판단을 내린다.

qmd collection add ~/notes --name notes
qmd collection add ~/work/docs --name docs

qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://docs "Work documentation"

qmd embed  # 벡터 임베딩 생성

AI 에이전트 연동

에이전트 워크플로를 위한 구조화 출력 포맷을 지원한다.

# LLM에 전달할 JSON 결과
qmd query "authentication flow" --json -n 10

# 파일 경로만 출력 (최소 점수 필터 포함)
qmd search "API" --all --files --min-score 0.3

# 전체 문서 내용 가져오기
qmd get "docs/api-reference.md" --full

MCP 서버

Claude Desktop 또는 Claude Code에서 바로 연결 가능한 MCP 서버를 내장한다.

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

Claude Code 플러그인으로도 설치할 수 있다.

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

HTTP 데몬 모드를 지원해 여러 클라이언트가 하나의 서버를 공유하고 모델 로딩 오버헤드를 줄일 수 있다.

설치 및 요구사항

npm install -g @tobilu/qmd
# 또는
bun install -g @tobilu/qmd

시스템 요구사항

• Node.js ≥ 22 또는 Bun ≥ 1.0
• macOS: brew install sqlite (FTS5 확장 지원)
• 첫 실행 시 GGUF 모델 자동 다운로드 (~2GB)

한국어·일본어·중국어 등 CJK 문서가 많다면 QMD_EMBED_MODEL 환경 변수로 Qwen3-Embedding-0.6B 모델로 교체할 수 있다.

경쟁 도구와 비교

누구에게 유용한가

• 개발자·연구자: 방대한 기술 문서, 논문, 노트를 자연어로 검색
• AI 에이전트 빌더: 에이전트가 개인 지식 베이스를 MCP 도구로 쿼리하는 파이프라인 구성
• 프라이버시 중시 팀: 사내 문서를 외부 서비스에 보내지 않고 로컬에서 RAG 구현
• Claude Code 사용자: .claude/ 폴더 지식 관리와 플러그인 연동

라이선스

MIT

관련 문서

• rag — RAG 개념 전체 설명
• mcp — MCP 프로토콜 개요
• context-mode — AI 코딩 에이전트 컨텍스트 창 절약 MCP 서버
• llm-wikid — AI가 유지하는 Obsidian 지식 베이스

참고 자료

• tobi/qmd — GitHub 공식 저장소