검색이 안 되는 노트는 없는 것과 같다
메모는 매일 쌓이는데, 정작 필요할 때 찾지 못한 경험이 누구에게나 있습니다. 회의록 수십 개, 문서 폴더, 개인 노트가 디스크 어딘가에 흩어져 있지만 파일명만으로는 그게 어디 있는지 알 수 없습니다. 검색이 안 되는 노트는 사실상 없는 것과 같습니다.
qmd는 이 문제를 정면으로 다룹니다. 한 줄로 정리하면, 마크다운 노트·회의록·문서를 인터넷 없이 내 컴퓨터에서 검색하는 온디바이스 검색엔진입니다. 키워드 검색과 자연어 검색을 같이 돌리고, 결과를 한 번 더 정렬해 정확도를 끌어올립니다.
이 도구가 푸는 문제
기존 노트 검색은 둘 중 하나였습니다. 단순 키워드 grep은 빠르지만 의미를 모릅니다. 클라우드 기반 의미 검색은 똑똑하지만 내 노트를 외부 서버에 올려야 합니다. qmd는 두 방식의 장점을 합치되, 전부 로컬에서 돌립니다.
핵심은 세 가지 검색을 겹쳐 쓴다는 점입니다. BM25 전문 검색(키워드), 벡터 의미 검색(자연어), 그리고 LLM 재정렬입니다. 이 모든 게 node-llama-cpp와 GGUF 모델로 내 기기 안에서 작동합니다. 노트가 밖으로 나가지 않습니다.
핵심 동작 원리
qmd의 검색은 세 단계로 나뉩니다. 먼저 빠른 키워드 검색, 그다음 의미 기반 검색, 마지막으로 둘을 합쳐 재정렬하는 하이브리드 검색입니다. 명령어로 보면 차이가 분명합니다.
qmd search "project timeline" # Fast keyword search
qmd vsearch "how to deploy" # Semantic search
qmd query "quarterly planning process" # Hybrid + reranking (best quality)
qmd가 다른 검색 도구와 갈라지는 진짜 지점은 context 기능입니다. 각 컬렉션이나 경로에 설명을 붙여두면, 하위 문서가 검색될 때 그 설명이 함께 반환됩니다. 트리 구조로 작동해서 LLM이 어떤 문서를 고를지 훨씬 나은 판단을 하게 됩니다. README에서도 이 기능을 두고 'Don't sleep on it!'이라고 강조합니다.
설치와 시작 가이드
설치는 Node나 Bun으로 전역 설치하면 됩니다.
npm install -g @tobilu/qmd
# 또는
bun 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가 특히 빛나는 곳은 AI 에이전트 워크플로입니다. --json과 --files 출력은 LLM이 바로 쓰도록 설계됐습니다.
qmd search "authentication" --json -n 10
qmd query "error handling" --all --files --min-score 0.4
더 깊은 통합을 원하면 MCP 서버를 띄울 수 있습니다. Claude Code에서는 플러그인 설치가 권장 방식입니다.
claude plugin marketplace add tobi/qmd
claude plugin install qmd@qmd
HTTP 전송을 쓰면 서버가 한 번만 모델을 로드하고 계속 떠 있어, 매번 모델을 다시 불러오는 비용을 아낍니다.
언제 쓰면 안 되는가
qmd는 만능이 아닙니다. 로컬에서 GGUF 모델을 돌리므로 기기 사양에 따라 임베딩 생성과 재정렬에 시간과 메모리가 듭니다. 노트가 적거나 단순 파일명 검색이면 굳이 이 무게가 필요 없습니다.
또한 실시간 협업 검색이나 팀 전체가 공유하는 중앙 검색 인덱스가 목적이라면, 온디바이스 설계와는 결이 다릅니다. qmd는 '내 기기 안 내 지식'에 최적화된 도구입니다. 팀 공유보다 개인·에이전트 검색 쪽에 가깝습니다.
같은 카테고리 대안 비교
순수 의미 검색만 원하면 클라우드 임베딩 API에 벡터DB를 붙이는 조합이 흔합니다. 똑똑하지만 데이터가 외부로 나가고 비용이 누적됩니다. 반대로 ripgrep 같은 도구는 완전 로컬·초고속이지만 의미를 모릅니다.
qmd는 이 두 극단 사이에 있습니다. 로컬을 지키면서 키워드와 의미를 함께 쓰고, 마지막에 LLM 재정렬로 정확도를 보강합니다. 프라이버시와 검색 품질을 동시에 잡고 싶을 때 합리적인 선택지입니다.
AI 에이전트에 붙일 때 보는 포인트
qmd를 단순 노트 검색기로만 보면 조금 아깝습니다. README가 반복해서 강조하는 지점은 에이전트용 출력입니다. --json은 검색 결과를 구조화해서 넘기고, --files는 기준 점수 이상 파일 목록을 바로 뽑습니다. 에이전트가 전체 노트를 무작정 읽는 대신, 먼저 qmd로 후보 문서를 좁히고 필요한 문서만 qmd get으로 가져오게 만들 수 있습니다.
여기서 중요한 것은 context입니다. qmd context add qmd://docs "Work documentation"처럼 컬렉션 설명을 붙여두면, 하위 문서가 검색될 때 그 설명이 함께 따라옵니다. LLM 입장에서는 파일 하나의 조각만 보는 것보다, 이 문서가 어떤 묶음에 속한 자료인지 같이 판단할 수 있습니다. 검색 결과의 정확도보다 실제 답변 품질이 더 중요하다면 이 기능을 먼저 봐야 합니다.
자주 묻는 질문
qmd는 클라우드 검색 도구인가요?
아닙니다. README 기준으로 qmd는 node-llama-cpp와 GGUF 모델을 사용해 로컬에서 BM25 검색, 벡터 검색, LLM 재정렬을 수행합니다. 노트를 외부 서비스에 올리지 않는 구조가 핵심입니다.
그럼 무조건 빠른가요?
키워드 검색은 빠르지만, 임베딩 생성과 LLM 재정렬은 로컬 모델을 쓰기 때문에 기기 성능의 영향을 받습니다. 작은 노트 폴더라면 과할 수 있고, 회의록·문서·개인 지식베이스가 커질수록 장점이 커집니다.
Claude Code와는 어떻게 연결하나요?
CLI로 직접 호출해도 되고, 더 단단히 붙이려면 qmd mcp로 MCP 서버를 띄울 수 있습니다. Claude Code 플러그인 설치 경로도 README에 제시되어 있어 에이전트 워크플로에 넣기 쉽습니다.
마무리
노트가 검색되지 않으면 쌓아둔 의미가 없습니다. qmd는 그 노트를 내 기기 안에서, 키워드와 자연어 양쪽으로 찾아주는 검색엔진입니다. AI 에이전트에 검색 능력을 붙이려는 사람이라면, MCP 서버나 SDK로 자신의 워크플로에 연결해보는 것부터 시작해볼 만합니다. context 기능을 같이 쓰면 검색 품질이 한 단계 더 올라갑니다.
🐦 X에서 더 빠르게: @baegseungh7061
📚 이 시리즈 더 보기: AI 인사이트
💌 새 글 알림: X 팔로우 또는 블로그 RSS 구독