QMD memory engine

QMD memory engine 문서는 OpenClaw 공식 문서(concepts/memory-qmd)를 한국어로 정리한 가이드입니다. Local-first search sidecar with BM25, vectors, reranking, and query expansion 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Local-first search sidecar with BM25, vectors, reranking, and query expansion

한국어 가이드 범위: concepts/memory-qmd 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What it adds over builtin
Getting started
사전 요구사항
Enable
How the sidecar works
Search performance and compatibility
Model overrides
Indexing extra paths
Indexing session transcripts
Search scope
Citations
When to use
트러블슈팅
구성
관련 문서

상세 내용

본문

QMD is a local-first search sidecar that runs alongside OpenClaw. It combines BM25, vector search, and reranking in a single binary, and can index content beyond your workspace memory files.

What it adds over builtin

주요 항목:

Reranking and query expansion for better recall.
Index extra directories - project docs, team notes, anything on disk.
Index session transcripts - recall earlier conversations.
Fully local - runs with the official llama.cpp provider plugin and
Automatic fallback - if QMD is unavailable, OpenClaw falls back to the

Getting started

이 섹션의 세부 항목은 공식 문서 Getting started를 참고하세요.

사전 요구사항

주요 항목:

Install QMD: npm install -g @tobilu/qmd or bun install -g @tobilu/qmd
SQLite build that allows extensions (brew install sqlite on macOS).
QMD must be on the gateway's PATH.
macOS and Linux work out of the box. Windows is best supported via WSL2.

Enable

OpenClaw creates a self-contained QMD home under ~/.openclaw/agents//qmd/ and manages the sidecar lifecycle automatically - collections, updates, and embedding runs are handled for you. It prefers current QMD collection and MCP query shapes, but falls back to alternate collection-pattern flags and older MCP tool names when needed. Startup reconciliation also recreates stale managed collections back to their canonical patterns when an older QMD collection with the same name is still present.

{
  memory: {
    backend: "qmd",
  },
}

How the sidecar works

memory.qmd.paths. The QMD adapter owns update, embedding, debounce, and timeout heuristics; these are not user configuration.

주요 항목:

OpenClaw creates collections from workspace memory files and configured
QMD continues to own its index.sqlite, YAML collection config, and model
The default workspace collection tracks MEMORY.md plus the memory/
QMD's own scanner ignores hidden paths and common dependency/build
Searches use the configured searchMode (default: search; also supports
When searchMode is query, set memory.qmd.rerank to false to use
With QMD releases that advertise multi-collection filters, OpenClaw groups
If QMD fails entirely, OpenClaw falls back to the builtin SQLite engine.

Search performance and compatibility

OpenClaw keeps the QMD search path compatible with both current and older QMD installs.

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

qmd --help | grep -i collection

Model overrides

QMD model environment variables pass through unchanged from the gateway process, so you can tune QMD globally without adding new OpenClaw config:

Indexing extra paths

Point QMD at additional directories to make them searchable:

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

Indexing session transcripts

Enable session indexing to recall earlier conversations. QMD needs both the general memory.search session source and the QMD transcript exporter:

{
  memory: {
    backend: "qmd",
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
    qmd: {
      sessions: { enabled: true },
    },
  },
}

Search scope

By default, QMD search results are surfaced only in direct sessions (not group or channel chats). Configure memory.qmd.scope to change this:

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

Citations

When memory.citations is auto or on, search snippets get a Source: #L (or #L-L) footer appended. In auto mode the footer is added only for direct-chat sessions. Set memory.citations = "off" to omit the footer while still passing the path to the agent internally.

When to use

For simpler setups, the builtin engine works well with no extra dependencies.

주요 항목:

Reranking for higher-quality results.
To search project docs or notes outside the workspace.
To recall past session conversations.
Fully local search with no API keys.

트러블슈팅

runs as a service, create a symlink: sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd.

{
  memory: {
    backend: "qmd",
    qmd: {
      command: "/absolute/path/to/qmd",
    },
  },
}

구성

For the full config surface (memory.qmd.*), search modes, update intervals, scope rules, and all other knobs, see the Memory configuration reference.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/memory-qmd
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  memory: {
    backend: "qmd",
  },
}

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

qmd --help | grep -i collection

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

{
  memory: {
    backend: "qmd",
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
    qmd: {
      sessions: { enabled: true },
    },
  },
}

QMD memory engine

핵심 요약

Local-first search sidecar with BM25, vectors, reranking, and query expansion

한국어 가이드 범위: concepts/memory-qmd 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What it adds over builtin
Getting started
사전 요구사항
Enable
How the sidecar works
Search performance and compatibility
Model overrides
Indexing extra paths
Indexing session transcripts
Search scope
Citations
When to use
트러블슈팅
구성
관련 문서

상세 내용

본문

QMD is a local-first search sidecar that runs alongside OpenClaw. It combines BM25, vector search, and reranking in a single binary, and can index content beyond your workspace memory files.

What it adds over builtin

주요 항목:

Reranking and query expansion for better recall.
Index extra directories - project docs, team notes, anything on disk.
Index session transcripts - recall earlier conversations.
Fully local - runs with the official llama.cpp provider plugin and
Automatic fallback - if QMD is unavailable, OpenClaw falls back to the

Getting started

이 섹션의 세부 항목은 공식 문서 Getting started를 참고하세요.

사전 요구사항

주요 항목:

Install QMD: npm install -g @tobilu/qmd or bun install -g @tobilu/qmd
SQLite build that allows extensions (brew install sqlite on macOS).
QMD must be on the gateway's PATH.
macOS and Linux work out of the box. Windows is best supported via WSL2.

Enable

{
  memory: {
    backend: "qmd",
  },
}

How the sidecar works

memory.qmd.paths. The QMD adapter owns update, embedding, debounce, and timeout heuristics; these are not user configuration.

주요 항목:

OpenClaw creates collections from workspace memory files and configured
QMD continues to own its index.sqlite, YAML collection config, and model
The default workspace collection tracks MEMORY.md plus the memory/
QMD's own scanner ignores hidden paths and common dependency/build
Searches use the configured searchMode (default: search; also supports
When searchMode is query, set memory.qmd.rerank to false to use
With QMD releases that advertise multi-collection filters, OpenClaw groups
If QMD fails entirely, OpenClaw falls back to the builtin SQLite engine.

Search performance and compatibility

OpenClaw keeps the QMD search path compatible with both current and older QMD installs.

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

qmd --help | grep -i collection

Model overrides

QMD model environment variables pass through unchanged from the gateway process, so you can tune QMD globally without adding new OpenClaw config:

Indexing extra paths

Point QMD at additional directories to make them searchable:

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

Indexing session transcripts

Enable session indexing to recall earlier conversations. QMD needs both the general memory.search session source and the QMD transcript exporter:

{
  memory: {
    backend: "qmd",
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
    qmd: {
      sessions: { enabled: true },
    },
  },
}

Search scope

By default, QMD search results are surfaced only in direct sessions (not group or channel chats). Configure memory.qmd.scope to change this:

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

Citations

When to use

For simpler setups, the builtin engine works well with no extra dependencies.

주요 항목:

Reranking for higher-quality results.
To search project docs or notes outside the workspace.
To recall past session conversations.
Fully local search with no API keys.

트러블슈팅

runs as a service, create a symlink: sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd.

{
  memory: {
    backend: "qmd",
    qmd: {
      command: "/absolute/path/to/qmd",
    },
  },
}

구성

For the full config surface (memory.qmd.*), search modes, update intervals, scope rules, and all other knobs, see the Memory configuration reference.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/memory-qmd
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  memory: {
    backend: "qmd",
  },
}

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

qmd --help | grep -i collection

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

{
  memory: {
    backend: "qmd",
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
    qmd: {
      sessions: { enabled: true },
    },
  },
}

QMD memory engine

핵심 요약

문서 구성

상세 내용

본문

What it adds over builtin

Getting started

사전 요구사항

Enable

How the sidecar works

Search performance and compatibility

Model overrides

Indexing extra paths

Indexing session transcripts

Search scope

Citations

When to use

트러블슈팅

구성

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

QMD memory engine

핵심 요약

문서 구성

상세 내용

본문

What it adds over builtin

Getting started

사전 요구사항

Enable

How the sidecar works

Search performance and compatibility

Model overrides

Indexing extra paths

Indexing session transcripts

Search scope

Citations

When to use

트러블슈팅

구성

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드