README.md

QMD OpenClaw Kit

A reusable integration kit for turning QMD into a low-token local retrieval layer for OpenClaw and agent workflows.

English | 简体中文

Overview

• What this project is
• Why this exists
• Features
• Quick start
• Docs and examples
• Release status
• Attribution
• License

Impact at a glance

Measured runtime status

Estimated token-savings analysis

Audit snapshot

Metric	Current result
OpenClaw gateway	reachable
QMD MCP	running
QMD health endpoint	ok
GPU mode	CUDA (offloading: yes)
Indexed docs	125
Embedded vectors	291
Retrieval smoke test	passed
Estimated token savings (analysis, not billing export)	~33%–71%

Note: the health / MCP / GPU / docs / vectors figures are measured from the live deployment. The token-savings figures are estimated from representative local document sizes, not provider billing exports.

Why QMD helps

Without QMD	With QMD
reread multiple candidate markdown files	search locally first
often include large README/setup docs “just in case”	read only the likely answer-bearing docs
spend tokens rediscovering where the answer is	narrow the reread set before expensive context expansion
context payload grows quickly	context stays tighter and more targeted

See also:

• English audit: docs/audit-2026-04-22.md
• 中文审计：docs/audit-2026-04-22.zh-CN.md

What this project is

QMD OpenClaw Kit is a thin integration layer built on top of upstream QMD. It does not vendor or fork QMD. Instead, it provides:

• a practical installation flow
• a safer backend-selection wrapper for WSL/Linux hosts
• repeatable collection/context bootstrapping
• OpenClaw MCP configuration templates
• an OpenClaw-friendly retrieval skill
• bilingual documentation for reuse

The goal is simple: help an OpenClaw deployment search local markdown knowledge efficiently before paying token costs to reread large files.

Why this exists

OpenClaw-style agent environments often accumulate:

• workspace docs
• memory logs
• custom skills
• upstream product docs
• project-specific notes

Without a retrieval layer, agents end up rereading long markdown files again and again. QMD solves local retrieval well; this kit packages the surrounding operational glue.

Features

• Upstream-friendly: installs @tobilu/qmd from npm
• OpenClaw-oriented: templates for MCP and skill wiring
• Backend-aware: wrapper prefers real GPU backends when available, otherwise falls back to stable CPU mode instead of repeatedly crashing into bad autodetection paths
• Collection bootstrap: one script to register high-value markdown folders and attach context summaries
• Bilingual docs: English + Simplified Chinese
• Reusable: designed to be copied into another OpenClaw deployment with minimal edits

Repository layout

.
├── docs/
├── openclaw-custom-skills/
├── scripts/
└── templates/

Quick start

1) Install QMD

./scripts/install-qmd.sh

By default this installs @tobilu/qmd into the current user's npm prefix.

2) Bootstrap collections and contexts

WORKSPACE_ROOT="$HOME/.openclaw/workspace" \
OPENCLAW_HOME="$HOME/.openclaw" \
./scripts/bootstrap-collections.sh

This registers common OpenClaw knowledge sources such as:

• workspace root markdown
• workspace memory
• local docs
• bundled OpenClaw skills/docs
• custom skills
• optional projects folder

The bootstrap script is designed to be safe to rerun:

• existing collections are reused
• collection contexts are refreshed in place
• missing directories are skipped cleanly

3) Wire QMD into OpenClaw MCP

See templates/openclaw.jsonc.

Recommended pattern:

• install QMD normally
• use scripts/start-qmd-mcp.sh as the MCP command
• let the wrapper choose a sane backend mode

4) Optional: build embeddings

QMD_LLAMA_GPU=false qmd embed --max-docs-per-batch 12 --max-batch-mb 8

On CPU-only or unstable GPU setups, this is slower but reliable.

GPU / backend strategy

This kit treats backend selection as an operational concern, not a marketing checkbox.

Priority order:

1. honor an explicit QMD_LLAMA_GPU
2. use CUDA when real CUDA userland support is present
3. use Vulkan when Vulkan tooling is actually available
4. otherwise force CPU mode for stability

That avoids a common WSL/headless failure mode where auto-detection keeps attempting broken Vulkan builds.

OpenClaw skill

A reusable skill lives at:

• openclaw-custom-skills/qmd-retrieval/SKILL.md

Its policy is straightforward:

1. search with QMD first
2. read only the files that matter
3. keep token-heavy rereads as a last resort

Docs and examples

Core docs

• Architecture: docs/architecture.md
• GPU / backend notes: docs/gpu-setup.md
• CUDA verification helper: docs/check-qmd-cuda.md
• Deployment audit: docs/audit-2026-04-22.md
• Collections baseline: docs/collections.md
• Release checklist: docs/release-checklist.md
• Changelog: CHANGELOG.md

Examples

• Minimal setup: examples/openclaw-minimal
• WSL + NVIDIA notes: examples/openclaw-wsl-gpu

Project hygiene

• CI workflow: .github/workflows/ci.yml
• Contribution guide: CONTRIBUTING.md

Release status

This repository is now at an initial reusable release stage.

Suggested first tag:

• v0.1.0

Attribution

This project is based on upstream QMD by tobi / contributors:

• Upstream repo: https://github.com/tobi/qmd

Use this kit together with upstream QMD documentation; do not treat it as a replacement for upstream docs.

License

MIT for this integration kit.

Upstream QMD remains licensed by its own project and is not relicensed here.