로컬 지식 베이스 검색 엔진 QMD

QMD — 로컬 지식 베이스 검색

QMD는 사용자 작업 공간에 대한 로컬 벡터+키워드 검색 엔진입니다. 이미 문서화되어 있을 수 있는 질문에 답변하기 전에 사용하세요. 특히 사람, 프로젝트, 결정 및 과거 작업에 대한 맥락을 위해 사용합니다.

워크플로

워크플로는 항상 다음과 같습니다:

1. 검색 후보 문서를 찾습니다.
2. qmd get 또는 qmd multi-get으로 전체 소스를 검색합니다.
3. 검색된 텍스트에서 답변하며, 경로나 문서 ID를 인용합니다.

사용자가 사실, 결정, 인용문 또는 뉘앙스를 필요로 할 때는 스니펫만으로 답변하지 마십시오. 스니펫은 단지 단서일 뿐입니다.

검색한 내용을 보고할 때는 간결하게 표시하는 것으로 충분하며, 필요한 경우가 아니라면 전체 파일을 붙여넣지 마십시오:

검색됨: #abc123 wiki/projects/GenAICategorizer.md, #def432 memory/2026-05-26.md

올바른 검색 모드 선택

모드	명령어	사용 시기
BM25 키워드	qmd search	정확한 단어, 제목, 이름, 코드 기호, 희귀 구문
하이브리드 + 재순위화	qmd query	간접적인 표현, 개념적 검색, 최고 품질
구조화됨	qmd query (+ lex:/vec:/hyde: 필드)	정확한 앵커와 의미론적 검색이 필요한 어려운 검색

간단한 조회:

qmd search "챌린저 승무원 프로젝트 상태" -n 10
qmd search '"GenAI Categorizer"' -c wiki-main -n 5

의미론적 개념 조회:

qmd query "의사 결정 품질은 가정과 맥락을 표면화하는 데 달려있다" -n 10

구조화된 쿼리 (어려운 검색):

qmd query $'intent: OKR이 판단력을 대체하지 않고 메트릭을 도구로 보는 개념 노트를 찾습니다.\nlex: 계기판 도구 OKR Goodhart 메트릭 판단\nvec: 데이터 기반이며 메트릭 주도적이지 않은 제품 판단\nhyde: 개념 노트는 메트릭이 계기판처럼 유용하지만, 리더는 OKR과 대시보드가 제품 판단력을 Goodhart화할 수 있으므로 메트릭 주도보다는 데이터 정보에 기반해야 한다고 말합니다.'

구조화된 쿼리 필드:

• intent: 찾으려는 것과 피하려는 것을 명시합니다.
• lex: 정확한 용어, 별칭, 제목 및 희귀 단어.
• vec: 아이디어를 자연어로 바꿔 표현합니다.
• hyde: 요청을 충족시킬 문서나 답변을 설명합니다.

소스 검색

qmd get "#abc123"                        # 검색 결과의 문서 ID로
qmd get "wiki/projects/GenAICategorizer.md" --full  # 경로로
qmd multi-get "#abc123,#def432" --md     # 문서 ID로 일괄 처리
qmd multi-get 'memory/2026-05-*.md' -l 80  # 글로브(glob) 일괄 처리

여러 검색 결과를 비교하거나 여러 페이지에 걸쳐 맥락을 수집할 때는 multi-get을 사용하세요. 정확한 소스가 중요할 때는 --full을 사용하세요.

에이전트별 컬렉션

각 에이전트는 XDG 격리된 구성을 가진 자체 QMD 인덱스를 가지고 있습니다. 에이전트 목록은 ${OPENCLAW_HOME}/config/agents.map에 있습니다. CLI에서 검색할 때는 에이전트의 XDG 래퍼를 사용하세요:

# 메인 에이전트
XDG_CONFIG_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-config XDG_CACHE_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-cache qmd query "..."
# 개발 에이전트 및 기타 에이전트 — 동일한 패턴, 에이전트 이름만 변경

메인 에이전트 컬렉션

컬렉션	내용
identity-main	핵심 문서 — SOUL, IDENTITY, TOOLS, AGENTS, NETWORK, MEMORY 인덱스
wiki-main	지속 가능한 지식 코어텍스. Wiki — 에이전트 행동(교차 에이전트 규칙), 프로젝트, 도구, 개념, 사람. 2026-05-28 기준 기본 지속 가능한 메모리 저장소.
memory-main	일일 메모리 파일 (YYYY-MM-DD.md) — 7일 캡처 레이어로, 콘텐츠를 wiki-main으로 승격시킴
workspace-docs-main	전체 작업 공간 마크다운 (참조, 작업, 핸드오프, 학습)
skills-main	스킬 정의 (SKILL.md 파일)
agents-*-identity	다른 에이전트의 루트 아이덴티티/구성 문서 (에이전트별 작업 공간)
agents-*-memory	다른 에이전트의 일일 메모리 파일 (에이전트별 작업 공간)
agents-*-wiki	다른 에이전트의 지속 가능한 위키 (에이전트별 작업 공간) — 메인 에이전트는 전문가 지속 가능한 지식을 직접 쿼리할 수 있습니다.
handoffs-*	에이전트별 핸드오프 파일 (메인, 개발 및 기타 모든 에이전트)

전문가 컬렉션 힌트

아래 컬렉션 이름은 각 전문가 에이전트 자체 QMD 구성에서 가져온 것입니다. 메인 에이전트에서는 교차 에이전트 동등 항목(agents-<agent>-wiki, agents-<agent>-memory)을 사용하세요.

찾고 있는 항목	에이전트	주요 컬렉션 (해당 에이전트 내)	메인 에이전트에서
코드 프로젝트, 빌드 구성, 엔지니어링 결정	dev	projects-dev, identity-dev, wiki-dev	agents-dev-wiki, agents-dev-memory

컨텍스트 및 컬렉션 범위 지정

QMD의 context: 메타데이터(index.yml에서 설정하거나 qmd context add를 통해 설정)는 각 컬렉션의 내용을 설명하여 검색 관련성을 향상시킵니다. 결과와 함께 반환됩니다.

광범위한 쿼리가 잘못된 코퍼스로 표류할 때 -c로 검색 범위를 지정하세요:

qmd search "이번 주 스탠드업 노트" -c agents-dev-memory -n 10
qmd query "GenAI 프로젝트 상태" -c wiki-main -c projects-dev -n 10

모든 것을 검색하려면 -c를 생략하세요.

진단

qmd status     # 컬렉션 개수 및 대기 중인 임베딩
qmd update     # 재인덱싱 (인덱싱된 경로에 파일을 추가/편집한 후 사용)
qmd embed      # 업데이트 후 벡터 생성/재구축

qmd query 또는 qmd vsearch가 실패하면(모델/GPU를 사용할 수 없는 경우), 더 강력한 어휘 용어와 함께 qmd search로 대체하세요.

참고: 이전 문서는 qmd doctor를 참조했지만 — 해당 하위 명령어는 현재 CLI 버전에 없습니다. 상태 확인에는 qmd status를, 복구에는 qmd update/qmd embed를 사용하세요.

MCP 도구

MCP를 사용할 때(OpenClaw 에이전트의 기본값), 구조화된 쿼리를 선호하세요:

{
  "searches": [
    { "type": "lex", "query": "challenger crew status" },
    { "type": "vec", "query": "챌린저 승무원 프로젝트의 현재 상태는 무엇인가요?" }
  ],
  "intent": "프로젝트 상태를 찾고, 승무원에 대한 일반적인 개념은 찾지 않습니다.",
  "limit": 10
}

함정

• 스니펫에서 멈추지 마십시오. 주장하기 전에 문서를 가져오세요.
• 의미론적 검색을 남용하지 마십시오. 정확한 제목이나 용어를 알고 있다면 BM25가 더 빠르고 종종 더 좋습니다.
• 인덱스를 가볍게 변경하지 마십시오. qmd collection add, qmd update, qmd embed는 로컬 상태를 변경하며 비용이 많이 들 수 있습니다.
• 모델 기반 명령어는 환경에 민감할 수 있습니다. qmd query 또는 재순위화가 실패하면 더 강력한 어휘 용어와 함께 qmd search로 대체하세요.
• 모호한 사용자 표현에는 의도가 필요합니다. 쿼리 확장이 올바른 도메인을 추측하기를 바라기보다 intent:를 추가하세요.
• 컬렉션 이름이 중요합니다. 쿼리가 여러 도메인과 일치할 수 있을 때는 -c로 범위를 지정하세요.
• 최신성: QMD는 오래된 결과를 감쇠시키지 않습니다. 시간에 민감한 메모리의 경우 파일 이름을 확인하세요 — 오늘에 가까운 YYYY-MM-DD가 더 최신입니다.

설정 및 유지보수

요청받은 경우에만 실행하세요. 검색 및 검색은 안전하지만 인덱스 변경은 가벼운 작업이 아닙니다.

qmd collection add ~/notes --name notes   # index.yml 편집 대신 CLI 방식
qmd context add qmd://notes "설명"  # index.yml의 context: 대신 CLI 방식
qmd update                                # 컬렉션 재인덱싱
qmd embed                                 # 벡터 생성/재구축
qmd status                                # 변경 후 상태 확인