tobi/qmd

mini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local

QMD – 쿼리 마크업 문서

이것이 무엇인가

마크다운 스타일의 노트, 대화록, 문서 및 기타 지식 베이스를 위한 로컬 온디바이스 검색 엔진입니다.
세 가지 검색 방법을 결합합니다:
1. BM25 전체 텍스트(키워드) 검색.
2. 벡터 임베딩을 사용한 의미론적 검색.
3. LLM 재순위화 (node‑llama‑cpp 및 GGUF 모델 사용)로 관련성 향상.
모든 구성 요소는 로컬에서 실행되며 외부 API 호출이 필요하지 않습니다.

주요 개념

유형화된 하위 쿼리 – 어휘(lex) 검색, 벡터(vec) 검색 또는 HyDE(가상 문서) 확장을 명시적으로 요청할 수 있습니다. 시스템은 상호 순위 융합(RRF)으로 결과를 결합한 후 선택적으로 LLM으로 재순위화합니다.
컨텍스트 – 컬렉션에 첨부하는 계층적 메타데이터(예: "개인 노트 및 아이디어"). 컨텍스트 문자열은 결과와 함께 반환되어 다운스트림 에이전트가 더 나은 결정을 내리도록 돕습니다.
MCP 서버 – 다른 도구(Claude Desktop, 사용자 지정 에이전트)가 QMD를 프로그래밍 방식으로 호출할 수 있게 하는 경량 Model Context Protocol 서버(stdio 또는 HTTP).

빠른 시작 (CLI)

# 전역 설치 (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 collection add ~/work/docs  --name docs

# 각 컬렉션에 사람이 읽을 수 있는 컨텍스트 부여 (선택 사항이지만 권장)
qmd context add qmd://notes "개인 노트 및 아이디어"
qmd context add qmd://meetings "회의 대화록 및 노트"
qmd context add qmd://docs "업무 문서"

# 벡터 백엔드용 임베딩 생성
qmd embed

# 검색 예시
qmd search "프로젝트 타임라인"               # 빠른 BM25 키워드 검색
qmd vsearch "배포 방법"                # 순수 의미론적 검색
qmd query "분기별 계획 프로세스"      # 하이브리드 (BM25+벡터) + LLM 재순위화

# 파일 검색
qmd get "meetings/2024-01-15.md"
qmd get "#abc123"                         # 내부 문서 ID로
qmd multi-get "journals/2025-05*.md"        # 글로브 패턴

에이전트 친화적 출력

--json은 구조화된 데이터(파일 URI, 점수, 스니펫)를 반환합니다.
--files는 절대 파일 경로를 추가하여 소스를 열어야 하는 에이전트에게 유용합니다.

MCP 서버 (프로그래밍 방식 액세스)

qmd mcp --http를 실행하여 영구 HTTP 서버(기본 localhost:8181)를 시작합니다.
엔드포인트:
- POST /mcp – 전체 MCP 스트림 프로토콜.
- POST /query (별칭 /search) – CLI query 도구와 동일한 매개변수, qmd://collection/path 형식의 file 필드가 포함된 JSON 반환.
- POST /metadata – 사용 가능한 메타데이터 키/값 검색.
- GET /health – 활성 상태 확인.
보안: 기본적으로 루프백 출처만 허용됩니다. QMD_ALLOWED_ORIGINS 또는 QMD_ALLOWED_HOSTS로 완화할 수 있습니다.
서버는 요청 간에 LLM 모델을 VRAM에 유지합니다. 임베딩 컨텍스트는 5분 동안 비활성 상태이면 지워집니다.

SDK / 라이브러리 사용 (Node/Bun)

npm install @tobilu/qmd

import { createStore } from '@tobilu/qmd'

const store = await createStore({
  dbPath: './my-index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
      notes: { path: '/path/to/notes' },
    },
  },
})

// 간단한 하이브리드 검색 (자동 확장 + RRF + LLM 재순위화)
const results = await store.search({ query: 'authentication flow' })
console.log(results.map(r => `${r.title} (${(r.score*100).toFixed(0)}%)`))

await store.close()

SDK는 CLI 기능을 미러링합니다:

세 가지 검색 모드에 대한 search, searchLex, searchVector.
문서 검색을 위한 get, multiGet.
컬렉션 관리 (addCollection, listCollections, …).
컨텍스트 처리 (addContext, listContexts).
인덱싱 (update) 및 임베딩 (embed).
모든 공개 객체에 대한 풍부한 TypeScript 타입 정의.

QMD를 언제 사용하나요?

개인 지식 베이스 – 데이터를 클라우드로 보내지 않고 모든 마크다운 노트를 검색 가능하게 유지합니다.
에이전트 워크플로우 – LLM 에이전트(예: Claude, Auto‑GPT)가 MCP 서버를 호출하여 관련 스니펫이나 전체 문서를 즉시 가져올 수 있습니다.
하이브리드 검색 – 정확한 키워드 일치와 의미론적 유사성이 모두 필요하고, 최고 품질 결과를 위한 선택적 LLM 재순위화가 필요할 때.
자체 호스팅 환경 – 데이터 프라이버시 또는 오프라인 운영이 요구되는 모든 상황.

TL;DR

QMD는 마크다운 기반 지식 컬렉션을 위한 로컬 실행 하이브리드 검색 엔진입니다. BM25, 벡터 유사성 및 LLM 재순위화를 혼합하며, CLI, 에이전트용 HTTP/MCP 서버, 자체 애플리케이션에 포함하기 위한 전체 TypeScript SDK를 제공합니다.