Quick Markdown Search

https://github.com/tobi/qmd

사용하는 이유

한참을 찾던 도구다.

현재 난 로컬에 TIL, 회의록, 업무 문서 등을 많이 쌓아두고 있다. 모두 마크다운형식이다.

ai가 이걸 검색해서 기존에 했던일들을 잘 활용해서 답변을 해주면 좋겟다는 생각이 들었다.

today i learn 하위 폴더를 모두 검색해줘 .elastic cluster 정보가 필요해

til 폴더를 기준으로 확인해보면 다음과 같습니다.

TIL 검색 결과를 찾았습니다. Elasticsearch 클러스터 정보 요약입니다:

  Elasticsearch 클러스터 요약
  ┌──────────┬────────┬─────────┬──────────────────────────┬──────┬─────────────────────────┐
  │ 클러스터 │  버전  │ 노드 수 │       Master Host        │ Port │        Tier 방식        │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ SV5      │ 7.10.0 │ 22      │ elasticmaster1-eqix-sv5  │ 9400 │ 레거시 (node.attr.type) │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ SV5-SMB  │ 8.12.0 │ 8       │ smbelasticm1-eqix-sv5    │ 9200 │ 레거시                  │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ DC3      │ 9.0.0  │ 7       │ elasticmaster1-eqix-dc3  │ 9200 │ 레거시                  │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ DC3-SMB  │ 8.17.0 │ 7       │ smbelasticm1-eqix-dc3    │ 9200 │ 레거시                  │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ SV10     │ 9.1.2  │ 7       │ elasticmaster1-eqix-sv10 │ 9200 │ 연결 실패               │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ DC10     │ 9.1.2  │ 7       │ elasticmaster1-eqix-dc10 │ 9200 │ 미사용                  │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ LD4      │ 8.10.2 │ 5       │ elastic1-eqix-ld4        │ 9200 │ 레거시                  │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ MD2      │ 8.10.2 │ 3       │ elastic1-eqix-md2        │ 9200 │ 레거시                  │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ JN1      │ 9.1.2  │ 7       │ elasticmaster1-eqix-jn1  │ 9200 │ Data Tiers              │
  ├──────────┼────────┼─────────┼──────────────────────────┼──────┼─────────────────────────┤
  │ SY5      │ 9.1.2  │ 7       │ elasticmaster1-eqix-sy5  │ 9200 │ Data Tiers              │
  └──────────┴────────┴─────────┴──────────────────────────┴──────┴─────────────────────────┘
  주요 포인트

  1. SV5만 포트 9400 사용, 나머지는 9200
  2. JN1, SY5만 최신 Data Tiers 방식 (node.roles: data_hot, data_warm)
  3. 2026-01-28 업데이트: 대부분 클러스터에서 ILM allocate.require 제거 → 티어 이동 없이 모든 데이터 노드 동등 사용
  4. 총 서버 수: 약 60대

  접속 명령어 예시

  # SV5 (포트 9400)
  curl -k -u elastic:$ELASTIC_PASS https://localhost:9400/_cluster/health

  # 다른 클러스터 (포트 9200)
  curl -k -u elastic:$ELASTIC_PASS https://localhost:9200/_cluster/health

  상세 노드 목록이나 특정 클러스터 정보가 더 필요하면 말씀해주세요.

이런식으로 나만의 지식 디비를 구축하고 ai가 검색해서 활용할 수 있으면 좋겟다.

설치 및 초기 설정

# install sqlite
brew install sqlite

# install bun
curl -fsSL https://bun.sh/install | bash

# install qmd
bun install -g https://github.com/tobi/qmd

# Create collections for your notes, docs, and meeting transcripts
qmd collection add ~/Desktop/ooma-gitlab/_ooma-til --name til

Creating collection 'til'...
Collection: /Users/ragon/Desktop/ooma-gitlab/_ooma-til (**/*.md)
Indexing: 1454/1454 ETA: 0s
Indexed: 1440 new, 0 updated, 0 unchanged, 0 removed

Run 'qmd embed' to update embeddings (1439 unique hashes need vectors)
✓ Collection 'til' created successfully

# qmd collection add ~/Documents/meetings --name meetings
# qmd collection add ~/work/docs --name docs

# Add context to help with search results
qmd context add qmd://til "today i learned"

✓ Added context for: qmd://til/ (collection root)
Context: today i learned

# qmd context add qmd://meetings "Meeting transcripts and notes"
# qmd context add qmd://docs "Work documentation"

# Generate embeddings for semantic search
qmd embed

Chunking 1439 documents by token count...
Downloading to ~/.cache/qmd/models
⏵ hf_ggml-o...Q8_0.gguf     6.331% (20.80MB/328.58MB)      330.96kB/s | 15m left

# 한참 걸림

# Search across everything
qmd search "elastic"                    # Fast keyword search

# 결과가 잘 나옮
qmd vsearch "how to deploy"             # Semantic search
qmd query "quarterly planning process"  # Hybrid + reranking (best quality)

# Get a specific document
qmd get "meetings/2024-01-15.md"

# Get a document by docid (shown in search results)
qmd get "#abc123"

# Get multiple documents by glob pattern
qmd multi-get "journals/2025-05*.md"

# Search within a specific collection
qmd search "API" -c notes

# Export all matches for an agent
qmd search "API" --all --files --min-score 0.3

검색이 잘된다. 이걸 어떻게 쓴다..

Using with AI Agents

# Get structured results for an LLM
qmd search "authentication" --json -n 10

# List all relevant files above a threshold
qmd query "error handling" --all --files --min-score 0.4

# 전체문서 가져오기
qmd get "til/2026/01/27/elastic-cluster-info.md" --full

Folder Context: today i learned
---

# Elasticsearch Cluster Node Summary

## Hot/Warm/Cold Tier 구현 현황

| 클러스터 | 버전   | Tier 구현 방식                     | Hot | Warm | Cold | ILM 동작        |
| -------- | ------ | ---------------------------------- | --- | ---- | ---- | --------------- |
| SV5      | 7.10.0 | 레거시 (`node.attr.type`)          | 7   | 4    | 5    | ✅ 티어이동없음 |
| SV5-SMB  | 8.12.0 | 레거시 (allocate require 비어있음) | 2   | 2    | 1    | ❌              |
| DC3      | 9.0.0  | 레거시 (`node.attr.type`)          | 2   | 2    | -    | ✅ 티어이동없음 |
| DC3-SMB  | 8.17.0 | 레거시 (allocate 미사용)           | 1   | 1    | 2    | ❌              |
| SV10     | 9.1.2  | 연결 실패                          | ?   | ?    | ?    | ?               |
| DC10     | 9.1.2  | 미사용 (allocate 없음)             | -   | -    | -    | ✅ 티어이동없음 |
| LD4      | 8.10.2 | 레거시 (`node.attr.type`)          | 2   | 2    | -    | ✅ 티어이동없음 |
| MD2      | 8.10.2 | 레거시 (`node.attr.type`)          | 1   | 1    | -    | ✅ 티어이동없음 |
| JN1      | 9.1.2  | **Data Tiers** (`node.roles`)      | 2   | 2    | -    | ✅ 티어이동없음 |
| SY5      | 9.1.2  | **Data Tiers** (`node.roles`)      | 2   | 2    | -    | ✅ 티어이동없음 |

이걸로 llm에 쓰기가 불편한데 skills을 만들가?

MCP Server

이 도구는 에이전트에게 명령줄에서 사용하도록 지시하기만 해도 완벽하게 작동하지만, 더 긴밀한 통합을 위해 MCP(모델 컨텍스트 프로토콜) 서버도 제공합니다.

공개된 도구:

• qmd_search- 빠른 BM25 키워드 검색 (컬렉션 필터 지원)

• qmd_vsearch- 의미 벡터 검색(컬렉션 필터 지원)

• qmd_query- 재순위 지정 기능을 갖춘 하이브리드 검색 (컬렉션 필터 지원)

• qmd_get- 경로 또는 문서 ID로 문서를 검색합니다(유사 일치 제안 기능 포함).

• qmd_multi_get- 글로브 패턴, 목록 또는 문서 ID를 사용하여 여러 문서를 검색합니다.

• qmd_status- 인덱스 상태 및 수집 정보

클로드 데스크톱 구성 ( ~/Library/Application Support/Claude/claude_desktop_config.json ):

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

claude code ( ~/.claude.json ):

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

디렉토리 관리

# Create a collection from current directory
qmd collection add . --name myproject

# Create a collection with explicit path and custom glob mask
qmd collection add ~/Documents/notes --name notes --mask "**/*.md"

# List all collections
qmd collection list

# Remove a collection
qmd collection remove myproject

# Rename a collection
qmd collection rename myproject my-project

# List files in a collection
qmd ls notes
qmd ls notes/subfolder

벡터 임베딩 생성

# Embed all indexed documents (800 tokens/chunk, 15% overlap)
qmd embed

# Force re-embed everything
qmd embed -f

검색 명령어

┌──────────────────────────────────────────────────────────────────┐
│                        Search Modes                              │
├──────────┬───────────────────────────────────────────────────────┤
│ search   │ BM25 full-text search only                           │
│ vsearch  │ Vector semantic search only                          │
│ query    │ Hybrid: FTS + Vector + Query Expansion + Re-ranking  │
└──────────┴───────────────────────────────────────────────────────┘

# Full-text search (fast, keyword-based)
qmd search "authentication flow"

# Vector search (semantic similarity)
qmd vsearch "how to login"

# Hybrid search with re-ranking (best quality)
qmd query "user authentication"

option

# Search options
-n <num>           # Number of results (default: 5, or 20 for --files/--json)
-c, --collection   # Restrict search to a specific collection
--all              # Return all matches (use with --min-score to filter)
--min-score <num>  # Minimum score threshold (default: 0)
--full             # Show full document content
--line-numbers     # Add line numbers to output
--index <name>     # Use named index

# Output formats (for search and multi-get)
--files            # Output: docid,score,filepath,context
--json             # JSON output with snippets
--csv              # CSV output
--md               # Markdown output
--xml              # XML output

# Get options
qmd get <file>[:line]  # Get document, optionally starting at line
-l <num>               # Maximum lines to return
--from <num>           # Start from line number

# Multi-get options
-l <num>           # Maximum lines per file
--max-bytes <num>  # Skip files larger than N bytes (default: 10KB)

인덱스 유지 관리

# Show index status and collections with contexts
qmd status

# Re-index all collections
qmd update

# Re-index with git pull first (for remote repos)
qmd update --pull

# Get document by filepath (with fuzzy matching suggestions)
qmd get notes/meeting.md

# Get document by docid (from search results)
qmd get "#abc123"

# Get document starting at line 50, max 100 lines
qmd get notes/meeting.md:50 -l 100

# Get multiple documents by glob pattern
qmd multi-get "journals/2025-05*.md"

# Get multiple documents by comma-separated list (supports docids)
qmd multi-get "doc1.md, doc2.md, #abc123"

# Limit multi-get to files under 20KB
qmd multi-get "docs/*.md" --max-bytes 20480

# Output multi-get as JSON for agent processing
qmd multi-get "docs/*.md" --json

# Clean up cache and orphaned data
qmd cleanup

[21:03][ragon ~/Desktop/ooma-gitlab/_ooma-til] git:(main) ✗
# qmd status
QMD Status

Index: /Users/ragon/.cache/qmd/index.sqlite
Size:  34.4 MB

Documents
  Total:    1440 files indexed
  Vectors:  4240 embedded
  Pending:  57 need embedding (run 'qmd embed')
  Updated:  2h ago

Collections
  til (qmd://til/)
    Pattern:  **/*.md
    Files:    1440 (updated 2h ago)
    Contexts: 1
      /: today i learned

Examples
  # List files in a collection
  qmd ls til
  # Get a document
  qmd get qmd://til/path/to/file.md
  # Search within a collection
  qmd search "query" -c til
[21:03][ragon ~/Desktop/ooma-gitlab/_ooma-til] git:(main) ✗
# qmd embed
Chunking 57 documents by token count...
Embedding 57 documents (137 chunks, 187.7 KB)
22 documents split into multiple chunks
Model: embeddinggemma

데이터 저장소

~/.cache/qmd/index.sqlite

collections     -- Indexed directories with name and glob patterns
path_contexts   -- Context descriptions by virtual path (qmd://...)
documents       -- Markdown content with metadata and docid (6-char hash)
documents_fts   -- FTS5 full-text index
content_vectors -- Embedding chunks (hash, seq, pos, 800 tokens each)
vectors_vec     -- sqlite-vec vector index (hash_seq key)
llm_cache       -- Cached LLM responses (query expansion, rerank scores)

embedding flow

문서는 800개 토큰 단위로 분할되며, 각 단위는 15%씩 겹칩니다.

임베딩

qmd status

# add file
qmd embed
#✓ All content hashes already have embeddings.

# update file or remove
qmd update

Updating 6 collection(s)...

[1/6] til (**/*.md)
Collection: /Users/ragon/Desktop/ooma-gitlab/_ooma-til (**/*.md)
Indexing: 1453/1453 ETA: 0s
Indexed: 0 new, 0 updated, 1439 unchanged, 0 removed

[2/6] gitbook (**/*.md)
Collection: /Users/ragon/Desktop/GitHub/teamsmiley/gitbook (**/*.md)
Indexing: 232/232 ETA: 0s
Indexed: 0 new, 1 updated, 231 unchanged, 0 removed
Cleaned up 1 orphaned content hash(es)

[3/6] gitbook-kafka (**/*.md)
Collection: /Users/ragon/Desktop/GitHub/teamsmiley/gitbook-kafka (**/*.md)
Indexing: 19/20 ETA: 0s
Indexed: 0 new, 0 updated, 13 unchanged, 0 removed

[4/6] homelab (**/*.md)
Collection: /Users/ragon/Desktop/GitHub/teamsmiley/homelab (**/*.md)
Indexing: 10/10 ETA: 0s
Indexed: 0 new, 0 updated, 10 unchanged, 0 removed

[5/6] teamsmiley-blog (**/*.md)
Collection: /Users/ragon/Desktop/GitHub/teamsmiley/teamsmiley.github.io (**/*.md)
Indexing: 322/322 ETA: 0s
Indexed: 0 new, 0 updated, 322 unchanged, 0 removed

[6/6] today-i-learn (**/*.md)
Collection: /Users/ragon/Desktop/GitHub/teamsmiley/today-i-learn (**/*.md)
Indexing: 352/352 ETA: 0s
Indexed: 0 new, 0 updated, 352 unchanged, 0 removed

✓ All collections updated.

Run 'qmd embed' to update embeddings (1 unique hashes need vectors)

새로운 파일만 한다.