OpenClaw QMD: 로컬 하이브리드 검색으로 10배 더 똑똑한 메모리

Source: Dev.to

번역을 진행하려면 전체 텍스트를 제공해 주시겠어요? 텍스트를 받는 대로 요청하신 대로 한국어로 번역해 드리겠습니다.

기본 메모리가 규모에서 실패하는 이유

OpenClaw의 내장 메모리는 간단합니다:

1. Append to MEMORY.md.
2. Inject the whole file into every prompt.

~500 토큰 정도에서는 잘 작동하지만, ~5 000 토큰이 되면 무너집니다.

문제는 복합적으로 나타납니다

QMD가 네 가지를 모두 해결합니다

마크다운 파일을 로컬에서 인덱싱하고, 세 가지 검색 전략을 결합한 하이브리드 검색을 실행하며, 관련 스니펫만 반환합니다.

• 700 characters max 결과당 (기본값 = 6개 결과).
• 10 000‑token 메모리 사용량이 ≈ 200 tokens of gold 로 감소합니다.

What interviewers are actually testing: 컨텍스트 인젝션의 토큰 경제학을 설명할 수 있나요?
Insight: 컨텍스트 길이는 O(n) 비용이지만, 중요한 것은 관련성입니다. Retrieval‑augmented generation (RAG)은 “모두 포함한다”는 방식이 확장되지 않기 때문에 존재합니다.

하이브리드 검색 – 세 단계

1단계 – BM25 (키워드 매칭)

전통적인 IR: 용어 빈도, 역문서 빈도, 문서 길이 정규화.

Score = Σ IDF(term) × TF(term,doc) × (k₁+1) / (TF + k₁ × (1‑b + b × |doc|/avgdl))

• 빠르고 결정적이며 정확한 매칭에 강점이 있음.
• 예시: “SwiftUI navigation”을 검색하면 해당 정확한 용어가 포함된 문서를 찾음.

제한점: 의미적 관계를 놓침 (예: “iOS routing”은 “SwiftUI navigation”과 매칭되지 않음).

2단계 – 벡터 검색 (시맨틱 매칭)

• Jina v3 임베딩 사용 (로컬, 약 1 GB GGUF 모델).
• 텍스트 → 1024 차원 벡터; 의미가 비슷한 내용이 서로 가까이 클러스터링됨.
• “iOS routing”은 “SwiftUI navigation” 근처에 위치함.

임베딩 모델은 첫 실행 시 자동으로 다운로드됩니다. API 키도 필요 없고, 클라우드 호출도 없습니다. 여러분의 노트는 절대 머신을 떠나지 않습니다.

3단계 – LLM 재랭킹 (정밀도 향상)

BM25와 벡터 검색이 후보를 반환한 뒤, 로컬 LLM이 실제 질의와의 관련성을 기준으로 재랭킹합니다.

Query: "Ray's SwiftUI style"
├── BM25 후보 (10)
├── 벡터 후보 (10)
└── LLM 재랭커 → 상위 6개 결과 (≈700 문자 each)

• 키워드와 시맨틱 매칭 모두 놓치는 경우를 포착합니다.
• 예시: Ray의 코드 리뷰 선호도에 관한 스니펫이 단순히 SwiftUI를 언급한 스니펫보다 높은 순위를 차지합니다.

면접관이 실제로 평가하는 부분: 하이브리드 검색은 2026년 현재 프로덕션 RAG의 표준입니다. 순수 벡터 검색은 리콜 문제가 있고, 순수 BM25는 의미적 문제가 있습니다. 두 방식을 결합하고 재랭킹을 추가하는 것이 실제로 작동하는 검색 시스템을 구축하는 방법입니다.

로컬에서 실행하는 이유?

트레이드오프: 컴퓨팅. 모델을 로드할 수 있는 충분한 RAM을 가진 머신이 필요합니다(~4 GB 권장). 클라우드 인스턴스도 사용할 수 있지만 API 호출 대신 컴퓨팅 비용을 지불하게 됩니다.

면접관이 실제로 평가하는 것: 머신러닝 인프라의 구축‑대‑구매 결정. 로컬 모델은 API 비용을 컴퓨팅 비용으로 교환합니다. 손익분기점은 쿼리 양, 지연 시간 요구사항, 프라이버시 제약에 따라 달라집니다. 자신의 수치를 파악하세요.

QMD 아키텍처

• Rust CLI – 빠르고, 단일 바이너리, 크로스‑플랫폼.
• GGUF 모델 – 로컬 추론을 위해 양자화됨 (~1 GB 전체).
• SQLite 인덱스 – BM25 + 메타데이터가 로컬에 저장됨.
• Jina v3 임베딩 – 1024‑차원 벡터, 다국어 지원.

Mac Mini M2에서 1 000개의 마크다운 파일을 임베딩하는 데 약 30 초가 걸립니다. 쿼리는 ≈ 100 ms 안에 반환됩니다.
면접관이 실제로 테스트하는 것: 시스템 통합 패턴. 메모리 백엔드와 같은 구성 요소를 시스템 나머지를 깨뜨리지 않고 어떻게 교체할 수 있나요? 답은 깔끔한 인터페이스, 설정 기반 전환, 그리고 새로운 백엔드가 실패할 경우의 우아한 감소를 포함합니다.

QMD의 모델 컨텍스트 프로토콜 (MCP) 서버

QMD는 MCP 서버를 제공하여 에이전트가 메모리를 프로그래밍 방식으로 (예: HTTP/JSON을 통해) 조회할 수 있게 합니다. 이를 통해 다음을 가능하게 합니다:

• 언어에 구애받지 않는 접근을 모든 에이전트 구현에서 제공
• 세밀한 제어를 통한 검색 파라미터 설정 (최대 결과 수, 문자 제한, 필터 등)
• MCP 서버가 사용 불가능할 경우 내장 메모리로의 부드러운 폴백

TL;DR

• 기본 “모두 주입” 메모리는 확장성이 없습니다.
• 하이브리드 검색 (BM25 + 벡터 + LLM 재정렬)은 저비용, 프라이버시 보호, 저지연 검색을 제공합니다.
• QMD는 이를 로컬에서 제공하고, 간단한 설정을 통해 OpenClaw와 통합되며, 에이전트의 메모리를 빠르고, 관련성 높으며, 안전하게 유지할 수 있게 합니다.

자체 치유 메모리 워크플로 활성화

예시: 오래된 항목을 정리하는 압축 스킬

// Memory compaction skill
const staleEntries = await qmd.query({
  collection: "agent-logs",
  filter: { olderThan: "30d", accessCount: 0 }
});

for (const entry of staleEntries) {
  if (await confirmDeletion(entry)) {
    await qmd.delete(entry.id);
  }
}

await qmd.reindex();

MCP 인터페이스

이것은 메모리를 수동적인 저장소에서 능동적인 시스템으로 전환합니다. 에이전트는 자체 컨텍스트를 관리하며, 관련 없는 항목을 정리하고 유용한 항목을 강조할 수 있습니다.

패턴 팁: 쿼리 패턴을 분석하고, 한 번도 검색되지 않은 항목을 식별하여 보관하는 야간 작업을 실행하세요. 메모리는 수동 관리 없이도 가볍게 유지됩니다.

면접관이 실제로 테스트하는 내용

“스스로 유지되는 시스템을 설계할 수 있나요?”
자체 치유 인프라는 시니어 엔지니어의 관심사입니다. 구체적인 기술(메모리 압축)보다 패턴이 더 중요합니다: 관찰 → 분석 → 실행 → 검증.

Benchmarking QMD vs. Default Memory

Environment

• OpenClaw v2026.2.0+
• Bun 또는 Node 22+
• 4 GB RAM, 모델용 디스크 약 2 GB

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

Verify Installation

qmd --version
# Expected: qmd 0.4.2 or higher

Index Your Existing Memory

qmd collection add ~/.openclaw/agents/main/memory --name test-memory

Build Embeddings (first run takes 30‑60 s)

qmd embed --collection test-memory

Run a Hybrid Search

time qmd query "database connection pooling" --collection test-memory

Compare Token Counts

echo "QMD returns ~700 chars × 6 results = 4,200 chars max"

echo "Full MEMORY.md injection = $(wc -c MEMORY.md)"

Cost tip: MEMORY.md 파일이 2 000 토큰을 초과하고 토큰당 컨텍스트 삽입 비용을 지불하고 있다면, QMD는 일주일 만에 비용을 회수할 수 있습니다.

Sources

• OpenClaw의 메모리 검색을 QMD로 고치는 방법 – José Casanova
• OpenClaw 메모리 문서
• QMD 스킬 – OpenClaw 스킬 플레이북
• Tobi Lütke의 QMD 통합