QMD: 로컬 환경에서 구현하는 강력한 개인용 AI 검색 엔진

QMD 메인 이미지

정보 과잉의 시대, 우리는 수많은 문서, 미팅 요약, 노트를 쏟아냅니다. 하지만 정작 필요한 순간에 그 정보를 찾는 것은 여전히 어렵습니다. 특히 AI 에이전트가 우리의 작업을 도우려 할 때, 방대한 로컬 문서를 정확하게 참조하는 것은 큰 도전 과제입니다.

Shopify의 CEO인 Tobi Lütke(@tobi)가 개발한 QMD는 이 문제를 해결하기 위해 탄생한 미니 CLI 검색 엔진입니다. 최근 v2.0 릴리스와 함께 더욱 강력해진 QMD는 “로컬 우선(Local-first)“과 “에이전트 중심(Agentic)“이라는 두 가지 핵심 가치에 집중합니다.

1. 왜 QMD인가?

단순한 grep이나 기존의 전체 텍스트 검색(FTS)만으로는 충분하지 않습니다. QMD는 현대적인 검색 기술의 정점(SOTA)을 로컬 환경에 그대로 가져왔습니다.

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

QMD는 세 가지 검색 방식을 결합하여 최상의 결과를 도출합니다:

BM25 (FTS5): 정확한 키워드 매칭을 위한 빠른 전체 텍스트 검색.
벡터 검색 (Vector Search): 의미적 유사성을 파악하는 시맨틱 검색.
LLM 리랭킹 (Re-ranking): 추출된 결과 중 사용자의 질문에 가장 적합한 순서를 LLM이 다시 매깁니다.

AI 에이전트를 위한 설계

QMD는 단순히 사람이 읽기 위한 도구가 아닙니다. JSON 출력을 기본으로 지원하며, MCP(Model Context Protocol) 서버를 내장하고 있어 Claude Desktop이나 Claude Code 같은 AI 도구와 즉시 연결됩니다. 이는 당신의 에이전트가 로컬 지식 베이스를 실시간으로 검색하고 활용할 수 있음을 의미합니다.

2. 기술적 딥다이브: 검색 아키텍처

QMD의 내부 작동 방식은 매우 정교합니다. 모든 과정은 외부 클라우드 의존 없이 사용자의 로컬 머신에서 실행됩니다.

QMD 아키텍처

스마트 마운틴(Smart Chunking)

단순히 글자 수로 문서를 자르지 않습니다. QMD는 마크다운 구조(헤더, 코드 블록, 단락)를 이해하는 점수 알고리즘을 사용하여 의미 단위가 깨지지 않도록 약 900토큰 단위로 청킹합니다. 특히 코드 블록은 가능한 한 하나의 단위로 유지되도록 보호됩니다.

로컬 LLM의 적극적 활용

node-llama-cpp를 통해 세 가지 GGUF 모델을 자동으로 활용합니다:

EmbeddingGemma (300M): 벡터 임베딩 생성.
Qwen3-Reranker (0.6B): 검색 결과의 정교한 재정렬.
QMD-Query-Expansion (1.7B): 사용자의 짧은 질문을 검색에 유리한 형태로 확장.

3. 주요 기능 및 사용법

설치 및 초기화

Node.js 또는 Bun 환경에서 간단히 설치할 수 있습니다.

# 글로벌 설치
npm install -g @tobilu/qmd

# 컬렉션(문서 폴더) 추가
qmd collection add ~/notes --name notes

# 임베딩 생성 (최초 1회 및 업데이트 시)
qmd embed

세 가지 검색 모드

상황에 맞는 검색 모드를 제공합니다:

qmd search "키워드": 매우 빠른 키워드 기반 검색.
qmd vsearch "의미적 질문": 의미가 유사한 내용 찾기.
qmd query "복합 질문": 쿼리 확장과 리랭킹이 포함된 최상 품질 검색.

컨텍스트 레이어 (Key Feature)

QMD의 독특한 기능 중 하나는 경로별로 **컨텍스트(Context)**를 추가할 수 있다는 점입니다.

qmd context add qmd://meetings "미팅 트랜스크립트 및 회의록"

이 메타데이터는 검색 결과와 함께 에이전트에게 전달되어, AI가 특정 문서의 성격을 훨씬 더 정확하게 파악할 수 있게 돕습니다.

4. MCP를 통한 에이전트 통합

Claude를 사용 중이라면 QMD를 외부 지식 저장소로 즉시 연결할 수 있습니다. claude_desktop_config.json에 다음 설정을 추가하기만 하면 됩니다.

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

이제 Claude에게 “내 지식 베이스에서 최근 프로젝트 일정에 대해 찾아줘”라고 요청하면, Claude가 직접 QMD를 통해 로컬 파일을 뒤져 답변을 생성합니다.

마치며: 로컬 지식의 가치 극대화

QMD는 “개인용 검색 엔진이 갖춰야 할 모든 것”을 미니멀하면서도 강력하게 구현했습니다. 데이터는 외부에 유출되지 않고 오직 당신의 기기에 머물며, AI 에이전트에게는 가장 똑똑한 기억 장치가 되어줍니다.

당신의 마크다운 노트와 문서들이 단순히 디스크 공간을 차지하는 데이터로 남을지, 아니면 즉시 호출 가능한 지능형 지식 베이스가 될지는 QMD에 달려 있습니다.

🔗 관련 정보

GitHub: https://github.com/tobi/qmd
공식 문서/사이트: https://qmd.dev (준비 중)
작성자: Tobi Lütke
주요 기술: TypeScript, SQLite, Vector Search, MCP